# 部署与运维

## 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。