sanguo_vnpy_v2/docs/deployment/env-version-matrix.md

三机环境版本矩阵（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 静默踩坑

1. 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 差异失败或行为不同。
   • 这是最危险的不一致：单测绿不代表行为一致。

2. numpy major 版本分裂：Mac venv311 = numpy 1.26.4，NAS 容器 = numpy 2.2.6。

   • numpy 2.0 有 breaking change（部分标量类型 Promotion 规则改变、np.float_ 移除等）。
   • 方向与 pandas 相反：Mac 反而比 prod 旧。

3. 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 依赖不完整（已知）

4. venv311 缺核心运行时依赖（本轮未补，按任务约束只做 collect-only + trader 子集）：

   • TA-Lib（需先 brew install ta-lib，C 库依赖）
   • pyzmq / SQLAlchemy / redis / APScheduler / deap / plotly / PySide6
   • akshare（Mac 完全没装，日线采集靠 NAS 宿主 python）
   • vnpy（源码引用，故意不 pip install —— 容器也是源码引用）

5. VPS 信息未本轮 SSH 复核：49.232.102.198:22 Connection closed，本轮失败。文档记录的版本来自 vps-production-runbook.md，标注日期前的核实结果。

🟢 INFO —— 可接受的小差异

6. polars/pandas/pyarrow 小版本 drift（pyarrow 25 vs 24、uvicorn 0.51 vs 0.49）：patch/minor 差异，影响小。

---

🎯 锁定决策（2026-07-15）

产出文件：requirements-lock.txt（项目根，三机共享单一基线）。本节记录决策依据与迁移/验证步骤。

目标版本组合

维度	目标版本	依据
Python	3.10（三机统一基线）	xtquant 限 3.6–3.12；VPS 生产锁 3.10.11；NAS 容器 3.10.20。三机唯一交集
pandas	2.3.3（2.x 稳定线顶端，非 3.0）	见下方「pandas 不升 3.0 的依据」
numpy	2.2.6（2.2.x 最新稳定）	TA-Lib 0.6.8 在 NAS 容器与 numpy 2.2.6 实证兼容；vnpy 要 >=2.2.3
TA-Lib	0.6.8	vnpy 要 >=0.6.4；0.6.8 ≫ 0.4.32（numpy 2.x 兼容门槛），NAS 实证
fastapi / uvicorn	0.139.0 / 0.49.0	NAS 实证版本
polars / pyarrow	1.42.1 / 24.0.0	NAS 实证版本
其余依赖	见 requirements-lock.txt（全部 == 钉到 NAS 实证版本）	「已验证可跑」> 盲目追新

关键证据 1：vnpy 4.4.0 声明的依赖上限（决定性）

读 vnpy_v4.4.0/pyproject.toml（项目靠 sys.path.insert 引用源码，其声明即天花板）：

requires-python = ">=3.10"        # classifiers: 3.10 / 3.11 / 3.12 / 3.13
dependencies = [
    ...
    "numpy>=2.2.3",               # ← 仅下限，无上限（不钉 <3）
    "pandas>=2.2.3",              # ← 仅下限，无上限（不钉 <3）
    "ta-lib>=0.6.4",
    "PySide6==6.8.2.1",           # ← 精确钉死
    ...
]

结论：vnpy 4.4.0 并未声明 pandas<3。 pandas 3.0 在语法上被允许。因此选 2.3.x 是稳定性决策（见下），而非 vnpy 强制天花板。

关键证据 2：TA-Lib 与 numpy 2.x 兼容

• NAS 容器实地核实（docker exec ... python -c）：Python 3.10.20 + pandas 2.3.3 + numpy 2.2.6 + TA-Lib 0.6.8 全部正常 import。
• TA-Lib 0.6.8 远高于支持 numpy 2.x 的 0.4.32 门槛。目标 numpy 2.2.6 与 TA-Lib 不冲突。

pandas 不升 3.0 的依据（与新稳定原则的对应）

• pandas 3.0 有大量破坏性变更（默认 dtype 变、chained assignment / SettingWithCopyWarning 升级为异常等），未经 vnpy 4.4.0 源码回归。
• NAS 生产容器跑 pandas 2.3.3 已验证稳定；「新稳定」≠「盲追 major」，2.3.x 顶端的 2.3.3 本身就是近期版本、不算旧。
• 与 §「不推荐的方向」一致：prod 升 3.0 major 须先在测试库充分回归，本次 lock 默认保守。
• 若未来要升 pandas 3.0：必须先跑全套 pytest + CTA 回测冒烟确认无回归，再改本 lock。

三机迁移步骤

1. Mac 重建 venv310（对齐生产 Python）：

   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 源码引用（sys.path.insert），无需 pip install vnpy
   # akshare 若 Mac 不跑采集可不装
   

   废弃 venv311（pandas 3.0.3 / numpy 1.26.4 的分裂环境）。
2. NAS 容器：当前生产依赖已与 lock 一致（lock 即取自该容器 freeze），按需 pip install -r requirements-lock.txt 校齐；不动 vnpy 源码引用。
3. VPS：pip install -r requirements-lock.txt 装公共基线；xtquant 仍由 miniQMT site-packages 提供（Windows only，不入 lock）。

⚠️ 验证前置条件（lockfile 落生产前必须通过）

• 全套 pytest 0 回归：测试环境按 requirements-lock.txt 全新装一遍后 pytest -q 全绿。
• CTA 回测冒烟：至少跑一个 CTA 策略回测，确认 vnpy 源码 + TA-Lib + pandas 2.3.3 + numpy 2.2.6 协同无回归（收益/指标与基线一致）。
• 任一项失败 → 不得部署到生产；回到本文件修正目标版本后再验。

---

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	当前版本即可	已对齐

落地步骤（建议，不在本任务范围）

1. 生成 lockfile：在 NAS 容器内跑 pip freeze > requirements-lock.txt，作为三机共享 lock 基线。
2. 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（可选，按需）
   

3. 加 requirements 约束：在 pyproject.toml 的 dependencies 加上限：

   "pandas>=2.3,<3",      # 避免 pandas 3.x breaking change
   "numpy>=2.2,<3",
   

4. CI 校验：在 Gitea Actions 加一步 pip check + import 探针，防止 drift 再发生。
5. 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）