From 1803610f231ea9a686c82ef14c426459621c19ff Mon Sep 17 00:00:00 2001 From: claude_dev Date: Sat, 4 Jul 2026 20:13:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20NAS=20Docker=20?= =?UTF-8?q?=E8=BF=AD=E4=BB=A3=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 docs/deployment/nas-deploy-plan.md，固化应用层/镜像层分离的部署流程（rsync + docker restart）。CLAUDE.md 参考文档段加入索引。 --- .claude/CLAUDE.md | 1 + docs/deployment/README.md | 32 +++++++- docs/deployment/nas-deploy-plan.md | 125 +++++++++++++++++++++++++++++ docs/deployment/synology-nas.md | 12 ++- 4 files changed, 167 insertions(+), 3 deletions(-) create mode 100644 docs/deployment/nas-deploy-plan.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 2deb8d6..d91ce23 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -126,3 +126,4 @@ Linus 三问过滤 - 项目参考：`sanguo_moziplus_v3` 设计文档 - Gitea 配置：`.claude/gitea-config.json` - 工作流脚本：`.claude/workflows/` +- NAS 部署 vnpy：`docs/deployment/nas-deploy-plan.md` diff --git a/docs/deployment/README.md b/docs/deployment/README.md index f1e0339..0fb8f38 100644 --- a/docs/deployment/README.md +++ b/docs/deployment/README.md @@ -119,4 +119,34 @@ tar xzf vnpy_backup_YYYYMMDD.tar.gz -C / --- -**最后更新**: 2026-07-01 +## 部署历史 + +### Phase 1 后端部署 (2026-07-04) + +**部署内容：** +- ✅ 修复 VeighNa 模块加载问题 +- ✅ 修复循环导入问题 +- ✅ 成交监控 API (4 个端点) +- ✅ 资金监控 API (3 个端点) +- ✅ 全局配置 API (2 个端点) + +**部署文件：** +- `sanguo_web/api/__init__.py` - 注册新路由 +- `sanguo_web/api/deps.py` - 修复循环导入 +- `sanguo_web/services/main_service.py` - 添加 offset 和 gateway_name 字段 +- `sanguo_web/api/routes/trades.py` - 成交监控路由 +- `sanguo_web/api/routes/accounts.py` - 资金监控路由 +- `sanguo_web/api/routes/settings.py` - 全局配置路由 +- `run_web.py` - 添加 vnpy_v4.4.0 路径 + +**备份位置：** `~/.sanguo_projects/sanguo_vnpy_v2/backup_20260704_170319/` + +**验证结果：** +- 总路由数：52 +- Trades 路由：4 个 +- Accounts 路由：3 个 +- Settings 路由：2 个 + +--- + +**最后更新**: 2026-07-04 diff --git a/docs/deployment/nas-deploy-plan.md b/docs/deployment/nas-deploy-plan.md new file mode 100644 index 0000000..c4198ba --- /dev/null +++ b/docs/deployment/nas-deploy-plan.md @@ -0,0 +1,125 @@ +# 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`。 diff --git a/docs/deployment/synology-nas.md b/docs/deployment/synology-nas.md index c6de8b0..8793caa 100644 --- a/docs/deployment/synology-nas.md +++ b/docs/deployment/synology-nas.md @@ -299,9 +299,17 @@ http://your-nas-ip:8000 ### 默认登录凭据 - **用户名**: `admin` -- **密码**: `admin123` +- **密码**: 通过环境变量 `ADMIN_PASSWORD` 配置 -**重要**: 首次登录后请立即修改密码！ +**配置方式**：在 `.env` 文件中设置： +```env +ADMIN_PASSWORD=your-secure-password +``` + +**安全提示**： +- 生产环境请使用强密码 +- 不要在代码中硬编码密码 +- 建议使用密钥管理服务存储敏感信息 ### WebSocket 连接