dekun
112 lines
6.0 KiB
Markdown
112 lines
6.0 KiB
Markdown
# Gate.io USDT Perpetual Monitor (Exchange-Only)
|
||
|
||
> 仓库总览与 Git 克隆见上级目录：[../README.md](../README.md)、[../CLONE.md](../CLONE.md)。
|
||
|
||
Python service for 7x24 monitoring of **Gate.io USDT-settled linear perpetual futures** using **public REST v4** market data (no on-chain dependency).
|
||
|
||
## Policy（主线）
|
||
|
||
- Only **live Gate USDT linear perpetual** contracts (`BASE_USDT`, non-delisting) are eligible.
|
||
- **`monitor.universe: all_swaps` (default)**：自动扫 Gate 上架中的线性合约，用 `min_24h_quote_volume_usdt` 按 24h **计价货币（USDT）成交额**过滤（默认 **≥ 1 百万 USDT**，可在 `config.yaml` 调整）；**不要**混用 `watch_symbols`。成交额优先读 ticker 的 `volume_24h_quote`。
|
||
- **`monitor.universe: watchlist`**：只监控 `watch_symbols` 里列出的 base 合约（须为 Gate 上架 USDT 线性）。
|
||
- `all_swaps` 模式下 **`min_24h_quote_volume_usdt` 必须大于 0**，否则会扫全市场（极低流动性）。
|
||
- 监控主周期 **5m**，规则与触发逻辑见 `app/exchange_rules.py`。
|
||
|
||
### 附加（非产品主线说明）
|
||
|
||
- **`monitor.btc_daily_gate_enabled`（默认关闭）**：可选的 **BTC 日线横盘过滤**——在判定为日线横盘 regime 下叠加 **K 线形态**等附加条件；实验性/非必选风控，**不作为对外产品主线说明**。实现见 `app/btc_regime.py`，可在 `config.yaml` 关闭。
|
||
|
||
### 自动下单（gate_order_executor）
|
||
|
||
- **下单执行器**：在 Web 面板 **「下单执行器 · 转发链」** 维护列表（`runtime/order_executors.json`），支持运行中增删；首次启动可从 `config.yaml` 的 `order_executor` 导入一条。
|
||
- 仅在 **企业微信突破推送成功之后**，向列表中已启用的执行器 **广播** 同一 `POST /v1/signal`；价位与企微 **方案 A** 一致。详见 [`docs/多执行器与信号转发归档.md`](docs/多执行器与信号转发归档.md)。
|
||
- 该 HTTP 请求 **不走** `proxy.url`，便于同机访问执行器。
|
||
|
||
全市场模式下扫描量较大，建议把 `poll_interval_seconds` 调到 **300 秒或更长**，并遵守 Gate 公开频率限制。
|
||
|
||
## Web Panel
|
||
|
||
- Login required for all `/api/*` and dashboard (unless `auth.enabled: false`).
|
||
- **MATRIX 主视图**：表格列为 **Gemma 漏斗评分**（`/api/funnel`），按 `composite_score` 排序。
|
||
- **K 线周期**：监控主周期 **5m**；其它周期沿用内部命名（如 `4H`、`1D`），在 `app/gate.py` 映射为 Gate 的 `interval`。
|
||
|
||
## Gemma 漏斗（本地 Ollama）
|
||
|
||
1. 安装并启动 [Ollama](https://ollama.com)，`ollama pull` 你的 Gemma 模型（如 `gemma2:2b`）；多模态需带 vision 的 tag 才能送 K 线图。
|
||
2. 在 `config.yaml` 中 `gemma.enabled: true`，按需改 `model`、`ollama_base_url`。
|
||
3. 每个 **5m 扫描** 产生 `WATCH` / `TRIGGER` 后，按 **24h 成交额** 与 `max_funnel_per_cycle` 上限，取 **日线 OHLCV** + 可选图表；按 `vision_top_n` 张 **matplotlib 生成的 PNG 截图**（base64）给 Ollama（纯文本模型设 `send_chart_image: false`）。
|
||
4. 模型必须返回 JSON 结构（见 `app/gemma_client.py`）。合并 `composite_score` 后写入 `alerts`（`details.source === gemma_funnel`）；若 `priority >= gemma_push_priority_min` **或** `composite_score >= composite_push_min`，则 **企业微信** 推送一条「MATRIX · 漏斗优先」提醒。
|
||
5. 若 Ollama 对 `format: json` 不稳，可将 `gemma.json_mode` 设为 `false`。
|
||
|
||
## Project Layout
|
||
|
||
```text
|
||
onchain_scout_gate/
|
||
app/
|
||
main.py
|
||
web.py
|
||
monitor.py
|
||
gate.py
|
||
exchange_rules.py
|
||
btc_regime.py
|
||
daily_features.py
|
||
chart_candles.py
|
||
gemma_client.py
|
||
notifier.py
|
||
order_executor_forward.py
|
||
storage.py
|
||
models.py
|
||
config.py
|
||
templates/
|
||
static/
|
||
deploy/
|
||
ecosystem.config.cjs # PM2: python -m app.main
|
||
onchain-scout.service # 可选：systemd + pm2-runtime
|
||
config.example.yaml
|
||
requirements.txt
|
||
```
|
||
|
||
## 本地 / 服务器部署（PM2，推荐）
|
||
|
||
1. Python **3.10+**，`python -m venv .venv`，`pip install -r requirements.txt`。
|
||
2. 复制 `config.example.yaml` → `config.yaml`，填写 `auth`、`wecom`、`monitor` 等。
|
||
3. 安装 [Node.js](https://nodejs.org/) 后：`npm install -g pm2`。
|
||
4. 在项目根：**`pm2 start deploy/ecosystem.config.cjs`**
|
||
5. 常用：`pm2 logs onchain-scout`、`pm2 restart onchain-scout`、`pm2 save`（配合 `pm2 startup` 开机）。
|
||
|
||
监听地址与端口以 **`config.yaml`** 的 `app.host` / `app.port`（与 `app.main` 起 uvicorn 一致）。
|
||
|
||
## SOCKS5 代理
|
||
|
||
- 代理写在 **`config.yaml` 的 `proxy`**（`enabled` / `url`），仅用于访问 **Gate** 的 httpx；**当前实现**里企业微信等为直连 `proxy_url=None`；**本地 Ollama 不走代理**。
|
||
- 详见 **[docs/本地部署-SOCKS5代理.md](docs/本地部署-SOCKS5代理.md)**。
|
||
|
||
## Linux Quick Start（venv + PM2）
|
||
|
||
```bash
|
||
cd /opt/onchain_scout_gate
|
||
chmod +x deploy/bootstrap.sh
|
||
./deploy/bootstrap.sh /opt/onchain_scout_gate
|
||
# 编辑 config.yaml
|
||
source .venv/bin/activate
|
||
npm install -g pm2
|
||
pm2 start deploy/ecosystem.config.cjs
|
||
```
|
||
|
||
也可用当前脚本快速试：**`deploy/start.sh`**（uvicorn，非 PM2）。
|
||
|
||
## systemd（可选）
|
||
|
||
长期用 systemd 托管 **PM2**（进程用 `pm2-runtime`），可参考 `deploy/onchain-scout.service`（需已安装 `pm2`，并按环境改 `WorkingDirectory` / `ExecStart`）。
|
||
|
||
## Config Keys
|
||
|
||
- `gate.api_base`：默认 `https://api.gateio.ws/api/v4`；亦可按官方文档使用 `https://fx-api.gateio.ws/api/v4`。
|
||
- `gate.settle`：USDT 线性填 `usdt`。
|
||
- `gate.quote_currency`：计价货币，默认 `USDT`。
|
||
- `monitor.universe`: `all_swaps` | `watchlist`.
|
||
- `watch_symbols`: 仅在 `watchlist` 模式下使用。
|
||
- `monitor.min_24h_quote_volume_usdt`: 24h 成交额（USDT）下限；`all_swaps` 须填 `>0`。默认 **1 百万**。
|
||
- `monitor.btc_daily_gate_enabled` / `btc_sideways_*`: **可选** BTC 日线横盘过滤（**非主线说明**）；默认关闭，见 `config.yaml`。
|
||
- `gemma.*`、`proxy.*`、`app.poll_interval_seconds`: 见 `config.example.yaml`。
|