319 lines
9.4 KiB
Markdown
319 lines
9.4 KiB
Markdown
# Campux‑idoknow 校园墙系统完整部署文档
|
||
> 基于本次成功部署流程编写，零基础可按照步骤复刻，包含全部BUG修复、宝塔操作细节、踩坑记录。
|
||
|
||
## 目录
|
||
1. 前置服务器环境要求
|
||
2. 安装宝塔面板
|
||
3. 宝塔内安装Docker及Docker‑Compose
|
||
4. 域名解析配置
|
||
5. 拉取项目源码
|
||
6. 修改环境配置文件.env（修复第一个致命BUG）
|
||
7. 修复开通向导机器人Platform校验BUG（前端代码修改）
|
||
8. Docker‑Compose编译构建项目（宝塔重建按钮坑点说明）
|
||
9. 查看容器日志，校验项目启动状态
|
||
10. 宝塔网站配置Nginx反向代理 + 申请SSL证书
|
||
11. 微信浏览器缓存问题解决方案
|
||
12. NapCat‑QQ机器人对接流程
|
||
13. 日常运维命令清单
|
||
14. 全部踩坑问题汇总
|
||
|
||
## 1. 前置服务器环境要求
|
||
### 硬件最低配置
|
||
- CPU：2核
|
||
- 内存：**4G及以上（低于4G编译前端会直接卡死，构建失败）**
|
||
- 硬盘：20GB+
|
||
|
||
### 系统
|
||
CentOS 7（优先，宝塔兼容性最佳），Ubuntu 22.04同样兼容。
|
||
|
||
### 网络放行端口
|
||
1. 服务器安全组放行：22(SSH)、80、443；
|
||
2. 数据库、MinIO图片存储仅容器内部通信，无需对外开放端口。
|
||
|
||
### 域名
|
||
准备已备案域名，示例：`qq.yunsya.cn`，A记录解析至服务器公网IP。
|
||
|
||
## 2. 安装宝塔面板
|
||
1. 使用Xshell/FinalShell/宝塔网页终端登录服务器；
|
||
2. CentOS7一键安装命令：
|
||
```bash
|
||
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. 粘贴全部文本，保存即可。
|
||
后续迁移服务器、重装系统，直接对照本文档即可一键复现部署流程。 |