首次上传

2026-05-16 22:25:48 +08:00
commit 2b8f902548
88 changed files with 16386 additions and 0 deletions
@@ -0,0 +1,428 @@
+# gate_scout_order · 完整部署说明
+
+本文档面向 **Linux 云服务器（Ubuntu / Debian）** 从零部署 **扫描端 + 下单执行器**，仓库地址：
+
+**https://git.bz121.com/dekun/gate_scout_order.git**
+
+（Gitea 私有仓库：[dekun/gate_scout_order](https://git.bz121.com/dekun/gate_scout_order)）
+
+---
+
+## 目录
+
+1. [系统架构](#1-系统架构)
+2. [升级前备份（已在跑旧版必读）](#2-升级前备份已在跑旧版必读)
+3. [服务器环境准备](#3-服务器环境准备)
+4. [克隆代码](#4-克隆代码)
+5. [部署扫描端 onchain_scout_gate](#5-部署扫描端-onchain_scout_gate)
+6. [部署执行器 gate_order_executor](#6-部署执行器-gate_order_executor)
+7. [扫描端与执行器串联](#7-扫描端与执行器串联)
+8. [多执行器 / 多账户](#8-多执行器--多账户)
+9. [云服务器关闭代理](#9-云服务器关闭代理)
+10. [日常运维与升级](#10-日常运维与升级)
+11. [防火墙与安全](#11-防火墙与安全)
+12. [故障速查](#12-故障速查)
+
+---
+
+## 1. 系统架构
+
+```text
+/opt/gate_scout_order/                    ← git clone 根目录
+├── onchain_scout_gate/                   ← 扫描端  :8088
+│   ├── config.yaml                       ← 本地配置（不入库）
+│   └── runtime/
+│       ├── alerts.db                     ← 告警、面板策略参数
+│       └── order_executors.json          ← 执行器转发列表（面板维护）
+└── gate_order_executor/                  ← 执行器  :8090（可多实例）
+    ├── config.yaml
+    └── runtime/
+        ├── signals.sqlite                ← 信号流 / 执行结果
+        ├── risk_prefs.json               ← 面板「最低盈亏比」
+        ├── breakeven_prefs.json          ← 移动保本开关
+        └── breakeven_active.json         ← 移动保本运行态
+```
+
+| 服务 | PM2 名称 | 默认端口 | 作用 |
+|------|----------|----------|------|
+| 扫描端 | `onchain-scout` | 8088 | Gate 5m 监控、企微告警、向执行器 POST 信号 |
+| 执行器 | `gate-order-executor` | 8090 | 接信号、Gate 下单、止盈止损、移动保本 |
+
+---
+
+## 2. 升级前备份（已在跑旧版必读）
+
+若你 **之前已在服务器上运行** 扫描端和/或执行器（目录可能是 `/root/onchain_scout_gate`、`/root/gate_order_executor` 等），在 **停进程、拉新代码或改目录** 之前，请先备份下列文件。**`config.yaml` 与 `runtime/` 不会进 Git**，丢失后需重新填密钥并丢失历史记录。
+
+### 2.1 必须备份（丢失难恢复）
+
+| 来源目录 | 文件 | 内容 |
+|----------|------|------|
+| **扫描端** `onchain_scout_gate/` | `config.yaml` | 企微 Webhook、auth 密码、`session_secret`、proxy、monitor 等 |
+| **扫描端** | `runtime/alerts.db` | 历史告警、**Web 面板写入的策略参数**（横盘/放量/黑名单/晨报开关等 SQLite KV） |
+| **扫描端** | `runtime/order_executors.json` | **执行器转发列表**、总开关、面板里的 Webhook 密钥（若已用面板配置） |
+| **执行器** `gate_order_executor/` | `config.yaml` | Gate `api_key` / `api_secret`、`webhook_secret`、`dry_run`、风险参数等 |
+| **执行器** | `runtime/signals.sqlite` | **信号流与每笔下单结果**（面板导出/对账） |
+| **执行器** | `runtime/risk_prefs.json` | 面板保存的 **最低盈亏比**（覆盖 config 默认） |
+| **执行器** | `runtime/breakeven_prefs.json` | **移动保本** 全局/单合约开关 |
+| **执行器** | `runtime/breakeven_active.json` | 当前持仓的移动保本登记态（entry、initial_sl、是否已拉保本） |
+
+### 2.2 建议备份（便于排障）
+
+| 来源 | 文件 |
+|------|------|
+| 扫描端 | `runtime/system.log` |
+| 扫描端 | `runtime/pm2-out.log`、`runtime/pm2-error.log` |
+| 执行器 | `runtime/executor.log` |
+| 执行器 | `runtime/pm2-executor-out.log`、`runtime/pm2-executor-error.log` |
+
+### 2.3 一键打包示例（按你实际旧路径改）
+
+```bash
+BACKUP_DIR=/root/backup_gate_$(date +%Y%m%d_%H%M%S)
+mkdir -p "$BACKUP_DIR"
+
+# 若旧版扫描端在此路径：
+OLD_SCOUT=/root/onchain_scout_gate
+if [ -d "$OLD_SCOUT" ]; then
+  mkdir -p "$BACKUP_DIR/onchain_scout_gate"
+  cp -a "$OLD_SCOUT/config.yaml" "$BACKUP_DIR/onchain_scout_gate/" 2>/dev/null || true
+  cp -a "$OLD_SCOUT/runtime" "$BACKUP_DIR/onchain_scout_gate/" 2>/dev/null || true
+fi
+
+# 若旧版执行器在此路径：
+OLD_EXEC=/root/gate_order_executor
+if [ -d "$OLD_EXEC" ]; then
+  mkdir -p "$BACKUP_DIR/gate_order_executor"
+  cp -a "$OLD_EXEC/config.yaml" "$BACKUP_DIR/gate_order_executor/" 2>/dev/null || true
+  cp -a "$OLD_EXEC/runtime" "$BACKUP_DIR/gate_order_executor/" 2>/dev/null || true
+fi
+
+# 若已是 monorepo 子目录：
+NEW_ROOT=/opt/gate_scout_order
+if [ -d "$NEW_ROOT/onchain_scout_gate" ]; then
+  mkdir -p "$BACKUP_DIR/monorepo_scout"
+  cp -a "$NEW_ROOT/onchain_scout_gate/config.yaml" "$BACKUP_DIR/monorepo_scout/" 2>/dev/null || true
+  cp -a "$NEW_ROOT/onchain_scout_gate/runtime" "$BACKUP_DIR/monorepo_scout/" 2>/dev/null || true
+fi
+if [ -d "$NEW_ROOT/gate_order_executor" ]; then
+  mkdir -p "$BACKUP_DIR/monorepo_executor"
+  cp -a "$NEW_ROOT/gate_order_executor/config.yaml" "$BACKUP_DIR/monorepo_executor/" 2>/dev/null || true
+  cp -a "$NEW_ROOT/gate_order_executor/runtime" "$BACKUP_DIR/monorepo_executor/" 2>/dev/null || true
+fi
+
+echo "备份完成: $BACKUP_DIR"
+ls -la "$BACKUP_DIR"
+```
+
+### 2.4 停旧进程
+
+```bash
+pm2 stop onchain-scout gate-order-executor 2>/dev/null || true
+pm2 delete onchain-scout gate-order-executor 2>/dev/null || true
+pm2 save
+```
+
+### 2.5 新目录恢复配置
+
+克隆新仓库后，将备份 **拷回对应子目录**（不要覆盖新代码，只覆盖 `config.yaml` 和 `runtime/`）：
+
+```bash
+# 示例：从备份恢复到新 clone 路径
+NEW=/opt/gate_scout_order
+cp -a /root/backup_gate_xxxx/onchain_scout_gate/config.yaml "$NEW/onchain_scout_gate/"
+cp -a /root/backup_gate_xxxx/onchain_scout_gate/runtime/* "$NEW/onchain_scout_gate/runtime/"
+
+cp -a /root/backup_gate_xxxx/gate_order_executor/config.yaml "$NEW/gate_order_executor/"
+cp -a /root/backup_gate_xxxx/gate_order_executor/runtime/* "$NEW/gate_order_executor/runtime/"
+```
+
+恢复后执行 `git pull` 时 **不要** 用 `git checkout -- runtime/` 覆盖业务数据。
+
+---
+
+## 3. 服务器环境准备
+
+```bash
+sudo apt update && sudo apt install -y python3 python3-venv python3-pip curl git
+
+# Node.js + PM2（任选一种安装 Node 的方式）
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+sudo npm install -g pm2
+
+# 验证 Gate 网络（云主机通常直连即可）
+curl -I --max-time 15 https://api.gateio.ws
+```
+
+建议部署路径（可自定）：
+
+```text
+/opt/gate_scout_order
+```
+
+---
+
+## 4. 克隆代码
+
+### 4.1 HTTPS（常用）
+
+```bash
+sudo mkdir -p /opt
+cd /opt
+git clone https://git.bz121.com/dekun/gate_scout_order.git gate_scout_order
+cd gate_scout_order
+```
+
+私有仓库会提示输入 Gitea **用户名 + 密码**（或 Personal Access Token）。
+
+### 4.2 SSH（已配置公钥时）
+
+```bash
+cd /opt
+git clone git@git.bz121.com:dekun/gate_scout_order.git gate_scout_order
+cd gate_scout_order
+```
+
+### 4.3 首次推送代码到空仓库（仅维护者）
+
+若远程仍为空仓库，在开发机仓库根目录：
+
+```bash
+git remote add origin https://git.bz121.com/dekun/gate_scout_order.git
+git branch -M main
+git push -u origin main
+```
+
+---
+
+## 5. 部署扫描端 onchain_scout_gate
+
+```bash
+cd /opt/gate_scout_order/onchain_scout_gate
+chmod +x deploy/*.sh
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -r requirements.txt
+
+# 若无 config.yaml（升级已从备份恢复则跳过）
+cp config.example.yaml config.yaml
+chmod 600 config.yaml
+nano config.yaml
+```
+
+**`config.yaml` 至少修改：**
+
+| 项 | 说明 |
+|----|------|
+| `app.session_secret` | 随机长字符串 |
+| `auth.username` / `auth.password` | 面板登录 |
+| `wecom.webhook` | 企业微信群机器人 URL |
+| `proxy.enabled` | 云服务器能直连 Gate 时设为 **`false`**（见 §9） |
+| `monitor.*` | 成交额门槛、universe 等 |
+
+**启动 PM2：**
+
+```bash
+cd /opt/gate_scout_order/onchain_scout_gate
+source .venv/bin/activate
+pm2 start deploy/ecosystem.config.cjs
+pm2 save
+```
+
+验证：`http://服务器IP:8088/dashboard`（端口以 `config.yaml` 的 `app.port` 为准）。
+
+```bash
+pm2 logs onchain-scout
+```
+
+---
+
+## 6. 部署执行器 gate_order_executor
+
+```bash
+cd /opt/gate_scout_order/gate_order_executor
+chmod +x deploy/*.sh
+bash deploy/bootstrap.sh /opt/gate_scout_order/gate_order_executor
+
+nano config.yaml   # 或从备份恢复后再改
+```
+
+**`config.yaml` 至少修改：**
+
+| 项 | 说明 |
+|----|------|
+| `security.webhook_secret` | 与扫描端面板/Webhook 一致 |
+| `app.session_secret` | 随机长字符串 |
+| `auth` | 对外暴露时 `enabled: true` |
+| `gate.api_key` / `gate.api_secret` | Gate 子账户 API（建议 IP 白名单） |
+| `gate.dry_run` | 联调 **`true`**，验证后再改 **`false`** |
+| `proxy.enabled` | 云主机通常 **`false`** |
+| `app.host` | 仅本机扫描调用可 `127.0.0.1`；远程看面板用 `0.0.0.0` |
+
+**启动 PM2：**
+
+```bash
+cd /opt/gate_scout_order/gate_order_executor
+bash deploy/pm2-start.sh
+pm2 save
+```
+
+验证：
+
+```bash
+curl -s http://127.0.0.1:8090/health
+# 面板：http://服务器IP:8090/dashboard
+pm2 logs gate-order-executor
+```
+
+---
+
+## 7. 扫描端与执行器串联
+
+1. 两边的 `webhook_secret` 一致（扫描端以 **面板「下单执行器」** 保存为准，会写入 `runtime/order_executors.json`）。
+2. 打开扫描端面板 → **「下单执行器 · 转发链」**：
+   - 打开 **总开关**
+   - 填写 **Webhook 密钥**（与各执行器 `security.webhook_secret` 相同）
+   - **添加执行器**：名称随意，Base URL 填 `http://127.0.0.1:8090`（同机）
+3. 执行器 `gate.dry_run: false` 且 API 有效后，企微 **TRIGGER 推送成功** 才会向执行器 POST `/v1/signal`。
+4. 转发 **不走** 扫描端 proxy，直连 `base_url`。
+
+联调执行器（可选）：
+
+```bash
+curl -s -X POST "http://127.0.0.1:8090/v1/test" \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Secret: 你的密钥" \
+  -d '{"action":"balance"}'
+```
+
+详见 [gate_order_executor/docs/使用说明.md](gate_order_executor/docs/使用说明.md) §4.1。
+
+---
+
+## 8. 多执行器 / 多账户
+
+| 目标 | 做法 |
+|------|------|
+| 单账户 | 扫描面板只保留 **1 条** URL（`:8090`） |
+| 两账户对照实验 | 再部署一份执行器（不同目录或同目录改 `app.port: 8091`），面板添加第二条 URL |
+| 暂停某一账户 | 面板将该执行器设为「停用」 |
+
+每个执行器实例需要：
+
+- 独立 `config.yaml`（不同 Gate API）
+- 独立 `runtime/`（尤其 `signals.sqlite`、移动保本状态）
+- 独立 PM2 应用名（复制 `ecosystem.config.cjs` 并改 `name`、端口）
+
+扫描端仍只维护 **一份** `order_executors.json`。
+
+设计说明：[onchain_scout_gate/docs/多执行器与信号转发归档.md](onchain_scout_gate/docs/多执行器与信号转发归档.md)
+
+---
+
+## 9. 云服务器关闭代理
+
+本机开发常用 `proxy.enabled: true` + 本地 SOCKS；**境外云主机**在能 `curl` 通 Gate 后应关闭：
+
+**扫描端** `onchain_scout_gate/config.yaml`：
+
+```yaml
+proxy:
+  enabled: false
+```
+
+**执行器** `gate_order_executor/config.yaml`（每个实例都要改）：
+
+```yaml
+proxy:
+  enabled: false
+```
+
+```bash
+pm2 restart onchain-scout
+pm2 restart gate-order-executor
+```
+
+---
+
+## 10. 日常运维与升级
+
+### 10.1 拉取新代码
+
+```bash
+cd /opt/gate_scout_order
+git pull
+```
+
+### 10.2 更新依赖并重启
+
+```bash
+cd /opt/gate_scout_order/onchain_scout_gate
+source .venv/bin/activate && pip install -r requirements.txt
+pm2 restart onchain-scout
+
+cd /opt/gate_scout_order/gate_order_executor
+source .venv/bin/activate && pip install -r requirements.txt
+bash deploy/pm2-restart.sh
+```
+
+### 10.3 定期备份（建议 cron 每周）
+
+```bash
+BACKUP=/root/backup_gate_weekly/$(date +%Y%m%d)
+mkdir -p "$BACKUP"
+cp -a /opt/gate_scout_order/onchain_scout_gate/config.yaml "$BACKUP/scout_config.yaml"
+cp -a /opt/gate_scout_order/onchain_scout_gate/runtime/alerts.db "$BACKUP/"
+cp -a /opt/gate_scout_order/onchain_scout_gate/runtime/order_executors.json "$BACKUP/" 2>/dev/null || true
+cp -a /opt/gate_scout_order/gate_order_executor/config.yaml "$BACKUP/executor_config.yaml"
+cp -a /opt/gate_scout_order/gate_order_executor/runtime/signals.sqlite "$BACKUP/"
+cp -a /opt/gate_scout_order/gate_order_executor/runtime/risk_prefs.json "$BACKUP/" 2>/dev/null || true
+cp -a /opt/gate_scout_order/gate_order_executor/runtime/breakeven_prefs.json "$BACKUP/" 2>/dev/null || true
+cp -a /opt/gate_scout_order/gate_order_executor/runtime/breakeven_active.json "$BACKUP/" 2>/dev/null || true
+```
+
+### 10.4 PM2 开机自启
+
+```bash
+pm2 startup
+# 按提示执行 sudo 命令
+pm2 save
+```
+
+---
+
+## 11. 防火墙与安全
+
+- 执行器若仅本机扫描调用：`app.host: 127.0.0.1`，**不要**对公网开放 8090。
+- 需外网访问面板：`0.0.0.0` + **防火墙白名单** + `auth.enabled: true`，建议 Nginx HTTPS 反代。
+- `chmod 600` 各子项目的 `config.yaml`。
+- **勿** 将含 API Key 的 config 或 `runtime/*.db` 提交到 Git。
+
+---
+
+## 12. 故障速查
+
+| 现象 | 处理 |
+|------|------|
+| `git clone` 403 / 认证失败 | 检查 Gitea 账号、Token；或改用 SSH |
+| 扫描端拉不到行情 | `proxy`、防火墙；`curl -I https://api.gateio.ws` |
+| 有 TRIGGER 未下单 | 面板执行器总开关、列表为空、webhook 不一致；日志搜 `order_executor_` |
+| 执行器 401 | `X-Webhook-Secret` 与配置不一致 |
+| 升级后面板策略丢了 | 是否未恢复 `runtime/alerts.db` |
+| 信号流空了 | 是否未恢复 `runtime/signals.sqlite` |
+| PM2 反复重启 | `pm2 logs`；检查 `config.yaml` 校验、端口占用 |
+
+---
+
+## 相关文档
+
+| 文档 | 路径 |
+|------|------|
+| 仓库总览 | [README.md](README.md) |
+| Git 克隆摘要 | [CLONE.md](CLONE.md) |
+| 扫描端专题 | [onchain_scout_gate/交易系统部署说明.md](onchain_scout_gate/交易系统部署说明.md) |
+| 执行器专题 | [gate_order_executor/docs/部署说明.md](gate_order_executor/docs/部署说明.md) |
+| 多执行器归档 | [onchain_scout_gate/docs/多执行器与信号转发归档.md](onchain_scout_gate/docs/多执行器与信号转发归档.md) |