feat(packaging): v1.19.1 支持 Windows 单 EXE 打包 + 系统托盘 + 自动发版

面向零基础老年用户,easy-tdx 可打包成单一 Windows EXE,双击即用。

新增:
- 后端同源托管前端 dist(app.py 三级探测:env → _MEIPASS → web-ui/dist)
- easy-tdx serve 默认 --open-browser,启动后自动开浏览器
- PyInstaller 打包入口(__main__.py)+ spec 配置(easy_tdx.spec)
- 系统托盘(tray.py):右下角图标,右键"打开浏览器/退出"
  解决老人不会用任务管理器关闭的问题
- GitHub Actions release.yml:打 v* tag 自动构建并发布 EXE 到 Releases
- docs/packaging.md 打包使用文档

修复:
- K 线残缺尾记录导致 500(security_bars.py):通达信服务器偶发
  ret_count 与 body 长度不匹配,改为 try/except 优雅降级丢弃残缺尾,
  返回已解析的完整记录。GetIndexBarsCmd 同改。加 4 个回归测试。
- PyInstaller frozen 模式三个坑:
  1. console=False 下 stdout/stderr 为 None → 重定向到日志文件
  2. multiprocessing spawn 子进程重新 import __main__ → freeze_support + 子进程检测
  3. 系统托盘需主线程消息泵 → uvicorn 挪到后台线程

文档:
- README/手册改为三档分流:EXE(零基础)/ Python(一条命令)/ 源码(打包)
- 删除 npm run dev / 5173 / 两个终端的过时说明
- 手册补虚拟环境配置 + EXE 打包附录 + EXE 排错 FAQ
This commit is contained in:
Justin Gu
2026-07-07 01:48:07 +08:00
parent c901d198ca
commit 0b4ed9af62
13 changed files with 1065 additions and 141 deletions
+123
View File
@@ -0,0 +1,123 @@
# 打包为 Windows EXE(面向老年用户)
本文档说明如何把 easy-tdx + Vue 前端打包成单一 Windows EXE,让老人双击即可
使用量化回测界面,无需安装 Python、Node 或任何依赖。
## 给最终用户(老人 / 量化初学者)
### 下载
到 [Releases 页面](https://github.com/<owner>/easy_tdx/releases) 下载最新的
`easy-tdx-<版本号>-windows.exe`(约 80-150MB)。
### 运行
1. 双击 `easy-tdx-<版本号>-windows.exe`
2. 首次运行 Windows 会弹"已保护你的电脑"(蓝色 SmartScreen 窗口):
- 点击 **更多信息**
- 点击 **仍要运行**
- (Phase 2 引入代码签名后会消除此提示)
3. 等待 2-5 秒(EXE 首次解压),浏览器会自动打开
`http://localhost:8000`
4. 即可看到回测界面,开始使用
### 关闭
直接关闭浏览器标签页**不会**停止后台服务。完整退出请:
- 在任务管理器结束 `easy-tdx.exe` 进程,或
- 在命令行运行 `taskkill /IM easy-tdx.exe /F`
### 已知限制
- **必须联网**:在线行情数据需要连接通达信服务器。
- **离线 .day 读取需要通达信**:若没安装 Windows 版通达信,离线读取本地
数据功能不可用;在线行情不受影响。
- **收藏的策略不会丢**:策略保存在 `~/.easy_tdx/strategies.db`,跨重启保留。
升级 EXE 时该文件不会被覆盖。
### 排查问题
双击后没反应(浏览器没打开):
1. 打开命令提示符(Win+R 输入 `cmd`
2. 拖拽 EXE 到命令行,加 ` serve`,回车
3. 查看报错信息(通常是端口 8000 被占用,改用 `--port 8001`
---
## 给开发者:本地构建 EXE
### 前置
- Windows 10/11PyInstaller 不支持跨平台编译)
- Python 3.10+
- Node.js 20+
- 项目已 `pip install -e ".[web]"` 安装到当前环境
### 步骤
```bash
# 1. 安装 PyInstaller
pip install pyinstaller
# 2. 构建前端
cd web-ui
npm ci
npm run build
cd ..
# 3. 构建 EXE
pyinstaller easy_tdx.spec --noconfirm
# 4. 产物
ls -lh dist/easy-tdx.exe
```
双击 `dist/easy-tdx.exe` 验证:浏览器自动打开,能跑通一次内置策略回测。
### 调试
`.spec` 默认 `console=False`(无黑窗)。排查启动失败时:
```bash
# 临时改 console=True 重新打包,或在命令行运行看 stderr
dist/easy-tdx.exe serve --no-open-browser
```
---
## GitHub Actions 自动发版
打 tag 触发:
```bash
git tag v1.19.0
git push origin v1.19.0
```
`.github/workflows/release.yml` 会自动:
1.`windows-latest` runner 上构建前端 + EXE
2. 重命名为 `easy-tdx-<版本>-windows.exe`
3. 创建 GitHub Release 并上传 EXE
该 workflow 与 `publish.yml`PyPI**完全独立**:即使 PyPI 发布失败,EXE
照样能发布。两个 workflow 共享 `v*` tag 触发器但互不依赖。
---
## 当前限制(Phase 1
| 项 | 状态 | 说明 |
|---|---|---|
| Windows EXE | ✅ | 单文件,双击即用 |
| 代码签名 | ❌ | 未签名,SmartScreen 会拦截,需手动绕过 |
| macOS | ❌ | 延后到 Phase 3(需 Apple 开发者账号 + 公证) |
| 自动更新 | ❌ | 老人需手动下载新版本 |
| EXE 体积 | ~80-150MB | pandas/numpy/scipy/uvicorn/Vue 全包 |
Phase 2 计划:购买 OV/EV 代码签名证书,在 GitHub Actions 中签名 EXE
消除 SmartScreen 提示。
Phase 3 计划:macOS 构建 + Apple 公证。