# 三机环境版本矩阵（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 差异，影响小。

---

## 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）