Campux‑idoknow 校园墙系统完整部署文档

基于本次成功部署流程编写，零基础可按照步骤复刻，包含全部BUG修复、宝塔操作细节、踩坑记录。

前置服务器环境要求
安装宝塔面板
宝塔内安装Docker及Docker‑Compose
域名解析配置
拉取项目源码
修改环境配置文件.env（修复第一个致命BUG）
修复开通向导机器人Platform校验BUG（前端代码修改）
Docker‑Compose编译构建项目（宝塔重建按钮坑点说明）
查看容器日志，校验项目启动状态
宝塔网站配置Nginx反向代理 + 申请SSL证书
微信浏览器缓存问题解决方案
NapCat‑QQ机器人对接流程
日常运维命令清单
全部踩坑问题汇总

1. 前置服务器环境要求

硬件最低配置

CPU：2核
内存：4G及以上（低于4G编译前端会直接卡死，构建失败）
硬盘：20GB+

系统

CentOS 7（优先，宝塔兼容性最佳），Ubuntu 22.04同样兼容。

网络放行端口

服务器安全组放行：22(SSH)、80、443；
数据库、MinIO图片存储仅容器内部通信，无需对外开放端口。

域名

准备已备案域名，示例：qq.yunsya.cn，A记录解析至服务器公网IP。

2. 安装宝塔面板

使用Xshell/FinalShell/宝塔网页终端登录服务器；
CentOS7一键安装命令：

yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec
 
 
3. 安装完成后，记录面板地址、账号、密码；
4. 浏览器访问宝塔面板，阿里云/腾讯云服务器需额外在安全组放行宝塔8888端口。
 
3. 宝塔安装Docker、Docker‑Compose
 
1. 左侧菜单打开【软件商店】；
2. 搜索 Docker ，点击一键安装；
3. Docker安装完毕会自动附带Docker‑Compose；
4. 安装完成后左侧出现【Docker】菜单。
 
4. 域名解析配置
 
1. 进入域名服务商后台；
2. 添加A记录：主机记录 @ ，记录值填写服务器公网IP；
3. 等待5‑30分钟解析生效，可通过站长工具检测。
 
5. 拉取项目源码
 
1. 打开宝塔【终端】，逐条执行命令：
 
bash
  
# 进入网站根目录
cd /www/wwwroot
# 拉取idoknow版Campux源码，文件夹固定为campux‑source
git clone https://github.com/idoknow/Campux.git campux-source
# 进入项目目录
cd campux-source
 
 
2. 在宝塔文件管理器  /www/wwwroot  内可看到项目文件夹。
 
6. 修改环境配置文件 .env
 
BUG说明：原版 CAMPUX_TENANT_DOMAIN_TTL=-1 ，Zod校验不允许负数，会导致容器反复崩溃，必须修改。
 
1. 宝塔文件管理器打开路径：
 /www/wwwroot/campux-source/.env 
2. 编辑文件，替换内容，按需修改域名与密钥：
 
env
  
# 网站访问域名，修改为自己的HTTPS域名
CAMPUX_WEB_ORIGIN=https://qq.yunsya.cn
# 会话加密密钥，自行生成一串随机字母数字
CAMPUX_BOT_SESSION_SECRET=Kd2c58e9337f54144e0d8f61d500b41f51500b41
# 图片资源访问地址
S3_PUBLIC_BASE_URL=https://qq.yunsya.cn/s3
# 租户域名后缀，留空
CAMPUX_TENANT_DOMAIN_SUFFIX=""
# 修复BUG，由‑1改为86400秒(1天)
CAMPUX_TENANT_DOMAIN_TTL=86400
# 关闭遥测数据收集
CAMPUX_TELEMETRY_DISABLED=true
 
 
3. 保存 .env 文件。
 
必改项清单
 
1.  CAMPUX_WEB_ORIGIN  替换为个人域名；
2.  CAMPUX_BOT_SESSION_SECRET  自定义随机字符串；
3.  S3_PUBLIC_BASE_URL  替换为个人域名；
4.  CAMPUX_TENANT_DOMAIN_TTL  修改为 86400 。
 
7. 修复开通向导Platform校验BUG
 
问题描述
 
开通校园墙第二步「接入墙号机器人」，点击创建墙号报错：
 invalid_union_discriminator Expected "onebot" | "official_qq" 
原因：前端请求缺少 platform:"onebot" 字段。
 
1. 打开文件路径：
 /www/wwwroot/campux-source/apps/web/src/features/onboarding/OnboardingWizard.tsx 
2. 找到 createBot 函数内的请求代码：
 
ts
  
await api("/api/admin/bots", {
  method: "POST",
  body: JSON.stringify({
    qqUin: botQq.trim(),
    displayName: botName.trim() || `${tenant.name} 墙号`,
    reviewGroupId: reviewGroup.trim() || undefined,
    reviewNotificationEnabled: true,
    createPublishTarget: true,
  }),
});
 
 
3. 添加一行 platform: "onebot", ，修改后代码：
 
ts
  
await api("/api/admin/bots", {
  method: "POST",
  body: JSON.stringify({
    qqUin: botQq.trim(),
    displayName: botName.trim() || `${tenant.name} 墙号`,
    reviewGroupId: reviewGroup.trim() || undefined,
    reviewNotificationEnabled: true,
    createPublishTarget: true,
    platform: "onebot",
  }),
});
 
 
4. 保存文件。
 
