docs: add workflow reference manual (v1.0)
This commit is contained in:
315
docs/guides/workflow_reference.md
Normal file
315
docs/guides/workflow_reference.md
Normal file
@ -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 只做研发和设计，不参与线上调度
|
||||
Reference in New Issue
Block a user