claude_dev
54f9ab4c4f
vps-production-runbook(VPS运维一站式,已验证状态+拓扑+发布流水线+人类闸口+排障); env-version-matrix(三机Python/deps矩阵+Lock建议); scripts/ops(NAS bridge探针-容器无curl-+VPS→NAS备份脚本); nas-deploy-plan§3(修rsync --exclude语法,原会删万级staging parquet+破坏entrypoint启动).
8.4 KiB
8.4 KiB
三机环境版本矩阵（Mac 开发 / NAS 容器 / Windows VPS）
创建：2026-07-14。目的：记录三机 Python + 关键依赖版本现状，暴露不一致，给出 Lock 建议。 数据来源：Mac venv311 + NAS 容器均经实地
pip list核实；VPS 基于部署文档vps-production-runbook.md，未本轮直接 SSH 复核（SSH 不通）。
1. 机器角色一览
| 机器 | 角色 | Python | 虚拟环境 / 路径 | 数据来源 |
|---|---|---|---|---|
| Mac Mini | 开发 + 测试 | 3.11.15（venv311） | ./venv311/（项目内） |
实地 pip list |
| Mac 系统 Python | 不参与项目 | 3.14.6（homebrew）/ 3.9.6（/usr/bin） | — | python3 --version |
NAS 容器 sanguo_vnpy_v2 |
测试 + 回测 + 采集（生产近邻） | 3.10.20 | /app（容器内）= NAS /volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2 |
实地 docker exec ... pip list |
Windows VPS 49.232.102.198 |
生产（miniQMT + bridge） | 3.10.11 | C:\Python310\python.exe |
部署文档（本轮未直连） |
2. 关键依赖版本矩阵
版本号 =
pip show的 Version 字段；❌ = 未安装；🚫 = 平台不兼容（Windows only）；🔍 = 仅有源码引用（sys.path.insert）未 pip install。
| 依赖 | Mac venv311 (3.11.15) | NAS 容器 (3.10.20) | Windows VPS (3.10.11) | 备注 |
|---|---|---|---|---|
| python | 3.11.15 | 3.10.20 | 3.10.11 | ⚠️ Mac 比 prod 高一个小版本 |
| vnpy | 🔍 源码引用（vnpy_v4.4.0/） |
🔍 源码引用（/app/vnpy_v4.4.0）+ vnpy 4.4.0 pip metadata |
❌ 不装（VPS 只跑 bridge） | Mac 容器均靠 sys.path.insert 引用源码，不 pip install vnpy |
| vnpy_ctastrategy | ❌ | 1.4.1 | ❌ | |
| vnpy_sqlite | ❌ | 1.1.3 | ❌ | |
| fastapi | 0.139.0（本次新装） | 0.139.0 | ✅ 装了（文档未给版本） | 一致 |
| uvicorn | 0.51.0（本次新装） | 0.49.0 | ✅ 装了 | 小版本差 |
| akshare | ❌ | ❌ | ❌ | 三机都没装；日线采集走 NAS 宿主系统 python（akshare 在 NAS 宿主，不在容器里） |
| baostock | 0.9.3 | 0.9.3 | ❌ | Mac/NAS 一致 |
| polars | 1.42.1（本次新装） | 1.42.1 | ❌ | Mac/NAS 一致；Mac 此前缺失致 collect-only 失败 |
| xtquant | 🚫 Windows only | 🚫 Windows only | ✅（miniQMT site-packages） | VPS 专属，靠 miniQMT 客户端 |
| pandas | 3.0.3 | 2.3.3 | ? | 🔴 major 版本分裂（Mac=3.x / NAS=2.x） |
| numpy | 1.26.4 | 2.2.6 | ? | 🔴 major 版本分裂（Mac=1.x / NAS=2.x） |
| pyarrow | 25.0.0 | 24.0.0 | ❌ | 小版本差 |
| PyJWT | 2.13.0（本次新装） | 2.13.0 | ❌ | 一致 |
| bcrypt | 5.0.0（本次新装） | 5.0.0 | ❌ | 一致 |
| TA-Lib | ❌ | 0.6.8 | ❌ | Mac 缺（需 brew install ta-lib） |
| pyzmq | ❌ | 27.1.0 | ❌ | Mac 缺 |
| PySide6 | ❌ | 6.8.2.1 | ❌ | Mac 缺（GUI 依赖，dev 可选） |
| SQLAlchemy | ❌ | 2.0.51 | ❌ | Mac 缺 |
| redis | ❌ | 8.0.1 | ❌ | Mac 缺 |
| APScheduler | ❌ | 3.11.3 | ❌ | Mac 缺 |
| deap | ❌ | 1.4.4 | ❌ | Mac 缺（遗传算法，回测用） |
| plotly | ❌ | 6.8.0 | ❌ | Mac 缺 |
| scipy | 1.17.1 | 未列（应已装） | ❌ | Mac 有 |
| pytest | 9.1.1 | 未列 | ❌ | dev 工具 |
3. 当前发现的不一致（按严重度）
🔴 CRITICAL —— 可能在 Mac 跑通但在 prod 静默踩坑
-
pandas major 版本分裂：Mac venv311 = pandas 3.0.3，NAS 容器 = pandas 2.3.3。
- pandas 3.0 有大量破坏性变更（默认 dtype、
chained assignment、SettingWithCopyWarning升级为异常等）。 - 在 Mac 过的测试，到 NAS 容器可能因为 pandas 3→2 的 API 差异失败或行为不同。
- 这是最危险的不一致：单测绿不代表行为一致。
- pandas 3.0 有大量破坏性变更（默认 dtype、
-
numpy major 版本分裂：Mac venv311 = numpy 1.26.4，NAS 容器 = numpy 2.2.6。
- numpy 2.0 有 breaking change（部分标量类型 Promotion 规则改变、
np.float_移除等）。 - 方向与 pandas 相反：Mac 反而比 prod 旧。
- numpy 2.0 有 breaking change（部分标量类型 Promotion 规则改变、
-
Python minor 分裂：Mac venv311 = 3.11.15，NAS/VPS = 3.10.x。
- 影响有限但存在（如
match语法、tomllib、ExceptionGroup、类型 Hint 差异）。 pyproject.toml已声明requires-python = ">=3.10"，理论上 3.11 合法，但偏离 prod。
- 影响有限但存在（如
🟡 WARNING —— Mac venv311 依赖不完整（已知）
-
venv311 缺核心运行时依赖（本轮未补，按任务约束只做 collect-only + trader 子集）：
TA-Lib（需先brew install ta-lib，C 库依赖）pyzmq/SQLAlchemy/redis/APScheduler/deap/plotly/PySide6akshare（Mac 完全没装，日线采集靠 NAS 宿主 python）vnpy（源码引用，故意不 pip install —— 容器也是源码引用）
-
VPS 信息未本轮 SSH 复核：49.232.102.198:22 Connection closed，本轮失败。文档记录的版本来自
vps-production-runbook.md，标注日期前的核实结果。
🟢 INFO —— 可接受的小差异
- polars/pandas/pyarrow 小版本 drift（pyarrow 25 vs 24、uvicorn 0.51 vs 0.49）：patch/minor 差异，影响小。
4. Lock 建议（推荐方案，不执行）
推荐基线：对齐 NAS 容器（最稳定的生产近邻）
理由：NAS 容器是当前依赖最齐、跑得最稳的环境；VPS 只跑 bridge 子集，依赖面窄；Mac 是开发机，应模拟 prod 而不是超前。Python 3.10 是三机唯一交集。
| 维度 | 推荐基线（= NAS 当前） | 落地动作（Mac 侧） |
|---|---|---|
| Python | 3.10.x（容器 3.10.20 / VPS 3.10.11） | 重建 venv：python3.10 -m venv venv310（用 homebrew python@3.10），废弃 venv311 |
| pandas | 2.3.x（NAS 2.3.3） | pip install 'pandas>=2.3,<3'（锁 <3） |
| numpy | 2.2.x（NAS 2.2.6） | pip install 'numpy>=2.2,<3' |
| polars | 1.42.x | 已对齐 |
| pyarrow | 24.x | pip install 'pyarrow>=24,<25' |
| fastapi / uvicorn / PyJWT / bcrypt | 当前版本即可 | 已对齐 |
落地步骤（建议，不在本任务范围）
- 生成 lockfile：在 NAS 容器内跑
pip freeze > requirements-lock.txt，作为三机共享 lock 基线。 - Mac 重建 venv310：
brew install python@3.10 /opt/homebrew/bin/python3.10 -m venv venv310 ./venv310/bin/pip install -r requirements-lock.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 不含 vnpy（源码引用）/ PySide6（可选 GUI）/ xtquant（Windows only）/ akshare（可选，按需） - 加 requirements 约束：在
pyproject.toml的dependencies加上限："pandas>=2.3,<3", # 避免 pandas 3.x breaking change "numpy>=2.2,<3", - CI 校验：在 Gitea Actions 加一步
pip check+ import 探针，防止 drift 再发生。 - VPS 不动：VPS 只跑
sanguo_qmt_bridge（依赖面 = fastapi + uvicorn + xtquant），与主项目 lock 解耦。
不推荐的方向
- ❌ 把 prod 升到 pandas 3 / numpy 2 / Python 3.11 来"追平" Mac：prod 是稳定优先，3.0 新 major 须先在测试库充分回归。
- ❌ 在 Mac venv311 补装 vnpy：vnpy 源码引用是项目既定设计（容器也是源码引用），pip install 会引入版本冲突。
5. 本轮修复记录（2026-07-14）
为让 pytest --collect-only 0 错误通过，在 venv311 内新装：
| 包 | 版本 | 原因 |
|---|---|---|
| polars + polars-runtime-32 | 1.42.1 | tests/factor/test_data_adapter.py collect 失败；polars 是 pyproject.toml [alpha] 真实依赖 |
| fastapi | 0.139.0 | tests/api/* collect 失败（No module named 'fastapi'） |
| uvicorn[standard] | 0.51.0 | fastapi.testclient 间接需要 |
| PyJWT | 2.13.0 | sanguo_api/auth.py import jwt |
| bcrypt | 5.0.0 | sanguo_api/auth.py import bcrypt |
结果：pytest --collect-only -q 从 380 collected + 1 error → 384 collected, 0 errors。
pytest tests/trader/ tests/data_platform/ → 228 passed, 0 failed。
6. 待办（跟踪项）
- VPS SSH 复核（本轮 22 端口 Connection closed，下一轮巡检补实测版本）
- pandas 3.x 锁上限决策（见 §4 步骤 3）
- venv310 重建计划排期
- requirements-lock.txt 生成（从 NAS 容器 freeze）