Yokon 笔记教程与实操笔记
← 返回首页

OpenTrading 部署教程

2026-10-15 · 元 / yokon

依据官方仓库 JayCheng113/OpenTrading 的 README、docs/guide/installation.md、docs/guide/quick-start.md、docs/guide/features.md、docs/guide/faq.md，并对照本机 C:\Users\你的用户名\OpenTrading 的实际状态整理。
编写日期：2026-10-15（Asia/Shanghai）。

1. 你现在的状态（已装好什么）

项目 本机情况 结论
安装目录 C:\Users\你的用户名\OpenTrading 已存在
Python .venv 可用，Python 3.12.10（满足官方 3.12+） 已完成
后端包 ez-trading 0.3.3，可编辑安装（editable） 已完成
前端 web/node_modules 存在；Node.js v24.20.0 / npm 11.19.0（满足 22+） 已完成
启停脚本 根目录有本机定制的 start.ps1 / stop.ps1（官方 Linux 对应 scripts/start.sh） 已完成
环境文件 .env 已从模板创建；TUSHARE_TOKEN、DEEPSEEK_API_KEY、FMP_API_KEY 均为空 部分完成
数据源配置 configs/default.yaml 中 A 股 primary: "akshare"，backup: ["tushare", "tencent"] 本机定制（官方默认以 Tushare 为主）
数据目录 data/ez_trading.db + data/cache/ 已出现 已完成
运行状态（检查时） http://127.0.0.1:8000、http://127.0.0.1:3000 均返回 HTTP 200 当前在跑
Git 仓库 目录下没有 .git（更像解压/拷贝，而非 git clone） 不影响日常使用；升级需另作说明
用户策略目录 strategies/ 基本为空；内置策略在 ez/strategy/builtin/（如 momentum、ma_cross） 正常

一句话：软件主体已装好并能双端访问；要做完整 A 股量化 + AI，还差 Token/Key，以及按官方路径走完「第一次回测 → 模拟盘」闭环。

2. 官方要求 vs 本机对照

2.1 官方前提条件

来源：docs/guide/installation.md、CONTRIBUTING.md。

官方要求 本机
Python 3.12+ 3.12.10 ✅
Node.js 22+ v24.20.0 ✅
pip / uv 已用 .venv + pip 可编辑安装 ✅
Docker 20.10+ / Compose v2（仅 Docker 路径） 本机走的是本地双进程，非 Docker — 可选
TUSHARE_TOKEN 安装指南写「必填」；README/FAQ 又说明无 Token 可用内置 ETF 种子数据。本机为空 ⚠️
DEEPSEEK_API_KEY（AI 助手，推荐） 空 ⚠️
FMP_API_KEY（美股，可选） 空（做 A 股可暂缓）

2.2 官方启动方式 vs 本机

方式 官方做法 本机做法
开发双进程 scripts/start.sh：uvicorn :8000 + web 的 npm run dev → 浏览器开 :3000 start.ps1 等价实现（写 PID 到 logs\ez-trading.pids）→ :3000 + :8000
单服务 npm run build 后只跑 uvicorn，访问 :8000 未采用（当前是热重载前端）
Docker docker compose up（或 --build），访问 :8000 未采用

2.3 数据源：官方 vs 本机定制（请分清）

  • 官方：Tushare 是 A 股主数据源；AKShare 在功能总览中定位为「ETF 净值、部分备用行情」。完整历史缓存脚本 python scripts/build_data_cache.py 也要求先配好 TUSHARE_TOKEN。
  • 本机定制（已改 configs/default.yaml）：
data_sources:
  cn_stock:
    primary: "akshare"          # 本机：无 Token 也能拉 A 股
    backup: ["tushare", "tencent"]

说明：这是为「先跑通 A 股、Token 未填」做的本地调整，不是官方默认。日后若补上 Tushare 积分与 Token，可把 primary 改回 tushare，或保持 akshare 主源、tushare 作备份。

3. 从零部署（完整步骤，便于重装或教别人）

下面按官方文档整理三条路径。你当前已走过「本地开发双进程」；Windows 启停用本机 start.ps1/stop.ps1。

3.A 本地开发模式（推荐日常；本机正在用）

前提：Python 3.12+、Node.js 22+、Git（可选）。

# 1. 获取代码（官方）
git clone https://github.com/JayCheng113/OpenTrading.git
cd OpenTrading

# 2. 虚拟环境（官方示例用系统 pip；Windows 建议 venv）
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 3. 后端（官方）
pip install -e ".[all]"
# 至少需要数据源相关时也可：pip install -e ".[tushare,akshare]"

# 4. 前端（官方 README 开发模式：只 npm install；安装指南「单服务」才要 build）
cd web
npm install
cd ..

# 5. 环境变量（官方）
copy .env.example .env
# 编辑 .env：至少按需填写 TUSHARE_TOKEN；AI 填 DEEPSEEK_API_KEY

