# 使用说明

**本文件对应仓库：`crypto_monitor_okx`（OKX USDT 本位永续）。**  
功能、界面与 **Gate.io USDT 永续版**（目录 `crypto_monitor_gate`）基本一致，差异主要在 **`.env` 里交易所密钥与部分参数名**（`OKX_*` / `GATE_*`），文末有对照。

**部署、代理、PM2 等**请参考本仓库说明或 **`crypto_monitor_gate`** 下的 **`部署文档.md`**（该文以 Gate + SSH SOCKS 为例；OKX 侧将 API 与密钥改为 `OKX_*` 即可类比）。  
**关键位自动开仓的规则、RR、结案原因**见本目录 **`关键位自动下单说明.md`**。

---

## 1. 它能做什么

面向个人盘面的 **Web 控制台**，主要能力包括：

| 模块 | 说明 |
|------|------|
| **关键位监控** | 录入上/下沿与类型，按 **5m 收线** 做硬条件过滤；符合条件后 **企业微信** 提醒，部分类型可 **自动市价开仓**（见第 4 节与专门文档）。 |
| **实盘下单监控** | 手工填止损/止盈，**以损定仓** 市价开单，挂上条件止盈止损，并在页面跟踪浮盈亏、保本逻辑等。 |
| **交易记录 / 复盘** | 平仓结果、盈亏、错过的单等归档与导出；可选 **AI 复盘**（见仓库根 [AI复盘与模型配置说明.md](../AI复盘与模型配置说明.md)）。 |
| **策略交易** | 顶栏 `/strategy`：**趋势回调**（左）与 **顺势加仓**（右）左右并列；细则见 [策略交易说明.md](../策略交易说明.md)。 |

后台按 **`MONITOR_POLL_SECONDS`**（默认几秒）轮询行情与监控逻辑。**切勿**在未理解规则时同时运行两套程序共用一个实盘账户。

---

## 2. 运行前必须配置（`.env`）

首次在本目录执行 **`cp .env.example .env`**，再编辑 `.env`（`.env` 勿提交 Git；`git pull` 不会改你的 `.env`，升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`）。

至少检查以下项（具体键名以 **`.env.example`** 为准）：

| 类别 | 说明 |
|------|------|
| **登录网页** | `APP_PASSWORD`：打开站点后的登录口令。`FLASK_SECRET_KEY`：Session 密钥，请勿使用默认值。 |
| **企业微信** | `WECHAT_WEBHOOK`：告警与关键位推送机器人的 Webhook。 |
| **是否真下单** | `LIVE_TRADING_ENABLED=false`：**不会**向交易所发送开仓指令（适合测试流程）。改为 `true` 且密钥正确才会实盘。 |
| **交易所 API** | **本仓库：** `OKX_API_KEY`、`OKX_API_SECRET`；永续相关见 `OKX_TD_MODE`、`OKX_POS_MODE`、`OKX_TRIGGER_WORKING_TYPE` 等。**勿**把 `.env` 提交到 Git。 |
| **关键位 RR / 止损外扩** | `KEY_AUTO_MIN_PLANNED_RR`、`KEY_STOP_OUTSIDE_BREAKOUT_PCT`（详见 `关键位自动下单说明.md`）。 |
| **AI 复盘** | 默认 `AI_PROVIDER=openai`，`OPENAI_API_BASE=https://op.bz121.com/v1`、`OPENAI_API_KEY`、`OPENAI_MODEL=gemma4:e4b`；或 `AI_PROVIDER=ollama` + `OLLAMA_API` / `AI_MODEL`。详见 [AI复盘与模型配置说明.md](../AI复盘与模型配置说明.md)。 |

网络需要代理时可配置 **`OKX_SOCKS_PROXY` / `OKX_HTTP_PROXY`**（与 Gate 版 `GATE_*_PROXY` 用法类似）。

---

## 3. 如何启动与登录

1. 准备 Python 虚拟环境并安装依赖（如 `flask`、`requests`、`ccxt`、按需 `Pillow`、`PySocks` 等），配置好 `.env`。  
2. 启动 Flask 应用（可用 **`ecosystem.config.cjs`** 交给 PM2，或本地 `python app.py` / `flask run`，以你当前脚本为准）。  
3. 浏览器访问站点，打开 **`/login`**，使用 **`.env` 里的 `APP_PASSWORD`** 登录。

登录后顶栏：**关键位监控** | **实盘下单**（默认首页）| **策略交易**（`/strategy`，趋势回调 + 顺势加仓双栏）| **策略交易记录**（`/strategy/records`）| **交易记录与复盘** | **统计分析**。

---

## 4. 关键位监控（顶栏「关键位监控」→ `/key_monitor`）

### 4.1 添加一条关键位

