# 交易系统部署说明（Gate USDT 永续 · PM2）

## 1. 系统概要

本系统是基于 Python 的云端监控服务，仅使用 **Gate.io** 交易所公共 API（REST v4）。

- 监控市场：Gate **USDT 本位线性永续**（合约名如 `BTC_USDT`）
- 方向：策略支持多空信号；企业微信推送文案随信号方向变化
- 周期：监控主循环固定 **5m**
- 信号分级：WATCH / TRIGGER
- 数据：`/futures/usdt/contracts`、`/tickers`、`/candlesticks`

## 2. 当前策略（摘要）

- WATCH：横盘结构成立
- TRIGGER：横盘 + 5m 收盘突破边界 + 放量
- 可调参数：横盘时长、振幅、放量倍数、回看根数、缓冲（见 Web 面板 / SQLite `kv_store`）

## 3. config.yaml 示例

```yaml
app:
  host: 0.0.0.0
  port: 8088
  poll_interval_seconds: 300
  log_file: ./runtime/system.log
  database_url: sqlite+aiosqlite:///./runtime/alerts.db
  session_secret: please-replace-with-strong-random-value

auth:
  username: admin
  password: ChangeThisPassword!

wecom:
  webhook: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=replace
  mentioned_mobile_list: []

gate:
  api_base: https://api.gateio.ws/api/v4
  settle: usdt
  quote_currency: USDT

monitor:
  universe: all_swaps
  min_24h_quote_volume_usdt: 10000000

watch_symbols: []

# 可选：与并列项目 gate_order_executor 联动（企微推送成功后再 POST /v1/signal）
order_executor:
  enabled: false
  base_url: "http://127.0.0.1:8090"
  webhook_secret: "same-as-executor-security-webhook_secret"
  timeout_seconds: 15
```

### 3.1 企微与自动下单

- 默认仅 **企业微信** 文本告警。若部署 **gate_order_executor** 并设置 `order_executor.enabled: true`、**`webhook_secret` 与执行器一致**，则在 **企微推送成功之后** 自动向执行器发结构化信号（方案 A 止盈/止损与企微文案一致）。
### 3.2 执行器联调（curl，无面板按钮）

并列项目 **`gate_order_executor`** 的 Web 面板 **不再提供**「拉取余额 / 测试市价」入口；需在服务器用 **`curl`** 或脚本调用 **`POST /api/test`**、**`POST /v1/test`** 做联调（`micro_market` 须 `gate.test_orders_enabled: true`）。**完整命令与鉴权说明**见 **`gate_order_executor/docs/使用说明.md` §4.1** 与 **`gate_order_executor/docs/部署说明.md` §11**。

## 4. 云端部署（Python venv + PM2，推荐）

以下以 Ubuntu/Debian、项目路径 `/root/onchain_scout_gate` 为例：

### 4.1 系统依赖

```bash
apt update && apt install -y python3 python3-pip python3-venv curl
```

安装 Node.js（用于 PM2），参见 NodeSource 或发行版自带 `nodejs` / `npm`。

```bash
npm install -g pm2
```

### 4.2 上传项目

将项目放到 `/root/onchain_scout_gate`（包含 `app/`、`requirements.txt`、`deploy/ecosystem.config.cjs`）。

### 4.3 虚拟环境与 Python 依赖

```bash
cd /root/onchain_scout_gate && \
python3 -m venv .venv && \
source .venv/bin/activate && \
python -m pip install -U pip && \
pip install -r requirements.txt
```

### 4.4 配置文件

```bash
nano /root/onchain_scout_gate/config.yaml
```

至少修改：`auth`、`session_secret`、`wecom.webhook`、`monitor`。**旧版 `okx:` 配置需改为 `gate:`**（见上方示例）。

### 4.5 PM2 启动与自检

在项目根目录执行：

```bash
cd /root/onchain_scout_gate
pm2 start deploy/ecosystem.config.cjs
pm2 logs onchain-scout
```

验证：浏览器访问 `http://服务器IP:8088`（端口以 `config.yaml` 为准）。

