beast-trader/docs/guides/workflow_reference.md

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 代码入仓

# 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 内执行）：

# 全周期回测（必须用此配置才能复现结果）
docker exec freqtrade freqtrade backtesting \
  --strategy StructureFlowStrategyV22d \
  --timerange 20210101-20260601 \
  --config /freqtrade/user_data/config.backtest.json \
  --export trades

逐年回测：

# 逐年独立执行
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

回测结果归档：

# 将结果复制到仓库
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 发布部署

# 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）

# 查看当前 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：

# 每小时导出交易记录
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 操作

# 克隆仓库
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 操作

# 查看运行容器
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 管理

# 重启 Gitea
sudo systemctl restart gitea

# 查看 Gitea 状态
sudo systemctl status gitea

# 查看 Gitea 日志
sudo tail -f /var/lib/gitea/log/gitea.log

回测

# 全周期
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。

---

七、首次使用（新机器）

如果你在新电脑上工作，需要先克隆仓库：

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 只做研发和设计，不参与线上调度