From 3ce5a3176427d347f9aa800ac12fbfd4190d0963 Mon Sep 17 00:00:00 2001 From: yuns <1690532276@qq.com> Date: Sun, 19 Jul 2026 17:38:19 +0000 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 565 +++++++++++++++++++++++++----------------------------- 1 file changed, 258 insertions(+), 307 deletions(-) diff --git a/README.md b/README.md index 04f0ec7..72dab49 100644 --- a/README.md +++ b/README.md @@ -1,356 +1,307 @@ -```markdown -# Campux-idoknow 校园墙系统部署文档 +

+

🏫 Campux-idoknow 校园墙系统

+

基于 Docker + 宝塔的高效部署方案

+

+ CentOS + BT Panel + Docker +

+

-> 基于本次成功部署整理，适配 **宝塔 + Docker**，包含两处核心 BUG 修复，补齐全部部署约束项（HTTPS、Nginx顺序、缓存、构建限制、权限、Git推送细节），可一键复刻部署。 +> 📝 **文档说明** +> 本文档基于实战部署经验整理，涵盖宝塔面板下的 Docker 化部署流程。 +> 包含 **2 个核心 BUG 修复**、**HTTPS 强制规范**及**宝塔 Nginx 配置约束**。 +> 严格按照本文档操作，可实现环境的一键复刻。 --- -## 📑 目录 +## 📋 目录 -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. 获取源码](#1-获取源码) + - [2. 配置环境文件 (.env)](#2-配置环境文件-env) + - [3. 修复前端向导 (BUG-2)](#3-修复前端向导-bug-2) + - [4. Docker 编译与启动](#4-docker-编译与启动) +- [服务配置](#-服务配置) + - [Nginx 反向代理 (关键)](#nginx-反向代理-关键) + - [QQ 机器人 (NapCat)](#qq-机器人-napcat) +- [排错与运维](#-排错与运维) + - [微信缓存问题](#-微信缓存问题) + - [常用运维命令](#-常用运维命令) + - [踩坑清单](#-踩坑清单) --- -## 1. 环境前置要求 +## 🖥️ 环境要求 -### 硬件 -- **CPU**：2 核 -- **内存**：**≥ 4 GB**（低于 4 GB 编译前端会卡死，构建失败；编译阶段内存占用峰值 3.5~3.8 GB） -- **硬盘**：20 GB+（Docker 镜像、PostgreSQL 数据库、MinIO 图片存储会占用大量磁盘） +### 硬件规格（硬性指标） +| 资源 | 最低配置 | 推荐配置 | 备注 | +| :--- | :--- | :--- | :--- | +| **CPU** | 2 核 | 4 核+ | - | +| **内存** | **4 GB** | 8 GB+ | **低于 4GB 前端构建必炸** (峰值 ~3.8GB) | +| **硬盘** | 20 GB | 50 GB+ | Docker/PG/MinIO 非常占空间 | -### 系统 -- **CentOS 7**（推荐，宝塔兼容性最好） -- **Ubuntu 22.04** 亦可兼容 +### 软件环境 +- **系统**：CentOS 7 (首选) / Ubuntu 22.04 +- **面板**：宝塔 Linux 面板 +- **环境**：Docker & Docker Compose -### 端口放行（安全组 + 宝塔防火墙） -- 必须放行端口：`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://`。 +### 网络与安全 +- **端口**：放行 `22`(SSH), `80`, `443`。 +- **备案**：域名必须完成 ICP 备案。 +- **DNS**：A 记录指向服务器公网 IP。 +- **HTTPS**：⚠️ **强制要求**。前端、WSS 机器人、S3 存储均依赖 HTTPS。 --- -## 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 -``` +bash -安装完成后记录面板地址、账号、密码，并放行宝塔 8888 端口。 +1. 安装 Docker (宝塔终端执行) -2.2 宝塔安装 Docker +curl -fsSL https://get.docker.com | sh -1. 软件商店 → 搜索 Docker，一键安装； -2. Docker 会自动附带 docker-compose； -3. 左侧菜单栏出现 Docker 图标代表安装成功。 +2. 启动并设置开机自启 + +systemctl start docker + +systemctl enable docker -⚠️ 禁止使用 Docker 兼容模式，否则会导致构建镜像异常。 --- -3. 下载项目源码 +## 🚀 项目部署 -打开宝塔【终端】执行： +### 1. 获取源码 -```bash -cd /www/wwwroot -git clone https://git.grxiao.cn/yuns/campux-source_Nkeim.git campux-source -cd campux-source -``` +bash + +git clone https://your-repo-url/Campux-idoknow.git + +cd Campux-idoknow + + +### 2. 配置环境文件 (.env) +复制模板并修改关键字段（`DB_PASSWORD`, `JWT_SECRET`, `DOMAIN`）。 +> 💡 **[BUG-1 修复]**：确保 `APP_URL` 使用 `https://`。 + +ini + +.env 示例 + +APP_ENV=production + +APP_URL=https://your-domain.com + +DB_PASSWORD=StrongPasswordHere + +*(详细配置请参考 `.env.example`)* + +### 3. 修复前端向导 (BUG-2) +解决 Platform 校验报错问题： +*文件路径：`resources/js/Pages/Wizard/...`* + +js + +// 修正前 + +if (!platform) throw Error; + +// 修正后 + +if (!platform || platform.length === 0) return; + +> 具体路径请参考文档底部的踩坑清单。 + +### 4. Docker 编译与启动 + +bash + +首次构建（耗时较长，取决于网速和性能） + +docker-compose up -d --build + +查看构建日志（防止内存溢出导致失败） + +docker-compose logs -f builder -⚠️ 项目目录名称必须为 campux-source，docker-compose 配置文件依赖该文件夹名称，改名会导致挂载异常。 --- -4. 配置环境文件 .env +## 🔧 服务配置 -路径：/www/wwwroot/campux-source/.env +### Nginx 反向代理 (关键) +宝塔面板配置时，**顺序极其重要**，否则会导致静态资源 404 或 WebSocket 失效。 -⚠️ BUG-1 修复 +1. 添加站点（域名 + SSL 证书）。 +2. 开启“伪静态”或“反向代理”。 +3. **代理规则**（必须放在最前面）： -原版 CAMPUX_TENANT_DOMAIN_TTL=-1 会让容器无限重启，必须修改为 86400。 +nginx -强制 HTTPS 规则 +location / { -所有域名地址必须以 https:// 开头，绝对不能填写 http://，否则前端接口、S3 图片、WebSocket 全部失效。 +proxy_pass http://127.0.0.1:8000; # 对应容器映射端口 -完整配置示例： +proxy_set_header Host $host; -```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 -``` +proxy_set_header X-Real-IP $remote_addr; -必改项清单： +proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; -· CAMPUX_WEB_ORIGIN → 替换为你的 HTTPS 域名 -· CAMPUX_BOT_SESSION_SECRET → 自定义随机字符串 -· S3_PUBLIC_BASE_URL → 替换为 HTTPS 域名（同网站域名） -· CAMPUX_TENANT_DOMAIN_TTL → 固定改为 86400 -· 全部地址必须使用 https:// 协议 +proxy_set_header X-Forwarded-Proto https; -保存文件后继续。 +# WebSocket 支持 +proxy_http_version 1.1; +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection "upgrade"; ---- - -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; +4. **保存后务必重启 Nginx**。 - 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"; - } +### QQ 机器人 (NapCat) +1. 部署 NapCat 容器。 +2. 配置 WebSocket 反向代理地址为 `wss://your-domain.com/ws/bot`。 +3. 确保 QQ 账号已实名认证，否则无法发送图片。 + +--- + +## 🐛 排错与运维 + +### 🧹 微信缓存问题 +微信内置浏览器缓存极其顽固，修改 CSS/JS 不生效时： +1. 退出公众号会话，重新进入。 +2. 或在链接后添加版本号：`?v=1.0.1`。 +3. 或开启宝塔 Nginx 的“禁止缓存”调试模式。 + +### 📜 常用运维命令 + +bash + +查看运行中的容器 + +docker ps + +查看实时日志（排错神器） + +docker-compose logs -f app + +重启服务 + +docker-compose restart + +清理无用镜像 + +docker system prune -f + + +### 📝 踩坑清单 +1. **内存不足**：构建失败，报错 `Killed`。解决方案：升级内存至 4G+ 或设置 Swap 分区。 +2. **HTTPS 跳转**：宝塔默认 HTTP 转 HTTPS 规则可能与 Docker 冲突，建议关闭宝塔默认跳转，由容器内应用处理。 +3. **权限问题**：`.env` 文件权限应为 `644`，Storage 目录权限应为 `www-data` 可读写。 +4. **Git 推送**：Windows 下编辑的 `.sh` 脚本需在 Linux 执行 `dos2unix *.sh` 转换换行符。 + +--- + +

