refactor: 清理历史 AI Agent 文档残留 + 重构 docs/ + Pipeline 健壮性修复
- docs: 删除 CLAUDE.md / continuation.md / english-news-plan.md 及旧版 intlnews_usage.*，
统一迁移到 docs/{README,architecture,quickstart,usage,pipeline,configuration,deployment,development,faq}.md
- README: 精简为仓库入口，指向 docs/
- configs/sources.yaml: 更新注释指向新文档
- .env.example: 修正 DashScope Embedding 端点说明
Pipeline 修复：
- dedup/llm/embedding/vectorstore/reporter: 过滤 M2 no_content / 空正文，避免污染下游与 Qdrant
- dedup/pipeline: 改为先写唯一文件再写指纹，避免崩溃导致文章永久丢失
- crawler/orchestrator: sources_crawled 改为“尝试数”，成功数 = crawled - failed
- crawler/storage: write_index_jsonl 从文章路径推断日期，修复跨天/测试路径问题
- scheduler/pipeline: STEP_TIMEOUTS 实际生效（SIGALRM）
- scheduler/reporter: emb_count 排除 index.json；日报跳过无原文事件
- vectorstore/pipeline: payload 增加 source_ids；--recreate --all 时空日期也重建 collection
- app/cli: extract/dedup/translate/embed/index/pipeline 支持 --date；embed/index 支持 --all；crawl 全源失败返回非零
- scripts: domestic_full/crawl_8g/crawl_2g/pipeline 安全加载 .env；M1 全失败不标记且最终退出码=1
This commit is contained in:
@@ -0,0 +1,145 @@
|
||||
# 部署与运维
|
||||
|
||||
## 1. 目标环境
|
||||
|
||||
当前生产环境为国内单节点（Raspberry Pi 4, 8GB），路径 `/home/pi/intlnews`。海外服务器已停用。
|
||||
|
||||
```text
|
||||
Pi /home/pi/intlnews
|
||||
├── Python 3.11 + uv + .venv
|
||||
├── Playwright（Chromium）
|
||||
├── Xvfb :99
|
||||
├── Privoxy 127.0.0.1:3128 → ss-local SOCKS5 1088
|
||||
├── 本地 Qdrant 文件模式 data/qdrant_storage
|
||||
└── crontab 定时 full pipeline
|
||||
```
|
||||
|
||||
## 2. 系统依赖
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y python3.11 python3.11-venv uv xvfb \
|
||||
shadowsocks-libev privoxy chromium # chromium 可根据 Playwright 安装方式调整
|
||||
```
|
||||
|
||||
> 本项目使用 `uv` 管理 Python 环境，不依赖系统 pip 安装依赖。Playwright 浏览器建议按 `crawl4ai` 文档安装。
|
||||
|
||||
## 3. 首次部署步骤
|
||||
|
||||
```bash
|
||||
# 1. 拉取/同步代码到 /home/pi/intlnews
|
||||
cd /home/pi/intlnews
|
||||
|
||||
# 2. 安装 Python 依赖
|
||||
uv sync
|
||||
|
||||
# 3. 准备 .env
|
||||
cp .env.example .env
|
||||
# 编辑 .env：DeepSeek / DashScope / MySQL 等
|
||||
|
||||
# 4. 启动 Xvfb（headful 抓取需要）
|
||||
Xvfb :99 -screen 0 1280x1024x24 -ac +extension RANDR &
|
||||
|
||||
# 5. 启动代理（如果国内访问海外需要）
|
||||
sudo systemctl enable --now shadowsocks-libev-local
|
||||
sudo systemctl enable --now privoxy
|
||||
# 验证代理
|
||||
curl -x http://127.0.0.1:3128 -I https://www.google.com
|
||||
```
|
||||
|
||||
## 4. 代理配置参考
|
||||
|
||||
- Shadowsocks 配置文件：`/etc/shadowsocks-libev/config.json`
|
||||
- Privoxy 配置追加：
|
||||
|
||||
```
|
||||
forward-socks5t 127.0.0.1:1088 .
|
||||
listen-address 127.0.0.1:3128
|
||||
```
|
||||
|
||||
- `domestic_crawl_8g.sh` 会自动 `export HTTP_PROXY/HTTPS_PROXY` 到 `127.0.0.1:3128`，并使用 `8g_headful` Profile。
|
||||
|
||||
## 5. Xvfb 管理
|
||||
|
||||
```bash
|
||||
# 查看是否运行
|
||||
pgrep -x Xvfb
|
||||
|
||||
# 手动启动
|
||||
Xvfb :99 -screen 0 1280x1024x24 -ac +extension RANDR &
|
||||
|
||||
# 开机自启（示例 systemd）
|
||||
# 也可由 domestic_crawl_8g.sh 自动检测并启动
|
||||
```
|
||||
|
||||
## 6. 定时任务（crontab）
|
||||
|
||||
推荐 crontab：
|
||||
|
||||
```cron
|
||||
0 6 * * * cd /home/pi/intlnews && bash scripts/domestic_full.sh >> logs/cron_06.log 2>&1
|
||||
0 12 * * * cd /home/pi/intlnews && bash scripts/domestic_full.sh >> logs/cron_12.log 2>&1
|
||||
0 18 * * * cd /home/pi/intlnews && bash scripts/domestic_full.sh >> logs/cron_18.log 2>&1
|
||||
0 22 * * * cd /home/pi/intlnews && bash scripts/domestic_full.sh >> logs/cron_22.log 2>&1
|
||||
```
|
||||
|
||||
如果希望中断恢复语义，可以在每次调度前追加 `--resume`？注意：`--resume` 通常用于手动恢复；日常定时全量不带 `--resume` 也能靠文件级增量避免重复处理。按需选择。
|
||||
|
||||
## 7. MySQL / 日报依赖
|
||||
|
||||
M9 日报写入共用 MySQL `myquant` 库，需要以下网络配置：
|
||||
|
||||
- Pi 通过内网访问 `192.168.1.10:13306`（该端口是到远程 MySQL 的 autossh 隧道）
|
||||
- 用户名/库名通常为 `myquant` / `myquant`
|
||||
- `.env` 中必须配置 `NEWS_DB_PASSWORD`
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
uv run en-news report
|
||||
```
|
||||
|
||||
成功会输出 `report_id=...`。
|
||||
|
||||
## 8. 日志与清理
|
||||
|
||||
- 日志目录：`logs/`
|
||||
- `domestic_full_*.log`
|
||||
- `pipeline_*.log`
|
||||
- 保留策略：默认保留 14 天，执行 `scripts/cleanup_logs.sh`。
|
||||
- 可加入 crontab：
|
||||
|
||||
```cron
|
||||
30 3 * * * cd /home/pi/intlnews && bash scripts/cleanup_logs.sh >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
## 9. 升级/同步代码
|
||||
|
||||
```bash
|
||||
cd /home/pi/intlnews
|
||||
# 拉取新代码
|
||||
git pull # 如果使用 git
|
||||
# 同步依赖
|
||||
uv sync
|
||||
# 执行一次冒烟
|
||||
uv run en-news --help
|
||||
# 查看关键日志
|
||||
tail -100 logs/pipeline_*.log | tail -100
|
||||
```
|
||||
|
||||
## 10. 故障排查指引
|
||||
|
||||
| 现象 | 可能原因 | 处理 |
|
||||
|------|----------|------|
|
||||
| 抓取全部失败 | 代理未启动 / 网络不通 | `curl -x http://127.0.0.1:3128 ...` |
|
||||
| headful 起不来 | Xvfb 未运行 / DISPLAY 不对 | 启动 Xvfb，`DISPLAY=:99` |
|
||||
| M4 翻译失败 | DeepSeek Key 未配置 / 余额不足 | 检查 `.env`，单独跑 `uv run en-news translate` |
|
||||
| M5 失败 | DashScope Key 未配置 | 检查 `.env` |
|
||||
| report 失败 | `NEWS_DB_PASSWORD` 缺失 / 隧道不通 | 检查 `.env` 和 MySQL 端口 |
|
||||
| Qdrant 入库失败 | 本地文件损坏 / collection 异常 | 备份后重建 `data/qdrant_storage`，`uv run en-news index --recreate` |
|
||||
|
||||
## 11. 容量建议
|
||||
|
||||
- `data/` 会随时间增长，建议定期归档旧数据。
|
||||
- 日志 `logs/` 用 `cleanup_logs.sh` 清理。
|
||||
- Qdrant 本地文件模式对 Pi 友好，但大规模检索建议迁移到独立服务器/远程 Qdrant。
|
||||
Reference in New Issue
Block a user