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启动).
149 lines
8.4 KiB
Markdown
149 lines
8.4 KiB
Markdown
# 三机环境版本矩阵（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）
|