From f89a699344673cf1df60182539d8168a61dc3ac0 Mon Sep 17 00:00:00 2001 From: FXY Date: Thu, 11 Jun 2026 23:56:30 +0800 Subject: [PATCH] docs: add workflow reference manual (v1.0) --- docs/guides/workflow_reference.md | 315 ++++++++++++++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 docs/guides/workflow_reference.md diff --git a/docs/guides/workflow_reference.md b/docs/guides/workflow_reference.md new file mode 100644 index 0000000..ba40c9d --- /dev/null +++ b/docs/guides/workflow_reference.md @@ -0,0 +1,315 @@ +# Beast Trader 工作流参考手册 + +> 版本：v1.0 | 更新：2026-06-11 +> +> 本手册描述 Beast Trader 量化策略的完整研发工作流，涵盖从策略编写到实盘运行的全生命周期。 +> 所有自动化任务全部部署在东京服务器（43.163.225.30），不依赖 WorkBuddy 的调度能力。 + +--- + +## 一、总体工作流 + +``` +编写 → 回测 → 评估 → 发布(tag) → 实盘 → 复盘 + ↑ │ + └────────────────── 迭代 ──────────────┘ +``` + +| 阶段 | 在哪里做 | 产出 | 自动化程度 | +|:---|:---|:---|:---| +| 编写 | WorkBuddy | 策略代码 .py | 手动 | +| 回测 | 服务器 Docker | 回测结果 .txt/.json | 半自动（命令固化） | +| 评估 | WorkBuddy | 决策 | 手动 | +| 发布 | 服务器 Gitea | git tag + 部署脚本 | 手动触发，脚本执行 | +| 实盘 | 服务器 Docker | 成交记录 → trades/ | cron 每小时自动导出 | +| 复盘 | WorkBuddy | 优化思路 | 手动 | + +--- + +## 二、基础设施 + +### 2.1 服务器 + +| 项目 | 说明 | +|:---|:---| +| IP | 43.163.225.30 | +| 系统 | Ubuntu | +| SSH | `ssh -i ~/Desktop/ssh_new.pem ubuntu@43.163.225.30` | +| 密钥 | `C:/Users/32779/Desktop/ssh_new.pem` | + +### 2.2 服务清单 + +| 服务 | 端口 | 用途 | 管理方式 | +|:---|:---|:---|:---| +| Gitea | 3000 | 版本仓库 | `systemctl restart gitea` | +| Freqtrade | 8081 (内部) | 策略执行引擎 | `docker-compose down && up -d` | +| Dashboard | 9000 | 实时看板 | 后端 FastAPI + nginx | +| Halo | 8090 | 博客 | docker | +| Lucky | — | DDNS/网络 | docker | + +### 2.3 Gitea 仓库 + +| 项目 | 说明 | +|:---|:---| +| URL | `http://43.163.225.30:3000/fxy/beast-trader` | +| Git Clone | `git clone http://43.163.225.30:3000/fxy/beast-trader.git` | +| 用户 | fxy | +| Token | 存储于服务器 `~/.gitea_token` | + +### 2.4 目录结构 + +``` +/home/ubuntu/ +├── beast-trader/ # Gitea 本地工作副本 +│ ├── strategies/ # 策略代码（按版本归档） +│ ├── backtests/ # 回测结果 +│ ├── trades/ # 实盘交易记录（自动生成） +│ ├── daily_briefs/ # 日报（自动推送） +│ ├── docs/ # 文档 +│ ├── config/ # 配置文件 +│ ├── scripts/ # 自动化脚本 +│ └── tools/ # 工具脚本 +├── freqtrade/ # freqtrade 主目录（Docker volume 映射） +│ ├── docker-compose.yml +│ └── user_data/ +│ ├── strategies/ # f证qtrade 实际使用的策略 +│ ├── config.json +│ ├── secrets.json # API 密钥（不入库） +│ ├── backtest_results/ +│ └── daily_briefs/ +├── trading_app/ # Dashboard +└── .keys/ # API 密钥原始文件 + └── binance_readonly +``` + +--- + +## 三、策略研发流程 + +### 3.1 编写策略 + +在 WorkBuddy 中编写/修改策略代码。策略文件按以下约定命名： + +``` +structure_flow_v{主版本}.{小版本}.py # 趋势策略 +structure_flow_swing_v{主版本}.{小版本}.py # 波段策略 +``` + +**版本规则：** + +| 变化类型 | 版本号示例 | 说明 | +|:---|:---|:---| +| 重大架构变革 | v3.0 → v4.0 | 整数跳 | +| 功能改良 | v3.1 → v3.2 | 小版本 | +| 热修复 | v3.0.1 | Patch | + +**当前基线：** v2.2d（205,684%，1375 笔，Sharpe 1.03） + +### 3.2 代码入仓 + +```bash +# 1. 复制策略到仓库 +cp ~/structure_flow_v3.0.py ~/beast-trader/strategies/current/ + +# 2. 按版本归档 +mkdir -p ~/beast-trader/strategies/v3.0 +cp ~/structure_flow_v3.0.py ~/beast-trader/strategies/v3.0/ + +# 3. 提交推送 +cd ~/beast-trader +git add strategies/ +git commit -m "feat: v3.0 全新入场逻辑" +git push +``` + +### 3.3 回测验证 + +**标准回测命令（Docker 内执行）：** + +```bash +# 全周期回测（必须用此配置才能复现结果） +docker exec freqtrade freqtrade backtesting \ + --strategy StructureFlowStrategyV22d \ + --timerange 20210101-20260601 \ + --config /freqtrade/user_data/config.backtest.json \ + --export trades +``` + +**逐年回测：** + +```bash +# 逐年独立执行 +for year in 2021 2022 2023 2024 2025 2026; do + docker exec freqtrade freqtrade backtesting \ + --strategy StructureFlowStrategyV22d \ + --timerange ${year}0101-$((${year}+1))0101 \ + --config /freqtrade/user_data/config.backtest.json +done +``` + +**回测结果归档：** + +```bash +# 将结果复制到仓库 +cp ~/freqtrade/user_data/backtest_results/backtest-result-*.zip ~/beast-trader/backtests/full/ +cd ~/beast-trader && git add backtests/ && git commit -m "backtest: $(date +%Y-%m-%d) 全周期结果" && git push +``` + +**对比基准：** v2.2d 全周期 205,684%（2057倍），任何新版本必须与此对比。 + +### 3.4 发布部署 + +```bash +# 1. 打标签发布 +cd ~/beast-trader +git tag v3.0.0 +git push --tags + +# 2. 使用部署脚本 +bash scripts/deploy_strategy.sh strategies/current/structure_flow_v3.0.py +``` + +`deploy_strategy.sh` 会自动： +1. 复制策略到 `freqtrade/user_data/strategies/` +2. 重启 Docker 容器 +3. 记录部署版本 + +### 3.5 复盘 + +登录 Gitea 查看 `trades/` 目录下的实盘记录，分析胜率、盈亏分布、出场原因分布。将分析结果写入新的策略迭代。 + +--- + +## 四、自动化任务 + +### 4.1 定时任务（crontab） + +```bash +# 查看当前 cron +crontab -l +``` + +| 时间 (UTC) | 任务 | 功能 | +|:---|:---|:---| +| 23:55 每日 | `daily_brief.py` | 生成日报 + Server酱推送微信 | +| 00:05 每日 | `push_brief_to_gitea.sh` | 日报推送到 Gitea | + +### 4.2 实盘交易自动导出（待启用） + +**脚本：** `scripts/export_trades.sh` + +当实盘运行后，解注释脚本中的 SQL 查询部分，然后添加到 cron： + +```bash +# 每小时导出交易记录 +0 * * * * bash /home/ubuntu/beast-trader/scripts/export_trades.sh +``` + +导出格式为 Markdown 表格，包含：序号、时间、方向、入场价、出场价、数量、盈亏、收益率、出场原因。 + +数据源：`freqtrade/user_data/tradesv3.sqlite`（Docker 内）。 + +### 4.3 日报自动推送 + +`scripts/push_brief_to_gitea.sh` 在 daily_brief.py 生成日报后，自动： +1. 复制日报到 `beast-trader/daily_briefs/{年份}/` +2. git add + commit + push + +--- + +## 五、常用命令速查 + +### Git 操作 + +```bash +# 克隆仓库 +git clone http://43.163.225.30:3000/fxy/beast-trader.git + +# 拉取最新 +cd ~/beast-trader && git pull + +# 提交推送 +git add <文件> && git commit -m "feat: 说明" && git push + +# 查看提交历史 +git log --oneline +``` + +### Docker 操作 + +```bash +# 查看运行容器 +docker ps + +# 进入 freqtrade 容器 +docker exec -it freqtrade bash + +# 查看 freqtrade 日志 +docker logs freqtrade --tail 50 + +# 重启 freqtrade +cd ~/freqtrade && docker-compose down && docker-compose up -d +``` + +### Gitea 管理 + +```bash +# 重启 Gitea +sudo systemctl restart gitea + +# 查看 Gitea 状态 +sudo systemctl status gitea + +# 查看 Gitea 日志 +sudo tail -f /var/lib/gitea/log/gitea.log +``` + +### 回测 + +```bash +# 全周期 +docker exec freqtrade freqtrade backtesting --strategy StructureFlowStrategyV22d --timerange 20210101-20260601 --config /freqtrade/user_data/config.backtest.json + +# 指定年份 +docker exec freqtrade freqtrade backtesting --strategy StructureFlowStrategyV22d --timerange 20250101-20260101 --config /freqtrade/user_data/config.backtest.json +``` + +--- + +## 六、密钥管理 + +### API 密钥存储 + +``` +原始文件： ~/freqtrade/.keys/binance_readonly（KEY=VALUE，600权限） +桥接文件： ~/freqtrade/user_data/secrets.json（JSON，600权限） +Docker 加载： config.json(空key) → pairlist → secrets.json(覆盖) +``` + +**密钥权限：** Futures + Trade（未勾选提币/充值），IP 白名单锁定 43.163.225.30 + +**注意：** secrets.json 已加入 .gitignore，不会提交到 Gitea。 + +--- + +## 七、首次使用（新机器） + +如果你在新电脑上工作，需要先克隆仓库： + +```bash +git clone http://43.163.225.30:3000/fxy/beast-trader.git +cd beast-trader +``` + +然后在 WorkBuddy 中阅读 `docs/guides/workflow_reference.md`，按手册操作。 + +--- + +## 八、铁律 + +1. **只增不删** — 策略、回测、交易记录一律保留，禁止删除 +2. **版本归档** — 每个策略版本独立目录，包含代码、回测、配置 +3. **密钥不入库** — secrets.json、.gitea_token、*.key 已被 gitignore +4. **回测数字仅供参考** — 回测好不等于实盘好 +5. **commit message 写清楚** — 方便日后回溯 +6. **自动化全在服务器** — WorkBuddy 只做研发和设计，不参与线上调度