Files

T

simon 3b44f64f66 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

2026-08-22 20:47:53 +08:00

4.2 KiB

Raw Blame History

部署与运维

1. 目标环境

当前生产环境为国内单节点（Raspberry Pi 4, 8GB），路径 /home/pi/intlnews。海外服务器已停用。

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. 系统依赖

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. 首次部署步骤

# 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 管理

# 查看是否运行
pgrep -x Xvfb

# 手动启动
Xvfb :99 -screen 0 1280x1024x24 -ac +extension RANDR &

# 开机自启（示例 systemd）
# 也可由 domestic_crawl_8g.sh 自动检测并启动

6. 定时任务（crontab）

7. MySQL / 日报依赖

M9 日报写入共用 MySQL myquant 库，需要以下网络配置：

Pi 通过内网访问 192.168.1.10:13306（该端口是到远程 MySQL 的 autossh 隧道）
用户名/库名通常为 myquant / myquant
.env 中必须配置 NEWS_DB_PASSWORD

验证：

uv run en-news report

成功会输出 report_id=...。

8. 日志与清理

日志目录：logs/
- domestic_full_*.log
- pipeline_*.log
保留策略：默认保留 14 天，执行 scripts/cleanup_logs.sh。
可加入 crontab：

30 3 * * * cd /home/pi/intlnews && bash scripts/cleanup_logs.sh >> /dev/null 2>&1

9. 升级/同步代码

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。

4.2 KiB Raw Blame History Unescape Escape

部署与运维

1. 目标环境

2. 系统依赖

3. 首次部署步骤

4. 代理配置参考

5. Xvfb 管理

6. 定时任务（crontab）

7. MySQL / 日报依赖

8. 日志与清理

9. 升级/同步代码

10. 故障排查指引

11. 容量建议

4.2 KiB

Raw Blame History