# 6. 启动
# Linux/macOS（官方）：
#   scripts/start.sh
# Windows（本机已提供）：
.\start.ps1

访问：

  • UI：http://127.0.0.1:3000（或 http://localhost:3000）
  • API / Swagger：http://127.0.0.1:8000（常见为 /docs）

停止（本机）：

.\stop.ps1

3.B 单服务模式（官方「安装指南」本地安装）

适合不想单独跑前端开发服务器、只要一个端口：

pip install -e ".[all]"
cd web && npm install && npm run build && cd ..
cp .env.example .env   # Windows: copy .env.example .env
# 填写 TUSHARE_TOKEN 等
uvicorn ez.api.app:app --host 0.0.0.0 --port 8000

访问：http://localhost:8000。

3.C Docker（官方「安装指南」推荐路径；适合干净试跑）

git clone https://github.com/JayCheng113/OpenTrading.git
cd OpenTrading
cp .env.example .env
# 编辑 .env，填入 TUSHARE_TOKEN
docker compose up
# 或 README：docker compose up --build

访问：http://localhost:8000。

官方 volume 持久化（重建容器不丢数据）：

容器内 宿主机 用途
/app/data ./data DuckDB + Parquet 缓存
/app/strategies 等 同名目录 用户策略 / 因子 / 配置

3.D 可选：C++ 加速

官方：pip install -e . --no-build-isolation。失败可忽略，自动回退纯 Python。Windows 需 Visual Studio Build Tools，官方写明暂未测试。

4. 本机补齐清单（Token、重启、验证）

按优先级做下面几项即可从「能打开」进到「能正经做 A 股研究」。

4.1 必做 / 强烈建议

  1. 申请并填写 TUSHARE_TOKEN
    - 注册：https://tushare.pro
    - 个人中心 → 接口 Token → 写入 C:\Users\你的用户名\OpenTrading\.env：
    TUSHARE_TOKEN=你的token
    - 也可在 UI 右上角齿轮设置里配置（官方：改完立即生效，不必重启）。
    - FAQ：基础日线等对新用户免费开放；无 Token 时只能靠内置 ETF 种子数据（如 510300.SH）或本机 akshare 主源。

  2. （做 AI 助手时）填写 DEEPSEEK_API_KEY
    - 同一 .env：DEEPSEEK_API_KEY=...
    - 也可用 OpenAI 兼容：OPENAI_API_KEY + OPENAI_BASE_URL。

  3. 确认数据源策略
    - 维持本机定制：akshare 主源即可先跑 A 股。
    - 若要以官方完整缓存 / 基本面为主：配好 Token 后，可把 configs/default.yaml 的 cn_stock.primary 改回 tushare，再执行：
    powershell cd C:\Users\你的用户名\OpenTrading .\.venv\Scripts\python.exe scripts\build_data_cache.py
    （官方提醒：耗时、耗积分，建议非交易时段。）

  4. 重启一次服务（改 .env 后若未用 UI 热更新）
    powershell cd C:\Users\你的用户名\OpenTrading .\stop.ps1 .\start.ps1

  5. 验证
    - 浏览器打开 http://127.0.0.1:3000。
    - 无 Token：搜索 510300.SH 做一次样例回测。
    - 有 Token / akshare：按快速上手用 000001.SZ 等 A 股代码试回测。
    - API：http://127.0.0.1:8000/docs 应能打开。

4.2 可选

  • FMP_API_KEY：仅美股需要。
  • Docker：本机已有本地路径，一般不必再上容器。
  • 若希望以后用 git pull 升级：重新 git clone 到旁路目录，再拷贝 .env、configs/default.yaml、data/、strategies/ 等，或初始化 git remote。

4.3 常见坑（官方 FAQ + 本机经验）

现象 处理
端口 8000/3000 被占用 stop.ps1 会尝试清理；或改端口 / 结束占用进程
PowerShell 里找不到 node/npm start.ps1 会刷新 Machine+User PATH；新开终端或确认 Node 已装在 C:\Program Files\nodejs\
PID 文件与实际进程不一致 以端口监听为准，再跑一次 stop.ps1
C++ 编译失败 可忽略
Docker 起不来 查版本、端口、是否复制了 .env、磁盘空间；docker compose logs ez-trading
回测结果与其他平台不一致 官方严格执行 T+1、涨跌停、印花税 0.1%、整手 100 股

5. 日常启停

在项目根目录 C:\Users\你的用户名\OpenTrading：

.\start.ps1
# 输出示例：
# Backend PID ...  http://127.0.0.1:8000
# Frontend PID ... http://127.0.0.1:3000

.\stop.ps1
# 按 logs\ez-trading.pids 停进程，并清理 8000/3000 残留

日志目录：logs\（backend.log / backend.err.log / frontend.log 等）。

