gate_scout_order/部署说明.md

# 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. 服务器环境准备

> **Python 版本**：项目要求 **3.9～3.12**（不支持 3.8）。Ubuntu 20.04 默认 `python3` 为 3.8，请安装 `python3.9` 或更高版本，详见 **[Python3.9部署说明.md](Python3.9部署说明.md)**。

```bash
sudo apt update && sudo apt install -y python3.9 python3.9-venv python3.9-dev 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.9～3.12（见 Python3.9部署说明.md）
bash deploy/bootstrap.sh /opt/gate_scout_order/onchain_scout_gate

# 或手动（Ubuntu 20.04 务必用 python3.9，不要用默认 python3）：
# python3.9 -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
```

日常 **手动** 备份与恢复（路径 `/opt/gate_scout_order` → `/root`）：见 **[备份恢复说明.md](备份恢复说明.md)**。

### 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` |
| `matplotlib` / `str \| None` / Pydantic 注解报错 | Python 版本低于 3.9 或 venv 用错；见 **[Python3.9部署说明.md](Python3.9部署说明.md)** |
| 有 TRIGGER 未下单 | 面板执行器总开关、列表为空、webhook 不一致；日志搜 `order_executor_` |
| 执行器 401 | `X-Webhook-Secret` 与配置不一致 |
| 升级后面板策略丢了 | 是否未恢复 `runtime/alerts.db` |
| 信号流空了 | 是否未恢复 `runtime/signals.sqlite` |
| PM2 反复重启 | `pm2 logs`；检查 `config.yaml` 校验、端口占用 |

---

## 13. 接入本地导航（LocalNav）

**扫描端 / 执行器一般在本仓库所在云服务器**；办公室或家里的 [LocalNav](https://git.bz121.com/dekun/LocalNav) 通过 HTTPS 链接触发 iframe 内嵌（不是把 gate_scout 装在本机）。

| 服务 | 云主机端口 | 面板路径 |
|------|------------|----------|
| 扫描端 | 8088 | `/dashboard` |
| 执行器 | 8090 | `/dashboard` |

**云上（PM2 / systemd 环境变量）** — 允许本地导航页嵌入（**不要写进 config.yaml**）：

```bash
# PM2：编辑 deploy/ecosystem.config.cjs 的 env 段，然后 pm2 restart ...
NAV_ALLOW_EMBED=true
NAV_EMBED_ORIGINS=http://192.168.8.6:5070
```

**本机 LocalNav `.env`** — 指向云地址（子域名反代示例）：

```env
NAV_SEED_GATE_SCOUT=1
NAV_GATE_SCOUT_UPDATE=1
NAV_GATE_SCOUT_SCHEME=https
NAV_GATE_SCOUT_SCOUT_HOST=scout.example.com
NAV_GATE_EXECUTOR_HOST=exec.example.com
NAV_GATE_SCOUT_PORT=443
NAV_GATE_EXECUTOR_PORT=443
```

重启 LocalNav 后左侧出现 **「Gate 扫单」**。若之前误配成 `127.0.0.1`，设 `NAV_GATE_SCOUT_UPDATE=1` 再重启即可覆盖。

公网须 **Nginx HTTPS 反代** + `auth.enabled: true`；**不要**对公网裸奔 8088/8090。

---

## 相关文档

| 文档 | 路径 |
|------|------|
| 仓库总览 | [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) |