```markdown
# Campux-idoknow 校园墙系统部署文档

> 基于本次成功部署整理，适配 **宝塔 + Docker**，包含两处核心 BUG 修复，补齐全部部署约束项（HTTPS、Nginx顺序、缓存、构建限制、权限、Git推送细节），可一键复刻部署。

---

## 📑 目录

1. [环境前置要求](#1-环境前置要求)
2. [服务器初始化操作](#2-服务器初始化操作)
3. [下载源码](#3-下载项目源码)
4. [配置环境文件 `.env`（BUG-1 修复 + HTTPS强制规则）](#4-配置环境文件-env)
5. [修复前端向导 Platform 报错（BUG-2）](#5-修复前端向导-platform-报错)
6. [Docker 编译打包部署](#6-docker-编译打包部署)
7. [宝塔 Nginx 反向代理配置（关键顺序约束）](#7-宝塔-nginx-反向代理配置)
8. [微信浏览器缓存问题](#8-微信浏览器缓存问题)
9. [NapCat-QQ 机器人对接](#9-napcat-qq-机器人对接)
10. [运维命令汇总](#10-运维命令汇总)
11. [完整踩坑清单](#11-完整踩坑清单)

---

## 1. 环境前置要求

### 硬件
- **CPU**：2 核
- **内存**：**≥ 4 GB**（低于 4 GB 编译前端会卡死，构建失败；编译阶段内存占用峰值 3.5~3.8 GB）
- **硬盘**：20 GB+（Docker 镜像、PostgreSQL 数据库、MinIO 图片存储会占用大量磁盘）

### 系统
- **CentOS 7**（推荐，宝塔兼容性最好）
- **Ubuntu 22.04** 亦可兼容

### 端口放行（安全组 + 宝塔防火墙）
- 必须放行端口：`22`、`80`、`443`
- Postgres、MinIO 仅容器内部通信，无需对外开放端口

### 域名硬性规则（⚠️ 重点）
1. 域名必须**完成备案**；
2. 域名 A 记录解析指向服务器公网 IP；
3. **系统必须使用 HTTPS 协议运行，不可仅使用 HTTP**：
   - 前端、WebSocket 机器人通信、图片 S3 存储全部依赖 HTTPS；
   - 若只配置 HTTP，页面会出现接口跨域、机器人连接失败、提交表单报错；
4. `.env` 内 `CAMPUX_WEB_ORIGIN`、`S3_PUBLIC_BASE_URL` **必须填写 `https://` 开头的域名**，不能写 `http://`。

---

## 2. 服务器初始化操作

### 2.1 安装宝塔面板（CentOS 7）
```bash
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec
```

安装完成后记录面板地址、账号、密码，并放行宝塔 8888 端口。

2.2 宝塔安装 Docker

1. 软件商店 → 搜索 Docker，一键安装；
2. Docker 会自动附带 docker-compose；
3. 左侧菜单栏出现 Docker 图标代表安装成功。

⚠️ 禁止使用 Docker 兼容模式，否则会导致构建镜像异常。

---

3. 下载项目源码

打开宝塔【终端】执行：

```bash
cd /www/wwwroot
git clone https://git.grxiao.cn/yuns/campux-source_Nkeim.git campux-source
cd campux-source
```

⚠️ 项目目录名称必须为 campux-source，docker-compose 配置文件依赖该文件夹名称，改名会导致挂载异常。

---

4. 配置环境文件 .env

路径：/www/wwwroot/campux-source/.env

⚠️ BUG-1 修复

原版 CAMPUX_TENANT_DOMAIN_TTL=-1 会让容器无限重启，必须修改为 86400。

强制 HTTPS 规则

所有域名地址必须以 https:// 开头，绝对不能填写 http://，否则前端接口、S3 图片、WebSocket 全部失效。

完整配置示例：