免修改备选方案
开通向导页面返回上一页，跳过机器人绑定；校园墙创建完成后，在后台【机器人管理】页面添加QQ机器人，后台页面无此BUG。
 
8. Docker‑Compose编译构建项目
 
重要坑点
 
宝塔移动端Docker编排里的【重建】按钮仅能重启容器，不会编译新代码，修改的TSX文件无法打包进镜像，修改不生效。必须通过终端命令构建。
 
1. 打开宝塔终端，执行：
 
bash
  
cd /www/wwwroot/campux-source
docker compose up -d --build
 
 
2. 构建时长4‑8分钟，全程不可关闭终端、锁屏，断开连接会终止构建。
3. 出现如下输出，代表构建完成：
 
plaintext
  
✔ Image campux-source-campux Built
✔ Container campux-minio     Running
✔ Container campux-postgres  Healthy
✔ Container campux           Started
 
 
自动启动3个容器：
 
- campux：主程序服务
- campux‑postgres：PostgreSQL数据库
- campux‑minio：图片存储服务
 
校验服务是否正常启动
 
bash
  
docker logs -f campux
 
 
出现下面两行文字即代表运行正常：
 
plaintext
  
database migrations completed
Server listening at http://172.18.0.4:8989
 
 
按下 Ctrl + C 退出日志查看。
 
9. 宝塔网站配置Nginx反向代理 & 申请SSL证书
 
9‑1 添加站点
 
1. 【网站】→【添加站点】；
2. 域名填写： qq.yunsya.cn ；
3. 网站目录随意填写（示例： /www/wwwroot/qq.yunsya.cn ，程序不使用该目录）；
4. 数据库：不创建数据库；
5. PHP版本：纯静态；
6. 点击提交。
 
9‑2 修改Nginx配置
 
1. 网站列表点击【设置】‑【配置文件】；
2. 删除全部原有代码，粘贴下方配置：
 
nginx
  
server
{
    listen 80;
    server_name qq.yunsya.cn;
    return 301 https://$host$request_uri;
}

server
{
    listen 443 ssl;
    server_name qq.yunsya.cn;
    ssl_certificate /www/server/panel/vhost/cert/qq.yunsya.cn/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/qq.yunsya.cn/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8989;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /s3/ {
        proxy_pass http://127.0.0.1:9000/campux-next/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
 
 
9‑3 申请HTTPS证书
 
1. 切换到【SSL】选项卡；
2. 选择Let‑Encrypt免费证书，勾选域名进行申请；
3. 申请成功后开启【强制HTTPS】；
4. 保存Nginx配置。
 
保存Nginx报错提示证书不存在，代表证书未申请完成，需先完成证书申请。
 
10. 微信浏览器缓存问题（必踩坑）
 
Docker已经构建最新代码，但微信浏览器缓存了旧JS，表单依旧提交旧数据，依旧会报错。
 
1. 手机后台彻底上滑关闭微信进程；
2. 重新打开微信，访问域名；
3. 再次进入开通向导，BUG修复完成。
 
电脑端浏览器按 Ctrl+F5 强制刷新清除缓存。
 
11. NapCat‑QQ机器人对接
 
1. 校园墙开通后，复制页面内反向WebSocket地址；
2. 打开NapCat后台，新增反向WebSocket客户端；
3. 粘贴地址并启用；
4. 页面状态显示「已连接」，机器人接入完成。
 
12. 日常运维命令
 
bash
  
# 查看实时日志
docker logs -f campux

# 仅重启容器(不重新构建镜像，30秒内完成)
cd /www/wwwroot/campux-source
docker compose restart

# 更新项目源码并重新部署
cd /www/wwwroot/campux-source
git pull
docker compose up -d --build

# 停止整套服务
cd /www/wwwroot/campux-source
docker compose down
 
 
13. 踩坑问题汇总
 
1. 容器反复重启： .env 文件内 CAMPUX_TENANT_DOMAIN_TTL=-1 ，修改为86400；
2. 开通墙号报platform错误：修改 OnboardingWizard.tsx ，添加 platform:"onebot" ；
3. 修改代码后宝塔重建不生效：宝塔重建仅重启容器，必须执行 docker compose up -d --build ；
4. Docker构建卡死：服务器内存低于4G，升级内存；
5. 修改代码后网页依旧报错：微信浏览器缓存问题，彻底关闭微信；
6. Nginx配置保存失败：SSL证书未申请完成；
7. 域名无法访问：检查域名解析、服务器安全组、宝塔防火墙80/443端口。
 
plaintext
  

### 使用方法
1. 宝塔文件管理器进入`/www/wwwroot/campux-source`；
2. 新建文件，命名为`README.md`；
3. 粘贴全部文本，保存即可。
后续迁移服务器、重装系统，直接对照本文档即可一键复现部署流程。

README.md Unescape Escape

Campux‑idoknow 校园墙系统完整部署文档

目录

1. 前置服务器环境要求

硬件最低配置

系统

网络放行端口

域名

2. 安装宝塔面板

README.md