# 中控（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 名 | 代码目录 | 配置 |
|------|------|--------|----------|------|
| 策略机 | 5155 | `eth-hedge-api` | `backend/` + `frontend/` | 仓库根 `.env` |
| 中控 | 5160 | `eth-hedge-control` | `control/backend` + `control/frontend` | 仓库根 `.env.control` |

中控浏览器**不直连**策略机 API（避免跨域与密钥进前端）；一律由中控后端代理。

---

## 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) 一键部署策略机 | 克隆/构建，启动 `eth-hedge-api` :5155 |
| 2) 一键部署中控机 | 构建中控，启动 `eth-hedge-control` :5160；自动补全 `.env.control`（**已有非空值不覆盖**） |
| 3) 一键卸载 | 卸载策略相关（按现有 uninstall 逻辑） |
| 4) 更新策略机 | `git pull` + 构建 + reload 策略机 |
| 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` | 状态摘要 + 持仓/策略详情 |
| 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 状态。  
- **运行中**：卡片绿色；底部按钮显示「运行中」且不可点启动。  
- **点击卡片**：放大弹层 — 策略详情 + 持仓腿表；**净浮盈 / 浮盈** 正绿负红加粗。  
- **登录策略机**：免密新标签打开策略页。  
- **更新代码 / 勾选更新**：**二次确认**后执行；会 reload 进程，**不会**自动 start。  

中控**不做**：改策略参数、代开平仓、资金划转、直连交易所。

---

## 6. 安全边界

- 中控无交易所 API Key；交易密钥只在各策略机 `.env`。  
- Fleet Token 权限含启停/更新/签发登录票 → 泄露后两边立即轮换。  
- 局域网免登录仅私网 IP；勿对公网暴露中控端口。  
- 策略机 LIVE 启停仍走本机 `live_ready()` 等门禁，中控不能绕过。

---

## 7. 相关文档与入口

| 文档 | 内容 |
|------|------|
| 本文 | 中控安装、配对、监控、安全 |
| [更新说明](./更新说明.md) | 发版变更记录 |
| [代码结构](./代码结构.md) | 仓库目录（含 `control/`） |
| [README](../README.md) | 总览与部署入口 |

产品文档索引（README「文档」一节）含本页链接。