1. **币种**：如 `BTC` 或 `BTC/USDT`（会规范成内部符号）。  
2. **类型**（必选其一）：  

   | 类型 | 行为摘要 |
   |------|----------|
   | **箱体突破** | 通过门控且计划 RR 达标 → **自动市价开仓**（需 `LIVE_TRADING_ENABLED=true` 且无其他持仓占位）。结案后本条从列表消失并记入历史。 |
   | **收敛突破** | 同上（自动开仓类）。 |
   | **关键阻力位** | **不自动开仓**；触发后 **发 1 次微信**，然后本条 **结案进历史**。 |
   | **关键支撑位** | 同上（仅提醒）。 |
   | **触价开仓** | **不挂交易所限价**；标记价触达计划入场价后 **下一轮询市价开仓**（RR 门槛同关键位 `KEY_AUTO_MIN_PLANNED_RR`）；有效期 **24h**；全仓杠杆模式可用。 |

3. **方向**：做多 / 做空（触价开仓 / 箱体 / 收敛 / 斐波必选；阻力/支撑不选）。  
4. **价位**：箱体/收敛/阻力/支撑填 **上沿 / 下沿**；触价开仓填 **入场 E / 止损 SL / 止盈 TP**。

**限制：**  
活跃持仓数达到 **`MAX_ACTIVE_POSITIONS`**（默认 1）时，**不允许**再添加「**箱体突破** / **收敛突破**」；仍可添加「**关键阻力位 / 支撑位**」。  
若 **4h EMA55** 与你的方向逆势，页面会 **额外 Flash 提示**，**不阻挡**提交。

### 4.2 触发后会发生什么（简版）

- **箱体 / 收敛**：门控通过后算计划 SL/TP 与 RR；不达标 → 微信说明 + **`rr_insufficient`** 结案；达标 → **市价开仓**，成功 **`auto_opened`** / 失败 **`exchange_failed`**，均不重试同一关键位。  
- **阻力 / 支撑**：仅 **单次推送** → **`key_level_alert_only`** 结案。

详细公式与字段见 **`关键位自动下单说明.md`**。

### 4.3 列表与历史

当前条目与历史记录的用法与 Gate 版相同；结案后可在历史区查阅 **`close_reason`**。

---

## 5. 实盘下单（顶栏「实盘下单」→ `/trade`）

- 持仓上限由 **`MAX_ACTIVE_POSITIONS`** 控制（默认 1）。  
- **人工开仓**计划盈亏比不得低于 **`MANUAL_MIN_PLANNED_RR`**（默认 1.4:1）。  
- 填写币种、方向、杠杆（可选）、止损/止盈（价格或百分比按表单）。  
- 移动保本等选项按页面与 `.env` 默认。

开仓成功后卡片 **「来源」**：手工一般为 **下单监控**；关键位自动为 **关键位监控**。

---

## 6. 企业微信

推送逻辑与 Gate 版一致；未配置 **`WECHAT_WEBHOOK`** 时可能没有消息，请以 **交易所端** 核对持仓与挂单。

---

## 7. 强烈建议的风险与运维习惯

1. **先用 `LIVE_TRADING_ENABLED=false`** 熟悉流程再实盘。  
2. **API 权限**最小化，密钥勿泄露。  
3. **同一账户避免多程序重复开仓**。  
4. **自动备份**：服务器上执行 `bash scripts/install_backup_cron.sh`（每天北京时间 0:00 → `/root/backups`，保留 30 天）；升级前也可 `bash scripts/backup_data.sh` 手动跑一次。  
5. 升级代码后留意 **首轮启动**有无数据库迁移报错。

---

## 8. 常见问题（简要）

| 现象 | 可自查 |
|------|--------|
| 关键位永远不触发 | 门控五项、日成交量排名、`KLINE_TIMEFRAME`。 |
| 有信号但不自动开仓 | `LIVE_TRADING_ENABLED`、RR 阈值、是否已有持仓、API/保证金错误信息。 |
| 加不了箱体/收敛 | 是否已有持仓。 |
| 推送收不到 | Webhook、网络。 |

---

## 9. 与币安版（`crypto_monitor_binance`）差异速查

| 项目 | OKX 本仓库 | 币安版 |
|------|------------|--------|
| API 变量 | `OKX_API_KEY`、`OKX_API_SECRET`、`OKX_API_PASSPHRASE` | `BINANCE_API_KEY`、`BINANCE_API_SECRET` |
| 代理 | `OKX_SOCKS_PROXY` | `BINANCE_SOCKS_PROXY` |
| 默认端口 | 常为 `5004` | 常为 `5001` |
| TP/SL 实现 | `_okx_place_tp_sl_orders`、页面 `/api/order/.../cancel_tpsl` | `_binance_place_tp_sl_orders` |

业务流程、顶栏分栏、策略交易、风控参数名已与币安版对齐；仅需更换目录与 `.env`。