beast-trader/docs/gitea_workflow_design.md

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：

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。这需要一个一次性脚本：

#!/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 — 实盘交易记录导出

#!/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 — 策略自动部署

#!/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 写清楚改动内容