```env
# 必须填写 HTTPS 域名，禁止 http
CAMPUX_WEB_ORIGIN=https://qq.yunsya.cn
# 会话加密密钥，自定义一串随机字符
CAMPUX_BOT_SESSION_SECRET=自定义随机字符
# S3 图片地址，同样必须使用 HTTPS
S3_PUBLIC_BASE_URL=https://qq.yunsya.cn/s3
CAMPUX_TENANT_DOMAIN_SUFFIX=""
# 修复 Zod 校验 BUG，固定改为 86400，禁止使用 -1
CAMPUX_TENANT_DOMAIN_TTL=86400
CAMPUX_TELEMETRY_DISABLED=true
```

必改项清单：

· CAMPUX_WEB_ORIGIN → 替换为你的 HTTPS 域名
· CAMPUX_BOT_SESSION_SECRET → 自定义随机字符串
· S3_PUBLIC_BASE_URL → 替换为 HTTPS 域名（同网站域名）
· CAMPUX_TENANT_DOMAIN_TTL → 固定改为 86400
· 全部地址必须使用 https:// 协议

保存文件后继续。

---

5. 修复前端向导 Platform 报错（BUG-2）

问题现象

开通校园墙 → 接入墙号机器人，创建时报错：

```
invalid_union_discriminator Expected "onebot" | "official_qq"
```

原因

前端请求缺少 platform: "onebot" 字段。

修改文件

路径：/www/wwwroot/campux-source/apps/web/src/features/onboarding/OnboardingWizard.tsx

找到 createBot 请求代码，新增 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",   // ✅ 新增此行
  }),
});
```

保存文件。

💡 备选方案（免改代码）

开通向导直接跳过机器人绑定；创建完校园墙后，在后台【机器人管理】页面手动添加 QQ 机器人。

---

6. Docker 编译打包部署

⚠️ 重点坑点

1. 宝塔移动端「重建」按钮只会重启容器，不会编译新代码。修改 TSX 等前端文件后，必须执行下方构建命令才能生效。
2. 构建期间不要关闭宝塔终端、锁屏、断开 SSH 连接，会话中断会终止构建，导致镜像不完整。
3. 服务器内存必须 ≥ 4 GB，否则编译进程会被 OOM 直接杀死。

构建命令（宝塔终端执行）

```bash
cd /www/wwwroot/campux-source
docker compose up -d --build
```

· 构建耗时：4~8 分钟
· 构建成功标识：

```
✔ Image campux-source-campux Built
✔ Container campux-minio     Running
✔ Container campux-postgres  Healthy
✔ Container campux           Started
```

校验服务是否正常运行

```bash
docker logs -f campux
```

出现以下两行代表启动成功：

```
database migrations completed
Server listening at http://172.18.0.4:8989
```

按 Ctrl+C 退出日志。

注意：容器内部运行地址为 HTTP，外部访问必须通过 Nginx 反向代理转为 HTTPS。

---

7. 宝塔 Nginx 反向代理配置（关键顺序约束）

⚠️ 硬性操作顺序

1. 先申请 SSL 证书（Let's Encrypt）
2. 再粘贴 Nginx 配置文件

如果先粘贴 Nginx 配置，证书文件不存在，Nginx 配置校验会直接报错，无法保存。

7.1 添加站点

1. 网站 → 添加站点；
2. 域名：qq.yunsya.cn（替换为你的域名）；
3. 网站目录：随意填写（程序运行在 Docker 内，不使用此目录）；
4. 数据库：不创建；
5. PHP：纯静态。

7.2 申请 SSL 证书（第一步）

1. 网站设置 → SSL；
2. 申请 Let's Encrypt 免费证书；
3. 等待证书生成完毕，宝塔会自动创建证书目录与文件。

7.3 Nginx 配置文件（第二步）

完整配置如下（请替换域名和证书路径）：

```nginx
server
{
    listen 80;
    server_name qq.yunsya.cn;
    # 强制所有 HTTP 请求跳转到 HTTPS
    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;
        # 适配 WebSocket 连接（NapCat 机器人必须开启这两行）
        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;
    }
}
```

7.4 开启强制 HTTPS

在 SSL 页面开启【强制 HTTPS】，然后保存 Nginx 配置。

❗ 报错“证书不存在”：代表证书未申请完成，返回上一步先申请 SSL 证书。
❗ 机器人 WebSocket 连接失败：检查 Nginx 内 Upgrade、Connection 两行配置是否完整。

---

8. 微信浏览器缓存问题（高频踩坑）

即使 Docker 已经构建新代码，微信内置浏览器会缓存旧 JS 脚本，表单依旧提交旧数据，甚至还会报 platform 错误。

解决方法

· 手机端：彻底划掉微信后台进程，重新打开微信访问域名；
· 电脑端：Ctrl + F5 强制刷新清除浏览器缓存。

后续每次修改前端代码并重新构建后，都必须清理微信缓存。

---

9. NapCat-QQ 机器人对接

1. 开通校园墙后，复制页面内的反向 WebSocket 地址；
2. ⚠️ 网站为 HTTPS，WebSocket 地址协议应为 wss://，不能填写 ws://，否则 NapCat 连接会被浏览器拦截；
3. 在 NapCat 后台新增反向 WebSocket 客户端，粘贴 wss:// 开头的地址并启用；
4. 页面状态显示「已连接」即对接完成。

---

10. 运维命令汇总

```bash
# 查看实时日志
docker logs -f campux

