sanguo_vnpy/docs/04-deployment.md

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镜像

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

3.2 启动容器

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 验证部署

# 健康检查
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目录，直接修改文件：

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

修改后重启容器生效：

docker restart sanguo_vnpy

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

# 本地推送
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 常用命令

# 查看容器状态
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