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