Skip to content

Runbook

Jump to bottom
anyeduke11 edited this page Aug 30, 2026 · 1 revision

Runbook

本页为 Wiki 镜像摘录。权威全文在仓库：docs/RUNBOOK.md。 同步日期：2026-08-30 (v0.7.0)。

启动与停止

# 后端 (FastAPI + APScheduler)
python run.py                        # http://127.0.0.1:8000
PORT=8001 python run.py              # 指定端口

# 前端
cd frontend && npm run dev           # http://localhost:8898

# 停止后端
lsof -i :8000 | grep LISTEN          # 找 PID
kill <pid>

# 生产构建
cd frontend && npm run build         # tsc + vite build → dist/

状态查询

curl http://127.0.0.1:8000/api/health | jq '.'
curl http://127.0.0.1:8000/api/health | jq '.components.scheduler'
curl http://127.0.0.1:8000/api/health | jq '.components.collectors'
ls -lh backend/hotspot.db

故障排查

症状 排查
端口 8000 占用 lsof -i :8000 → kill <pid>
端口 8898 占用 受保护端口（CodeGarden 资源中枢），禁止释放
启动后端报错 激活 .venv，pip install -r backend/requirements.txt
前端启动报错 cd frontend && npm install
采集无数据 检查 backend/proxy_config.json 代理配置
数据库损坏 sqlite3 backend/hotspot.db "PRAGMA integrity_check;"

日志路径：backend/logs/hotspot.log（应用日志）。

手动追抓资讯

当发现"本周资讯空"或采集假死时：

# 1) 触发 24h 内追抓
curl -X POST http://127.0.0.1:8000/api/catchup/run \
  -H "Content-Type: application/json" \
  -d '{"since":"'$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)'","max_per_source":20}'

# 2) 看进度
curl http://127.0.0.1:8000/api/catchup/status?limit=5

# 3) 中止（跑太久时）
curl -X POST http://127.0.0.1:8000/api/catchup/abort -H "Content-Type: application/json" -d '{}'

UI 方式：首页 → 右上角 🔄「追抓资讯」按钮。另有 watchdog（60s）自动检测孤儿采集 + 每日 03:00 死源复活 job。

数据库维护

sqlite3 backend/hotspot.db "VACUUM;"
sqlite3 backend/hotspot.db "PRAGMA integrity_check;"
cp backend/hotspot.db backend/hotspot.db.backup

测试 / CI

# 后端
.venv/bin/python3 -m pytest backend/tests/ -v
.venv/bin/python3 -m pytest backend/tests/ -k "merge" -v

# 前端
cd frontend && npx vitest run
cd frontend && npx tsc --noEmit

CI：.github/workflows/ci.yml — Python compile + pytest + tsc + vitest + vite build + generate_meta.py --check + harness_analyze.py --check。

完整运维手册见仓库 docs/RUNBOOK.md。

Clone this wiki locally