247 lines
8.3 KiB
Markdown
247 lines
8.3 KiB
Markdown
# 追光AI 容器化部署文档
|
||
|
||
> 创建时间：2026-06-11
|
||
> 适用版本：V2.1.2+
|
||
|
||
## 一、为什么容器化
|
||
|
||
服务器 119.45.242.239 上有 3+ 邻居项目（zhuiguang-quant / zhenfang / snowy-fgt / agent-system）+ 3 个共享 Docker 服务（redis-cache / nacos / minio）。
|
||
本项目 (zhuiguang-ai) 改用容器化部署的好处：
|
||
|
||
1. **环境隔离**：本项目 Node 依赖与邻居项目（Java/Python）零冲突
|
||
2. **可移植**：换服务器 1 行命令起服务
|
||
3. **可复现**：Dockerfile 锁 Node 版本、依赖版本
|
||
4. **资源上限**：内存/CPU 可设限，不拖累邻居项目
|
||
|
||
## 二、架构
|
||
|
||
```
|
||
┌─────────── Host (Ubuntu 22.04) ───────────┐
|
||
│ │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ zhuiguang-ai-app (Docker) │ │
|
||
│ │ - Next.js 14 (port 8301) │ │
|
||
│ │ - network_mode: host │ │
|
||
│ │ - 共享卷: data / public / logs │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ http://localhost:8301 │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ zhuiguang-ai-cron (Docker) │ │
|
||
│ │ - supercronic v0.2.33 │ │
|
||
│ │ - 13 个 cron 任务 │ │
|
||
│ │ - 共享卷: data / public / logs │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 共享服务 (邻居项目共用) ─┐ │
|
||
│ │ redis-cache: 6379 │ │
|
||
│ │ nacos: 8848/9848 │ │
|
||
│ │ minio: 9000/9001 │ │
|
||
│ └────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 外部服务 ─┐ │
|
||
│ │ 阿里云 RDS MySQL │ │
|
||
│ │ DeepSeek / 各 AI/新闻 API │ │
|
||
│ └────────────┘ │
|
||
│ │
|
||
│ ┌─ nginx 反代 ─┐ │
|
||
│ │ 80/443 → 8301│ │
|
||
│ └────────────┘ │
|
||
└────────────────────────────────────────────┘
|
||
```
|
||
|
||
**网络模式 `host` 的原因**：
|
||
|
||
需要访问宿主机上的 Redis/Nacos/MinIO 共享服务。`bridge` 网络要么把 host 的容器端口暴露给 bridge 网络（修改共享服务配置），要么用 `extra_hosts: host.docker.internal`（仅 Docker Desktop 支持，Linux server 需装 xinetd 替代）。
|
||
`host` 模式最简单，端口已锁定 8301-8310 不冲突。
|
||
|
||
## 三、目录结构
|
||
|
||
```
|
||
/home/ubuntu/zhuiguang-ai/
|
||
├── Dockerfile # 多阶段构建
|
||
├── docker-compose.yml # 2 个服务编排
|
||
├── .dockerignore # 构建排除
|
||
├── crontab.txt # supercronic 调度表
|
||
├── env/
|
||
│ └── .env.production # 生产环境变量 (DATABASE_URL / API_KEY)
|
||
├── scripts/
|
||
│ ├── entrypoint-app.sh # APP 启动入口
|
||
│ ├── entrypoint-cron.sh # CRON 启动入口
|
||
│ ├── backup-volumes.sh # 卷备份 (host 跑)
|
||
│ ├── install-cron-backup.sh # 备份 cron 安装 (host 跑)
|
||
│ ├── install-cron.sh # 旧 host cron 安装 (停用)
|
||
│ └── ... (业务脚本)
|
||
├── public/ # 静态资源 (volume)
|
||
├── data/ # bot-characters.json (volume)
|
||
├── logs/ # 运行日志 (volume)
|
||
└── ... (源码)
|
||
|
||
Docker 卷 (命名卷):
|
||
zhuiguang_ai_bot_data → /app/data
|
||
zhuiguang_ai_bot_public → /app/public
|
||
zhuiguang_ai_bot_logs → /app/logs
|
||
zhuiguang_ai_bot_prisma → /app/node_modules/.prisma
|
||
```
|
||
|
||
## 四、部署步骤
|
||
|
||
### 1. 准备 .env
|
||
|
||
```bash
|
||
cd /home/ubuntu/zhuiguang-ai
|
||
mkdir -p env
|
||
cp .env env/.env.production
|
||
chmod 600 env/.env.production
|
||
# 编辑 env/.env.production 填入生产 DATABASE_URL / API_KEY
|
||
```
|
||
|
||
### 2. 构建镜像
|
||
|
||
```bash
|
||
cd /home/ubuntu/zhuiguang-ai
|
||
docker compose build
|
||
# 首次 5-10 分钟，之后改 code 1-3 分钟
|
||
```
|
||
|
||
### 3. 启动
|
||
|
||
```bash
|
||
docker compose up -d
|
||
# 等 30s，让 prisma migrate deploy 跑完
|
||
docker compose ps
|
||
docker compose logs -f --tail 50 zhuiguang-ai-app
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
```bash
|
||
# 1) APP 探活
|
||
curl -I http://localhost:8301/api/health
|
||
|
||
# 2) CRON 探活
|
||
docker exec zhuiguang-ai-cron pgrep -f supercronic
|
||
docker exec zhuiguang-ai-cron supercronic-linux-amd64 -version
|
||
|
||
# 3) 触发 1 个 cron 任务手动跑
|
||
docker exec zhuiguang-ai-cron bash -c "set -a; . /app/.env; set +a; node /app/scripts/task1-discover-tools.mjs"
|
||
|
||
# 4) 看实时日志
|
||
docker compose logs -f zhuiguang-ai-cron
|
||
```
|
||
|
||
### 5. 安装 host 备份 cron
|
||
|
||
```bash
|
||
bash scripts/install-cron-backup.sh
|
||
# 安装：每天 03:30 备份 4 个卷到 /home/ubuntu/zhuiguang-ai-backup/dockers/
|
||
```
|
||
|
||
### 6. 旧 PM2 清理（验证通过后）
|
||
|
||
```bash
|
||
# 1) 停 PM2
|
||
pm2 stop zhuiguang-ai
|
||
# 2) 验证容器无问题 24h+ 后
|
||
pm2 delete zhuiguang-ai
|
||
pm2 save
|
||
|
||
# 3) 旧 host cron 清理（容器接管后失效）
|
||
crontab -l | grep -vE 'zhuiguang-ai|bot-activity' > /tmp/cron.new
|
||
crontab /tmp/cron.new
|
||
|
||
# 4) 旧代码归档（保留 7 天可回滚）
|
||
cd /home/ubuntu
|
||
mv zhuiguang-ai zhuiguang-ai-old-$(date +%Y%m%d)
|
||
# 把 git 仓库拉回来（容器卷只是数据，源码在 git）
|
||
git clone <repo-url> zhuiguang-ai
|
||
```
|
||
|
||
## 五、运维命令速查
|
||
|
||
```bash
|
||
# 查看服务
|
||
docker compose ps
|
||
docker compose logs -f zhuiguang-ai-app
|
||
docker compose logs -f zhuiguang-ai-cron
|
||
|
||
# 资源占用
|
||
docker stats zhuiguang-ai-app zhuiguang-ai-cron
|
||
|
||
# 进入容器
|
||
docker exec -it zhuiguang-ai-app sh
|
||
docker exec -it zhuiguang-ai-cron sh
|
||
|
||
# 手动跑一个脚本
|
||
docker exec zhuiguang-ai-cron bash -c "set -a; . /app/.env; set +a; node /app/scripts/bot-activity.mjs"
|
||
|
||
# 重启单个服务
|
||
docker compose restart zhuiguang-ai-app
|
||
|
||
# 重建镜像 + 重启
|
||
docker compose build --no-cache zhuiguang-ai-app
|
||
docker compose up -d zhuiguang-ai-app
|
||
|
||
# 备份
|
||
bash /home/ubuntu/zhuiguang-ai/scripts/backup-volumes.sh
|
||
|
||
# 回滚到 PM2
|
||
pm2 start zhuiguang-ai # 前提：旧代码还在 /home/ubuntu/zhuiguang-ai-old-*/
|
||
```
|
||
|
||
## 六、回滚方案
|
||
|
||
任何步骤出问题，立即回滚：
|
||
|
||
```bash
|
||
# 1) 停容器
|
||
cd /home/ubuntu/zhuiguang-ai
|
||
docker compose down
|
||
|
||
# 2) 切回旧代码
|
||
cd /home/ubuntu
|
||
mv zhuiguang-ai zhuiguang-ai-failed-$(date +%Y%m%d)
|
||
mv zhuiguang-ai-old-YYYYMMDD zhuiguang-ai
|
||
|
||
# 3) 启动 PM2
|
||
cd /home/ubuntu/zhuiguang-ai
|
||
pm2 start zhuiguang-ai
|
||
|
||
# 4) 确认线上恢复
|
||
curl -I http://localhost:8301/api/health
|
||
```
|
||
|
||
## 七、升级流程
|
||
|
||
```bash
|
||
# 1) 拉新代码
|
||
cd /home/ubuntu/zhuiguang-ai
|
||
git pull
|
||
|
||
# 2) 如改了 schema 需先备份
|
||
bash scripts/backup-volumes.sh
|
||
|
||
# 3) 重新构建
|
||
docker compose build
|
||
|
||
# 4) 滚动重启（先 cron 再 app 减少任务失败）
|
||
docker compose up -d
|
||
# 或分步
|
||
docker compose up -d zhuiguang-ai-cron
|
||
docker compose up -d zhuiguang-ai-app
|
||
|
||
# 5) 验证
|
||
curl -I http://localhost:8301/api/health
|
||
docker compose logs --tail 30 zhuiguang-ai-app
|
||
```
|
||
|
||
## 八、注意事项（项目铁律）
|
||
|
||
1. **端口锁定 8301-8310**：本项目所有端口只能在这区间，容器也必须遵守
|
||
2. **不动共享服务**：Redis/Nacos/MinIO 在宿主机 Docker，**绝不重启**
|
||
3. **不动邻居项目目录**：`/home/ubuntu/{zhuiguang-quant,zhenfang,snowy-fgt,agent-system}` 只读
|
||
4. **不动全局 crontab**：用 `crontab -e` 追加，不要 `crontab -r`
|
||
5. **不动 nginx**：容器绑定 8301，nginx 反代规则不动
|
||
6. **保留 PM2 镜像**：验证通过 24h 前不要 `pm2 delete`，出问题能秒切回
|