From e7529e9dc44202f72b4f243530acad9b88575eb6 Mon Sep 17 00:00:00 2001 From: dekun Date: Thu, 30 Jul 2026 13:07:25 +0800 Subject: [PATCH] Document Fleet control center across README and core docs. Co-authored-by: Cursor --- README.md | 15 ++-- docs/中控Fleet说明.md | 155 +++++++++++++++++++++++++++++++----------- docs/代码结构.md | 110 ++++++++++++++++++------------ docs/开发方案.md | 1 + docs/更新说明.md | 10 +++ 5 files changed, 204 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 704dcf5..486bf8d 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ - [商业化与授权方案](docs/商业化与授权方案.md) - [策略说明](docs/策略说明.md) - [实盘策略说明](docs/实盘策略说明.md) +- [中控 Fleet 说明](docs/中控Fleet说明.md)（本地中控：多机监控 / 启停 / 更新 / 免密登录） - [更新说明](docs/更新说明.md)（每次发版追加） ## 访问（测试机） @@ -34,6 +35,7 @@ - 反代：[`https://dc.hyf2.cc`](https://dc.hyf2.cc) → 本机 `5155`（PM2: `eth-hedge-api`） - 登录账号：见服务器 `/opt/eth_hedge_sim/.env` 的 `AUTH_USERNAME` / `AUTH_PASSWORD` - 可在「系统设置」修改用户名/密码；前端固定同源 API，无 API 地址配置项 +- **本地中控**：`http://<局域网IP>:5160`（PM2: `eth-hedge-control`）；说明见 [中控 Fleet 说明](docs/中控Fleet说明.md) ## 一键部署 / 更新（禁止 scp 传代码） @@ -48,9 +50,11 @@ curl -fsSL https://git.bz121.com/dekun/eth_hedge_sim/raw/branch/main/deploy/mana 菜单： -1. 一键部署 -2. 一键卸载（仅停删 `eth-hedge-api`，移走目录并备份 `.env`） -3. 更新（`git pull` + 构建 + reload） +1. 一键部署策略机 +2. 一键部署中控机 +3. 一键卸载 +4. 更新策略机 +5. 更新中控机 0. 退出 已安装后也可： @@ -66,10 +70,11 @@ bash /opt/eth_hedge_sim/deploy/manage.sh ```bash pip install paramiko export DEPLOY_PASS='***' -python scripts/deploy_remote.py +python scripts/deploy_remote.py # 策略机 +# python scripts/deploy_control.py # 中控（需 CONTROL_HOST / CONTROL_PASS） ``` -PM2 进程名：`eth-hedge-api`（端口 **5155**）。禁止 `pm2 restart all`。 +PM2 进程名：`eth-hedge-api`（端口 **5155**）、`eth-hedge-control`（端口 **5160**）。禁止 `pm2 restart all`。 ## 服务器上本地开发 / 调试（Ubuntu 22.04） diff --git a/docs/中控Fleet说明.md b/docs/中控Fleet说明.md index b017f40..dee69a1 100644 --- a/docs/中控Fleet说明.md +++ b/docs/中控Fleet说明.md @@ -1,34 +1,33 @@ # 中控（Fleet Control）使用说明 -中控与策略机在**同一仓库**，独立进程部署。中控跑在本地服务器，**不访问交易所**；只通过专用 API Token 读状态、启停、远程更新与免密登录策略机。 +中控与策略机在**同一仓库**（`eth_hedge_sim`），**独立进程**部署。中控通常跑在**本地局域网服务器**，**不访问交易所**；只通过专用 API Token 对多台策略机做：状态监控、启停、远程更新代码、免密进入策略页。 建议策略机与中控使用**同一 git 版本**（同 `main` / 同 tag），避免 `/api/fleet/*` 接口漂移。 -## 架构一览 +--- -| 组件 | 端口 | PM2 名 | 目录 | -|------|------|--------|------| -| 策略机 | 5155 | `eth-hedge-api` | `backend/` + `frontend/` | -| 中控 | 5160 | `eth-hedge-control` | `control/backend` + `control/frontend` | +## 1. 架构 -## 策略机：启用中控 Token +```text +本地中控 (5160) 云端策略机 × N (5155) +┌─────────────────┐ ┌──────────────────┐ +│ control 前端/后端 │──X-Fleet-Token──│ eth-hedge-api │ +│ 不连交易所 │──SSH 无需主路径──│ OKX/币安交易密钥 │ +└─────────────────┘ └──────────────────┘ +``` -1. 部署含本功能的策略机代码（`deploy_remote.py` / 现有一键更新）。 -2. 登录策略机 → **系统设置 → 登录账户 → 中控 API Token**。 -3. 粘贴中控生成的 Token 并保存（存哈希，不可回看明文）。 +| 组件 | 端口 | PM2 名 | 代码目录 | 配置 | +|------|------|--------|----------|------| +| 策略机 | 5155 | `eth-hedge-api` | `backend/` + `frontend/` | 仓库根 `.env` | +| 中控 | 5160 | `eth-hedge-control` | `control/backend` + `control/frontend` | 仓库根 `.env.control` | -策略机 Fleet 接口（请求头 `X-Fleet-Token`）： +中控浏览器**不直连**策略机 API（避免跨域与密钥进前端）；一律由中控后端代理。 -- `GET /api/fleet/status` -- `POST /api/fleet/start` / `pause` -- `POST /api/fleet/update`（本机跑 `deploy/lib/update.sh`） -- `POST /api/fleet/issue-login`（签发一次性免密登录票） +--- -免密登录兑换：`POST /api/auth/fleet-exchange` `{ "ticket": "..." }`，或打开 `/fleet-login?ticket=...`。 +## 2. 一键部署（manage.sh） -## 中控：本地安装与一键部署 - -在目标机执行（与策略机同一安装命令入口）： +目标机 Ubuntu 22.04： ```bash curl -fsSL https://git.bz121.com/dekun/eth_hedge_sim/raw/branch/main/deploy/manage.sh | bash @@ -36,29 +35,109 @@ curl -fsSL https://git.bz121.com/dekun/eth_hedge_sim/raw/branch/main/deploy/mana 交互菜单： -1. **一键部署策略机** — 端口 5155 / `eth-hedge-api` -2. **一键部署中控机** — 端口 5160 / `eth-hedge-control`（自动补全 `.env.control`，已有值不覆盖） -3. 一键卸载 -4. 更新策略机 -5. 更新中控机 +| 选项 | 作用 | +|------|------| +| 1) 一键部署策略机 | 克隆/构建，启动 `eth-hedge-api` :5155 | +| 2) 一键部署中控机 | 构建中控，启动 `eth-hedge-control` :5160；自动补全 `.env.control`（**已有非空值不覆盖**） | +| 3) 一键卸载 | 卸载策略相关（按现有 uninstall 逻辑） | +| 4) 更新策略机 | `git pull` + 构建 + reload 策略机 | +| 5) 更新中控机 | `control/deploy/update.sh` | +| 0) 退出 | — | -中控默认账号：`admin` / `admin123`；在中控 **系统设置** 可改用户名密码。 +也可本机已安装后： -## 配对步骤 +```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 +``` -1. 中控 **系统设置** → 添加策略机（名称 + 公网 Base URL，如 `https://dc.hyf2.cc`）。 -2. 点 **生成 Token** → 复制明文（只显示一次）。 -3. 登录该策略机 → 保存同一 Token。 -4. 回到中控 **监控区**：应显示在线与 Token 已配对。 +--- -## 监控区操作 +## 3. 中控登录与系统设置 -- **启动 / 停止**：经 Token 调策略机 `/api/fleet/start|pause`（LIVE 门禁仍在策略机侧）。 -- **登录策略机**：中控代签一次性 ticket，新标签打开策略机并免密进入 `/plan`。 -- **更新代码 / 勾选更新**：中控调 `/api/fleet/update`，策略机本机 git pull + 构建 + reload；**不会**自动 start 策略。 +### 3.1 默认账号 -## 安全注意 +- 首次：`admin` / `admin123`（一键部署写入 `.env.control`，已有值不覆盖）。 +- **改密后**：登录页与设置页**不再显示**默认账号提示。 +- 登录框**不预填用户名**，并关闭浏览器自动填充。 -- Fleet Token 可启停、更新、签发登录票，泄露后立即在两边轮换（中控重新生成 + 策略机覆盖保存）。 -- 登录票约 60 秒、一次性；长期 Token 不会出现在浏览器地址栏。 -- 中控建议仅内网访问；勿把 `.env.control` 与 Token 明文提交到 git。 +### 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_POLL_INTERVAL_SEC` | 监控轮询间隔 | + +**勿提交** `.env.control` 到 git。 + +--- + +## 4. 策略机配对（API Token） + +1. 中控 **策略机列表** → **生成 Token**（明文只显示一次，中控侧加密保存）。 +2. 登录该策略机 → **系统设置 → 登录账户 → 中控 API Token** → 粘贴保存（策略机存哈希）。 +3. 中控监控区显示「已配对」；若 Token 不一致则「配对失败」并提示重新生成保存。 + +### 策略机 Fleet 接口（头：`X-Fleet-Token`，也可 `Authorization: Fleet `） + +| 方法 | 路径 | 作用 | +|------|------|------| +| 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. 监控区 + +- **卡片**：在线/离线、SIM/LIVE、阶段、轮次、行情、Token 状态。 +- **运行中**：卡片绿色；底部按钮显示「运行中」且不可点启动。 +- **点击卡片**：放大弹层 — 策略详情 + 持仓腿表；**净浮盈 / 浮盈** 正绿负红加粗。 +- **登录策略机**：免密新标签打开策略页。 +- **更新代码 / 勾选更新**：**二次确认**后执行；会 reload 进程，**不会**自动 start。 + +中控**不做**：改策略参数、代开平仓、资金划转、直连交易所。 + +--- + +## 6. 安全边界 + +- 中控无交易所 API Key；交易密钥只在各策略机 `.env`。 +- Fleet Token 权限含启停/更新/签发登录票 → 泄露后两边立即轮换。 +- 局域网免登录仅私网 IP；勿对公网暴露中控端口。 +- 策略机 LIVE 启停仍走本机 `live_ready()` 等门禁，中控不能绕过。 + +--- + +## 7. 相关文档与入口 + +| 文档 | 内容 | +|------|------| +| 本文 | 中控安装、配对、监控、安全 | +| [更新说明](./更新说明.md) | 发版变更记录 | +| [代码结构](./代码结构.md) | 仓库目录（含 `control/`） | +| [README](../README.md) | 总览与部署入口 | + +产品文档索引（README「文档」一节）含本页链接。 diff --git a/docs/代码结构.md b/docs/代码结构.md index 514954c..3d07b40 100644 --- a/docs/代码结构.md +++ b/docs/代码结构.md @@ -12,55 +12,77 @@ eth_hedge_sim/ # 产品：比特骆驼自动化对冲系统 ├── README.md ├── .gitignore -├── .env.example # 无密钥的示例；真 .env 不上库 -├── package.json # 若前端/Node；或改用 Python 则 requirements.txt -├── requirements.txt # 后端若用 Python +├── .env.example # 策略机示例；真 .env 不上库 +├── .env.control.example # 中控示例；真 .env.control 不上库 +├── requirements.txt ├── docs/ -│ ├── 开发方案.md # 业务与部署方案（本文档姐妹篇） -│ └── 代码结构.md # 本文件 -├── deploy/ -│ ├── ecosystem.config.cjs # PM2：仅本项目进程 -│ └── pull_and_restart.sh # git pull + 构建 + pm2 reload（不碰现网） -├── backend/ # API + 行情 + 策略 + 本地撮合 -│ ├── app/ -│ │ ├── main.py # 或 index.ts：进程入口 -│ │ ├── config.py -│ │ ├── api/ # HTTP 路由 -│ │ ├── ws/ # 向前端推送 -│ │ ├── market/ # OKX 只读行情 -│ │ ├── strategy/ # 自动对冲状态机 -│ │ ├── sim/ # 本地撮合与账本 -│ │ ├── live/ # 实盘适配器（后期，默认关闭） -│ │ ├── models/ # DB 模型 / schema -│ │ └── services/ # 组、统计、设置等应用服务 -│ ├── data/ # 本地 SQLite 等（gitignore 数据文件） -│ └── tests/ -├── frontend/ # Web 控制台（比特骆驼） -│ ├── index.html -│ ├── package.json -│ ├── src/ -│ │ ├── main.tsx -│ │ ├── App.tsx -│ │ ├── layouts/ # 导航壳 -│ │ ├── pages/ -│ │ │ ├── Plan.tsx # 自动对冲计划 -│ │ │ ├── Trades.tsx # 交易记录 -│ │ │ ├── Stats.tsx # 统计 -│ │ │ └── Settings.tsx # 系统设置 -│ │ ├── components/ # 盘口、组标识、持仓条等 -│ │ ├── api/ # 调后端 -│ │ └── styles/ # 深色交易台风 -│ └── dist/ # 构建产物（可部署由 API 托管或 nginx） -└── scripts/ # 运维/一次性工具（可选） - └── smoke_market.py # 只读行情连通性检查 +│ ├── 开发方案.md +│ ├── 代码结构.md # 本文件 +│ ├── 中控Fleet说明.md # 本地中控安装 / 配对 / 监控 +│ └── 更新说明.md +├── deploy/ # 策略机部署 + manage.sh 菜单 +│ ├── manage.sh # 1策略机 / 2中控 / 4更新策略 / 5更新中控 +│ ├── ecosystem.config.cjs +│ └── pull_and_restart.sh +├── backend/ # 策略机 API +│ └── app/api/fleet.py # 中控专用：status/start/pause/update/issue-login +├── frontend/ # 策略机 Web +├── control/ # 本地中控（独立进程 :5160） +│ ├── backend/app/ # FastAPI：机器清单、Token、代理启停/更新 +│ ├── frontend/ # 监控区 + 系统设置（Tab） +│ └── deploy/ +│ ├── ecosystem.config.cjs # PM2 eth-hedge-control +│ └── update.sh +└── scripts/ + ├── deploy_remote.py # SSH 更新策略机 + └── deploy_control.py # SSH/本机更新中控 ``` -技术栈可在开工时二选一（建议尽快定一种，避免双栈）： +中控详细用法见 **[中控 Fleet 说明](./中控Fleet说明.md)**。 -- **推荐 A**：后端 Python（FastAPI）+ 前端 React/Vite（与现网 Python 生态接近，便于复制行情代码）。 -- **推荐 B**：全 Node（Nest/Express + React）。 +--- -下文按 **推荐 A** 描述模块；若选 B，目录名对应平移即可。 +## 1b. 中控模块职责（`control/`） + +| 路径 | 职责 | +|------|------| +| `control/backend/app/main.py` | 中控入口，托管前端 dist | +| `control/backend/app/api/nodes.py` | 机器 CRUD、探活、启停/更新/免密登录 URL | +| `control/backend/app/api/auth_routes.py` | 登录、改密、局域网免登、login-meta | +| `control/backend/app/envfile.py` | `.env.control` 补缺（不覆盖已有值） | +| `control/backend/app/lan.py` | 私网 IP 判断 | +| `control/frontend/src/pages/Monitor.tsx` | 监控卡片 / 详情弹层 | +| `control/frontend/src/pages/Settings.tsx` | 账户 / 添加机 / 列表 Tab | + +策略机侧配对接口：`backend/app/api/fleet.py` + 设置页「中控 API Token」。 + +--- + +## 1. 根目录总览（策略机为主，续） + +```text +eth_hedge_sim/ +├── backend/ # API + 行情 + 策略 + 本地撮合 +│ ├── app/ +│ │ ├── main.py +│ │ ├── config.py +│ │ ├── api/ # HTTP 路由（含 fleet） +│ │ ├── strategy/ +│ │ ├── sim/ +│ │ ├── live/ +│ │ └── models/ +│ ├── data/ +│ └── tests/ +├── frontend/ # 策略机 Web +│ └── src/pages/ +│ ├── Plan.tsx +│ ├── Trades.tsx +│ ├── Stats.tsx +│ └── Settings.tsx # 含中控 Token +└── ... +``` + +> 下文原「根目录总览」中较旧的骨架示意仍保留模块职责描述；以本节 + [中控说明](./中控Fleet说明.md) 为准补充 `control/`。 --- diff --git a/docs/开发方案.md b/docs/开发方案.md index ac8b5bc..f597a6d 100644 --- a/docs/开发方案.md +++ b/docs/开发方案.md @@ -20,6 +20,7 @@ | 行情 | OKX **实盘只读** API（REST + WebSocket） | | 成交（默认） | **本地模拟撮合 + 本地虚拟资金**（非 OKX 模拟盘） | | 后期 | 支持切换 **实盘下单**（显式开关 + 二次确认） | +| 中控 | 同仓 `control/`，本地局域网运维面板（多机监控/启停/更新）；见 [中控 Fleet 说明](./中控Fleet说明.md) | ### 1.1 硬边界 diff --git a/docs/更新说明.md b/docs/更新说明.md index 6f84a57..f8ee07d 100644 --- a/docs/更新说明.md +++ b/docs/更新说明.md @@ -5,6 +5,16 @@ --- +## 2026-07-30 — 中控文档与设置增强 + +### 变更 + +1. 完善 `docs/中控Fleet说明.md`；README / 代码结构 / 开发方案增加中控入口与目录说明。 +2. 中控设置改为 Tab（登录账户 / 添加策略机 / 策略机列表）；改密后隐藏默认账号提示；局域网免登录开关。 +3. 监控卡片运行中绿色、详情弹层持仓、更新二次确认、浮盈颜色加粗等（见中控说明 §5）。 + +--- + ## 2026-07-30 — 中控 Fleet Control（同仓 / Token 运维） ### 变更