4.4 KiB
用户操作与验收说明
1. 启动服务
首次使用先准备环境变量：
cp .env.example .env
打开 .env，填写：
TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
启动：
docker compose up -d --build
curl -f http://localhost:8000/health
浏览器打开：
http://localhost:8000
2. 创建任务
首页选择平台：
- 小红书
- 抖音
可调整抓取规模：
- 热点数：默认 5
- 每热点内容：默认 5
- 每内容评论：默认 50
轻量验收建议使用：
1 热点 × 1 内容 × 10 评论
默认规模验收使用：
5 热点 × 5 内容 × 50 评论
点击“开始抓取”后会进入任务详情页。
3. 查看任务状态
任务状态包括：
- 运行中
- 已完成
- 失败
运行中任务会自动刷新。页面会展示：
- 已处理 / 总内容数
- 成功 / 失败内容数
- AI 成功率
- AI 样本不足提示
- 失败阶段、错误类型和错误信息
如果任务刚开始且还没有热点，会看到“正在抓取热点数据，请稍候...”。
4. 查看报告
任务完成后，在任务详情页可以进入：
- 热点级汇总报告
- 内容详情页
报告页面会展示：
- AI 总结
- 评论样本数
- 情绪分布
- Top 标签
- 典型评论
- 评论明细
如果报告尚未生成，页面会显示“报告生成中，请稍候...”，不会返回 500。
5. 导出文件
支持导出：
- 热点报告 Markdown
- 内容报告 Markdown
- 热点评论 CSV
- 内容评论 CSV
CSV 使用 UTF-8-BOM，适合 Windows Excel 打开。评论内容中的换行会被替换为空格，= + - @ 开头的内容会自动加单引号，避免被 Excel 当作公式执行。
6. 小规模验收
分别创建两个任务：
小红书：1 × 1 × 10
抖音：1 × 1 × 10
通过标准：
- 任务最终为“已完成”。
- 至少有热点、内容、评论、报告。
- AI 成功率正常，或页面有明确“AI 样本不足”提示。
- 能打开热点报告、内容详情页。
- 能导出 Markdown 和 CSV。
7. 默认规模验收
分别创建两个任务：
小红书：5 × 5 × 50
抖音：5 × 5 × 50
注意：真实平台接口返回数量可能低于理论上限 1250 条评论。验收时重点判断：
- 任务是否完成。
- 是否有明确失败原因。
- 实际热点、内容、评论、报告数量。
- 页面和导出是否可用。
8. 常见问题
8000 端口被占用
先确认是否是本项目容器：
docker compose ps
lsof -nP -iTCP:8000 -sTCP:LISTEN
如果是旧容器：
docker compose down
docker compose up -d --build
不要临时改成 8001。
API Key 缺失
如果任务失败或没有真实数据，检查 .env：
TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
任务长期 running
先打开任务详情页看进度。如果长时间没有变化：
docker compose logs --tail=120 app
重启服务后，遗留 running 任务会被标记为失败，并显示“系统重启，任务被中断”。
评论数量少于请求上限
这通常是平台真实返回不足，不一定是代码失败。以任务状态、成功内容数、报告生成情况和错误信息为准。
报告摘要失败
页面会显示默认文案，但统计、标签、典型评论和导出仍应可用。
重置本地数据库
仅在不需要保留历史任务时执行：
docker compose down
rm -f data/app.db data/app.db-wal data/app.db-shm
docker compose up -d --build
curl -f http://localhost:8000/health
公网云服务器部署
公网部署前先确认部署方式、访问密码、是否允许消耗真实 TikHub 和 AI Key。未经确认不要直接开放公网。
如果确认使用云服务器 Docker Compose，步骤与本地类似：
git pull
cp .env.example .env
docker compose up -d --build
curl -f http://127.0.0.1:8000/health
公网演示建议先初始化脱敏 Demo 数据：
docker compose exec app python -m app.demo_seed
如果页面出现数据库不可用提示，系统会尽量把 SQLite 文件备份到：
data/corrupt-backups
9. 推荐提交节奏
按 docs/MVP-WorkOrders.md 的工单推进：
完成一个工单 → 跑测试 → Docker 健康检查 → 网页验收 → commit
运行数据目录 data/ 不提交到 Git。