docs: LAUNCH_CHECKLIST.md — step-by-step deploy guide with troubleshooting
Covers: env vars (what each one does and how to generate secrets), alembic upgrade, preflight check, launch_seed --seed-only warmup, start service, launch_smoke 14-check, BotFather /setcommands (exact paste-ready list), paper mode test checklist, UptimeRobot monitoring setup, and a quick-reference fault-finding table. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
k
@@ -0,0 +1,227 @@
|
||||
# 上线前操作手册
|
||||
|
||||
按顺序执行。每一项打✅后再往下。
|
||||
|
||||
---
|
||||
|
||||
## 第一步：填环境变量（在服务器上）
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # 或用你喜欢的编辑器
|
||||
```
|
||||
|
||||
逐项填写（全是必填，没有可以空着的）：
|
||||
|
||||
### 必填 — 少一个就无法启动
|
||||
|
||||
```bash
|
||||
# 1. 数据库
|
||||
DATABASE_URL=postgresql+asyncpg://trumpsignal:你的密码@localhost:5432/trumpsignal
|
||||
|
||||
# 2. 前端 CORS（必须和你部署的前端域名一致，不然浏览器全部 403）
|
||||
FRONTEND_URL=https://trumpsignal.com
|
||||
|
||||
# 3. HL API Key 加密密钥（生成：openssl rand -hex 32）
|
||||
# ⚠️ 生成后立刻备份到 deploy/ENCRYPTION_KEY_BACKUP.md
|
||||
# ⚠️ 一旦用户保存了 HL key，这个值不能再变，变了所有 key 作废
|
||||
ENCRYPTION_KEY=（openssl rand -hex 32 的输出）
|
||||
|
||||
# 4. 信号摄入接口密钥（生成：openssl rand -hex 32）
|
||||
INGEST_API_KEY=（openssl rand -hex 32 的输出）
|
||||
|
||||
# 5. AI 密钥（二选一，优先用 DeepSeek 因为便宜快）
|
||||
# 方案A（DeepSeek）：Trump 信号 + KOL 分析都走 DeepSeek
|
||||
AI_API_KEY=你的 DeepSeek API key
|
||||
AI_BASE_URL=https://api.deepseek.com/v1
|
||||
AI_MODEL=deepseek-v4-pro
|
||||
AI_LIVE_MODEL=deepseek-v4-flash
|
||||
# 方案B（Anthropic）：KOL 分析走 Claude，Trump 走 DeepSeek
|
||||
# ANTHROPIC_API_KEY=你的 Anthropic key
|
||||
# ⚠️ ANTHROPIC_API_KEY 优先级高于 AI_API_KEY（两个都填了用 Anthropic）
|
||||
|
||||
# 6. Telegram
|
||||
TELEGRAM_BOT_TOKEN=从 BotFather 拿到的 token（格式：123456:ABCDEF-xxxxx）
|
||||
TELEGRAM_BOT_USERNAME=你的 bot 用户名（不含 @，比如 trumpalpha_bot）
|
||||
|
||||
# 7. Etherscan（KOL 链上背离必须，否则链上数据为空）
|
||||
ETHERSCAN_API_KEY=从 etherscan.io 拿
|
||||
|
||||
# 8. Telegram 公共频道（Trump mention 告警发到这里）
|
||||
TELEGRAM_PUBLIC_CHANNEL_ID=@你的频道名
|
||||
|
||||
# 9. 运行环境
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
生成随机密钥的命令：
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第二步：数据库迁移
|
||||
|
||||
```bash
|
||||
# 确认迁移链完整（应该显示 026）
|
||||
alembic heads
|
||||
|
||||
# 执行迁移（首次部署会跑 001→026 全部）
|
||||
alembic upgrade head
|
||||
|
||||
# 验证当前版本
|
||||
alembic current
|
||||
# 输出应该是：026 (head)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第三步：运行 preflight（上线前健康检查）
|
||||
|
||||
```bash
|
||||
DATABASE_URL=$DATABASE_URL python scripts/preflight.py
|
||||
```
|
||||
|
||||
必须全绿。常见失败原因和修法：
|
||||
|
||||
| 报错 | 原因 | 修法 |
|
||||
|---|---|---|
|
||||
| `ENCRYPTION_KEY looks like a placeholder` | 没改默认值 | `openssl rand -hex 32` 重新生成 |
|
||||
| `DB connection failed` | DATABASE_URL 错误 | 检查用户名/密码/host/库名 |
|
||||
| `Telegram: 401 Unauthorized` | TELEGRAM_BOT_TOKEN 错误 | 回 BotFather 确认 token |
|
||||
| `AI provider: model not found` | AI_API_KEY 或 AI_BASE_URL 错误 | 检查 DeepSeek 控制台 |
|
||||
| `INGEST_API_KEY not set` | 忘填了 | openssl rand -hex 32 填进去 |
|
||||
|
||||
---
|
||||
|
||||
## 第四步：预热数据（首次上线必须）
|
||||
|
||||
生产库是空的，不跑这步用户进来全是空页面。
|
||||
|
||||
```bash
|
||||
# 只拉数据，不删任何东西
|
||||
DATABASE_URL=$DATABASE_URL python scripts/launch_seed.py --seed-only
|
||||
```
|
||||
|
||||
输出示例（正常）：
|
||||
```
|
||||
[1/5] Trump backfill (CNN archive)... ✓ done
|
||||
[2/5] KOL Substack/podcast/blog polling... ✓ done — 47 new posts (0 errors)
|
||||
[3/5] KOL on-chain snapshot... ✓ done
|
||||
[4/5] KOL divergence detection... ✓ done — 0 new divergence/alignment pairs
|
||||
[5/5] Scanner exercise skipped by default.
|
||||
```
|
||||
|
||||
常见失败：
|
||||
- `[2/5] FAILED: httpx.ConnectError` → 服务器出网被封，检查防火墙
|
||||
- `[3/5] FAILED: etherscan` → ETHERSCAN_API_KEY 没填或超限
|
||||
|
||||
---
|
||||
|
||||
## 第五步：启动服务
|
||||
|
||||
### Docker Compose（推荐）
|
||||
```bash
|
||||
docker compose up -d
|
||||
docker compose logs -f api # 看启动日志，等看到 "Application startup complete."
|
||||
```
|
||||
|
||||
### systemd
|
||||
```bash
|
||||
sudo cp deploy/trumpsignal-api.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now trumpsignal-api
|
||||
sudo journalctl -u trumpsignal-api -f # 看日志
|
||||
```
|
||||
|
||||
正常启动日志：
|
||||
```
|
||||
INFO Binance WebSocket task started.
|
||||
INFO HL supplemental price feed task started.
|
||||
INFO Truth Social pollers scheduled every 15s
|
||||
INFO Telegram bot task created
|
||||
INFO Application startup complete.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第六步：冒烟测试
|
||||
|
||||
```bash
|
||||
# 替换为你的实际域名
|
||||
python scripts/launch_smoke.py --base https://api.trumpsignal.com
|
||||
```
|
||||
|
||||
14 项全通才算上线。常见失败：
|
||||
- `CORS preflight failed` → FRONTEND_URL 和实际前端域名不一致
|
||||
- `health/deep: scrapers stale` → Truth Social 抓取没启动，查日志
|
||||
- `signals/ingest: 401` → INGEST_API_KEY 没填或和 scanners 配置不一致
|
||||
|
||||
---
|
||||
|
||||
## 第七步：Telegram BotFather 更新命令菜单
|
||||
|
||||
打开 Telegram → 搜索 `@BotFather` → 发送：
|
||||
|
||||
```
|
||||
/setcommands
|
||||
```
|
||||
|
||||
选择你的 bot，然后粘贴以下内容（整块复制，不要改格式）：
|
||||
|
||||
```
|
||||
start - 订阅信号推送（无需钱包）
|
||||
stop - 暂停实时推送
|
||||
status - 查看当前设置
|
||||
help - 所有命令列表
|
||||
trump - 开关 Trump Truth Social 信号
|
||||
btc - 开关 Macro Vibes 底部信号
|
||||
funding - 开关资金费率反转信号
|
||||
kol - 开关 KOL 言行偏离信号
|
||||
conf - 设置最低 AI 置信度（0-100，仅 Trump）
|
||||
quiet - 设置静默时段（UTC 小时，如 /quiet 23 7）
|
||||
digest - 手动触发日报 / 开关每日自动发送
|
||||
digest_time - 设置日报发送时间（UTC 小时）
|
||||
adopt - 将 Hyperliquid 仓位交给机器人管理
|
||||
release - 停止管理（仓位保留，机器人退出）
|
||||
test - 发送一条测试告警
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第八步：Paper mode 验证交易链路（在上真钱之前）
|
||||
|
||||
目的：确认 HL API 真实调用链路没有 bug（staged de-risk、pyramiding 从未在真实 HL 上跑过）。
|
||||
|
||||
1. **在 Settings 页开启 paper mode**（订阅时选 Paper）
|
||||
2. **发一条假 Trump 信号**（用 `/api/dev/test-signal` 或等真实帖子）
|
||||
3. **确认开仓**：Telegram 收到告警 + Trades 页出现 paper 仓位
|
||||
4. **等触发 TP 或 SL**：检查平仓是否正常 + P&L 数字合理
|
||||
5. **测试 /adopt 流程**：在 HL 上手动开一个小仓，用 `/adopt` 交给机器人，检查 Telegram 返回的梯形止损摘要是否正确
|
||||
6. **测试 /release**：确认 release 后仓位留在 HL，机器人不再管理
|
||||
|
||||
---
|
||||
|
||||
## 第九步：外部监控（上线后 30 分钟内配好）
|
||||
|
||||
1. 去 https://uptimerobot.com 注册（免费）
|
||||
2. 添加监控：
|
||||
- 类型：HTTPS
|
||||
- URL：`https://api.trumpsignal.com/api/health/deep`
|
||||
- 间隔：5 分钟
|
||||
- 报警：邮件 + Telegram（有 Telegram 报警 bot 选项）
|
||||
|
||||
---
|
||||
|
||||
## 快速索引（出问题时查这里）
|
||||
|
||||
| 症状 | 第一步查 |
|
||||
|---|---|
|
||||
| 前端 API 全报 403/CORS | `FRONTEND_URL` 是否和前端域名完全一致 |
|
||||
| Telegram 不发消息 | `TELEGRAM_BOT_TOKEN` 是否正确；bot 是否被用户 block |
|
||||
| KOL 背离数据为空 | `ETHERSCAN_API_KEY` 是否填写 |
|
||||
| Trump 信号不触发交易 | `INGEST_API_KEY` 是否和扫描器一致；`auto_trade` 是否开启 |
|
||||
| 服务启动后立刻崩溃 | `journalctl -u trumpsignal-api -n 50`，通常是 env var 缺失 |
|
||||
| alembic upgrade 失败 | `alembic heads` 看是否是 `026`；确认 `DATABASE_URL` 指向正确库 |
|
||||
| HL 仓位开了但没止损 | `hl_price_feed` 任务是否存活；检查 `health/deep` 的 `price_feeds` |
|
||||
Reference in New Issue
Block a user