# 上线前操作手册

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

---

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

```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` |