mirror of
https://ghfast.top/https://github.com/aeroxw/easy-tdx.git
synced 2026-09-12 21:34:16 +08:00
Justin Gu
0b4ed9af62
面向零基础老年用户，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
124 lines
3.3 KiB
Markdown
124 lines
3.3 KiB
Markdown
# 打包为 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/11（PyInstaller 不支持跨平台编译）
|
||
- 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 公证。
|