-不想写命令行？用浏览器。`easy-tdx serve` 启动后端，`web-ui/` 目录跑前端，浏览器打开就是完整的回测可视化界面。
+不想写命令行？用浏览器。`easy-tdx serve` 一条命令启动，浏览器自动打开 `http://localhost:8000`，就是完整的回测可视化界面。
**前置条件：**
```bash
-# 后端需安装 web 可选依赖（FastAPI + Uvicorn）
+# 需安装 web 可选依赖（FastAPI + Uvicorn）
pip install -e ".[web]"
-
-# 前端需 Node.js 18+（首次运行需装依赖）
-cd web-ui && npm install
```
-**启动（两个终端）：**
+**启动（一条命令）：**
```bash
-# 终端 1：启动后端 API 服务（提供行情数据 + 回测计算）
-easy-tdx serve --port 8000
+# 启动后端 + 自动打开浏览器（默认 http://localhost:8000）
+easy-tdx serve
-# 终端 2：启动前端开发服务器（web-ui/ 目录）
-cd web-ui && npm run dev
-# 浏览器打开 http://localhost:5173
+# 自定义端口/不自动开浏览器
+easy-tdx serve --port 8080 --no-open-browser
```
-> 前端开发服务器通过 Vite proxy 把 `/api` 请求转发到后端 `127.0.0.1:8000`，无需处理跨域。后端行情连接失败时回测路由仍可用（用内联数据），但取行情功能需要后端连通通达信服务器。
+> 后端启动后约 1-2 秒会自动弹出浏览器。前端界面已编译进 `web-ui/dist/`，由后端同源托管，无需单独跑前端开发服务器。后端行情连接失败时回测路由仍可用（用内联数据），但取行情功能需要后端连通通达信服务器。
+
+**不想装 Python？下载 EXE 直接用（面向零基础用户）：**
+
+Windows 用户可以下载打包好的单一 EXE（约 80-150MB），双击即可使用，无需安装 Python/Node 或任何依赖：
+
+1. 到 [Releases 页面](../../releases) 下载最新的 `easy-tdx-<版本>-windows.exe`
+2. 双击运行（首次会被 SmartScreen 拦截，点"更多信息 → 仍要运行"）
+3. 等待 2-5 秒，浏览器自动打开回测界面
+4. 右下角任务栏出现小图标，右键 → "退出" 可关闭
+
+EXE 打包方法见 [`docs/packaging.md`](./docs/packaging.md)。
打开浏览器后，顶部导航栏有五个页面：
diff --git a/docs/packaging.md b/docs/packaging.md
new file mode 100644
index 0000000..664ab7e
--- /dev/null
+++ b/docs/packaging.md
@@ -0,0 +1,123 @@
+# 打包为 Windows EXE（面向老年用户）
+
+本文档说明如何把 easy-tdx + Vue 前端打包成单一 Windows EXE，让老人双击即可
+使用量化回测界面，无需安装 Python、Node 或任何依赖。
+
+## 给最终用户（老人 / 量化初学者）
+
+### 下载
+
+到 [Releases 页面](https://github.com/从零开始,手把手教你在浏览器里完成股票策略回测
@@ -270,8 +270,8 @@easy-tdx 的回测系统需要两个软件配合:Python(负责算数据和回测)和 Node.js(负责显示网页界面)。这两个软件都是免费的,我们一步一步来。
+easy-tdx 提供三种使用方式,难度从低到高。请根据自己的情况选一种,不需要三种都试。
-这是最简单的方式。我们提供了打包好的单个 EXE 文件(约 80-150MB),里面已经包含了所有需要的东西,不用装 Python、不用装 Node.js、不用敲命令。
+ +用浏览器打开项目主页的 Releases(发布) 页面:
+https://github.com/handsomejustin/easy_tdx/releases
找到最新版本,下载那个名字像 easy-tdx-1.19.0-windows.exe 的文件。
下载后直接双击这个 EXE。
+第一次运行会被 Windows 拦截(弹出蓝色"已保护你的电脑"窗口),这是正常的,因为我们的 EXE 还没有花钱买"数字签名"。处理方法:
+EXE 首次启动需要解压(所以会慢几秒),然后浏览器会自动打开回测界面。看到顶部导航栏有"单标的回测 / 组合回测 / 参数寻优 / 结果对比 / 策略库"五个标签,就大功告成了!
+如果你愿意装一个软件(Python),用一条命令启动,这种方式更灵活,启动也更快。只需要装 Python,不需要 Node.js(网页界面已经预先编译好了,由后端自动提供)。
打开浏览器,访问官网下载页:
https://www.python.org/downloads/
页面会自动推荐 Windows 版本,点黄色按钮 "Download Python 3.12.x"(3.12 是目前最稳定的版本)。如果推荐的是 3.13 也可以。
+页面会自动推荐 Windows 版本,点黄色按钮 "Download Python 3.12.x"(3.12 是目前最稳定的版本)。如果推荐的是 3.13 也可以。必须 3.10 或更高版本。
如果显示 Python 3.12.x(数字无所谓,3.10 以上都行),就成功了。如果提示"不是内部或外部命令",说明上一步 PATH 没勾,请卸载重装一次。
如果你想看代码、改代码,或者想自己打包一个 EXE 分发给朋友,用这种方式。需要同时装 Python 和 Node.js(Node.js 仅用于修改前端界面后重新编译,日常使用不需要)。
访问官网:
-https://nodejs.org/zh-cn
下载左边那个 "LTS"(长期支持版),不要下右边那个最新尝鲜版。LTS 更稳定,新手用它不会出怪问题。版本号一般是 20.x 或 22.x。
+1装 Python +按上面"方式二"的第 1-3 步装好 Python 3.10+。
双击安装包,全部点"下一步",不用改任何选项,点"Install"等完成。
+2装 Node.js(LTS 长期支持版) +访问官网 https://nodejs.org/zh-cn,下载左边那个 "LTS" 版本。双击安装包,全部点"下一步"即可。
验证:打开命令行输入 node --version,显示 v20.x.x 或更高就成功了。
再次打开命令行(按 Win + R 输入 cmd),输入:
node --version显示 v20.x.x 或更高版本就成功了。
先按 第二章 把项目跑起来。打包 EXE 的方法见第十二章附录 "自己打包 EXE 分发"。
easy-tdx 是一个开源项目,代码托管在 GitHub。我们需要把代码下载到本地,然后启动两个服务。
+easy-tdx 是一个开源项目,代码托管在 GitHub。我们需要把代码下载到本地,装好 Python 依赖,然后一条命令启动。
D:\easy_tdx 最稳。
# 一次性安装项目本体和 Web 服务所需的所有 Python 依赖
+2创建虚拟环境(强烈推荐)
+虚拟环境可以把这个项目的依赖和系统里其他 Python 程序隔离开,避免冲突。在项目目录下输入:
+# 创建一个叫 venv 的虚拟环境(只做一次)
+python -m venv venv
+
+# 激活虚拟环境(每次开新窗口都要做)
+# Windows cmd 用这句:
+venv\Scripts\activate
+
+# Windows Git Bash 用这句:
+# source venv/Scripts/activate
+激活成功后,命令行最前面会多出一个 (venv) 标记,说明你已经在虚拟环境里了。
+venv\Scripts\activate 激活,看到 (venv) 才说明进对了。
+# 确认命令行前面有 (venv) 后执行
+# 一次性安装项目本体和 Web 服务所需的所有 Python 依赖
# 包括 FastAPI、Uvicorn、pandas、numpy 等
pip install -e ".[web]"这步会下载很多文件(约 100MB),需要等 3 到 5 分钟。看到最后有 Successfully installed ... 就成功了。
# 看到帮助信息就说明安装好了
easy-tdx --help装好之后,每次用只需要一条命令。打开命令行,激活虚拟环境,进入项目目录,然后:
# 还在项目目录里,进入前端目录
-cd web-ui
-
-# 安装前端依赖(第一次会下载约 200MB,耐心等 5 分钟)
-npm installnpm config set registry https://registry.npmmirror.com
-npm install这是新手最容易迷糊的地方:这个系统需要同时开两个命令行窗口,一个跑后端(算数据的厨房),一个跑前端(显示网页的服务员)。
- -按 Win + R 输入 cmd 回车,进入项目根目录:
D:
-cd \easy_tdx# 每次开新窗口都先做这两步
+D:
+cd \easy_tdx
+venv\Scripts\activateeasy-tdx serve --port 8000easy-tdx serve看到类似下面的输出就成功了:
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete.这个窗口不要关! 它一直开着,前端才能取到数据。
-按 Win + R 输入 cmd 回车,进入前端目录:
D:
-cd \easy_tdx\web-ui大约 1-2 秒后,浏览器会自动打开 http://localhost:8000,直接看到回测界面。不用再手动开浏览器,也不用跑第二个命令。
npm run dev看到这样的输出:
- VITE v8.x.x ready in 500 ms
-
- ➜ Local: http://localhost:5173/
- ➜ Network: use --host to expose打开 Chrome 或 Edge 浏览器,地址栏输入:
-http://localhost:5173
看到顶部导航栏有"单标的回测 / 组合回测 / 参数寻优 / 结果对比 / 策略库"五个标签,就大功告成了!
+3关闭系统 +用完后,在跑 easy-tdx serve 的命令行窗口里按 Ctrl + C 就能停止服务。然后关掉窗口即可。
easy-tdx serve --port 8000,一个跑 npm run dev,然后浏览器打开 http://localhost:5173 就行。
+关机后下次怎么用? 不用重新装,只要:D: → cd \easy_tdx → venv\Scripts\activate(激活虚拟环境)easy-tdx serve# 自定义端口(默认 8000,被占用时换一个)
+easy-tdx serve --port 8080
+
+# 不自动开浏览器(比如想用别的浏览器手动打开)
+easy-tdx serve --no-open-browser
+
+# 让局域网其他电脑也能访问(比如手机同 WiFi 访问)
+easy-tdx serve --host 0.0.0.0说明 Python 没装好或 PATH 没配置。回到第一章 1.1 重装 Python,务必勾选 "Add Python to PATH"。如果已装,在命令行输入 pip install -e ".[web]"(在项目目录下)重新安装。
Node.js 没装或没重启命令行。回到第一章 1.2 重装 Node.js,然后关闭所有 cmd 窗口重新打开。
-网络问题。换淘宝镜像:
-
npm config set registry https://registry.npmmirror.comnpm install。
-检查两点:
+EXE 启动需要 2-5 秒解压,请耐心等待。如果超过 30 秒还没反应:
easy-tdx serve --port 8000http://localhost:8000easy-tdx.exe 进程 serve --no-open-browser 跑,看报错信息这是正常的。我们的 EXE 没有花钱买"数字签名",Windows 会拦截。处理方法:
+只需第一次这样做,之后 Windows 会记住。
+直接关浏览器标签页不会停止后台服务。完整退出看屏幕右下角任务栏:
+或者打开任务管理器(Ctrl+Shift+Esc),结束 easy-tdx.exe 进程。
两种可能:
+(venv) 标记。先 cd \easy_tdx 再 venv\Scripts\activate。如果已装,在项目目录下(激活 venv 后)重新执行 pip install -e ".[web]"。
检查两点:
+easy-tdx serve%USERPROFILE%\.easy_tdx\easy_tdx_runtime.log 日志文件easy-tdx 需要连接通达信的行情服务器取数据。可能原因:
可以换个时间再试,或者用其他股票代码试试。
这是正常的。回测结果存在后端进程内存,重启就清空。重要的策略一定要点"保存策略"存进策略库,策略库的数据存在 SQLite 文件里,重启不丢。
这只股票/策略在回测期间交易笔数少于 10 笔。系统已经把胜率和利润因子的权重降到 0,只看净值类指标(夏普/卡玛/回撤)。长线策略常常这样,不一定是坏事。详见第七章 7.5 节。
参数取值组合太多。减少参数取值的数量,比如 fast 从 10 个值减到 5 个值,或者只寻优一个参数(不勾另一个)。
评级阈值是基于金融惯例校准的,可能在某些边界情况不完美。每个维度的打分逻辑在 web-ui/src/grading/thresholds.ts 文件里,如果你懂技术可以微调。或者截图给老师反馈。
评级阈值是基于金融惯例校准的,可能在某些边界情况不完美。每个维度的打分逻辑在 web-ui/src/grading/thresholds.ts 文件里,如果你懂技术可以微调。或者截图反馈。
在行情数据区的"周期"下拉里选 MIN_5(5 分钟)、WEEK(周线)等。注意:分钟线数据量很大,回测会慢很多,新手建议只用日线(DAY)。
如果你想把 easy-tdx 打包成单个 EXE,发给不会装 Python 的朋友/家人用,按下面的步骤操作。打包后的 EXE 双击即用,对方不用装任何东西。
+ +[web,packaging] 依赖在项目目录、激活虚拟环境后,执行:
+# web 依赖 + 打包依赖(系统托盘 pystray + 图标 Pillow)一起装
+pip install -e ".[web,packaging]"
+
+# 装 PyInstaller 打包工具
+pip install pyinstaller# 进入前端目录
+cd web-ui
+
+# 装前端依赖(首次需要)
+npm install
+
+# 编译前端到 web-ui/dist/
+npm run build
+
+# 回到项目根目录
+cd ..# 在项目根目录执行(venv 已激活)
+pyinstaller easy_tdx.spec --noconfirm打包过程约 1-3 分钟。完成后,在 dist\ 目录下会出现 easy-tdx.exe(约 80-150MB)。
dist\easy-tdx.exe
+等待 2-5 秒,浏览器应自动打开 http://localhost:8000。
应出现 K 线图样式的小图标,右键有"打开浏览器 / 退出"菜单。
+选一只股票 + 一个策略,确认能完整出图、出指标。再试一次"一键寻优"(选 4 或 8 进程),确认多进程正常。
+把 dist\easy-tdx.exe 这个单文件直接发给朋友即可(可以通过微信传文件、网盘等)。对方:
不用装任何东西,不用敲任何命令。
+ +这是因为 Windows GUI 模式下标准流为 None,而 uvicorn 假设它们存在。我们的代码已经在 __main__.py 里做了重定向处理,如果还报这个错,说明你用的是旧版入口代码。请拉取最新代码后重新打包。
多进程在打包模式下需要特殊处理。我们的代码已经在 __main__.py 加了 freeze_support() 和子进程检测。如果还报错,确认你拉的是最新代码。
大部分是无害的:numba(可选加速库,没装正常)、jinja2(模板引擎,本项目用不到)、scipy 内部模块改名。只要最后 dist\easy-tdx.exe 能正常启动,这些 WARNING 都可以忽略。
.github/workflows/release.yml 和 docs/packaging.md。
+