307 lines
7.3 KiB
Markdown
307 lines
7.3 KiB
Markdown
<p align="center">
|
||
<h1>🏫 Campux-idoknow 校园墙系统</h1>
|
||
<p><strong>基于 Docker + 宝塔的高效部署方案</strong></p>
|
||
<p>
|
||
<a href="#"><img src="https://img.shields.io/badge/CentOS-7+-262577?style=flat-square" alt="CentOS"></a>
|
||
<a href="#"><img src="https://img.shields.io/badge/BT-Panel-20B2AA?style=flat-square" alt="BT Panel"></a>
|
||
<a href="#"><img src="https://img.shields.io/badge/Docker-Ready-blue?style=flat-square" alt="Docker"></a>
|
||
</p>
|
||
</p>
|
||
|
||
> 📝 **文档说明**
|
||
> 本文档基于实战部署经验整理，涵盖宝塔面板下的 Docker 化部署流程。
|
||
> 包含 **2 个核心 BUG 修复**、**HTTPS 强制规范**及**宝塔 Nginx 配置约束**。
|
||
> 严格按照本文档操作，可实现环境的一键复刻。
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
- [环境要求](#-环境要求)
|
||
- [服务器初始化](#-服务器初始化)
|
||
- [项目部署](#-项目部署)
|
||
- [1. 获取源码](#1-获取源码)
|
||
- [2. 配置环境文件 (.env)](#2-配置环境文件-env)
|
||
- [3. 修复前端向导 (BUG-2)](#3-修复前端向导-bug-2)
|
||
- [4. Docker 编译与启动](#4-docker-编译与启动)
|
||
- [服务配置](#-服务配置)
|
||
- [Nginx 反向代理 (关键)](#nginx-反向代理-关键)
|
||
- [QQ 机器人 (NapCat)](#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://git.grxiao.cn/yuns/campux-source_Nkeim.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` 转换换行符。
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<sub>部署文档整理 by AI Assistant | Last Update: 202X-XX-XX</sub>
|
||
</p>
|
||
|
||
✅ 方案二：极简风（适合快速阅读）
|
||
|
||
特点：去掉花哨的徽章，专注于排版留白，适合放在内网 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* |