110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
# TradingView Alert Dispatcher
|
||
|
||
接收 TradingView webhook alert，按 `timeframe / symbol / strategy` 等条件路由到飞书 webhook，并提供管理控制台。
|
||
|
||
## Run Locally
|
||
|
||
```bash
|
||
python3 -m app
|
||
```
|
||
|
||
默认地址：`http://localhost:8000`
|
||
|
||
默认登录：
|
||
|
||
- 用户名：`admin`
|
||
- 密码：由 `ADMIN_PASSWORD` 决定，`.env.example` 中示例为 `12345678`
|
||
|
||
首次启动会把 `ADMIN_PASSWORD` 写入数据库并保存为哈希。之后请在管理台的「账号安全」页面修改密码；修改后环境变量不会覆盖数据库中的新密码。
|
||
|
||
Docker Compose 会自动读取同目录 `.env`。示例：
|
||
|
||
```env
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=12345678
|
||
SESSION_SECRET=DBUwycvdxjSUZX4LMvUKa0xMzWKzFJmg
|
||
WEBHOOK_TOKEN=vvyVmc33aC0I85LkH4yrd6ojvkqmyrb1
|
||
```
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
Compose 会启动两个服务：`dispatcher` 负责 Web/API/管理台，`worker` 负责周期性处理失败重试。
|
||
|
||
## Delivery Reliability
|
||
|
||
系统采用“先入库、后发送”的至少一次投递模型：
|
||
|
||
- TradingView webhook 命中规则后，会先写入 `alerts` 和 `deliveries`，再异步发送飞书。
|
||
- 未发送的飞书会保留在 `deliveries`，状态为 `pending`、`processing`、`retry` 或 `failed`。
|
||
- 每次实际发送尝试都会写入 `delivery_attempts`，包括 HTTP 状态、飞书返回体、错误原因和下次重试时间。
|
||
- 发送失败会按 `RETRY_BACKOFF_SECONDS` 延迟重试，直到达到 `MAX_DELIVERY_ATTEMPTS`。
|
||
- 飞书 HTTP 200 但响应体业务码非 0 时，也会按失败处理并进入重试。
|
||
- 管理台「日志」页面可以查看未发送、重试中、失败的分发记录，并可手动立即重发。
|
||
|
||
## TradingView Payload
|
||
|
||
```json
|
||
{
|
||
"timeframe": "5m",
|
||
"symbol": "BTCUSDT",
|
||
"strategy": "breakout",
|
||
"action": "buy",
|
||
"price": 68000
|
||
}
|
||
```
|
||
|
||
发送到：
|
||
|
||
```text
|
||
POST /webhook/tradingview
|
||
Content-Type: application/json
|
||
```
|
||
|
||
如果设置了 `WEBHOOK_TOKEN`，TradingView 需要使用以下任一方式携带 token：
|
||
|
||
```text
|
||
POST /webhook/tradingview?token=your-shared-secret
|
||
X-Webhook-Token: your-shared-secret
|
||
```
|
||
|
||
`docker-compose.yml` 默认已经设置了占位 token，生产使用前请替换；本地临时调试如果不想校验 token，可以把 `WEBHOOK_TOKEN` 置为空。
|
||
|
||
## Feishu Webhooks
|
||
|
||
「飞书 Webhook」页面只维护目标名称和机器人地址。目标一旦被路由规则选中就会发送，不再提供启用/停用状态。
|
||
|
||
## Feishu Message Templates
|
||
|
||
路由规则统一发送飞书 interactive card。可以先在「飞书模板」页面维护常用卡片模板，再在新增或编辑路由规则时从下拉框一键套用。
|
||
|
||
标题和正文模板支持 `{{field}}` 占位符，字段来自 TradingView alert JSON。嵌套字段可以写成 `{{order.id}}`。
|
||
|
||
每条路由规则通过「发送到」多选框选择一个或多个飞书 Webhook。`timeframe`、`symbol`、`strategy` 至少填写一个，空字段表示不限。例如只填 `symbol=BTCUSDT` 会匹配所有 BTCUSDT 信号。当前默认路由逻辑只匹配最高优先级的规则，但这条规则可以同时分发到多个飞书目标。
|
||
|
||
示例正文模板：
|
||
|
||
```text
|
||
**品种**: {{symbol}}
|
||
**周期**: {{timeframe}}
|
||
**策略**: {{strategy}}
|
||
**动作**: {{action}}
|
||
**价格**: {{price}}
|
||
```
|
||
|
||
## Environment
|
||
|
||
- `ADMIN_USERNAME`
|
||
- `ADMIN_PASSWORD`
|
||
- `SESSION_SECRET`
|
||
- `WEBHOOK_TOKEN`
|
||
- `DATABASE_PATH`
|
||
- `RETENTION_DAYS`
|
||
- `MAX_DELIVERY_ATTEMPTS`
|
||
- `RETRY_BACKOFF_SECONDS`
|
||
- `FEISHU_TIMEOUT_SECONDS`
|
||
- `WORKER_INTERVAL_SECONDS`
|