Twilight Drive — Operations Runbook

生产环境运维操作手册。CLAUDE.md 列出硬规则与上下文，本文档存放完整命令。

---

1. SSH 到 ECS

首次登录（拿 ~7 天 token）

cloudflared access login ssh-ecs.fsagent.cc

连接

ssh -o StrictHostKeyChecking=no \
    -i ~/.ssh/alibaba-ecs \
    -o "ProxyCommand=cloudflared access ssh --hostname ssh-ecs.fsagent.cc" \
    root@ssh-ecs.fsagent.cc

常见错误

• websocket: bad handshake → token 过期，重新跑 cloudflared access login ssh-ecs.fsagent.cc
• Cloudflare 浏览器 SSH 不支持 ed25519 key → 必须用 CLI SSH
• deploy 用户走 forced command，只能跑 twilight-deploy 子命令；要 shell 用 root

---

2. 容器清单（ECS）

容器	端口	角色
twilight-data	:8081	FastAPI 数据后端 — 持有 DuckDB 写锁
twilight-app-backend	:4000	NestJS app backend
twilight-app-frontend	:8082	React 前端
twilight-postgres	-	PostgreSQL
twilight-mcp-tushare	:9100	Tushare MCP

---

3. 部署

通过 GitHub Actions（标准路径）

gh workflow run deploy.yml --field ref=main

手动触发（SSH 后）

twilight-deploy <sha-xxxxxxx|latest> [all|data|backend|frontend]

twilight-deploy 流程：拉 ACR 镜像 → pg_dump 备份 → 滚动重启 → 健康检查 → 失败回滚。

deploy 用户子命令

deploy <sha-xxxxxxx|latest> [all|data|backend|frontend]
backfill <tiers> <workers>

---

4. Backfill（Tushare 数据回填）

触发

gh workflow run backfill.yml --field tiers=t3 --field workers=2
# tiers: t1, t2a, t2b, t3 或逗号组合

流程：停 twilight-data（释放 DuckDB 锁）→ 启一次性容器跑 backfill → 完成后重启 twilight-data。

清理 tier 进度（修复后重跑）

# 进 twilight-data 容器内执行
python -c "import duckdb; db=duckdb.connect('/data/warehouse.duckdb'); db.execute(\"DELETE FROM backfill_progress WHERE api_name LIKE 't3:%'\"); db.close()"
gh workflow run backfill.yml --field tiers=t3 --field workers=2

---

5. 更新 twilight-deploy 脚本（bootstrap）

ECS 源码目录没有 GitHub 凭据，git fetch 会静默失败。改 ecs-deploy.sh 后必须 scp：

scp -i ~/.ssh/alibaba-ecs \
    -o "ProxyCommand=cloudflared access ssh --hostname ssh-ecs.fsagent.cc" \
    deploy/ecs-deploy.sh root@ssh-ecs.fsagent.cc:/usr/local/bin/twilight-deploy

bootstrap 完成后，后续 deploy 会自更新。

---

6. 已知问题

T3 cashflow 字段数错位

Tushare cashflow 部分股票返回 15 个字段而非 20。修复在 FinancialIngest.run() 的 _pad_row()。部署后清进度重跑见 §4。

GHCR 拉取失败

ECS 在墙内，GHCR 不稳定。镜像走 Aliyun ACR 镜像（crpi-61k80mbsluufppdv.cn-beijing.personal.cr.aliyuncs.com）。

---

7. 镜像凭据

• GHCR: keychain entry ghcr.io-twilight-drive（LaCatFly），需 write:packages scope；~/.docker/config.json 有 uchg flag，登录时 DOCKER_CONFIG=/tmp/twilight-docker-cfg
• ACR: keychain entry aliyun-acr-twilight-drive；compose 用 --env-file 传凭据

---

8. 相关脚本

脚本	位置	用途
ecs-deploy.sh	deploy/ecs-deploy.sh	ECS 端 deploy 入口（部署后落到 /usr/local/bin/twilight-deploy）
manual.sh	scripts/deploy/manual.sh	本地手动触发 deploy/backfill
install.sh	scripts/deploy/install.sh	ECS 首次 bootstrap
spawn-profile.sh	profile/spawn-profile.sh	Hermes profile 拉起
stop-profile.sh	profile/stop-profile.sh	Hermes profile 停止