crypto_monitor/crypto_monitor_gate/使用说明.md

使用说明

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

更细的部署（SSH 代理、PM2、依赖安装） 见同目录 部署文档.md。
关键位自动开仓的规则、RR、结案原因 见 关键位自动下单说明.md。

---

1. 它能做什么

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

模块	说明
关键位监控	录入上/下沿与类型，按 5m 收线 做硬条件过滤；符合条件后 企业微信 提醒，部分类型可 自动市价开仓（见第 4 节与专门文档）。
实盘下单监控	手工填止损/止盈，以损定仓 市价开单，挂上条件止盈止损，并在页面跟踪浮盈亏、保本逻辑等。
交易记录 / 复盘	平仓结果、盈亏、错过的单等归档与导出；可选 AI 复盘（见 AI复盘与模型配置说明.md）。
策略交易	顶栏 /strategy：趋势回调 + 顺势加仓双栏；见 策略交易说明.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	本仓库： GATE_API_KEY、GATE_API_SECRET；合约相关见 GATE_MARGIN_MODE、GATE_POS_MODE、GATE_TPSL_* 等。勿把 .env 提交到 Git。
关键位 RR / 止损外扩	KEY_AUTO_MIN_PLANNED_RR、KEY_STOP_OUTSIDE_BREAKOUT_PCT（详见 关键位自动下单说明.md）。
AI 复盘	AI_PROVIDER=openai（默认）或 ollama；变量见 .env.example 与 AI复盘与模型配置说明.md。

网络不稳定时可为 Gate 配置 GATE_SOCKS_PROXY 等（见 部署文档.md）。

---

3. 如何启动与登录

1. 按 部署文档.md 建好虚拟环境、安装依赖（如 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 次微信，然后本条 结案进历史。
   关键支撑位	同上（仅提醒）。

3. 方向：做多 / 做空（必选）。

4. 上沿 / 下沿：必填；保存时会按交易所 价格精度 取整。

限制：
活跃持仓数达到 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 列表与历史

• 当前条目可 删除（会按规则记入历史的情形见页面说明）。
• 关键位历史：已结案记录；可配合导出链接（若有）做备份。

---

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

用于 自己点按钮 开单：

• 持仓上限由 MAX_ACTIVE_POSITIONS 控制（默认 1，与关键位自动单共用）。
• 人工开仓时计划盈亏比不得低于 MANUAL_MIN_PLANNED_RR（默认 1.4:1），否则页面弹窗且后端拒绝。
• 填写币种、方向、杠杆（可选）、止损/止盈（价格或百分比按表单说明）。
• 勾选是否启用 移动保本 等行为以 .env/页面默认值为准。

平仓通过页面 平仓（或等价入口），会从交易所市价处理并更新记录。删除/误操作可能造成真实盈亏，请先确认环境与方向。

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

---

6. 企业微信会看到什么

• 关键位：按类型与结案结果推送（RR 不足、下单失败、自动开仓成功、仅阻力支撑提醒等），每条关键位结案路径原则上一条主推送（详见 关键位自动下单说明.md）。
• 手工开仓、平仓、部分异常也会在规则满足时推送（以代码与配置为准）。

若未配置 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. 升级代码后：启动时会跑 数据库迁移（如新列 order_monitors.monitor_type）；首次启动关注一下日志或无报错页面。

---

8. 常见问题（简要）

现象	可自查
关键位永远不触发	5m 门控是否全通过（页面门控摘要）、币种日成交量是否在规则内、KLINE_TIMEFRAME。
有信号但不自动开仓	LIVE_TRADING_ENABLED、KEY_AUTO_MIN_PLANNED_RR、计划 RR、是否已有持仓、API/余额报错（微信或日志）。
加不了箱体/收敛	是否已有活跃持仓；先平仓或改用「阻力/支撑位」仅提醒。
推送收不到	WECHAT_WEBHOOK、企业微信机器人配额与网络。

---

9. Binance 版（crypto_monitor_binance）差异速查

项目	Gate 本仓库	Binance 版
API 变量	GATE_API_KEY、GATE_API_SECRET、GATE_*	BINANCE_API_KEY、BINANCE_API_SECRET、BINANCE_*
实盘开关	LIVE_TRADING_ENABLED（通用）	同上
止盈止损挂载路径	_gate_place_tp_sl_orders 与 GATE_TPSL_*	_binance_place_tp_sl_orders（U 本位条件单）
资金显示舍入	以本仓库为准	与 FUNDS_DECIMALS 等一致
专门文档	关键位自动下单说明.md（各仓库有一份，开头标明交易所）	同左

操作流程（登录、关键位四类、手工单、单仓）两份程序一致：换目录、换 .env 即可对照使用。