🏫 Campux-idoknow 校园墙系统

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

📝 文档说明 本文档基于实战部署经验整理，涵盖宝塔面板下的 Docker 化部署流程。 包含 2 个核心 BUG 修复、HTTPS 强制规范及宝塔 Nginx 配置约束。 严格按照本文档操作，可实现环境的一键复刻。

---

📋 目录

• 环境要求
• 服务器初始化
• 项目部署
  • 1. 获取源码
  • 2. 配置环境文件 (.env)
  • 3. 修复前端向导 (BUG-2)
  • 4. Docker 编译与启动
• 服务配置
  • Nginx 反向代理 (关键)
  • QQ 机器人 (NapCat)
• 排错与运维
  • 微信缓存问题
  • 常用运维命令
  • 踩坑清单

---

🖥️ 环境要求

硬件规格（硬性指标）

资源	最低配置	推荐配置	备注
CPU	2 核	4 核+	-
内存	4 GB	8 GB+	低于 4GB 前端构建必炸 (峰值 ~3.8GB)
硬盘	20 GB	50 GB+	Docker/PG/MinIO 非常占空间

软件环境

• 系统：CentOS 7 (首选) / Ubuntu 22.04
• 面板：宝塔 Linux 面板
• 环境：Docker & Docker Compose

网络与安全

• 端口：放行 22(SSH), 80, 443。
• 备案：域名必须完成 ICP 备案。
• DNS：A 记录指向服务器公网 IP。
• HTTPS：⚠️ 强制要求。前端、WSS 机器人、S3 存储均依赖 HTTPS。

---

⚙️ 服务器初始化

bash

1. 安装 Docker (宝塔终端执行)

curl -fsSL https://get.docker.com | sh

2. 启动并设置开机自启

systemctl start docker

systemctl enable docker

---

🚀 项目部署

1. 获取源码

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

---

🔧 服务配置

Nginx 反向代理 (关键)

宝塔面板配置时，顺序极其重要，否则会导致静态资源 404 或 WebSocket 失效。

1. 添加站点（域名 + SSL 证书）。
2. 开启“伪静态”或“反向代理”。
3. 代理规则（必须放在最前面）：

nginx

location / {

proxy_pass http://127.0.0.1:8000; # 对应容器映射端口

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 https;

WebSocket 支持

proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

}

4. 保存后务必重启 Nginx。

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";

}

3.2 微信缓存

若修改代码后访问无变化，请尝试：

1. 清除宝塔缓存。
2. 修改 URL 参数（如 xxx.css?v=2）。
3. 重启 Nginx。

四、运维命令

功能	命令
查看日志	docker-compose logs -f
重启服务	docker-compose restart
停止服务	docker-compose down

---

最后更新：2026/06/17