sanguo/sanguo_vnpy_v2
2
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c033cf6cb5d2aa0b04fb3291a1950f8973c0a7ca
sanguo_vnpy_v2/docs/deployment/env-version-matrix.md
T
claude_dev c66f7cb14e chore(deps): 锁三机统一依赖基线(Python3.10+pandas2.3/numpy2.2新稳定版, requirements-lock.txt) 
依据：
- vnpy 4.4.0 pyproject: numpy>=2.2.3 / pandas>=2.2.3（均无上限，不钉<3）
- pandas 目标=2.3.3（2.x 稳定线顶端，3.0 破坏性变更未回归，按稳定优先不采用）
- numpy 目标=2.2.6（与 TA-Lib 0.6.8 在 NAS 生产容器实证兼容）
- 其余依赖==钉到 NAS 容器已验证可跑版本（fastapi 0.139/uvicorn 0.49/polars 1.42 等）
- Python 3.10 三机统一基线（xtquant 限 3.6-3.12，VPS 锁 3.10）
- 不含 vnpy（源码引用）/ xtquant（VPS Windows only）/ CUDA（torch 传递依赖）
- 矩阵文档新增「锁定决策(2026-07-15)」小节：依据+迁移步骤+验证前置
- 验证前置：落生产前须全套 pytest 0 回归 + 一个 CTA 回测冒烟
2026-07-15 08:12:40 +08:00

217 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 三机环境版本矩阵（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` 引用源码，其声明即天花板）：
```toml
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）：
```bash
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**：
```bash
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` 加上限：
```toml
"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）
Reference in New Issue View Git Blame Copy Permalink