From c66f7cb14ed8728ad3c6dd5dd170c720e32c8763 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Wed, 15 Jul 2026 08:12:40 +0800 Subject: [PATCH] =?UTF-8?q?chore(deps):=20=E9=94=81=E4=B8=89=E6=9C=BA?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E4=BE=9D=E8=B5=96=E5=9F=BA=E7=BA=BF(Python3.?= =?UTF-8?q?10+pandas2.3/numpy2.2=E6=96=B0=E7=A8=B3=E5=AE=9A=E7=89=88,=20re?= =?UTF-8?q?quirements-lock.txt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 依据： - 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 回测冒烟 --- docs/deployment/env-version-matrix.md | 68 +++++++++++++++++ requirements-lock.txt | 104 ++++++++++++++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 requirements-lock.txt diff --git a/docs/deployment/env-version-matrix.md b/docs/deployment/env-version-matrix.md index a7c4231..2c18baf 100644 --- a/docs/deployment/env-version-matrix.md +++ b/docs/deployment/env-version-matrix.md @@ -83,6 +83,74 @@ --- +## 🎯 锁定决策（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 容器（最稳定的生产近邻） diff --git a/requirements-lock.txt b/requirements-lock.txt new file mode 100644 index 0000000..a24192f --- /dev/null +++ b/requirements-lock.txt @@ -0,0 +1,104 @@ +# ============================================================================ +# sanguo_vnpy_v2 三机统一依赖锁文件（Python 3.10 基线） +# ============================================================================ +# 创建：2026-07-15。单一基线，三机（Mac 开发 / NAS 容器 / Windows VPS）共享。 +# +# 目标版本决策依据（详见 docs/deployment/env-version-matrix.md §「锁定决策」）： +# - vnpy 4.4.0 pyproject.toml: numpy>=2.2.3 / pandas>=2.2.3（均无上限，不钉 <3） +# - pandas 目标 = 2.3.3（2.x 稳定线顶端）。pandas 3.0 有大量破坏性变更且未经 +# vnpy 4.4.0 源码回归，按「稳定优先」暂不采用，留作未来验证后再升。 +# - numpy 目标 = 2.2.6（2.2.x 最新稳定，与 TA-Lib 0.6.8 在 NAS 生产容器实证兼容） +# - 其余依赖取 NAS 生产容器「已验证可跑」的版本（pandas 2.3.3 / numpy 2.2.6 那套） +# +# 不含（按设计）： +# - vnpy：源码引用（sys.path.insert），不 pip install，故不入 lock +# - xtquant：VPS/Windows 专属（miniQMT），跨平台不兼容，不入共享 lock +# - CUDA/nvidia-*：torch 的平台相关传递依赖，随 torch 自动解析，不入 lock +# - 纯传递依赖（contourpy/cffi/certifi 等）：由解析器依直接依赖自动钉版 +# +# 验证前置（lockfile 落生产前必须通过）： +# 1. 测试环境按本文件 pip install -r 后跑全套 pytest（0 回归） +# 2. 至少一个 CTA 回测冒烟（确认 vnpy 源码 + TA-Lib + pandas/numpy 协同无回归） +# ============================================================================ + +# ============================================ +# 生产核心（runtime + vnpy 扩展包） +# ============================================ +# 数值/数据栈（关键 major 锁定，禁止擅自跨 major） +numpy==2.2.6 +pandas==2.3.3 +TA-Lib==0.6.8 + +# vnpy 4.4.0 扩展包（vnpy 本体源码引用，不列） +vnpy_ctastrategy==1.4.1 +vnpy_sqlite==1.1.3 + +# vnpy 核心依赖（与 vnpy_v4.4.0/pyproject.toml 对齐，钉到 NAS 实证版本） +pyzmq==27.1.0 +deap==1.4.4 +plotly==6.8.0 +pyqtgraph==0.14.0 +qdarkstyle==3.2.3 +PySide6==6.8.2.1 +tzlocal==5.4.4 +loguru==0.7.3 +tqdm==4.68.3 +nbformat==5.10.4 +requests==2.34.2 +qrcode==8.2 +PyYAML==6.0.3 + +# ============================================ +# 数据层（采集 / 数据平台） +# ============================================ +polars==1.42.1 +pyarrow==24.0.0 +baostock==0.9.3 +# akshare：日线采集走 NAS 宿主 python（不在容器内），此处钉最新稳定； +# 发版频繁，定期 bump。参考：https://pypi.org/project/akshare/ +akshare==1.18.64 +scipy==1.15.3 + +# ============================================ +# Web 服务（sanguo_api / bridge client） +# ============================================ +fastapi==0.139.0 +uvicorn==0.49.0 # 安装用 uvicorn[standard]==0.49.0（含 uvloop/httptools/watchfiles） +starlette==1.3.1 +pydantic==2.13.4 +pydantic-settings==2.14.2 +python-multipart==0.0.32 +PyJWT==2.13.0 +bcrypt==5.0.0 +python-jose==3.5.0 +passlib==1.7.4 +SQLAlchemy==2.0.51 +alembic==1.18.5 +redis==8.0.1 +aioredis==2.0.1 +APScheduler==3.11.3 +httpx==0.28.1 +websockets==16.0 +structlog==26.1.0 +prometheus-client==0.25.0 +python-dotenv==1.2.2 + +# ============================================ +# 测试 / 开发工具 +# ============================================ +pytest==9.1.1 +pytest-asyncio==1.4.0 + +# ============================================ +# 可选：Alpha 量化（重 ML 依赖，按需安装，-headless/CI 可省） +# 安装方式：pip install -r requirements-lock.txt 时含本段； +# 仅生产核心可手动截断本段之后。torch 会拉入平台相关 CUDA 包。 +# ============================================ +scikit-learn==1.7.2 +lightgbm==4.6.0 +torch==2.12.1 +alphalens-reloaded==0.4.6 +empyrical-reloaded==0.5.12 +statsmodels==0.14.6 +matplotlib==3.10.9 +seaborn==0.13.2