# 追光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 跑)
│   └── ... (业务脚本)
├── 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`，出问题能秒切回