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

交易系统部署说明（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 示例

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 系统依赖

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

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

npm install -g pm2

4.2 上传项目

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

4.3 虚拟环境与 Python 依赖

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 配置文件

nano /root/onchain_scout_gate/config.yaml

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

4.5 PM2 启动与自检

在项目根目录执行：

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

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

常用运维：

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

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

5. 前台调试（非守护）

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

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

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（每个实例）

proxy:
  enabled: false

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

8.3 同机典型拓扑

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 覆盖）。