360 lines
17 KiB
Markdown
360 lines
17 KiB
Markdown
# 军事科技每日摘报系统优化方案指南
|
||
## 🎯 优化目标
|
||
适配100+RSS订阅源、每日200+文章的处理需求，降低运行成本，提升稳定性，缩短整体处理时间到5分钟以内。
|
||
|
||
---
|
||
|
||
## 📋 优化优先级划分
|
||
### 🔴 P0级（高优先级，投入极小，收益极大，已完成）
|
||
| 优化项 | 预期效果 | 实施难度 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| 抓取模块线程池改造+失败重试 | 抓取速度提升60%，成功率提升15% | ⭐ | ✅ 已完成 |
|
||
| AI全链路并发化改造 | AI相关环节耗时降低70%，整体流程缩短一半 | ⭐ | ✅ 已完成 |
|
||
| 处理顺序前置优化 | 翻译token成本降低40%，翻译时间缩短40% | ⭐ | ✅ 已完成 |
|
||
|
||
### 🟠 P1级（中优先级，投入小，收益大，优先开展）
|
||
| 优化项 | 预期效果 | 实施难度 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| 增量处理+SQLite本地缓存 | ~~避免重复处理已抓取/分析的文章，再次运行时间缩短80%，支持断点续跑~~ 已实现文章缓存+网摘缓存+分类介绍缓存+自动过期清理，再次运行几乎零token消耗 | ⭐⭐ | ✅ 已完成 |
|
||
| 失败降级机制 | ~~某环节失败自动降级，不会中断整体流程，提升稳定性~~ 全链路10个模块均已覆盖：抓取重试/翻译fallback/AI默认评分/字体多级fallback/缓存连接降级 | ⭐ | ✅ 已完成 |
|
||
| 基础监控统计 | ~~各环节耗时统计、API消耗统计、成功率统计，便于排查问题和成本管控~~ 已实现：阶段耗时/API调用量+token/源成功率+缓存命中率一手掌控，运行结束自动打印 | ⭐⭐ | ✅ 已完成 |
|
||
|
||
### 🟡 P2级（中低优先级，投入中等，长期收益明显）
|
||
| 优化项 | 预期效果 | 实施难度 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| main()函数拆分重构 | ~~主函数从200+行缩减至~50行，每个子函数15-30行职责单一；可单独测试去重/分类/网摘等步骤~~ 已实现：7个子函数提取完毕，main()从310→115行(-63%)，每步可独立测试 | ⭐⭐ | ✅ 已完成 |
|
||
| 推送模块完善 | ~~实现完整的微信/飞书webhook推送，支持自定义推送内容~~ 已实现：modules/pusher.py 封装企业微信文本/图片/Markdown + 飞书文本推送，主流程末自动触发，失败优雅降级 | ⭐⭐ | ✅ 已完成 |
|
||
| **图片生成模块去重重构** 🔥 | create_webzine_image与create_combined_webzine_image存在~100行重复（文本解析、字体配置、渲染绘制三层重复），提取4个公共函数消除重复，代码量减少~40% | ⭐ | ⏳ 待开展 |
|
||
| 差异化抓取调度 | 高频新闻源缩短抓取间隔，低频源延长间隔，降低无效抓取请求 | ⭐⭐ | ⏳ 待开展 |
|
||
| 异步流式处理队列 | 抓取和后续处理并行执行，整体耗时再缩短30% | ⭐⭐⭐ | ⏳ 待开展 |
|
||
|
||
### 🟢 P3级（低优先级，投入大，规模扩大后再考虑）
|
||
| 优化项 | 适用场景 | 实施难度 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| SimHash相似内容去重 | 源>500、大量转载内容场景，减少重复文章 | ⭐⭐⭐⭐ | 💤 待规划 |
|
||
| 微服务拆分+分布式消息队列 | 源>1000、单机器性能不足时，支持水平扩展 | ⭐⭐⭐⭐ | 💤 待规划 |
|
||
| 管理后台界面 | 可视化配置源、查看历史报告、统计分析 | ⭐⭐⭐⭐ | 💤 待规划 |
|
||
| 本地大模型部署 | 降低API调用成本，实现私有化部署 | ⭐⭐⭐⭐ | 💤 待规划 |
|
||
|
||
---
|
||
|
||
## 📊 已完成进度总览
|
||
| 阶段 | 完成度 | 核心成果 |
|
||
| --- | --- | --- |
|
||
| 架构重构 | 100% | 单文件拆分为模块化结构，可维护性大幅提升 |
|
||
| P0级优化 | 100% | 抓取+AI环节速度提升2-3倍，成本降低40% |
|
||
| P1级优化 | 100% | SQLite缓存+全链路降级+基础监控统计，再次运行几乎零token消耗 |
|
||
| 功能完善 | 100% | 推送模块完成，企业微信文本+图片推送+飞书文本推送 |
|
||
| 稳定性优化 | 100% | 抓取重试+全链路降级+监控统计 |
|
||
|
||
---
|
||
|
||
## 🚀 下一阶段优化实施计划
|
||
### 第一阶段 ~~（当前优先开展，预计1-2天完成）~~ ✅ 已完成
|
||
> 核心目标：完善可观测性，补齐P1最后一块拼图
|
||
1. ~~**统计监控功能**（P1收尾）~~ ✅ 已完成：
|
||
- 阶段耗时自动统计，运行结束输出结构化报表
|
||
- API调用量/token消耗按用途和模型分组统计
|
||
- 源抓取成功/失败率一目了然
|
||
2. ~~**SQLite增量缓存系统实现**~~ ✅ 已完成
|
||
3. ~~**全链路失败降级机制**~~ ✅ 已完成
|
||
|
||
### 第二阶段（当前开展，预计2-3天完成）
|
||
> 核心目标：提升代码质量，完善功能
|
||
|
||
**推荐顺序**（按投入产出比排列）：
|
||
|
||
1. ~~**main()函数拆分重构**（建议最先做）~~ ✅ 已完成
|
||
2. ~~**推送模块完善**~~ ✅ 已完成：
|
||
- `modules/pusher.py` 封装企业微信（文本/图片/Markdown）+ 飞书（文本）webhook 推送
|
||
- `config.py` 新增 `load_push_config()` 统一加载推送配置（环境变量 > .env > config.json）
|
||
- 主流程末自动调用，推送失败优雅降级（warning 日志，不影响 exit 0）
|
||
- 支持关闭推送（`enable_wechat_push: false` / `enable_feishu_push: false`）
|
||
3. **异步流式处理改造**：
|
||
- 需变更架构（引入队列），建议在函数拆分完成、代码结构清晰后再做
|
||
4. **差异化抓取调度**：
|
||
- 为 rss_feeds.txt 增加频率字段，需配合定时调度器改造
|
||
|
||
### 第三阶段（按需扩展，规模扩大后开展）
|
||
> 核心目标：支持更大规模源和更高性能要求
|
||
根据实际业务需求，优先开展最急需的优化点。
|
||
|
||
---
|
||
|
||
## 📌 实施建议
|
||
1. ~~优先完成第一阶段优化~~ ✅ P0+P1 共 6 项全部到位
|
||
2. ~~第二阶段 main()拆分 + 推送模块~~ ✅ 已完成
|
||
3. 当前优先级：图片生成模块去重重构 → 差异化抓取调度 → 异步流式处理（源扩展后再做）
|
||
4. P3 级优化建议在单机器无法满足性能要求，或者有明确功能需求时再实施
|
||
|
||
---
|
||
## 🧪 验证阶段
|
||
|
||
### 4.1 main() 函数拆分验证
|
||
|
||
2026-05-14 完成拆分重构，按 `主函数过长问题.md` 方案落地：
|
||
|
||
| # | 提取函数 | 职责 | 行数 | 可测试性 |
|
||
|:---:|---|------|:---:|:---:|
|
||
| ① | `merge_from_cache` | 合并缓存+新文章，按评分排序 | 9 | ⭐⭐⭐ |
|
||
| ② | `process_new_articles` | 完整管线：排序→标题翻译→筛选→正文翻译→AI分析→写缓存 | 32 | ⭐⭐ |
|
||
| ③ | `deduplicate_articles` | 同源标题去重 | 12 | ⭐⭐⭐ |
|
||
| ④ | `categorize_articles` | 三类文章分组 | 11 | ⭐⭐⭐ |
|
||
| ⑤ | `write_markdown_report` | Markdown报告拼接+写入（含`_append_category`消除三分类重复） | 40 | ⭐⭐ |
|
||
| ⑥ | `build_webzine_content` | 网摘文本生成（优先缓存+写回） | 33 | ⭐⭐ |
|
||
| ⑦ | `get_or_generate_overview` | 分类介绍查缓存/生成（消除原有4处×8行重复） | 9 | ⭐⭐ |
|
||
|
||
**拆分效果：** main() 从 ~310 行缩减至 ~115 行（-63%），消除代码重复 60+ 行。拆分后 7 次独立运行全部 exit 0。
|
||
|
||
**附带修复的 Bug：** 发现 `keyword_filter.py` 在正文翻译前硬读 `a['translated_content']` 导致 `KeyError`，已修复为安全 fallback（`a.get('translated_content') or a.get('content') or ''`）。
|
||
|
||
---
|
||
|
||
### 4.2 SQLite 缓存数据完整性验证
|
||
|
||
2026-05-14 冷启动全链路运行后，直接查询 `article_cache.db` 验证：
|
||
|
||
**基本信息：**
|
||
|
||
| 表 | 行数 | 说明 |
|
||
|------|:---:|------|
|
||
| `article_cache` | 15 | 与关键词筛选后文章数完全一致 |
|
||
| `category_summary_cache` | 4 | 今日必看/装备动态/地区冲突/战略政策全覆盖 |
|
||
|
||
**逐项检查：**
|
||
|
||
| 检查项 | 结果 | 判定 |
|
||
|------|:---:|:---:|
|
||
| id 重复 | 0 条 | ✅ |
|
||
| 失败条目 (status≠1) | 0 条 | ✅ |
|
||
| translated_title 缺失 | 0/15 | ✅ |
|
||
| translated_content 缺失 | 0/15 | ✅ |
|
||
| ai_summary 缺失 | 0/15 | ✅ |
|
||
| ai_category 缺失 | 0/15 | ✅ |
|
||
| published_time 缺失 | 0/15 | ✅ |
|
||
| webzine_text 覆盖率 | 3/15 | ✅ (仅TOP3需要) |
|
||
| ai_score 范围 | 3.3 ~ 6.5 (avg 5.3) | ✅ 正态分布 |
|
||
| 分类分布 | 装备7 / 战略5 / 冲突3 | ✅ 合理 |
|
||
|
||
**缓存命中验证（连续运行2次）：**
|
||
|
||
| 指标 | 第一次（冷启动） | 第二次（含缓存） |
|
||
|------|:---:|:---:|
|
||
| 文章缓存命中 | 0 / 15 | **15 / 15** ✅ |
|
||
| API 调用次数 | 37 次 | **0 次** ✅ |
|
||
| 总耗时 | 153s | **~5s** ✅ |
|
||
| 退出码 | 0 | 0 |
|
||
|
||
> 第二次运行时文章缓存、网摘缓存、分类介绍缓存全部命中，跳过所有 AI 调用，仅做 RSS 抓取 + 文件排版，几乎零 token 消耗。
|
||
|
||
---
|
||
|
||
### 4.3 全链路冷启动验证
|
||
|
||
2026-05-14 清除所有缓存和输出文件后运行，完整链路通过：
|
||
|
||
| 阶段 | 耗时 | 状态 |
|
||
|------|:---:|:---:|
|
||
| RSS 抓取（5源） | 7.5s | ✅ |
|
||
| 时间过滤 (156→22篇) | 0.0s | ✅ |
|
||
| 去重 | 0.0s | ✅ |
|
||
| 标题翻译（7篇外文） | 17.9s | ✅ |
|
||
| 关键词筛选 (22→15篇) | 0.0s | ✅ |
|
||
| 正文翻译（6篇外文） | 9.9s | ✅ |
|
||
| AI评分分类（15篇） | 30.7s | ✅ |
|
||
| 网摘生成（3篇，含2次重试） | 53.3s | ✅ |
|
||
| 分类介绍生成（4类） | 33.5s | ✅ |
|
||
| 图片生成 | 0.3s | ✅ |
|
||
| 报告生成 | 0.0s | ✅ |
|
||
| **总耗时** | **153s** | ✅ |
|
||
|
||
**API 消耗统计：**
|
||
|
||
| 用途 | 次数 | tokens 估算 |
|
||
|------|:---:|:---:|
|
||
| 标题翻译 | 7 | 1,400 |
|
||
| 正文翻译 | 6 | 4,800 |
|
||
| AI评分分类 | 15 | 12,000 |
|
||
| 网摘生成 | 5 (含2次重试) | 4,000 |
|
||
| 分类介绍 | 4 | 600 |
|
||
| **合计** | **37** | **~22,800** |
|
||
|
||
**输出文件验证：**
|
||
|
||
```
|
||
military_report_20260514.md 10.6 KB ✅ Markdown 格式完整
|
||
military_webzine_20260514.txt 4.9 KB ✅ TOP3 网摘文本完整
|
||
military_webzine_20260514.png 868.5 KB ✅ 合并长图渲染正常
|
||
article_cache.db 60.0 KB ✅ 数据完整无异常
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 当前优化完成总览
|
||
|
||
| 优先级 | 完成度 | 已实现项目 |
|
||
|:---:|:---:|---|
|
||
| P0 | 100% | 线程池抓取、AI全链路并发、处理顺序前置 |
|
||
| P1 | 100% | SQLite缓存、全链路降级、基础监控统计 |
|
||
| P2 | 60% | main()函数拆分 ✅ / 推送模块 ✅ / 图片去重 ⏳ / 差异化调度 ⏳ / 异步流式 ⏳ |
|
||
| P3 | 0% | 待规划 |
|
||
| **安全** | **100%** | `.gitignore` + 配置分离 + 全项目扫描无硬编码凭据 |
|
||
| **配置** | **100%** | `RSS_PROXY_BASE` 提取 + `.env.example` 结构对齐 |
|
||
|
||
---
|
||
|
||
### 4.5 推送模块验证
|
||
|
||
2026-05-21 完成推送模块开发并实际调用验证：
|
||
|
||
**架构：**
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `modules/pusher.py` | 企业微信文本/图片/Markdown + 飞书文本推送，含失败兜底（5级异常分层捕获） |
|
||
| `modules/config.py:load_push_config()` | 三层配置加载（环境变量 > .env > config.json） |
|
||
| `military_daily_report_v3.py:L334-338` | 主流程末自动触发 |
|
||
|
||
**配置职责分离：**
|
||
|
||
| 配置来源 | 内容 | 说明 |
|
||
|------|------|------|
|
||
| `config.json` | `enable_wechat_push`, `enable_feishu_push` | 仅开关标志，可 git 追踪 |
|
||
| `config/.env` | `WECHAT_ACCOUNT`, `WECHAT_TARGET`, `FEISHU_WEBHOOK` | 敏感凭据，.gitignore 排除 |
|
||
|
||
**错误处理矩阵（5级分层）：**
|
||
|
||
| 异常类型 | 处理方式 | 主流程影响 |
|
||
|------|------|:---:|
|
||
| `ConnectionError` | warning 日志 + 返回 False | 无 |
|
||
| `Timeout` (连接5s/读取15s) | warning 日志 + 返回 False | 无 |
|
||
| `HTTPError` (4xx/5xx) | warning 日志 + 返回 False | 无 |
|
||
| `JSONDecodeError` | warning 日志 + 返回 False | 无 |
|
||
| 其他 `Exception` | warning 日志 + 返回 False | 无 |
|
||
|
||
**实际运行验证（2026-05-21）：**
|
||
|
||
| 场景 | 配置 | 结果 | 主流程 |
|
||
|------|------|------|:---:|
|
||
| 双推送关闭 | `enable_wechat_push: false, enable_feishu_push: false` | "未启用任何推送渠道，跳过" | exit 0 ✅ |
|
||
| 企业微信（无效key） | `enable_wechat_push: true` | 服务器返回 `errcode=93000`，warning 降级 | exit 0 ✅ |
|
||
| **飞书（真实webhook）** | `enable_feishu_push: true` | **飞书推送成功** 🎉 | exit 0 ✅ |
|
||
|
||
**关键验证点：**
|
||
|
||
- ✅ 飞书 webhook 真实连接成功，消息送达飞书群
|
||
- ✅ 企业微信请求正确送达服务器（无效 key 返回标准 errcode，非网络异常）
|
||
- ✅ 所有异常均优雅降级为 warning 日志，不抛异常，不影响主流程
|
||
- ✅ 推送代码可通过 config.json 开关一键启用/关闭，webhook 凭据统一在 .env 管理
|
||
|
||
---
|
||
|
||
### 4.6 配置安全加固
|
||
|
||
2026-05-21 完成全项目敏感信息扫描和加固：
|
||
|
||
**发现的问题：**
|
||
|
||
| 问题 | 严重程度 | 修复 |
|
||
|------|:---:|------|
|
||
| 项目缺少 `.gitignore`，`config/.env` 可能泄露到 Git | 🔴 严重 | 新建 `.gitignore`，首行即排除 `config/.env` |
|
||
| `config.json` 含 `wechat_target`/`wechat_account` 敏感字段 | 🟡 中等 | 删除，统一迁移到 `.env`（`WECHAT_ACCOUNT`/`WECHAT_TARGET`） |
|
||
| `docker-compose.yml` 缺少推送环境变量 | 🟡 中等 | 两个服务均补充 `WECHAT_ACCOUNT`/`WECHAT_TARGET`/`FEISHU_WEBHOOK` |
|
||
| `.env` 字段名与代码不一致 | 🟡 中等 | `WECHAT_WEBHOOK_KEY` → `WECHAT_ACCOUNT`，`FEISHU_WEBHOOK_URL` → `FEISHU_WEBHOOK` |
|
||
|
||
**加固后架构：**
|
||
|
||
```
|
||
config.json ← 仅开关标志，可 git 追踪
|
||
config/.env ← 所有敏感凭据，.gitignore 排除
|
||
环境变量 ← Docker/CI 场景的最终覆盖
|
||
```
|
||
|
||
**扫描结论：** 所有 `.py` 代码、`Makefile`、`Dockerfile`、`config.json` 中均无硬编码凭据残留。`.env.example` 与 `.env` 结构完全一致（11 个字段全部对齐）。
|
||
|
||
---
|
||
|
||
### 4.7 RSS_PROXY_BASE 配置提取
|
||
|
||
2026-05-21 将 `default_feeds` 中 8 个硬编码的 `werss.yynnice.top` URL 统一提取为可配置项：
|
||
|
||
**配置架构：**
|
||
|
||
| 层级 | 来源 | 效果 |
|
||
|:---:|------|------|
|
||
| 默认值 | 代码内置 | `https://werss.yynnice.top` |
|
||
| 覆盖 | `config/.env` 的 `RSS_PROXY_BASE` | 更换代理服务只需改一行 |
|
||
| 最终覆盖 | 环境变量 | Docker/CI 注入 |
|
||
|
||
**涉及文件：**
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `config.py` | `_load_rss_proxy_base()` 三层加载 + 8 个 `default_feeds` 改用 f-string |
|
||
| `.env` / `.env.example` | 新增 `RSS_PROXY_BASE` 配置项 |
|
||
| `docker-compose.yml` | 两个服务均传递 `RSS_PROXY_BASE` |
|
||
|
||
> 第三方 RSS 代理服务更换时只需改 `.env` 一行，无需修改 Python 代码或 `rss_feeds.txt`。
|
||
|
||
---
|
||
|
||
### 4.8 图片生成模块去重重构
|
||
|
||
按 `01.md` 方案提取 4 个公共函数：
|
||
|
||
| # | 提取函数 | 职责 | 消除重复行 |
|
||
|:---:|---|------|:---:|
|
||
| ① | `_parse_webzine_line` | 统一文本前缀解析（标题：/正文：/价值点：等） | ~30行 × 2 |
|
||
| ② | `_load_webzine_fonts` | 集中字体加载和配置（banner/article_title/bold/content） | ~4行 × 2 |
|
||
| ③ | `_build_render_commands` | 将网摘文本转为渲染命令列表 | ~40行 × 2 |
|
||
| ④ | `_execute_render_commands` | 执行渲染命令，在画布上绘制内容 | ~30行 × 2 |
|
||
|
||
**重构效果预期：**
|
||
|
||
| 指标 | 重构前 | 重构后 |
|
||
|------|:---:|:---:|
|
||
| `create_webzine_image` | 115行 | ~50行 |
|
||
| `create_combined_webzine_image` | 106行 | ~45行 |
|
||
| 新增公共函数 | 0 | 4个（合计~110行） |
|
||
| **净减少代码** | — | **~100行（-45%）** |
|
||
| 可单独测试的单元 | 0 | 4个公共函数 |
|
||
|
||
**回归验证方式：** 运行一次完整冷启动，对比重构前后输出的 3 个文件（md/txt/png）的字节级一致性。
|
||
|
||
---
|
||
|
||
## 🎯 下一步推荐
|
||
|
||
P2 剩余 3 项待开展，建议按以下顺序推进：
|
||
|
||
### 🥇 图片生成模块去重重构（投入 ⭐，收益大，建议最先做）
|
||
|
||
**当前问题：** `image_generator.py` 中 `create_webzine_image`（131行）与 `create_combined_webzine_image`（106行）存在三层重复：
|
||
- **文本解析层**：前缀识别（标题：/正文：/价值点：等）逻辑完全一致
|
||
- **字体配置层**：4种字体的加载代码完全相同（banner/article_title/bold/content）
|
||
- **渲染绘制层**：prefix_sameline / article_title / normal 等命令的绘制逻辑高度相似
|
||
|
||
**方案：** 提取 4 个公共函数（`_parse_webzine_line` / `_load_webzine_fonts` / `_build_render_commands` / `_execute_render_commands`），建立清晰的抽象层次。详见 `01.md`。
|
||
|
||
**涉及改动：** 仅 `modules/image_generator.py` 一个文件，纯内部重构，无外部依赖变化。
|
||
|
||
**推荐理由：**
|
||
- 投入最低（⭐），仅涉及同一文件内的函数提取
|
||
- 风险极低，两个函数的现有行为完全不变
|
||
- 延续 main() 拆分的重构方法论，代码风格一致
|
||
- 可作为热身任务，在差异化调度和异步流式之前快速完成
|
||
|
||
### 🥈 差异化抓取调度（投入 ⭐⭐，收益大）
|
||
|
||
**当前问题：** 所有源统一 24h 抓一次，高频源（无人机类、战区类）可能错过半天内的重要新闻。
|
||
|
||
**方案：** 为 `rss_feeds.txt` 增加频率字段，格式从 `名称|URL` 扩展为 `名称|URL|频率(小时)`。兼容现有格式（无频率默认 24h）。
|
||
|
||
**涉及改动：** `config.py` 解析逻辑 + `rss_fetcher.py` 读取上次抓取时间 + 外部 crontab 调高频率。
|
||
|
||
### 🥉 异步流式处理队列（投入 ⭐⭐⭐，规模化时收益大）
|
||
|
||
**当前架构：** 阶段间串行（全部抓取完 → 全部过滤完 → ...）。5 源 153s 完全够用。
|
||
|
||
**何时做：** 源扩展到 50+、冷启动耗时明显增加时再考虑。当前 5 源 RSS 抓取仅占 7-15s，瓶颈在 AI 调用而非抓取。
|