dekun/crypto_monitor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Normalize fullwidth punctuation to ASCII across codebase.

Browse Source 
Add scripts/normalize_ambiguous_unicode.py; fix corrupted patch_instance_theme_templates.py. Preserves curly quotes in string literals; removes Git homoglyph warnings on .env.example.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-07-08 23:42:26 +08:00
parent aaa72c7961
commit b733e551a0
392 changed files with 71522 additions and 71369 deletions
Download Patch File Download Diff File Expand all files Collapse all files
manual_trading_hub/部署文档.md
+336 -336
View File
@@ -1,336 +1,336 @@
# 多账户交易中控 — 部署文档（含 PM2）
本文档说明在 **Ubuntu / Linux** 上部署 **manual_trading_hub**（复盘系统中控：监控区、系统设置、登录保护）的推荐步骤。
- 功能与界面：[使用说明.md](./使用说明.md)
- **云服务器（VPS）完整配置**：[云服务器部署说明.md](./云服务器部署说明.md)
- **本地备份并迁到云上**：[本地数据迁移到云端.md](./本地数据迁移到云端.md)
- **局域网 IP:端口 / 反代域名、中控打开实例免登录**：[局域网与反代部署说明.md](./局域网与反代部署说明.md)
- 故障实录：[常见问题.md](./常见问题.md)
- 环境变量模板：[.env.example](./.env.example)
---
## 一、部署目标
| 组件 | 作用 | 默认监听 |
|------|------|----------|
| **hub.py** | 中控 Web + API | `0.0.0.0:5100` |
| **agent.py × N** | 各账户持仓 / 紧急全平 | `127.0.0.1:15200`～`15202` |
| **crypto_monitor_*.app** | 策略、关键位、下单逻辑 | 各目录 `.env` 的 `APP_PORT` |
- 账户列表与 URL 由 **`hub_settings.json`**（网页「系统设置」保存）或内置默认维护；**不再使用** `HUB_AGENTS`。
- 三实例 Flask **无需为中控改业务代码**（已注册 `hub_bridge`）；与中控并行运行。
---
## 二、前置条件
1. **Python 3.10+**、`python3-venv`、`pip`。
2. **Node.js + npm**（用于安装 PM2）：`sudo npm i -g pm2`。
3. 各 `crypto_monitor_*` 目录已 **`cp .env.example .env`** 并填好 API 密钥。
4. 端口无冲突：`5100`、`15200`～`15202`、各实例 `APP_PORT`（5000/5001/5004）。
5. 建议代码路径：`/opt/crypto_monitor/`（下文用此示例，请按实际路径替换）。
---
## 三、安装中控依赖
```bash
cd /opt/crypto_monitor/manual_trading_hub
python3 -m venv .venv
source .venv/bin/activate # 激活 venv（当前终端后续 pip/python 走虚拟环境）
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env：HUB_PORT、HUB_DISABLED_IDS、公网时 HUB_BRIDGE_TOKEN 等
chmod +x scripts/run_hub.sh scripts/run_agent.sh scripts/pm2_hub.sh scripts/pm2_agents.sh
chmod +x scripts/fix_hub_deps.sh scripts/verify_hub_deploy.sh scripts/fix_env_crlf.sh
deactivate # 可选；交给 PM2 时不必保持激活
```
**依赖说明**：`requirements.txt` 含 **`python-multipart`**（FastAPI 表单解析；旧版若保留下单接口时需要）、**`psutil`**（监控区服务器状态条）。当前中控**已移除下单区**，但仍建议安装完整依赖。
说明：
- **安装依赖**：必须在 **`manual_trading_hub/.venv`** 内执行，勿对系统 Python 直接 `pip install`（Debian/Ubuntu 会报 `externally-managed-environment`）。`source .venv/bin/activate` 后用 `pip install` 即可；不写 `activate` 时也可用 **`.venv/bin/pip install -r requirements.txt`**（效果相同）。快捷：`bash scripts/fix_hub_deps.sh`。
- **PM2 启动**：由 `scripts/run_hub.sh` 固定调用 **`.venv/bin/python`**，**不依赖**你是否在 shell 里激活过 venv。
- **监控磁盘**：可选环境变量 **`HUB_HOST_DISK_PATH`**（如 `/opt/crypto_monitor`），未设时 Linux 为 `/`、Windows 为系统盘。
子代理也使用 **本目录 `.venv`** 里的 Python（与各策略 Flask 的 venv 可分开）。
---
## 四、推荐启动顺序
```
1. 各实例 Flask（APP_PORT） ← 各 crypto_monitor_* 目录 ecosystem.config.cjs
2. 中控 + 子代理（5100 + 15200～15202） ← 本目录一条 PM2 命令同时启动
```
**`ecosystem.config.cjs` 会一次拉起 3 个 agent + 1 个 hub**，无需再单独 `pm2 start` 子代理。
仅反代中控到公网时：Flask / agent 仍只监听 **127.0.0.1**；系统设置里 URL 填 `http://127.0.0.1:端口`。
---
## 五、PM2 托管（hub + agent 一起启动，推荐）
### 5.1 一条命令启动全部
| 文件 | 包含进程 |
|------|----------|
| `ecosystem.config.cjs` | `manual-agent-binance` / `okx` / `gate` + **`manual-trading-hub`** |
`run_hub.sh` 加载 **`manual_trading_hub/.env`** 后执行 `hub.py`；各 agent 经 **`run_agent.sh`** 在对应策略目录加载 **`.env`**（含 API 密钥），再执行 `agent.py`。
```bash
cd /opt/crypto_monitor/manual_trading_hub
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
pm2 start ecosystem.config.cjs # 4 个进程一起起
pm2 save
# 或
bash scripts/pm2_hub.sh start
```
### 5.2 PM2 进程一览
| 进程名 | 工作目录 | 端口/说明 |
|--------|----------|-----------|
| manual-agent-binance | crypto_monitor_binance | agent `15200` |
| manual-agent-okx | crypto_monitor_okx | agent `15201` |
| manual-agent-gate | crypto_monitor_gate | agent `15202` |
| manual-trading-hub | manual_trading_hub | hub `5100` |
OKX 子代理会启动；不用 OKX 可 `pm2 stop manual-agent-okx`。
### 5.3 常用运维命令
```bash
pm2 status
pm2 logs manual-trading-hub --lines 200
pm2 restart ecosystem.config.cjs # 重启 hub + 全部 agent
bash scripts/pm2_hub.sh restart # 同上
bash scripts/pm2_hub.sh stop
bash scripts/pm2_hub.sh logs
```
仅重启中控、不动 agent：
```bash
pm2 restart manual-trading-hub
```
仅重启子代理：
```bash
pm2 restart manual-agent-binance manual-agent-gate manual-agent-okx
# 或
bash scripts/pm2_agents.sh restart
```
### 5.4 开机自启
```bash
pm2 save
pm2 startup
# 按终端提示执行一行 sudo 命令后，再 pm2 save
```
### 5.5 与各实例 Flask 一起查看
```bash
pm2 status
# 示例同时存在：
# manual-trading-hub、manual-agent-*
# crypto_binance / crypto_gate …（各策略目录自有 ecosystem.config.cjs）
```
### 5.6 Gate 子代理「一会能连、一会子代理不可用」（Windows `.env` 换行）
**现象**：Gate 卡片红字「子代理不可用」；`pm2 logs manual-agent-gate` 反复出现：
```text
./.env: line 22: $'\r': command not found
agent start: exchange=gate port=15202 ...
```
**原因**：在 Windows 编辑的 `crypto_monitor_gate/.env` 为 **CRLF**，Linux 上 `source` 失败；PM2 反复重启，中控轮询时偶发连不上（**不是外网问题**）。
**处理**（在服务器仓库根执行）：
```bash
cd /opt/crypto_monitor
sed -i 's/\r$//' crypto_monitor_gate/.env
bash manual_trading_hub/scripts/fix_env_crlf.sh
cd manual_trading_hub
pm2 delete manual-agent-gate 2>/dev/null || true
pm2 start ecosystem.config.cjs --only manual-agent-gate
pm2 save
curl -s http://127.0.0.1:15202/status | head -c 200 # 应 ok:true
```
**预防**：`.env` 保存为 **LF**（勿在 Windows 记事本直接保存 CRLF）。子代理须经 **`scripts/run_agent.sh`** 启动（内置去 CRLF 的 `load_dotenv_file`），勿裸跑 `python agent.py`。
详见 [常见问题.md](./常见问题.md) **§3.1**、**§3.3**。
---
## 六、手动启动（不用 PM2 时）
需**分别**起 agent 与 hub（与 PM2 合并启动不同）：
```bash
# 子代理：由 ecosystem.config.cjs 经 run_agent.sh 启动（勿用手动多终端）
# 中控：
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/run_hub.sh
```
---
## 七、浏览器验收
1. **http://127.0.0.1:5100/login** — 若 `.env` 已设 `HUB_PASSWORD`，用 `HUB_USERNAME` / `HUB_PASSWORD` 登录。
2. **http://127.0.0.1:5100/monitor** — 已启用账户显示持仓；Flask 已起时有关键位/趋势信息。
3. **http://127.0.0.1:5100/market** — 行情区可选交易所与周期拉 K 线；升级后强刷浏览器，详见 [行情区说明.md](./行情区说明.md)。
4. **http://127.0.0.1:5100/ai** — AI 教练（三户今日总结 + 聊天）；`manual_trading_hub/.env` 配与三实例相同的 `AI_*` 变量，见 [AI教练说明.md](./AI教练说明.md)。
5. **http://127.0.0.1:5100/settings** — 保存后生成 `hub_settings.json`（增加第五户、Gate 子账户等见 [使用说明.md §4.5](./使用说明.md#45-增加账户例如再挂一个-gate)）。
5. 监控卡片 **「实例」** — 在各 `crypto_monitor_*` 网页做下单、关键位、趋势；中控**不提供**下单表单。
**命令行验收**（推荐）：
```bash
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/verify_hub_deploy.sh
```
应看到：`OK: 无 api_trade_key`，`HTTP 200`，JSON 含 `"build":"20260521-no-trade-ui"`。
```bash
curl -s http://127.0.0.1:5100/api/ping
curl -s http://127.0.0.1:15200/status | head -c 200
```
---
## 八、仅反代中控到公网（实例不反代）
1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**，配置 **HTTPS**。
2. 反代需传递（登录 Cookie 正确识别 HTTPS）：
```nginx
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
```
3. `manual_trading_hub/.env` **务必设置**：
```env
HUB_USERNAME=你的用户名
HUB_PASSWORD=你的强密码
HUB_SESSION_SECRET=随机长串
HUB_COOKIE_SECURE=true
```
4. `hub_settings.json` 中 Flask/Agent 保持 **`http://127.0.0.1:...`**（中控本机调 API）。
5. 三实例 **`APP_AUTH_DISABLED=false`** + 与中控相同 **`HUB_BRIDGE_TOKEN`**。
6. 子代理 **`HOST=127.0.0.1`**；防火墙勿对公网开放 `15200`～`15202`、各 `APP_PORT`。
7. **复盘/实例外链**：`HUB_PUBLIC_ORIGIN=https://你的域名` 或内网 IP；否则其它设备点「复盘」会跳到 `127.0.0.1`。
**说明**：HTTPS 域名与 HTTP `内网IP:5100` Cookie **不共用**；内网访问 IP 需在 IP 地址再登录一次（见 [常见问题.md](./常见问题.md) §2.1）。
---
## 九、环境变量（中控 `.env`）
| 变量 | 默认 | 说明 |
|------|------|------|
| `HUB_HOST` | `0.0.0.0` | 监听地址 |
| `HUB_PORT` | `5100` | 端口 |
| `HUB_DISABLED_IDS` | `1` | 强制关闭的账户 id（OKX） |
| `HUB_TRUST_LAN` | `true` | 私网可访问；仅本机可 `false` |
| `HUB_PUBLIC_ORIGIN` | 空 | 浏览器用复盘链接；如 `http://192.168.1.100`（**内网其它电脑访问中控时建议设置**） |
| `HUB_BRIDGE_TOKEN` | 空 | 与三实例一致；公网建议配置 |
| `HUB_USERNAME` | `admin` | Web 登录用户名 |
| `HUB_PASSWORD` | 空 | 非空即启用登录 |
| `HUB_SESSION_SECRET` | — | 会话签名 |
| `HUB_COOKIE_SECURE` | `false` | HTTPS 反代建议 `true` |
| `HUB_SESSION_DAYS` | `7` | 登录保持天数 |
本地联调、实例 `APP_AUTH_DISABLED=true` 时可不配 `HUB_BRIDGE_TOKEN`；本机不设 `HUB_PASSWORD` 则无需登录页。
---
## 十、升级与回滚
```bash
cd /opt/crypto_monitor
git pull
cd manual_trading_hub
bash scripts/fix_hub_deps.sh
bash scripts/verify_hub_deploy.sh
pm2 restart ecosystem.config.cjs
# 若只改了中控：pm2 restart manual-trading-hub
```
- **`hub_settings.json`**、**`hub_ai_summaries.json`**、**`hub_ai_chat.json`**、**`.env`** 不在 Git 中，`git pull` 不会覆盖。
- 升级前可备份：`cp hub_settings.json hub_settings.json.bak`、`cp hub_ai_*.json hub_ai_backup/`、`cp .env .env.bak`。
**升级后自检**：`curl -s http://127.0.0.1:5100/api/ping` 须含 `"trade_ui":false`。若仍见 `api_trade_key` 报错，说明代码未更新或未重启，见 [常见问题.md](./常见问题.md) §1。
---
## 十一、故障排查（速查）
**完整实录**见 **[常见问题.md](./常见问题.md)**。
| 现象 | 处理 |
|------|------|
| PM2 启动后立刻退出 | `pm2 logs manual-trading-hub`；检查 `.venv`、`.env`、`run_hub.sh` |
| `api_trade_key` / `python-multipart` | `git pull` → `bash scripts/fix_hub_deps.sh` → `verify_hub_deploy.sh` → 重启 hub |
| `verify` ping 解析失败 | hub 未起：`pm2 restart manual-trading-hub` |
| 余额显示 — | agent 未加载 `.env`；`fix_env_crlf.sh`；`run_agent.sh` |
| agent `$'\r': command not found` | `bash scripts/fix_env_crlf.sh` |
| 监控无持仓 | `curl http://127.0.0.1:15200/status` |
| 无关键位 / 401 | 启动 Flask；核对 `HUB_BRIDGE_TOKEN` / `hub_bridge` |
| 域名能登、IP 不能登 | 见常见问题 §2.1（Cookie / HTTP vs HTTPS） |
| 公网访问中控 403 | 反代到 `127.0.0.1:5100`，勿公网直连 5100 |
| 改 `.env` 不生效 | `pm2 restart manual-trading-hub` |
---
## 十二、进程托管说明
中控与子代理 **仅使用 PM2**（`ecosystem.config.cjs`）。勿再用 screen / systemd / nohup 启动 `hub.py` 或 `agent.py`，以免端口冲突。
环境要求见 **[docs/ubuntu-server.md](../docs/ubuntu-server.md)**。
---
## 十三、安全清单
- [ ] 公网仅暴露反代端口，不暴露 Flask/agent 端口
- [ ] 已设 `HUB_USERNAME` + `HUB_PASSWORD`（中控 Web 登录）
- [ ] HTTPS 反代已设 `HUB_COOKIE_SECURE=true` 且传递 `X-Forwarded-Proto`
- [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED`
- [ ] API Key 最小权限；交易所 IP 白名单
- [ ] 已告知操作人员「全局全平」不可撤销；中控**不在网页下单**
---
## 十四、文档索引
| 文档 | 内容 |
|------|------|
| [使用说明.md](./使用说明.md) | 功能、页面、API、环境变量 |
| [常见问题.md](./常见问题.md) | 故障实录 |
| [README.md](./README.md) | 速览 |
| [.env.example](./.env.example) | 环境变量模板 |
| [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | PM2 常驻（唯一推荐） |
| [docs/ubuntu-server.md](../docs/ubuntu-server.md) | Ubuntu / Python / Node / PM2 |
| `scripts/fix_hub_deps.sh` | 安装依赖 |
| `scripts/verify_hub_deploy.sh` | 部署验收 |
| `scripts/fix_env_crlf.sh` | 修复 .env 换行 |
# 多账户交易中控 — 部署文档(含 PM2)
本文档说明在 **Ubuntu / Linux** 上部署 **manual_trading_hub**(复盘系统中控:监控区,系统设置,登录保护)的推荐步骤.
- 功能与界面:[使用说明.md](./使用说明.md)
- **云服务器(VPS)完整配置**:[云服务器部署说明.md](./云服务器部署说明.md)
- **本地备份并迁到云上**:[本地数据迁移到云端.md](./本地数据迁移到云端.md)
- **局域网 IP:端口 / 反代域名,中控打开实例免登录**:[局域网与反代部署说明.md](./局域网与反代部署说明.md)
- 故障实录:[常见问题.md](./常见问题.md)
- 环境变量模板:[.env.example](./.env.example)
---
## 一,部署目标
| 组件 | 作用 | 默认监听 |
|------|------|----------|
| **hub.py** | 中控 Web + API | `0.0.0.0:5100` |
| **agent.py × N** | 各账户持仓 / 紧急全平 | `127.0.0.1:15200`～`15202` |
| **crypto_monitor_*.app** | 策略,关键位,下单逻辑 | 各目录 `.env` 的 `APP_PORT` |
- 账户列表与 URL 由 **`hub_settings.json`**(网页「系统设置」保存)或内置默认维护;**不再使用** `HUB_AGENTS`.
- 三实例 Flask **无需为中控改业务代码**(已注册 `hub_bridge`);与中控并行运行.
---
## 二,前置条件
1. **Python 3.10+**,`python3-venv`,`pip`.
2. **Node.js + npm**(用于安装 PM2):`sudo npm i -g pm2`.
3. 各 `crypto_monitor_*` 目录已 **`cp .env.example .env`** 并填好 API 密钥.
4. 端口无冲突:`5100`,`15200`～`15202`,各实例 `APP_PORT`(5000/5001/5004).
5. 建议代码路径:`/opt/crypto_monitor/`(下文用此示例,请按实际路径替换).
---
## 三,安装中控依赖
```bash
cd /opt/crypto_monitor/manual_trading_hub
python3 -m venv .venv
source .venv/bin/activate # 激活 venv(当前终端后续 pip/python 走虚拟环境)
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env:HUB_PORT,HUB_DISABLED_IDS,公网时 HUB_BRIDGE_TOKEN 等
chmod +x scripts/run_hub.sh scripts/run_agent.sh scripts/pm2_hub.sh scripts/pm2_agents.sh
chmod +x scripts/fix_hub_deps.sh scripts/verify_hub_deploy.sh scripts/fix_env_crlf.sh
deactivate # 可选;交给 PM2 时不必保持激活
```
**依赖说明**:`requirements.txt` 含 **`python-multipart`**(FastAPI 表单解析;旧版若保留下单接口时需要),**`psutil`**(监控区服务器状态条).当前中控**已移除下单区**,但仍建议安装完整依赖.
说明:
- **安装依赖**:必须在 **`manual_trading_hub/.venv`** 内执行,勿对系统 Python 直接 `pip install`(Debian/Ubuntu 会报 `externally-managed-environment`).`source .venv/bin/activate` 后用 `pip install` 即可;不写 `activate` 时也可用 **`.venv/bin/pip install -r requirements.txt`**(效果相同).快捷:`bash scripts/fix_hub_deps.sh`.
- **PM2 启动**:由 `scripts/run_hub.sh` 固定调用 **`.venv/bin/python`**,**不依赖**你是否在 shell 里激活过 venv.
- **监控磁盘**:可选环境变量 **`HUB_HOST_DISK_PATH`**(如 `/opt/crypto_monitor`),未设时 Linux 为 `/`,Windows 为系统盘.
子代理也使用 **本目录 `.venv`** 里的 Python(与各策略 Flask 的 venv 可分开).
---
## 四,推荐启动顺序
```
1. 各实例 Flask(APP_PORT) ← 各 crypto_monitor_* 目录 ecosystem.config.cjs
2. 中控 + 子代理(5100 + 15200～15202) ← 本目录一条 PM2 命令同时启动
```
**`ecosystem.config.cjs` 会一次拉起 3 个 agent + 1 个 hub**,无需再单独 `pm2 start` 子代理.
仅反代中控到公网时:Flask / agent 仍只监听 **127.0.0.1**;系统设置里 URL 填 `http://127.0.0.1:端口`.
---
## 五,PM2 托管(hub + agent 一起启动,推荐)
### 5.1 一条命令启动全部
| 文件 | 包含进程 |
|------|----------|
| `ecosystem.config.cjs` | `manual-agent-binance` / `okx` / `gate` + **`manual-trading-hub`** |
`run_hub.sh` 加载 **`manual_trading_hub/.env`** 后执行 `hub.py`;各 agent 经 **`run_agent.sh`** 在对应策略目录加载 **`.env`**(含 API 密钥),再执行 `agent.py`.
```bash
cd /opt/crypto_monitor/manual_trading_hub
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
pm2 start ecosystem.config.cjs # 4 个进程一起起
pm2 save
# 或
bash scripts/pm2_hub.sh start
```
### 5.2 PM2 进程一览
| 进程名 | 工作目录 | 端口/说明 |
|--------|----------|-----------|
| manual-agent-binance | crypto_monitor_binance | agent `15200` |
| manual-agent-okx | crypto_monitor_okx | agent `15201` |
| manual-agent-gate | crypto_monitor_gate | agent `15202` |
| manual-trading-hub | manual_trading_hub | hub `5100` |
OKX 子代理会启动;不用 OKX 可 `pm2 stop manual-agent-okx`.
### 5.3 常用运维命令
```bash
pm2 status
pm2 logs manual-trading-hub --lines 200
pm2 restart ecosystem.config.cjs # 重启 hub + 全部 agent
bash scripts/pm2_hub.sh restart # 同上
bash scripts/pm2_hub.sh stop
bash scripts/pm2_hub.sh logs
```
仅重启中控,不动 agent:
```bash
pm2 restart manual-trading-hub
```
仅重启子代理:
```bash
pm2 restart manual-agent-binance manual-agent-gate manual-agent-okx
# 或
bash scripts/pm2_agents.sh restart
```
### 5.4 开机自启
```bash
pm2 save
pm2 startup
# 按终端提示执行一行 sudo 命令后,再 pm2 save
```
### 5.5 与各实例 Flask 一起查看
```bash
pm2 status
# 示例同时存在:
# manual-trading-hub,manual-agent-*
# crypto_binance / crypto_gate …(各策略目录自有 ecosystem.config.cjs)
```
### 5.6 Gate 子代理「一会能连,一会子代理不可用」(Windows `.env` 换行)
**现象**:Gate 卡片红字「子代理不可用」;`pm2 logs manual-agent-gate` 反复出现:
```text
./.env: line 22: $'\r': command not found
agent start: exchange=gate port=15202 ...
```
**原因**:在 Windows 编辑的 `crypto_monitor_gate/.env` 为 **CRLF**,Linux 上 `source` 失败;PM2 反复重启,中控轮询时偶发连不上(**不是外网问题**).
**处理**(在服务器仓库根执行):
```bash
cd /opt/crypto_monitor
sed -i 's/\r$//' crypto_monitor_gate/.env
bash manual_trading_hub/scripts/fix_env_crlf.sh
cd manual_trading_hub
pm2 delete manual-agent-gate 2>/dev/null || true
pm2 start ecosystem.config.cjs --only manual-agent-gate
pm2 save
curl -s http://127.0.0.1:15202/status | head -c 200 # 应 ok:true
```
**预防**:`.env` 保存为 **LF**(勿在 Windows 记事本直接保存 CRLF).子代理须经 **`scripts/run_agent.sh`** 启动(内置去 CRLF 的 `load_dotenv_file`),勿裸跑 `python agent.py`.
详见 [常见问题.md](./常见问题.md) **§3.1**,**§3.3**.
---
## 六,手动启动(不用 PM2 时)
需**分别**起 agent 与 hub(与 PM2 合并启动不同):
```bash
# 子代理:由 ecosystem.config.cjs 经 run_agent.sh 启动(勿用手动多终端)
# 中控:
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/run_hub.sh
```
---
## 七,浏览器验收
1. **http://127.0.0.1:5100/login** — 若 `.env` 已设 `HUB_PASSWORD`,用 `HUB_USERNAME` / `HUB_PASSWORD` 登录.
2. **http://127.0.0.1:5100/monitor** — 已启用账户显示持仓;Flask 已起时有关键位/趋势信息.
3. **http://127.0.0.1:5100/market** — 行情区可选交易所与周期拉 K 线;升级后强刷浏览器,详见 [行情区说明.md](./行情区说明.md).
4. **http://127.0.0.1:5100/ai** — AI 教练(三户今日总结 + 聊天);`manual_trading_hub/.env` 配与三实例相同的 `AI_*` 变量,见 [AI教练说明.md](./AI教练说明.md).
5. **http://127.0.0.1:5100/settings** — 保存后生成 `hub_settings.json`(增加第五户,Gate 子账户等见 [使用说明.md §4.5](./使用说明.md#45-增加账户例如再挂一个-gate)).
5. 监控卡片 **「实例」** — 在各 `crypto_monitor_*` 网页做下单,关键位,趋势;中控**不提供**下单表单.
**命令行验收**(推荐):
```bash
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/verify_hub_deploy.sh
```
应看到:`OK: 无 api_trade_key`,`HTTP 200`,JSON 含 `"build":"20260521-no-trade-ui"`.
```bash
curl -s http://127.0.0.1:5100/api/ping
curl -s http://127.0.0.1:15200/status | head -c 200
```
---
## 八,仅反代中控到公网(实例不反代)
1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**,配置 **HTTPS**.
2. 反代需传递(登录 Cookie 正确识别 HTTPS):
```nginx
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
```
3. `manual_trading_hub/.env` **务必设置**:
```env
HUB_USERNAME=你的用户名
HUB_PASSWORD=你的强密码
HUB_SESSION_SECRET=随机长串
HUB_COOKIE_SECURE=true
```
4. `hub_settings.json` 中 Flask/Agent 保持 **`http://127.0.0.1:...`**(中控本机调 API).
5. 三实例 **`APP_AUTH_DISABLED=false`** + 与中控相同 **`HUB_BRIDGE_TOKEN`**.
6. 子代理 **`HOST=127.0.0.1`**;防火墙勿对公网开放 `15200`～`15202`,各 `APP_PORT`.
7. **复盘/实例外链**:`HUB_PUBLIC_ORIGIN=https://你的域名` 或内网 IP;否则其它设备点「复盘」会跳到 `127.0.0.1`.
**说明**:HTTPS 域名与 HTTP `内网IP:5100` Cookie **不共用**;内网访问 IP 需在 IP 地址再登录一次(见 [常见问题.md](./常见问题.md) §2.1).
---
## 九,环境变量(中控 `.env`)
| 变量 | 默认 | 说明 |
|------|------|------|
| `HUB_HOST` | `0.0.0.0` | 监听地址 |
| `HUB_PORT` | `5100` | 端口 |
| `HUB_DISABLED_IDS` | `1` | 强制关闭的账户 id(OKX) |
| `HUB_TRUST_LAN` | `true` | 私网可访问;仅本机可 `false` |
| `HUB_PUBLIC_ORIGIN` | 空 | 浏览器用复盘链接;如 `http://192.168.1.100`(**内网其它电脑访问中控时建议设置**) |
| `HUB_BRIDGE_TOKEN` | 空 | 与三实例一致;公网建议配置 |
| `HUB_USERNAME` | `admin` | Web 登录用户名 |
| `HUB_PASSWORD` | 空 | 非空即启用登录 |
| `HUB_SESSION_SECRET` | — | 会话签名 |
| `HUB_COOKIE_SECURE` | `false` | HTTPS 反代建议 `true` |
| `HUB_SESSION_DAYS` | `7` | 登录保持天数 |
本地联调,实例 `APP_AUTH_DISABLED=true` 时可不配 `HUB_BRIDGE_TOKEN`;本机不设 `HUB_PASSWORD` 则无需登录页.
---
## 十,升级与回滚
```bash
cd /opt/crypto_monitor
git pull
cd manual_trading_hub
bash scripts/fix_hub_deps.sh
bash scripts/verify_hub_deploy.sh
pm2 restart ecosystem.config.cjs
# 若只改了中控:pm2 restart manual-trading-hub
```
- **`hub_settings.json`**,**`hub_ai_summaries.json`**,**`hub_ai_chat.json`**,**`.env`** 不在 Git 中,`git pull` 不会覆盖.
- 升级前可备份:`cp hub_settings.json hub_settings.json.bak`,`cp hub_ai_*.json hub_ai_backup/`,`cp .env .env.bak`.
**升级后自检**:`curl -s http://127.0.0.1:5100/api/ping` 须含 `"trade_ui":false`.若仍见 `api_trade_key` 报错,说明代码未更新或未重启,见 [常见问题.md](./常见问题.md) §1.
---
## 十一,故障排查(速查)
**完整实录**见 **[常见问题.md](./常见问题.md)**.
| 现象 | 处理 |
|------|------|
| PM2 启动后立刻退出 | `pm2 logs manual-trading-hub`;检查 `.venv`,`.env`,`run_hub.sh` |
| `api_trade_key` / `python-multipart` | `git pull` → `bash scripts/fix_hub_deps.sh` → `verify_hub_deploy.sh` → 重启 hub |
| `verify` ping 解析失败 | hub 未起:`pm2 restart manual-trading-hub` |
| 余额显示 — | agent 未加载 `.env`;`fix_env_crlf.sh`;`run_agent.sh` |
| agent `$'\r': command not found` | `bash scripts/fix_env_crlf.sh` |
| 监控无持仓 | `curl http://127.0.0.1:15200/status` |
| 无关键位 / 401 | 启动 Flask;核对 `HUB_BRIDGE_TOKEN` / `hub_bridge` |
| 域名能登,IP 不能登 | 见常见问题 §2.1(Cookie / HTTP vs HTTPS) |
| 公网访问中控 403 | 反代到 `127.0.0.1:5100`,勿公网直连 5100 |
| 改 `.env` 不生效 | `pm2 restart manual-trading-hub` |
---
## 十二,进程托管说明
中控与子代理 **仅使用 PM2**(`ecosystem.config.cjs`).勿再用 screen / systemd / nohup 启动 `hub.py` 或 `agent.py`,以免端口冲突.
环境要求见 **[docs/ubuntu-server.md](../docs/ubuntu-server.md)**.
---
## 十三,安全清单
- [ ] 公网仅暴露反代端口,不暴露 Flask/agent 端口
- [ ] 已设 `HUB_USERNAME` + `HUB_PASSWORD`(中控 Web 登录)
- [ ] HTTPS 反代已设 `HUB_COOKIE_SECURE=true` 且传递 `X-Forwarded-Proto`
- [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED`
- [ ] API Key 最小权限;交易所 IP 白名单
- [ ] 已告知操作人员「全局全平」不可撤销;中控**不在网页下单**
---
## 十四,文档索引
| 文档 | 内容 |
|------|------|
| [使用说明.md](./使用说明.md) | 功能,页面,API,环境变量 |
| [常见问题.md](./常见问题.md) | 故障实录 |
| [README.md](./README.md) | 速览 |
| [.env.example](./.env.example) | 环境变量模板 |
| [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | PM2 常驻(唯一推荐) |
| [docs/ubuntu-server.md](../docs/ubuntu-server.md) | Ubuntu / Python / Node / PM2 |
| `scripts/fix_hub_deps.sh` | 安装依赖 |
| `scripts/verify_hub_deploy.sh` | 部署验收 |
| `scripts/fix_env_crlf.sh` | 修复 .env 换行 |