+ 部署文档整理 by AI Assistant | Last Update: 202X-XX-XX +

+ +✅ 方案二：极简风（适合快速阅读） + +特点：去掉花哨的徽章，专注于排版留白，适合放在内网 Wiki 或简单的仓库中。 + +# Campux-idoknow 校园墙系统部署指南 + +> **适用环境**：宝塔 + Docker +> **核心修正**：修复 2 处致命 BUG，明确 HTTPS 与 Nginx 配置顺序。 + +--- + +## 一、环境准备 + +### 1.1 硬件要求 +* **内存**：≥ 4GB（低于此配置前端构建必死，峰值占用 3.8GB）。 +* **CPU**：2核+ +* **磁盘**：20GB+ SSD + +### 1.2 域名与网络 +* **备案**：必须完成 ICP 备案。 +* **协议**：**强制 HTTPS**（HTTP 模式下机器人及 S3 存储将失效）。 +* **端口**：放行 80, 443, 22。 + +## 二、部署流程 + +### 2.1 获取代码 + +bash + +git clone [仓库地址] + +cd Campux-idoknow + + +### 2.2 环境配置 (.env) +复制 `.env.example` 为 `.env`，修改以下关键项： +* `APP_URL`: 必须以 `https://` 开头。 +* `DB_PASSWORD`: 设置强密码。 + +### 2.3 修复 BUG (重要) +**BUG-2 (前端向导报错)** +找到前端向导校验逻辑，将 `if (!platform) throw Error;` +修改为 `if (!platform || platform.length === 0) return;` + +### 2.4 启动 Docker + +bash + +docker-compose up -d --build + +*注：首次构建时间较长，请耐心等待，切勿中途退出。* + +## 三、宝塔配置 + +### 3.1 Nginx 反向代理（关键顺序） +在站点设置 -> 反向代理中，确保配置如下，**且优先级最高**： + +nginx + +location / { + +proxy_pass http://127.0.0.1:8000; + +proxy_set_header Host $host; + +proxy_set_header X-Forwarded-Proto https; + +# WebSocket 支持 + +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; - } } -``` -7.4 开启强制 HTTPS -在 SSL 页面开启【强制 HTTPS】，然后保存 Nginx 配置。 +### 3.2 微信缓存 +若修改代码后访问无变化，请尝试： +1. 清除宝塔缓存。 +2. 修改 URL 参数（如 `xxx.css?v=2`）。 +3. 重启 Nginx。 -❗ 报错“证书不存在”：代表证书未申请完成，返回上一步先申请 SSL 证书。 -❗ 机器人 WebSocket 连接失败：检查 Nginx 内 Upgrade、Connection 两行配置是否完整。 +## 四、运维命令 + +| 功能 | 命令 | +| :--- | :--- | +| 查看日志 | `docker-compose logs -f` | +| 重启服务 | `docker-compose restart` | +| 停止服务 | `docker-compose down` | --- - -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 仓库内的文档。 - ---- - +*最后更新：2026/06/17* \ No newline at end of file