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