开发提示（官方）：前端 npm run dev 会把 API 代理到 http://localhost:8000，与本机 CORS 配置（已含 http://127.0.0.1:3000）一致。

6. 下一步：回测 / 模拟盘最小闭环（按文档）

目标：先纸面验证，再模拟盘；不要直接上实盘。

6.1 第一次策略回测（官方 docs/guide/quick-start.md）

前提：服务已开（本机用 :3000；官方快速上手示例写的是 :8000 单服务，步骤相同）。

  1. 左侧导航 → 代码编辑器 → 新建策略（如 my_momentum）。
  2. 可粘贴官方动量示例（继承 ez.strategy.base.Strategy，on_bar 里突破买入 / 跌破卖出）。
  3. 保存（Ctrl+S）；系统会做前视偏差等安全检查。
  4. 左侧 → 回测：选策略、代码如 000001.SZ、区间如 2020-01-01～2024-12-31 → 运行回测。
  5. 查看 K 线买卖点、净值相对沪深 300、Sharpe / 最大回撤等。

A 股代码格式：xxxxxx.SZ / xxxxxx.SH。

无完整数据时：先试 510300.SH（官方种子数据说明）。

6.2 因子 / 组合（官方功能总览）

  • 因子研究：IC / RankIC / 分组收益 / 相关性等，浏览器内完成。
  • 组合回测：多标的 + 优化器（均值方差、风险平价等）+ Brinson 归因。
  • 建议：单股回测跑通后再上组合。

6.3 模拟盘（Paper Trading）最小路径

官方用户文档（功能总览 §6、FAQ）：

  • 模拟盘用真实行情按 A 股规则模拟委托/成交/持仓，不动真实资金。
  • 含部署门控（DeployGate）、调度器、OMS 事件溯源；真券商走 QMT，且需更严门控。
  • UI：导航中的 模拟盘；典型路径是组合回测结果页 → 部署到模拟盘 → 门禁通过 → 开始模拟。

内部规格（docs/internal/specs/2026-04-06-v215-paper-trading-bridge.md，供理解，非日常必读）要求更严，例如：

  • 来源回测存在、Sharpe / 回撤 / 交易次数达标；
  • 需有 Walk-forward 结果；回测天数、标的数、集中度等；
  • 门禁不可跳过；未跑 WF 会直接不通过。

建议你当前的最小闭环：

  1. 配好数据（akshare 已可用；有条件再补 Tushare）。
  2. 完成一次单股回测（种子 ETF 或一只 A 股）。
  3. 再做一次组合回测 +（如有）Walk-forward。
  4. 在 UI 部署到模拟盘，用手动 tick / 调度观察几日。
  5. 不要在未稳定纸面/模拟前接 QMT 实盘。

6.4 AI 量化

  • 配 DEEPSEEK_API_KEY 后，编辑器内可用 AI 助手生成策略并回测。
  • 无 Key 时仍可手写策略 + 内置/自写因子，不影响回测与模拟盘主路径。

7. 环境变量速查（官方 .env.example）

变量 官方态度 说明
TUSHARE_TOKEN 安装指南：必填；README：完整 A 股建议填 tushare.pro
DEEPSEEK_API_KEY 可选，推荐 AI 助手 / 自主研究
FMP_API_KEY 可选 美股
OPENAI_API_KEY / OPENAI_BASE_URL 可选 OpenAI 兼容接口
API_PORT 可选，默认 8000
DB_PATH 可选，默认 data/ez_trading.db DuckDB

回测结果与部署元数据默认在本地 DuckDB：data/ez_trading.db。

8. 参考链接（已核对可打开）

说明 URL
仓库首页 / README https://github.com/JayCheng113/OpenTrading
安装指南（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/docs/guide/installation.md
快速上手（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/docs/guide/quick-start.md
功能总览（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/docs/guide/features.md
常见问题（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/docs/guide/faq.md
文档索引（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/docs/README.md
贡献指南（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/CONTRIBUTING.md
环境变量模板（raw） https://raw.githubusercontent.com/JayCheng113/OpenTrading/main/.env.example
Tushare 注册 https://tushare.pro
本机 UI http://127.0.0.1:3000
本机 API http://127.0.0.1:8000

本地文档副本（与上游一致，编码以编辑器为准）：

  • C:\Users\你的用户名\OpenTrading\docs\guide\installation.md
  • C:\Users\你的用户名\OpenTrading\docs\guide\quick-start.md
  • C:\Users\你的用户名\OpenTrading\docs\guide\features.md
  • C:\Users\你的用户名\OpenTrading\docs\guide\faq.md
  • C:\Users\你的用户名\OpenTrading\README.md

9. 免责声明（官方原文精神）

OpenTrading 仅用于量化研究、教学和工具开发，不构成投资建议。回测与模拟盘结果不代表未来收益；实盘请自行评估风险。本教程中的「本机定制」（akshare 主源、start.ps1）已单独标明，升级官方代码时注意合并冲突。