# Sanguo VeighNa — NAS Docker 迭代部署方案

> 维护人：诸葛亮 · 最后更新：2026-07-04
> 基于实机查证（Synology NAS `cfeasynas` 216+II）
> 首次安装见 [`synology-nas.md`](./synology-nas.md)，本文只讲**日常迭代与运维**。

---

## 一、核心思路：应用层与镜像层分离

代码不打进镜像运行时，而是 bind-mount 挂进容器。**绝大多数迭代不需要重新 build 镜像。**

| 层次 | 内容 | 变更频率 | 变更方式 |
|------|------|----------|----------|
| **镜像层** `sanguo_vnpy_v2:latest` (6.9GB) | Python 3.10 + pip 依赖 + TA-Lib + entrypoint.sh | 低 | `docker build` |
| **应用层** bind-mount → `/app` | 项目源码（sanguo_web、vnpy_v4.4.0…） | 高 | rsync + `docker restart` |
| **数据层** `/app/data` | SQLite、日志（持久化） | — | 不要覆盖 |

> 容器启动时 `/app` 被宿主机目录整体覆盖，镜像内 `COPY` 的代码运行时不生效。**改代码 = 改宿主机目录 + 重启容器。**

---

## 二、当前部署实况（已查证）

| 项目 | 值 |
|------|-----|
| NAS | `cfeasynas` 192.168.2.154 |
| SSH | `admin@192.168.2.154` |
| Docker 路径 | `/var/packages/Docker/target/usr/bin/docker`（**不在 PATH**） |
| 权限 | admin 在 `docker` 组，**无需 sudo** |
| 容器/镜像 | `sanguo_vnpy_v2` / `sanguo_vnpy_v2:latest` |
| 端口 | `8000→8000`、`8080→8080` |
| 代码挂载 | `/volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2` → `/app` |
| 启动 | `/app/entrypoint.sh` → `uvicorn ... --workers 2` |
| 重启策略 | `unless-stopped` |
| 启动方式 | `docker run`（非 compose） |

---

## 三、常规迭代（只改代码）— 90% 场景

```bash
# 在 Mac Mini 执行
export SSHPASS='Ccf7561523'
DOCKER="/var/packages/Docker/target/usr/bin/docker"
SRC=~/.openclaw/sanguo_projects/sanguo_vnpy_v2/
DEST=admin@192.168.2.154:~/.sanguo_projects/sanguo_vnpy_v2/

# 1) 同步代码（已排除数据/缓存）
sshpass -e rsync -avz --delete \
  --exclude='.git' '__pycache__' '*.pyc' '.pytest_cache' \
  --exclude='data/' 'logs/' 'temp/' '*.log' '.DS_Store' '.venv/' 'node_modules/' \
  -e "ssh -o StrictHostKeyChecking=no" \
  "$SRC" "$DEST"

# 2) 重启容器
sshpass -e ssh admin@192.168.2.154 "$DOCKER restart sanguo_vnpy_v2"

# 3) 看日志 + 冒烟
sleep 8
sshpass -e ssh admin@192.168.2.154 "$DOCKER logs --tail 20 sanguo_vnpy_v2"
curl -s http://192.168.2.154:8000/health
curl -s http://192.168.2.154:8000/api/v1/settings/global
```

| 验证项 | 期望 |
|--------|------|
| `docker ps` | `Up` |
| `/health` | `{"status":...}` |
| `/api/v1/trades` | `[]` 或数据 |
| `POST /api/v1/auth/login` | 返回 `access_token` |

---

## 四、依赖变更（改 requirements-docker.txt）— 偶尔

```bash
# 1) 先同步代码（含新 requirements）到 NAS，同第三节步骤 1
# 2) 在 NAS 重新 build
sshpass -e ssh admin@192.168.2.154 \
  "cd ~/.sanguo_projects/sanguo_vnpy_v2 && \
   /var/packages/Docker/target/usr/bin/docker build -f docker/Dockerfile -t sanguo_vnpy_v2:latest ."

# 3) 用相同参数重启容器
sshpass -e ssh admin@192.168.2.154 << 'EOF'
D=/var/packages/Docker/target/usr/bin/docker
$D stop sanguo_vnpy_v2 && $D rm sanguo_vnpy_v2
$D run -d --name sanguo_vnpy_v2 --restart unless-stopped \
  -p 8000:8000 -p 8080:8080 \
  -v /volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2:/app \
  sanguo_vnpy_v2:latest
EOF
```

> ⚠️ NAS CPU 弱，build 编 TA-Lib + 大包约 30–60 分钟。

---

## 五、外网链路（部署时不要动）

```
外网 https://vnpy.mysanguo.top
  → VPS Caddy :18000 → frps → Mac Mini frpc :8001
  → socat → 192.168.2.154:8000 → NAS 容器
```

**部署应用只动 NAS 容器，绝不碰 frpc / socat / Caddy。** 详见 `~/.openclaw/workspace/docs/vps-deployment-guide.md`。

---

## 六、已知问题

| 问题 | 影响 | 处理 |
|------|------|------|
| `threads can only be started once` | VeighNa 引擎在 2 workers 下重复初始化 | Web/登录/查询正常；真实交易需改 1 worker |
| `/health` 返回 `degraded` | 引擎未初始化的降级 | 非致命 |
| Docker 不在 PATH | — | 一律用全路径 |
| admin 密码硬编码 | 安全 | 后续改 SSH key |

---

## 七、回滚

代码层（镜像未动）：`git checkout <旧commit>` 后重跑第三节步骤 1-2。
镜像层：`docker images sanguo_vnpy_v2` 找旧 tag，重 `docker run`。