# 04 - 部署指南

**版本**: v1.0
**日期**: 2026-04-29

---

## 1. 环境要求

| 项目 | 要求 |
|------|------|
| NAS | 群晖DS220+（或同等级），ARM64/AMD64 |
| Docker | 群晖套件 Docker 20.x+ |
| 内存 | ≥4GB（推荐8GB） |
| 存储 | ≥50GB可用空间 |
| 网络 | 局域网可达 |

## 2. 部署架构

```
Mac Mini（开发机）                    群晖 NAS（生产环境）
192.168.2.153                        192.168.2.154
┌──────────────┐                    ┌──────────────────────┐
│ sanguo_vnpy   │ ── git push ──→   │ gitee.com             │
│ 本地仓库      │                    │ sanguo_vnpy 远程仓库   │
│               │                    │         │              │
│ 代码修改      │ ── SMB挂载 ──→    │ /volume1/stock/       │
│               │                    │ sanguo_vnpy/          │
└──────────────┘                    │         │              │
                                    │    Docker容器          │
                                    │    sanguo_vnpy         │
                                    │    ├─ 8088 回测API     │
                                    │    ├─ 8888 Jupyter     │
                                    │    └─ 2222 SSH        │
                                    └──────────────────────┘
```

## 3. 首次部署

### 3.1 构建Docker镜像

```bash
# 在NAS上执行
cd /volume1/stock/sanguo_vnpy
docker build -t sanguo_vnpy:with-scripts -f docker/Dockerfile .
```

### 3.2 启动容器

```bash
docker run -d --name sanguo_vnpy \
  --restart unless-stopped \
  -p 8888:8888 -p 8088:8088 -p 8000:8000 -p 2222:22 \
  -v /volume1/stock/sanguo_vnpy/bt-service:/app/scripts/backtest_service:ro \
  -v /volume1/stock/sanguo_vnpy/entrypoint.sh:/app/entrypoint.sh:ro \
  sanguo_vnpy:with-scripts
```

### 3.3 验证部署

```bash
# 健康检查
curl http://192.168.2.154:8088/api/backtest/health

# 预期返回
{"code":0,"msg":"ok","data":{"pending_count":0,...}}
```

## 4. 代码更新

### 4.1 方式一：SMB挂载直接修改（当前方式）

Mac Mini通过SMB挂载NAS目录，直接修改文件：

```bash
# NAS挂载点
/Volumes/stock/sanguo_vnpy/
├── bt-service/          → 容器内 /app/scripts/backtest_service
└── entrypoint.sh        → 容器内 /app/entrypoint.sh
```

修改后重启容器生效：
```bash
docker restart sanguo_vnpy
```

### 4.2 方式二：Git同步（推荐长期方案）

```bash
# 本地推送
cd sanguo_vnpy && git push origin main

# NAS拉取
ssh admin@192.168.2.154
cd /volume1/stock/sanguo_vnpy && git pull
docker restart sanguo_vnpy
```

## 5. 服务端口

| 服务 | 容器端口 | NAS端口 | 用途 |
|------|---------|---------|------|
| Jupyter Lab | 8888 | 8888 | 开发环境 |
| 回测API | 8088 | 8088 | 回测任务接口 |
| WebTrader | 8000 | 8000 | Web交易（预留） |
| SSH | 22 | 2222 | 运维通道 |

## 6. 运维操作

### 6.1 常用命令

```bash
# 查看容器状态
docker ps | grep sanguo_vnpy

# 查看容器日志
docker logs sanguo_vnpy --tail 50

# 重启容器
docker restart sanguo_vnpy

# 进入容器
docker exec -it sanguo_vnpy bash
```

### 6.2 故障排查

| 症状 | 检查项 | 解决方案 |
|------|--------|---------|
| API无响应 | `curl :8088/api/backtest/health` | `docker restart sanguo_vnpy` |
| 策略执行失败 | 查看容器日志 | 检查策略代码是否含CtaTemplate子类 |
| pip包丢失 | 容器重启后 | entrypoint.sh已添加自动安装 |
| 数据加载失败 | 检查akshare连接 | 确认网络可达 |

---

*下一步：[05-user-manual.md](05-user-manual.md)*