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