常用运维：

```bash
pm2 restart onchain-scout
pm2 save
pm2 startup   # 按提示配置开机自启
```

日志：`runtime/system.log`（应用轮转日志）、`runtime/pm2-out.log` / `runtime/pm2-error.log`（PM2）。

## 5. 前台调试（非守护）

便于排查问题时临时使用：

```bash
cd /root/onchain_scout_gate && source .venv/bin/activate && \
python -m app.main
```

或：`uvicorn app.main:app --host 0.0.0.0 --port 8088 --workers 1`

## 6. systemd（可选）

若希望用 systemd 托管 **pm2-runtime**（保持进程在前台供 systemd 监控），可复制并修改 `deploy/onchain-scout.service` 中的路径与 `ExecStart`。**生产环境更常见做法是仅用 PM2 自带的 `pm2 startup`。**

## 7. 多执行器转发（Web 面板维护）

同一套突破信号可向 **多个** `gate_order_executor` 广播（对照实验：各执行器自行配置盈亏比、仓位等）。

| 部署 | 操作 |
|------|------|
| **单账户** | 面板「下单执行器」中保留 **1 条** Base URL（如 `http://127.0.0.1:8090`） |
| **多账户** | 添加多条 URL（如 `:8090`、`:8091`），各进程绑定不同 Gate API |
| **暂停某一账户** | 将该条设为「停用」，或关闭总开关 |
| **Webhook** | 面板保存的密钥须与各执行器 `security.webhook_secret` **一致**（改后需同步执行器 config） |

- 列表保存在 `runtime/order_executors.json`，**仅扫描端维护**，执行器不会反向注册。
- 转发请求 **不走** `proxy`，直连 `base_url`（同机可用 `127.0.0.1`）。
- 详细设计见 `docs/多执行器与信号转发归档.md`。

## 8. 云服务器：关闭代理

本机开发若使用 Clash 等 SOCKS（`proxy.enabled: true`），迁到 **可直连 Gate 的境外云主机** 后应关闭代理。

### 8.1 扫描端 `config.yaml`

```yaml
proxy:
  enabled: false
  url: "socks5h://127.0.0.1:1080"   # enabled=false 时可保留
```

修改后：`pm2 restart onchain-scout`（或你的 PM2 应用名）。

**说明：**

- `proxy` 仅影响 **Gate 行情** 请求；企业微信、转发执行器均为 **直连**。
- 自检：`curl -I --max-time 15 https://api.gateio.ws` 成功后再关代理。

### 8.2 执行器 `gate_order_executor/config.yaml`（每个实例）

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

每个执行器进程改完后分别 `pm2 restart gate-order-executor`（多实例用不同应用名/端口）。

### 8.3 同机典型拓扑

```text
onchain_scout_gate :8088   proxy.enabled: false
gate_order_executor :8090  账户 A
gate_order_executor :8091  账户 B（第二份目录或第二 PM2 应用）
```

面板两条 Base URL 指向上述地址即可。

## 9. 常见问题

| 现象 | 处理 |
|------|------|
| `配置文件校验失败` / 缺少 `gate` | 将 `config.yaml` 中 `okx:` 改为本文 §3 的 `gate:` 段 |
| ModuleNotFoundError | 进入 `.venv` 后执行 `pip install -r requirements.txt` |
| 拉不到行情 | 检查网络、`proxy`、防火墙；可选 `curl -I https://api.gateio.ws` |
| 限流 / 周期过长 | 增大 `poll_interval_seconds` 或提高 `min_24h_quote_volume_usdt` |
| 有 TRIGGER 但未下单 | 看面板执行器总开关、列表是否为空、webhook 是否一致；查运行日志 `order_executor_*` |

## 10. 运维建议

- 公网建议 Nginx 反代 + HTTPS，8088 仅内网暴露。
- 定期备份：`runtime/alerts.db`、`runtime/order_executors.json`。
- 修改 `config.yaml` 后执行 **`pm2 restart onchain-scout`**（执行器列表以面板为准，已有 `order_executors.json` 不会被 yaml 覆盖）。