首次上传

onchain_scout_gate/交易系统部署说明.md

@@ -0,0 +1,206 @@
+# 交易系统部署说明（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 覆盖）。