dekun
4585dba3c3
Settings toggle, Plan panel, Fleet monitor, exit locks and armed TOCTOU gates; docs and dual audits. Co-authored-by: Cursor <cursoragent@cursor.com>
170 lines
7.9 KiB
Markdown
170 lines
7.9 KiB
Markdown
# 中控（Fleet Control）使用说明
|
||
|
||
中控与策略机在**同一仓库**（`eth_hedge_sim`），**独立进程**部署。中控通常跑在**本地局域网服务器**，**不访问交易所**；只通过专用 API Token 对多台策略机做：状态监控、启停、远程更新代码、免密进入策略页。
|
||
|
||
建议策略机与中控使用**同一 git 版本**（同 `main` / 同 tag），避免 `/api/fleet/*` 接口漂移。
|
||
|
||
---
|
||
|
||
## 1. 架构
|
||
|
||
```text
|
||
本地中控 (5160) 云端策略机 × N (5155)
|
||
┌─────────────────┐ ┌──────────────────┐
|
||
│ control 前端/后端 │──X-Fleet-Token──│ eth-hedge-api │
|
||
│ 不连交易所 │──SSH 无需主路径──│ OKX/币安交易密钥 │
|
||
└─────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
| 组件 | 端口 | PM2 名 | 代码目录 | 配置 |
|
||
|------|------|--------|----------|------|
|
||
| 策略机（槽位 1） | 5155 | `eth-hedge-api` | `/opt/eth_hedge_sim` | 该目录 `.env` |
|
||
| 策略机（槽位 2，可选） | 5156 | `eth-hedge-api-2` | `/opt/eth_hedge_sim_2` | 独立 `.env` / SQLite |
|
||
| 策略机（槽位 3，可选） | 5157 | `eth-hedge-api-3` | `/opt/eth_hedge_sim_3` | 独立 `.env` / SQLite |
|
||
| 中控 | 5160 | `eth-hedge-control` | `control/backend` + `control/frontend` | 仓库根 `.env.control` |
|
||
|
||
中控浏览器**不直连**策略机 API（避免跨域与密钥进前端）；一律由中控后端代理。
|
||
|
||
### 同机多套策略机（测试用）
|
||
|
||
- **实盘**：一机一套，只用**槽位 1**。
|
||
- **测试**：同一台机可再装槽位 2/3（完整独立克隆 + 独立进程），菜单选槽位即可；端口/PM2 名自动分配。
|
||
- 中控登记多套时，每套一条「策略机」：Base URL 带不同端口，例如 `http://x.x.x.x:5155`、`:5156`、`:5157`（或各自反代域名）。
|
||
- 更新「全部」为**串行**（避免 2G 内存并行 `npm build`）。
|
||
|
||
| 槽位 | 目录 | 端口 | PM2 |
|
||
|------|------|------|-----|
|
||
| 1 | `/opt/eth_hedge_sim` | 5155 | `eth-hedge-api` |
|
||
| 2 | `/opt/eth_hedge_sim_2` | 5156 | `eth-hedge-api-2` |
|
||
| 3 | `/opt/eth_hedge_sim_3` | 5157 | `eth-hedge-api-3` |
|
||
|
||
非交互示例：
|
||
|
||
```bash
|
||
INSTANCE_SLOT=2 SKIP_SLOT_PROMPT=1 bash /opt/eth_hedge_sim/deploy/lib/install.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 一键部署（manage.sh）
|
||
|
||
目标机 Ubuntu 22.04：
|
||
|
||
```bash
|
||
curl -fsSL https://git.bz121.com/dekun/eth_hedge_sim/raw/branch/main/deploy/manage.sh | bash
|
||
```
|
||
|
||
交互菜单：
|
||
|
||
| 选项 | 作用 |
|
||
|------|------|
|
||
| 1) 一键部署策略机 | 选槽位 1/2/3 → 克隆/构建，启动对应端口 |
|
||
| 2) 一键部署中控机 | 构建中控，启动 `eth-hedge-control` :5160；自动补全 `.env.control`（**已有非空值不覆盖**） |
|
||
| 3) 一键卸载 | 选槽位，只卸该套（不影响其它槽位） |
|
||
| 4) 更新策略机 | 选槽位，或 `a` 全部串行更新 |
|
||
| 5) 更新中控机 | `control/deploy/update.sh` |
|
||
| 0) 退出 | — |
|
||
|
||
也可本机已安装后：
|
||
|
||
```bash
|
||
bash /opt/eth_hedge_sim/deploy/manage.sh
|
||
# 或仅更新中控
|
||
bash /opt/eth_hedge_sim/control/deploy/update.sh
|
||
# 开发机 SSH 触发中控（可选）
|
||
# CONTROL_HOST=... CONTROL_PASS=... python scripts/deploy_control.py
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 中控登录与系统设置
|
||
|
||
### 3.1 默认账号
|
||
|
||
- 首次：`admin` / `admin123`（一键部署写入 `.env.control`，已有值不覆盖）。
|
||
- **改密后**：登录页与设置页**不再显示**默认账号提示。
|
||
- 登录框**不预填用户名**，并关闭浏览器自动填充。
|
||
|
||
### 3.2 系统设置（三个 Tab）
|
||
|
||
1. **中控登录账户**
|
||
- 修改用户名/密码（改后旧会话作废）。
|
||
- **本地局域网免登录**：开关；开启后，从私网 IP（如 `192.168.x` / `10.x` / `172.16–31.x` / 本机）访问可自动进入监控区，无需输密码。
|
||
2. **添加策略机** — 名称 + 公网 Base URL（如 `https://dc.hyf2.cc`）。
|
||
3. **策略机列表** — 生成/轮换 Token、删除。
|
||
|
||
### 3.3 `.env.control` 常用项
|
||
|
||
见仓库 [`.env.control.example`](../.env.control.example)：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `CONTROL_AUTH_USERNAME` / `PASSWORD` | 中控登录 |
|
||
| `CONTROL_AUTH_SECRET` | Token 加密与签名密钥（部署自动填默认值，有值不覆盖） |
|
||
| `CONTROL_LAN_AUTH_BYPASS` | `1`=局域网免登录，`0`=关闭 |
|
||
| `CONTROL_SSE_INTERVAL_SEC` | 监控 SSE 推送间隔（默认 1 秒） |
|
||
| `CONTROL_SSE_PROBE_TIMEOUT_SEC` | 单次探测策略机超时（默认 2.5 秒） |
|
||
| `CONTROL_POLL_INTERVAL_SEC` | 兼容保留（旧前端轮询；现以 SSE 为主） |
|
||
|
||
**勿提交** `.env.control` 到 git。
|
||
|
||
---
|
||
|
||
## 4. 策略机配对（API Token）
|
||
|
||
1. 中控 **策略机列表** → **生成 Token**（明文只显示一次，中控侧加密保存）。
|
||
2. 登录该策略机 → **系统设置 → 登录账户 → 中控 API Token** → 粘贴保存（策略机存哈希）。
|
||
3. 中控监控区显示「已配对」；若 Token 不一致则「配对失败」并提示重新生成保存。
|
||
|
||
### 策略机 Fleet 接口（头：`X-Fleet-Token`，也可 `Authorization: Fleet <token>`）
|
||
|
||
| 方法 | 路径 | 作用 |
|
||
|------|------|------|
|
||
| GET | `/api/fleet/status` | 状态摘要 + 持仓/策略详情 |
|
||
| GET | `/api/fleet/stats` | 整体统计（组数/胜率/盈亏/手续费/平仓原因/按组盈亏） |
|
||
| POST | `/api/fleet/start` | 启动策略（LIVE 仍过策略机门禁） |
|
||
| POST | `/api/fleet/pause` | 停止/暂停 |
|
||
| POST | `/api/fleet/update` | 本机 `deploy/lib/update.sh`（reload，不自动 start） |
|
||
| POST | `/api/fleet/issue-login` | 签发一次性免密登录票 |
|
||
|
||
免密进策略页：中控拿到 ticket 后打开
|
||
`https://<策略机>/fleet-login?ticket=...`
|
||
→ `POST /api/auth/fleet-exchange` 兑换普通会话 → `/plan`。
|
||
票约 **60 秒、一次性**；长期 Token **不进**浏览器地址栏。
|
||
|
||
---
|
||
|
||
## 5. 监控区
|
||
|
||
- **实时推送**：浏览器通过 SSE（`GET /api/nodes/status/stream`）接收状态；中控约每秒**并行**拉取各策略机 `/api/fleet/status`，有变化才推送；断线自动重连。工具栏显示「实时 · 1s」。
|
||
- **刷新**：仍可手动走 `/api/nodes/status/all` 拉一次。
|
||
- **卡片**：在线/离线、SIM/LIVE、阶段、持仓、轮次、行情、Token 状态；模式列在开启半自动时显示「半自动」（否则永期/期期）。
|
||
- **运行中**：卡片绿色；底部按钮显示「运行中」且不可点启动。
|
||
- **点击卡片**：放大弹层 — 策略详情 + **整体统计**（按需拉 `/api/nodes/{id}/stats` → 策略机 `/api/fleet/stats`，同策略页统计）+ 持仓腿表；**净浮盈 / 浮盈** 正绿负红加粗；半自动时状态含授权/方向，出场列显示点数与净利目标。
|
||
- **登录策略机**：免密新标签打开策略页。
|
||
- **更新代码 / 勾选更新**：**二次确认**后执行；会 reload 进程，**不会**自动 start。
|
||
|
||
中控**不做**：改策略参数、代开平仓、资金划转、直连交易所。
|
||
|
||
---
|
||
|
||
## 6. 安全边界
|
||
|
||
- 中控无交易所 API Key；交易密钥只在各策略机 `.env`。
|
||
- Fleet Token 权限含启停/更新/签发登录票 → 泄露后两边立即轮换。
|
||
- 局域网免登录仅私网 IP；勿对公网暴露中控端口。
|
||
- 策略机 LIVE 启停仍走本机 `live_ready()` 等门禁，中控不能绕过。
|
||
|
||
---
|
||
|
||
## 7. 相关文档与入口
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| 本文 | 中控安装、配对、监控、安全 |
|
||
| [更新说明](./更新说明.md) | 发版变更记录 |
|
||
| [代码结构](./代码结构.md) | 仓库目录（含 `control/`） |
|
||
| [README](../README.md) | 总览与部署入口 |
|
||
|
||
产品文档索引（README「文档」一节）含本页链接。
|