docs: add strategy manual, office report, workflow design doc
This commit is contained in:
397
docs/gitea_workflow_design.md
Normal file
397
docs/gitea_workflow_design.md
Normal file
@ -0,0 +1,397 @@
|
||||
# Beast Trader — Gitea 仓库结构与自动化工作流设计
|
||||
|
||||
> 版本：v1.0 | 日期：2026-06-11 | 作者：FXY
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
Gitea 1.24.2 已部署于东京服务器（43.163.225.30:3000），库存为空，数据库为 SQLite。现有量化交易系统（freqtrade + Binance Futures）的后端基础设施已就位，需建立完整的版本管理、研发工作流和自动化运维体系。
|
||||
|
||||
---
|
||||
|
||||
## 二、仓库结构
|
||||
|
||||
### （一）总体方案：单仓库（Monorepo）
|
||||
|
||||
理由：单人使用场景下多仓库增加管理成本，且策略、回测、文档之间存在强耦合关系。
|
||||
|
||||
### （二）目录结构
|
||||
|
||||
```
|
||||
beast-trader/ # 根仓库
|
||||
│
|
||||
├── strategies/ # ── 策略代码 ──
|
||||
│ ├── current/ # 当前活跃策略（软链指向具体版本）
|
||||
│ ├── v1.6/ # 历史版本（从 versions/ 迁移）
|
||||
│ ├── v2.1/
|
||||
│ ├── v2.2b/
|
||||
│ ├── v2.2c/
|
||||
│ ├── v2.2d/ # 🔥 当前最优基线
|
||||
│ └── swing/ # 波段策略系列
|
||||
│ ├── v3.0/
|
||||
│ └── v3.1/
|
||||
│
|
||||
├── backtests/ # ── 回测结果 ──
|
||||
│ ├── full/ # 全周期回测（2021-2026）
|
||||
│ │ ├── v2_2c_full.txt
|
||||
│ │ ├── v2_2c_full.meta.json
|
||||
│ │ └── v2_2d_full.txt
|
||||
│ ├── yearly/ # 逐年回测
|
||||
│ │ ├── v2_2d_2021.txt
|
||||
│ │ ├── v2_2d_2022.txt
|
||||
│ │ └── ...
|
||||
│ └── swing/ # 波段策略回测
|
||||
│
|
||||
├── trades/ # ── 实盘交易记录（自动生成）──
|
||||
│ ├── 2026/
|
||||
│ │ ├── 06/
|
||||
│ │ │ ├── trades_2026-06-11.md
|
||||
│ │ │ ├── trades_2026-06-12.md
|
||||
│ │ │ └── ...
|
||||
│ │ └── ...
|
||||
│ ├── monthly/ # 月度汇总（自动生成）
|
||||
│ │ ├── 2026-06.md
|
||||
│ │ └── ...
|
||||
│ └── INDEX.md # 交易记录索引（自动维护）
|
||||
│
|
||||
├── daily_briefs/ # ── 日报 ──
|
||||
│ ├── 2026/
|
||||
│ │ ├── 06/
|
||||
│ │ │ ├── brief_2026-06-11.md
|
||||
│ │ │ └── ...
|
||||
│ │ └── ...
|
||||
│ └── INDEX.md
|
||||
│
|
||||
├── docs/ # ── 文档 ──
|
||||
│ ├── manual/ # 策略说明书
|
||||
│ │ ├── v2_2d_manual.pdf
|
||||
│ │ └── v2_2d_manual.html
|
||||
│ ├── reports/ # 阶段性报告
|
||||
│ │ ├── today_report_2026-06-11.md
|
||||
│ │ └── ...
|
||||
│ └── guides/ # 操作指南
|
||||
│ ├── api_deployment.md
|
||||
│ └── workflow_reference.md
|
||||
│
|
||||
├── config/ # ── 配置文件 ──
|
||||
│ ├── freqtrade/
|
||||
│ │ ├── config.json # Docker内配置（去掉密钥占位）
|
||||
│ │ ├── config.pairlist.json
|
||||
│ │ └── config.backtest.json
|
||||
│ ├── docker/
|
||||
│ │ ├── docker-compose.yml
|
||||
│ │ └── Dockerfile
|
||||
│ └── dashboard/
|
||||
│ ├── nginx.conf
|
||||
│ └── dashboard.env
|
||||
│
|
||||
├── scripts/ # ── 自动化脚本（服务器可执行）──
|
||||
│ ├── export_trades.sh # 实盘交易导出 → git push
|
||||
│ ├── generate_brief.sh # 日报生成 → git push
|
||||
│ ├── deploy_strategy.sh # 策略部署到 Docker
|
||||
│ ├── archive_backtest.py # 回测结果自动归档
|
||||
│ └── init_gitea_repo.sh # 首次初始化脚本
|
||||
│
|
||||
├── .gitea/workflows/ # ── Gitea Actions 工作流 ──
|
||||
│ ├── deploy-on-tag.yml # tag 推送时自动部署
|
||||
│ └── daily-backup.yml # 每日自动备份
|
||||
│
|
||||
├── .gitignore
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### （三）设计原则
|
||||
|
||||
1. **按时间组织**：trades/、daily_briefs/ 按年/月两级目录自然归档
|
||||
2. **按版本归档**：strategies/ 每个版本独立子目录（延续现有原则）
|
||||
3. **自动写入，人工阅读**：实盘记录和日报是程序自动写入的，格式要规范可读
|
||||
4. **一台服务器，一套体系**：开发者 = 用户，不需要分支策略，master/main 即可
|
||||
5. **紧耦合不分离**：策略代码和它的回测结果放在不同目录但同一仓库，禁止拆分
|
||||
|
||||
---
|
||||
|
||||
## 三、完整工作流设计
|
||||
|
||||
### （一）生命周期总览
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ [研发] ──→ [回测] ──→ [评估] ──→ [发布] ──→ [实盘] ──→ [复盘] │
|
||||
│ ↑ │ │
|
||||
│ └──────────────────── 迭代 ──────────────────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### （二）各阶段详细流程
|
||||
|
||||
#### Phase 1：策略研发
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 1.1 | 在 WorkBuddy 中编写/修改策略代码 | — |
|
||||
| 1.2 | `git add strategies/current/ && git commit -m "v2.3: XXXX"` | — |
|
||||
| 1.3 | `git push` 到 Gitea | ✅ 触发 Gitea Webhook 通知 |
|
||||
|
||||
#### Phase 2：回测验证
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 2.1 | Docker 内回测：`freqtrade backtesting ...` | ✅ 可脚本化 |
|
||||
| 2.2 | 回测结果保存到 `backtests/full/` | ✅ 脚本自动写入 |
|
||||
| 2.3 | 回测结果推送到 Gitea | ✅ git push |
|
||||
|
||||
*标准回测命令（固化）：*
|
||||
```
|
||||
# 策略层 full 测试
|
||||
freqtrade backtesting --strategy StructureFlowStrategyV2_2d \
|
||||
--timerange 20210101-20260601 \
|
||||
--config /freqtrade/user_data/config.backtest.json \
|
||||
--export trades
|
||||
```
|
||||
|
||||
#### Phase 3：评估决策
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 3.1 | 查看回测结果（对比 v2.2d 基线） | — |
|
||||
| 3.2 | 决定是否部署 | — |
|
||||
| 3.3 | 如优化，回到 Phase 1；如发布，进入 Phase 4 | — |
|
||||
|
||||
#### Phase 4：代码发布（Release）
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 4.1 | 更新 `strategies/current/` 指向新版本 | — |
|
||||
| 4.2 | `git tag v2.3.0 && git push --tags` | ✅ 触发 Actions 自动部署 |
|
||||
| 4.3 | 服务器拉取 → 复制策略到 `user_data/strategies/` | ✅ Shell 脚本 |
|
||||
| 4.4 | 重启 freqtrade Docker 容器 | ✅ `docker-compose down && up -d` |
|
||||
|
||||
#### Phase 5：实盘运行
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 5.1 | freqtrade 启动 live/dry-run | — |
|
||||
| 5.2 | 每笔成交 → 自动记录到 `trades/` | ✅ 每小时 cron 导出 |
|
||||
| 5.3 | 每日日报 → Server酱推送微信 | ✅ daily_brief.py + cron |
|
||||
| 5.4 | 日报 → 推送至 Gitea | ✅ cron + git push |
|
||||
|
||||
#### Phase 6：复盘优化
|
||||
|
||||
| 步骤 | 操作 | 自动化 |
|
||||
|:---|:---|:---|
|
||||
| 6.1 | 查看 `trades/` 实盘记录 | — |
|
||||
| 6.2 | 分析盈亏分布、胜率、出场原因 | — |
|
||||
| 6.3 | 提出新思路 → 回到 Phase 1 | — |
|
||||
|
||||
---
|
||||
|
||||
## 四、自动化架构
|
||||
|
||||
### （一）总体架构图
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────┐
|
||||
│ WorkBuddy（智能调度层） │
|
||||
│ ┌──────────────┐ ┌───────────────────────┐ │
|
||||
│ │ 每日08:00读取 │ │ Webhook 接收通知 │ │
|
||||
│ │ Gitea 最新日报│ │ → 触发回测/分析 │ │
|
||||
│ └──────────────┘ └───────────────────────┘ │
|
||||
└───────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────────────────┐
|
||||
│ 东京服务器（执行层） │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||||
│ │ Cron │ │ Gitea │ │ Gitea Actions │ │
|
||||
│ │ (系统级)│ │ Webhooks │ │ （CI/CD 可选） │ │
|
||||
│ └────┬────┘ └────┬─────┘ └───────┬──────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────┐ │
|
||||
│ │ Shell 脚本层 │ │
|
||||
│ │ export_trades.sh │ generate_brief.sh │ │
|
||||
│ │ deploy.sh │ archive_results.sh │ │
|
||||
│ └────────────────────┼────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────┐ │
|
||||
│ │ Docker/Freqtrade │ │
|
||||
│ │ 实盘执行 / 回测引擎 │ │
|
||||
│ └─────────────────────────────────────────────┘ │
|
||||
└───────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### （二）Cron 任务表
|
||||
|
||||
| 任务 | 调度 | 脚本 | 功能 |
|
||||
|:---|:---|:---|:---|
|
||||
| 实盘导出 | **每小时** | `export_trades.sh` | 查 Freqtrade DB → 写入 trades/ → git commit+push |
|
||||
| 日报生成 | 每日 **23:55 UTC** | `daily_brief.py`（已有） | 现行系统，扩充写入 Gitea |
|
||||
| 日报推送 | 日报生成后 | `generate_brief.sh` | 日报文件 → git push |
|
||||
| 仓库备份 | 每日 **03:00** | `backup_repo.sh` | Gitea 内 git bundle → 备份到独立存储 |
|
||||
|
||||
### （三）实盘交易记录自动导出机制
|
||||
|
||||
这是本次设计的核心创新点。方案如下：
|
||||
|
||||
```
|
||||
Freqtrade SQLite DB
|
||||
│ tradesv3.sqlite（Docker内 /freqtrade/user_data/）
|
||||
│
|
||||
▼
|
||||
export_trades.sh（每小时 cron 执行）
|
||||
│
|
||||
├── 1. 拉取最新成交记录（自上次导出时间戳之后）
|
||||
├── 2. 格式化为 Markdown 表格
|
||||
├── 3. 写入 trades/2026/06/trades_2026-06-11.md
|
||||
├── 4. 更新 INDEX.md（追加本日记录入口）
|
||||
├── 5. git add + git commit + git push
|
||||
│
|
||||
▼
|
||||
Gitea 仓库自动更新
|
||||
```
|
||||
|
||||
**每条记录的字段：**
|
||||
|
||||
| 字段 | 说明 | 来源 |
|
||||
|:---|:---|:---|
|
||||
| 序号 | #001, #002... | 自动递增 |
|
||||
| 时间 | 入场/出场时间戳 | Freqtrade DB |
|
||||
| 方向 | 做多/做空 | Freqtrade DB |
|
||||
| 入场价 | | Freqtrade DB |
|
||||
| 出场价 | | Freqtrade DB |
|
||||
| 数量 | ETH 数量 | Freqtrade DB |
|
||||
| 盈亏 | 绝对金额（USDT） | Freqtrade DB |
|
||||
| 收益率 | % | 计算 |
|
||||
| 出场原因 | take_profit / stop_loss / trailing_stop / signal | Freqtrade DB |
|
||||
| 冷却期 | 交易后冷却剩余 | 策略上下文 |
|
||||
| 备注 | 人工填写 | 手动 |
|
||||
|
||||
**查询 SQL：**
|
||||
```sql
|
||||
SELECT id, pair, open_time, close_time, open_rate, close_rate,
|
||||
amount, close_profit, close_profit_abs, exit_reason
|
||||
FROM trades
|
||||
WHERE close_time > {last_export_timestamp}
|
||||
ORDER BY close_time ASC;
|
||||
```
|
||||
|
||||
### （四）首次初始化脚本
|
||||
|
||||
首次搭建时，需要将服务器上现有的所有文件推送到 Gitea。这需要一个一次性脚本：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# init_gitea_repo.sh — 首次初始化
|
||||
|
||||
# 1. 在 Gitea 创建仓库
|
||||
# 2. git init + 建立目录结构
|
||||
# 3. 复制现有策略文件到 strategies/
|
||||
# 4. 复制回测结果到 backtests/
|
||||
# 5. 复制文档到 docs/
|
||||
# 6. 复制配置文件到 config/
|
||||
# 7. 复制 Dashboard 代码到 dashboard/
|
||||
# 8. 首次 commit + push
|
||||
```
|
||||
|
||||
### （五）关键自动化脚本设计
|
||||
|
||||
#### 5.1 `export_trades.sh` — 实盘交易记录导出
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 每小时执行，从 Freqtrade DB 导出新成交记录到 Gitea 仓库
|
||||
|
||||
LAST_EXPORT_FILE="/var/lib/gitea/export_timestamp.txt"
|
||||
TRADES_DB="/home/ubuntu/freqtrade/user_data/tradesv3.sqlite"
|
||||
REPO_DIR="/home/ubuntu/beast-trader"
|
||||
TRADES_DIR="$REPO_DIR/trades/$(date +%Y/%m)"
|
||||
|
||||
# 1. 读取上次导出时间
|
||||
if [ -f "$LAST_EXPORT_FILE" ]; then
|
||||
LAST_TS=$(cat "$LAST_EXPORT_FILE")
|
||||
else
|
||||
LAST_TS=0
|
||||
fi
|
||||
|
||||
# 2. 查询新成交记录（需在 Docker 内或直接读 SQLite）
|
||||
# 注意：tradesv3.sqlite 在 Docker volume 内，需从宿主机访问
|
||||
# 如果 Docker 挂载了目录，可直接读取
|
||||
|
||||
# 3. 格式化写入 Markdown
|
||||
# ...
|
||||
|
||||
# 4. 更新 INDEX.md
|
||||
# ...
|
||||
|
||||
# 5. git push
|
||||
cd "$REPO_DIR" && git add . && git commit -m "trades: auto export $(date +%Y-%m-%d %H:%M)" && git push
|
||||
```
|
||||
|
||||
#### 5.2 `deploy_strategy.sh` — 策略自动部署
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 在 git tag push 后触发
|
||||
|
||||
TAG=$1 # 例如 v2.3.0
|
||||
|
||||
# 1. 从 Gitea 拉取最新代码
|
||||
cd /home/ubuntu/beast-trader && git pull
|
||||
|
||||
# 2. 将策略复制到 freqtrade 目录
|
||||
cp strategies/current/*.py /home/ubuntu/freqtrade/user_data/strategies/
|
||||
|
||||
# 3. 重启 freqtrade Docker
|
||||
cd /home/ubuntu/freqtrade && docker-compose down && docker-compose up -d
|
||||
|
||||
# 4. 记录部署版本
|
||||
echo "Deployed: $TAG at $(date)" >> deploy_history.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、实现优先级建议
|
||||
|
||||
建议分三个阶段推进：
|
||||
|
||||
### 第一阶段：数据入仓（1-2天）
|
||||
|
||||
| 优先级 | 任务 | 产出 |
|
||||
|:---|:---|:---|
|
||||
| P0 | 写好 `init_gitea_repo.sh`，将现有全部文件推送到 Gitea | Gitea 仓库完整初始化 |
|
||||
| P0 | 建立目录结构 | 目录框架 |
|
||||
| P1 | 迁移 strategies/ 下所有版本 | 版本历史完整 |
|
||||
| P1 | 迁移 backtest_results/ 下的结果 | 回测历史完整 |
|
||||
| P2 | 迁移 docs/ 说明书和报告 | 文档完整 |
|
||||
|
||||
### 第二阶段：自动化搭建（2-3天）
|
||||
|
||||
| 优先级 | 任务 | 产出 |
|
||||
|:---|:---|:---|
|
||||
| P0 | 编写 `export_trades.sh` + 配置 cron | 实盘记录每小时自动归档 |
|
||||
| P0 | 日报增加 git push 步骤 → Gitea | 日报自动入仓 |
|
||||
| P1 | 编写 `deploy_strategy.sh` | 一键部署 |
|
||||
| P1 | 实现 `scripts/archive_backtest.py` | 回测结果自动归档 |
|
||||
|
||||
### 第三阶段：工作流闭环（持续）
|
||||
|
||||
| 优先级 | 任务 | 产出 |
|
||||
|:---|:---|:---|
|
||||
| P1 | Gitea Webhook → WorkBuddy 通知 | 变更即感知 |
|
||||
| P2 | 月度交易报告自动生成 | 复盘辅助 |
|
||||
| P2 | Gitea Actions 搭建 | CI/CD 能力 |
|
||||
| P3 | 策略对比看板（Gitea Pages） | 可视化演进 |
|
||||
|
||||
---
|
||||
|
||||
## 六、附则
|
||||
|
||||
1. **密钥不入库**：Exchange API key/secret、Server酱 SendKey 等敏感信息禁止提交到 Gitea
|
||||
2. **回测数字仅供参考**：回测结果说明"过去表现好"，不代表未来收益
|
||||
3. **只增不删**：trades/ 和 daily_briefs/ 是单向录入，禁止手动删除
|
||||
4. **日志即文档**：Gitea 的 commit log 本身就是研发日志，commit message 写清楚改动内容
|
||||
Reference in New Issue
Block a user