# 仅重启容器（不重新构建，约 30 秒完成，只重启服务）
cd /www/wwwroot/campux-source
docker compose restart

# 更新仓库代码并重新构建部署（修改前端代码必须加 --build）
cd /www/wwwroot/campux-source
git pull
docker compose up -d --build

# 停止整套服务
cd /www/wwwroot/campux-source
docker compose down

# 推送修改后的文档到 Gitea 仓库
cd /www/wwwroot/campux-source
git add README.md
git commit -m "完善部署文档，补齐 HTTPS、Nginx 顺序、构建约束项"
git push origin main
```

---

11. 完整踩坑清单（所有注意事项汇总）

序号 问题现象 原因与解决方案
1 容器反复重启 .env 内 CAMPUX_TENANT_DOMAIN_TTL=-1，修改为 86400；或 .env 域名误用了 http://，必须改为 https://。
2 开通墙号报 platform 错误 修改 OnboardingWizard.tsx，添加 platform:"onebot" 字段；构建镜像必须执行 docker compose up -d --build。
3 修改代码后宝塔重建不生效 宝塔「重建」按钮仅重启容器，不会编译新代码，必须执行构建命令。
4 Docker 构建进程卡死/被终止 服务器内存 < 4 GB，升级内存；构建过程不能断开 SSH 终端。
5 网页修改后依旧报旧错误 微信浏览器缓存，必须彻底关闭微信后台进程，清除缓存。
6 Nginx 配置保存失败 操作顺序错误：未先申请 SSL 证书就粘贴 Nginx 配置；正确顺序：先申请 Let's Encrypt 证书，再配置 Nginx。
7 NapCat 机器人 WebSocket 无法连接 ① 网站未开启强制 HTTPS，WebSocket 协议应为 wss://；② Nginx 配置缺少 Upgrade、Connection 升级头；③ .env 内域名填写了 http:// 协议。
8 图片无法加载（S3 资源 403/404） S3_PUBLIC_BASE_URL 域名填写错误，必须和网站域名一致，且协议为 https://。
9 项目目录改名后 Docker 启动异常 文件夹名称必须为 campux-source，docker-compose 挂载依赖该目录名。
10 仅使用 HTTP 访问网站 会出现接口跨域、机器人连接失败、表单提交异常，系统强制依赖 HTTPS 运行。

---

✅ 本次文档新增补充内容清单

· 明确了 Nginx 操作顺序：先申请 SSL 证书，再写 Nginx 配置；
· 强调 .env 必须全部使用 https:// 协议，禁止 HTTP；
· 标注 WebSocket 协议为 wss://，及 NapCat 连接的约束；
· 补充构建时内存、SSH 会话断开的风险；
· 项目文件夹名称固定要求；
· 新增 S3 图片 403 报错、跨域问题、目录改名异常的踩坑项；
· 补充 Git 推送命令，一键更新 Gitea 仓库内的文档。

---