Files

T

k 06d367f073 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>

2026-05-29 17:22:50 +08:00

7.1 KiB

Raw Permalink Blame History

上线前操作手册

按顺序执行。每一项打✅后再往下。

第一步：填环境变量（在服务器上）

cp .env.example .env
nano .env   # 或用你喜欢的编辑器

逐项填写（全是必填，没有可以空着的）：

必填 — 少一个就无法启动

# 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

生成随机密钥的命令：

openssl rand -hex 32

第二步：数据库迁移

# 确认迁移链完整（应该显示 026）
alembic heads

# 执行迁移（首次部署会跑 001→026 全部）
alembic upgrade head

# 验证当前版本
alembic current
# 输出应该是：026 (head)

第三步：运行 preflight（上线前健康检查）

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 填进去

第四步：预热数据（首次上线必须）

生产库是空的，不跑这步用户进来全是空页面。

# 只拉数据，不删任何东西
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（推荐）

docker compose up -d
docker compose logs -f api    # 看启动日志，等看到 "Application startup complete."

systemd

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.

第六步：冒烟测试

# 替换为你的实际域名
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 上跑过）。

在 Settings 页开启 paper mode（订阅时选 Paper）
发一条假 Trump 信号（用 /api/dev/test-signal 或等真实帖子）
确认开仓：Telegram 收到告警 + Trades 页出现 paper 仓位
等触发 TP 或 SL：检查平仓是否正常 + P&L 数字合理
测试 /adopt 流程：在 HL 上手动开一个小仓，用 /adopt 交给机器人，检查 Telegram 返回的梯形止损摘要是否正确
测试 /release：确认 release 后仓位留在 HL，机器人不再管理

第九步：外部监控（上线后 30 分钟内配好）

去 https://uptimerobot.com 注册（免费）
添加监控：
- 类型：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`

7.1 KiB Raw Permalink Blame History Unescape Escape