# 多执行器与信号转发 · 设计归档

本文档归档 2026-05 前后关于 **onchain_scout_gate（扫描端）** 与 **gate_order_executor（执行器）** 联动的讨论结论与已实现能力，便于后期检阅。

---

## 1. 背景与目标

| 目标 | 说明 |
|------|------|
| **一套信号** | 扫描端在企微突破推送成功后，构造 **一份** 方案 A 止盈/止损 payload |
| **多套账户** | 可向多个执行器进程广播，各绑不同 Gate API，用于盈亏比等规则的对照实验 |
| **规则在执行器** | 最低盈亏比、仓位、移动保本等 **不在扫描端** 区分，由各执行器自行配置 |
| **统一 Webhook** | 全系统使用 **同一个** `webhook_secret` |
| **仅扫描端登记** | 执行器列表 **只能** 在扫描端 Web 面板（及对应 API）维护，**禁止执行器反向注册** |

---

## 2. 架构

```mermaid
flowchart LR
  scout[onchain_scout_gate :8088]
  scout -->|1 次| wecom[企业微信]
  scout -->|同一 payload| exA[执行器 A]
  scout -->|同一 payload| exB[执行器 B]
  exA --> gateA[Gate 账户 A]
  exB --> gateB[Gate 账户 B]
```

- 转发 **不走** 扫描端 `proxy`，直连各 `base_url`（通常 `http://127.0.0.1:8090` 或内网 IP）。
- 各执行器独立进程、独立 `config.yaml`、独立 SQLite；互不通信。

---

## 3. 扫描端实现要点（已实现）

### 3.1 持久化

| 文件 | 内容 |
|------|------|
| `runtime/order_executors.json` | 总开关、`webhook_secret`、`timeout_seconds`、执行器列表 |
| `config.yaml` `order_executor` | **仅冷启动**：首次无 json 时从 `base_url` / `enabled` / `secret` 导入一条 |

之后以 **面板修改** 为准；改 `config.yaml` **不会** 覆盖已有 json。

### 3.2 执行器列表字段

| 字段 | 说明 |
|------|------|
| `id` | UUID |
| `name` | 展示名（日志、面板） |
| `base_url` | 如 `http://127.0.0.1:8090` |
| `enabled` | 单条开关 |
| `last_forward` | 最近一次转发结果（HTTP、exec_status） |

### 3.3 HTTP API（需登录）

| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/api/order-executors` | 读取完整配置 |
| PUT | `/api/order-executors/settings` | 总开关、webhook_secret、timeout |
| POST | `/api/order-executors` | 新增 |
| PATCH | `/api/order-executors/{id}` | 改名称/URL/启用 |
| DELETE | `/api/order-executors/{id}` | 删除 |

### 3.4 转发逻辑

1. `build_order_executor_payload()` 仍只构建 **一次**（与企微方案 A 一致）。
2. 对 `enabled=true` 的列表项 **并行** `POST {base_url}/v1/signal`。
3. **同一 `signal_id`** 发往所有目标。
4. 部分失败只记日志，不阻断其他执行器。

### 3.5 Web 面板

路径：Dashboard → **「下单执行器 · 转发链」**

- 总开关、Webhook 密钥（可改）、超时
- 添加 / 启用 / 停用 / 删除
- 展示上次转发状态

### 3.6 代码模块

| 文件 | 职责 |
|------|------|
| `app/order_executors_store.py` | 读写 json、CRUD |
| `app/order_executor_forward.py` | 构建 payload、多路 POST |
| `app/monitor.py` | 企微成功后调用转发 |
| `app/web.py` | API + 启动时 `ensure_store_initialized` |

---

## 4. 执行器侧（gate_order_executor）

本次 **未改** 执行器业务代码。多账户 = 多实例部署：

| 实例 | 典型差异 |
|------|----------|
| 目录/PM2 名 | 两份 `gate_order_executor` |
| `app.port` | 8090 / 8091 |
| `gate.api_key/secret` | 不同子账户 |
| `security.webhook_secret` | 与扫描端面板 **相同** |
| `risk.*`、移动保本 | 各实例自行实验 |

另见执行器仓库已实现的 **移动保本**（1R 拉至开仓价±0.2%、面板开关、`breakeven_prefs` 等），与多路转发正交。

---

## 5. 部署套数怎么选

| 场景 | 面板操作 |
|------|----------|
| 单账户 | 列表 **1 条** URL |
| 双账户对照 | **2 条** URL，各指向不同端口/机器 |
| 临时只跑一套 | 另一条 `enabled: false` 或关总开关 |
| 完全停止自动下单 | 总开关 `enabled: false` |

---

## 6. 盈亏比对照实验（用法）

1. 扫描端产生同一 `signal_id`、同一 TP/SL。
2. 执行器 A：`min_reward_risk_ratio = 1.3` → 可能 `accepted`。
3. 执行器 B：`min_reward_risk_ratio = 1.8` → 可能 `skipped` / `reward_risk_below_min`。
4. 分别在两个执行器面板「信号流」与 Gate 平仓统计中对比结果。

---

## 7. 云服务器关闭代理

### 7.1 何时关闭

- **本机 + 本地 SOCKS**：`proxy.enabled: true`
- **境外云、可直连 Gate**：`proxy.enabled: false`

### 7.2 扫描端

```yaml
proxy:
  enabled: false
```

仅影响 **Gate 行情**；企微、转发执行器本就直连。

### 7.3 执行器（每个实例）

```yaml
proxy:
  enabled: false
```

影响 Gate 下单/查仓及（若开启）企微出站。

### 7.4 自检

```bash
curl -I --max-time 15 https://api.gateio.ws
```

### 7.5 文档索引

- `onchain_scout_gate/交易系统部署说明.md` §7、§8
- `onchain_scout_gate/docs/本地部署-SOCKS5代理.md`（本地 SOCKS）
- `gate_order_executor/docs/部署说明.md` §6.1

---

## 8. 日志关键字

扫描端运行日志（面板「运行日志」或 `runtime/system.log`）：

| 日志前缀 | 含义 |
|----------|------|
| `order_executor_ok name=...` | 该执行器 HTTP 成功 |
| `order_executor_failed name=...` | HTTP 或业务失败 |
| `order_executor_no_active_targets` | 总开关开但无启用条目 |
| `webhook_secret is empty` | 未配置密钥 |

---

## 9. 安全与约束

- **Webhook 密钥** 在面板修改后，须手动同步到 **每一个** 执行器 `security.webhook_secret`。
- **勿** 将执行器 `8090/8091` 对公网裸奔；建议仅本机或内网 + 防火墙。
- 执行器 **不会** 也 **不能** 向扫描端注册；避免运维混乱。

---

## 10. 变更记录

| 日期 | 内容 |
|------|------|
| 2026-05 | 多执行器运行时存储、面板 CRUD、并行广播、部署与代理文档 |

---

## 11. 相关路径速查

```text
onchain_scout_gate/
  runtime/order_executors.json    # 执行器列表（面板写入）
  app/order_executors_store.py
  app/order_executor_forward.py
  templates/dashboard.html        # 「下单执行器」区块
  static/app.js

gate_order_executor/              # 多实例部署，代码无需为多账户改动
  config.yaml                     # 每实例独立 API / risk / proxy
```