FreshRSS 版本演进深度解读:从 0.7.2 到 1.23.1 的功能迭代、架构变迁与运维要点
FreshRSS 版本演进深度解读:从 0.7.2 到 1.23.1 的功能迭代、架构变迁与运维要点
本文基于仓库内 docs/CHANGELOG-old2.md("old 2" 号变更日志,与 CHANGELOG.md 及更早的 docs/CHANGELOG-old.md 衔接),系统梳理 FreshRSS 自 2014 年 6 月(0.7.2)至 2023 年 12 月(1.23.1)九个年头的版本演进史。读者可从中掌握 FreshRSS 搜索语法、抓取模式(HTML/XML+XPath)、Dynamic OPML、标签体系、API 兼容、CLI 运维工具、Docker 部署与安全加固等核心能力的来龙去脉,并理解当前仓库代码中大量设计的由来。
文档定位与阅读方法
CHANGELOG-old2.md 是 FreshRSS 官方维护的历史变更记录,按"版本号 + 发布日期"倒序排列,每条记录内部再按 Features / Bug fixing / UI / Security / Deployment / i18n / API / CLI / Extensions / SimplePie / Misc. 等类别分节。阅读时建议把握三条主线:
- 按时间轴看演进:从底部(2014 年的 0.7.x 时代)向上读到顶部(2023 年的 1.23.x),能看到项目从小型 PHP 阅读器成长为支持多数据库、多 API、多用户的自托管聚合器的全过程。
- 按主题看能力:同一能力(如搜索语法、Docker 部署)往往在多版本中持续增强,按主题聚合阅读更容易形成完整认识——这正是下文的主要组织方式。
- 结合源码看实现:文档中记录的功能大多能在当前仓库中找到对应实现,例如 app/Models/Search.php 与 app/Models/BooleanSearch.php 承载搜索操作符解析,constants.php 定义全局常量,cli/ 目录收录全部命令行工具。
版本演进总览:九年的关键里程碑
| 时间 | 版本 | 里程碑主题 |
|---|---|---|
| 2014-06 | 0.7.2 | 兼容 Google Reader API 2 级;播客(音频/视频 enclosure)基础支持;date: / pubdate: 搜索过滤器 |
| 2014-10 ~ 2015-05 | 0.8/0.9/1.0/1.1 | 扩展系统雏形、自动更新系统、SQLite 支持(beta)、PubSubHubbub、强制 HTTPS 域名列表、CSRF 令牌 |
| 2016-07 ~ 2017-03 | 1.2 ~ 1.6.3 | 新 CLI、PostgreSQL 正式支持、多用户令牌、disable_update 选项、reconfigure.php |
| 2017-10 ~ 2018-12 | 1.7 ~ 1.13 | 更强大的搜索(多 intitle:、否定搜索、双引号)、Fever API、标签(labels)、用户查询排序、X-Forwarded-Prefix 反向代理支持 |
| 2019 | 1.14 ~ 1.15 | Filter actions(自动标记已读)、Ansum/Mapco 新主题、基于 OPML 的默认订阅、e-mail 能力、默认 SQLite 安装 |
| 2020 | 1.16 ~ 1.17 | 流式输出(yield)、RTL 语言、用户管理页、标签管理页、多管理员 |
| 2021 | 1.18 ~ 1.19 | PHP 8 支持、并行抓取、PWA、按标签搜索操作符 L:/label:、keep-max-unread 设置 |
| 2022 | 1.20 ~ 1.21 | HTML+XPath 抓取、Dynamic OPML、50k+ 订阅、嵌套括号搜索、XML+XPath、用户自定义时区 |
| 2023 | 1.22 ~ 1.23 | OpenID Connect、Unix socket 数据库连接、Important feeds 分组、Filter actions 全局化、PHP 7.4+ 要求与 typed properties |
内容获取与解析能力的演进
从"仅 RSS/Atom"到 XPath 抓取
FreshRSS 早期只解析标准 RSS/Atom。1.20.0 引入的 HTML+XPath 功能(#4220 等)让没有 RSS 输出的普通网页也能被订阅:用户通过 CSS 选择器指定网页中的标题与内容节点,由 lib/phpgt/cssxpath/ 库将 CSS 选择器转换为 XPath 完成提取。1.21.0 进一步补充 XML+XPath 模式,用于无 RSS/Atom 的 XML 文档(#5076);同版本还允许在 HTML+XPath 模式下直接处理 HTML 内容(#4878),并把最大 HTTP 超时提升到 15 分钟(#5074)。
围绕 XPath 还有一系列配套修正:
- 1.20.0 新增"通过 CSS 选择器排除文章全文中的某些 DOM 元素"选项(#4501),支持
a[href*="example"]这类带通配符的选择器; - 1.16.0 允许用逗号组合多个选择器,如
#article .title, #article .content,并支持在全文抓取前预览 CSS 规则效果(#2778、#2874); - 1.20.1 修复了 XPath 自定义日期/时间格式解析(#4703)、HTML+XPath 的字符集与 CSS 选择器 HTML 编码问题(#4623、#4707)。
全文抓取与 enclosures
1.18.0 起支持"文章内容变化后重新抓取全文"(#3506),并允许为单个订阅设置独立的 cURL 参数(代理、Cookie、User-Agent,#3367、#3494、#3516)。1.21.0 强化了对 feed enclosures(图片/音频/视频附件)的整体支持(#4944),1.23.0 又补充了更多缩略图类型与"非绝对路径 favicon"支持(#5806、#5839)。1.20.0 还为全文抓取引入了互斥信号量,避免并发 actualize 时的竞争(#5235)。
Dynamic OPML(1.20.0)
该版本同时带来了双向 Dynamic OPML(#4407):
- 订阅者侧:分类可以被远程 OPML 文件动态填充,远程列表变化后分类内的订阅随之更新;
- 发布者侧:可将任意视图(全部、单个 feed、分类)动态导出为 OPML,供他人订阅。
SimplePie 依赖的长期维护
作为底层 RSS 解析库,SimplePie 在多个版本中被同步更新:1.11.0 修复非唯一 GUID 的 feed 与 Atom 命名空间问题;1.13.0 升级至 1.5.2;1.16.0 升级至 1.5.4(要求 PHP 5.6+,兼容 PHP 7.4,新增俄语/德语日期);1.19.1 手动更新至 1.5.8;1.20.0 引入 rename_attribute() 方法以支持对文章内容做样式化/隐藏处理(simplepie#717)。文档还记录了多处与 PHP 8 相关的兼容修复(如 status_code 类型、loadHTML 的 ValueError 捕获)。
搜索系统:从轻量布尔搜索到完整表达式引擎
早期(1.7.0 之前)
0.7.2 已具备 date: 与 pubdate: 过滤器,支持 ISO 8601 区间如 date:2013-2014、pubdate:P1W,并可组合:date:2014-05 intitle:FreshRSS intitle:Open great reader #Internet。1.7.0 增强了多关键字能力:支持多个 intitle:、inurl:、author:,支持 ! / - 前缀否定(如 !intitle:unwanted、-inurl:unwanted、-author:unwanted、-#unwanted),并允许双引号 author:"some name"。
1.11.0 的轻量布尔搜索
实现了一版轻量布尔搜索:各词之间默认隐式 AND,显式书写 OR 才表示或;不支持括号;用引号关闭布尔语义,如 "This or that"。示例:Hello intitle:World OR date:P1D example OR author:Else intitle:"This or that"。
1.20.0 的表达式搜索引擎
引入支持(可嵌套)括号的新搜索引擎(#4378、#4503):
(author:Alice OR intitle:hello) (author:Bob OR intitle:world)
!((author:Alice intitle:hello) OR (author:Bob intitle:world))
search:"My query" # 按名称调用已保存的用户查询
search:QueryA # 按名称(无空格)调用
S:3 # 按 ID 调用已保存查询
括号解析与深度限制在 app/Models/BooleanSearch.php 中实现(__construct 中会校验搜索长度与括号嵌套深度,超出则抛出 Minz_BadRequestException),search: 与 S: 的用户查询展开逻辑也位于该文件。
各操作符的持续补齐
- 1.16.1:按 feed ID 过滤——
f:123 more-search、多 IDf:123,234,345、排除!f:456,789; - 1.16.0:
!date:排除任意日期区间,如!date:P1W、!pubdate:2019、-date:2020-01-01/P5d; - 1.19.0:按标签搜索——
L:12,13,14(标签 ID)、label:something、labels:"my label,my other label"、L:*(任意标签)、!L:*(无标签);同时引入date:/pubdate:之外的"同标题自动已读""单 feed 最大未读数"设置(#3303); - 1.19.1:按文章 ID 搜索——
e:1639310674957894或逗号分隔多个 ID(或语义)(#4058); - 1.21.0:搜索只匹配完整标签名而非子串(#4882);支持
\(/\)转义搜索括号(#4989)。
当前 app/Models/Search.php 的字段定义可视为这些操作符的完整清单:intitle / intitle_regex、inurl / inurl_regex、author / author_regex、tags / tags_regex、label_ids / label_names、input_date / min_date / max_date、input_pubdate / min_pubdate / max_pubdate、entry_ids / feed_ids 等,另含 not_* 系列用于否定查询。
阅读体验、标签体系与界面演进
已读状态与滚动阅读
- 1.6.0 重做"滚动时标记已读"选项(默认开启),并引入 keep unread 与按
?a=rss&hours=3/?a=rss&nb=10控制 RSS 输出条数的能力; - 1.14.0 将滚动已读改为批量提交(batch scroll-as-read),显著改善客户端/服务端性能(#2199);
- 1.16.0 新增 Alt+r 快捷键将"之前的"文章标记已读、重置浏览器会话时的滚动位置以避免误标已读;
- 1.19.0 增加"同标题文章自动标记已读"与"单 feed 最大未读数"设置,后者在 1.23.0 中进一步提升了可靠性(#5905);
- 1.23.0 增加"重要订阅"(Important feeds)分组及新优先级:重要订阅的文章不会因滚动、聚焦或"全部标记已读"而被误标(#5782)。
标签(labels)体系
1.12.0 引入"标签"(自定义标签,#928),同时通过 Google Reader API 提供支持(News+ 完整支持,FeedMe/EasyRSS 部分支持,Fever API 不支持),并允许含空格及逗号分隔的标签(#2023)、含空格与逗号/分号分隔的作者(#2025)。此后标签在 1.18.0 被改名为 Label management,1.19.0 加入按标签搜索操作符,1.23.0 增加隐藏文章页脚"My labels"的显示选项(#5884)。标签功能的 DAO 实现在 app/Models/TagDAO.php 及其 PgSQL/SQLite 变体中。
用户查询(User Queries)
0.7.3 引入"用户查询"(视图过滤快捷方式);1.13.0 增加查询排序与拖拽(#3346、#3355);1.20.0 支持在 config-user.default.php 中为新用户预置默认查询(#4360);1.21.0 修复保存查询时的 get/排序问题(#5515)与"在搜索中使用用户查询"(#5669)。
主题体系
主题演进贯穿始终:0.9.x 时代新增 BlueLagoon、Screwdriver;1.12.0 加入 Swage;1.14.0 加入 Ansum 与 Mapco;1.19.0 统一以 Origine 为模板文件;1.20.0 加入 Dark pink 与 Nord;1.20.1 引入 CSS 变量便于自定义配色(#4641);1.21.0 为 Origine/Origine compact 增加暗色模式并标记 BlueLagoon、Flat、Screwdriver 为"暂时弃用";1.22.0 最终删除 BlueLagoon 与 Screwdriver(#5374、#5694)。全部主题位于 p/themes/,p/themes/index.html 为选择器入口。
其他值得一提的 UI 里程碑
- 1.16.0 的流式输出(
yield数据管线)显著缩短首字节时间(#2588),并因此移除了妨碍缓冲的min_posts_per_rss配置;该特性要求 Web 栈支持高效流式 flush,仓库内提供了 Docker + Traefik 参考部署。 - 1.16.0 支持 RTL 语言(#2776);
- 1.19.0 支持安装式 PWA(#3890);
- 1.20.0 增加
icons-as-emojis性能选项、1000+ 订阅时布局自动简化(#4357)、自定义 HTML Logo/标题、统计页展示出错/静默/空订阅; - 1.22.0 新增"在文章底部显示网站名和/或 favicon"选项(#4969)、支持
<meta name="theme-color">(#5105)、配置界面滑动面板化。
API 与协议兼容:Google Reader、Fever 与 WebSub
Google Reader API(GReader)
0.7.2 即兼容 Google Reader API 2 级,支持 News+(Android)、EasyRSS;此后持续加固:1.8.0 修复 PostgreSQL 下与 EasyRSS 的兼容 bug;1.12.0 通过该 API 开放标签能力;1.13.0 增强 API 并支持 Vienna RSS(macOS);1.16.1 放宽 GReader 长短 ID 检测(Reeder)并修复 Usec 字段类型、Fever 整数类型;1.18.0 增加 OPML 导入导出、canonical 字段、兼容 BazQux、修复 continuation token 类型(Reeder);1.20.1 继续小步改进。API 入口位于 p/api/greader.php。
Fever API
1.11.0 加入 Fever 兼容 API(#1406),支持 Fiery Feeds、Unread(iOS)、Readkit(macOS);1.14.0 曾修复其编码与 32 位平台问题。实现见 p/api/fever.php。
WebSub / PubSubHubbub
1.1.2 支持 PubSubHubbub 即时通知;1.13.0 将协议更名为标准名 WebSub(#2184),并与 Mastodon 2.6.2+、Friendica 2018.12+ 互通;1.16.1 修复 WebSub feed 变更地址场景;1.20.0 用哈希代替 base64 处理长 URL(#4282)。相关配置键 pubsubhubbub_enabled 在 config.default.php 中默认关闭,公共地址服务器需显式开启。
兼容客户端生态
文档确认的第三方客户端包括:News+、EasyRSS、FeedMe、Vienna RSS、Reeder、Newsboat 2.24+、RSS Guard、Readrops、Fluent Reader、FocusReader、FeedReader、Readably、BazQux 客户端等——这些均属于文档记载事实。
多用户、认证与安全加固
用户与权限
- 1.10.0:管理员可重置用户密码(#960);
- 1.16.0:允许多个管理员(#2096);用户列表显示语言与邮箱;
- 1.17.0:新用户管理页、添加 feed/分类页、禁用/启用用户(#3056)、HTTP Basic 登录自动注册(#3003);
- 1.15.0:支持
data/config-user.custom.php定义默认用户设置与默认订阅(#2490、#2515);1.15.1 改为基于 OPML 定义新用户默认订阅(#2627); - 匿名模式权限逐步收紧:1.19.0 起匿名用户不再显示"添加订阅""标记已读/未读/收藏"等操作(#4040、#3871);1.22.0 支持匿名模式分享(#5261)。
认证方式
表单登录之外,文档记录支持:HTTP Basic 认证(含 Apache REMOTE_USER / REDIRECT_REMOTE_USER)、X-WebAuth-User 委托认证(1.13.1)、以及 1.22.0 的 OpenID Connect(仅 Debian 系默认 Docker 镜像的 x86_64 架构,依赖 libapache2-mod-auth-openidc,#5351 等)。OpenID Connect 相关环境变量(如 OIDC_SCOPES)在 1.22.1 中修复了冒号兼容问题。
安全加固要点(不完全列举)
- CSRF:1.5.0 引入 POST 令牌;1.14.0 重做令牌与会话的边界处理;
- CSP 与 HTTP 头:1.3.1-beta 加入 CSP、
X-Content-Type-Options: nosniff、HTTPS 下 CookieSecure标记、API POST 限制 1MB;1.14.0 移除已废弃的child-src;1.20.0 改进错误页,规范返回 HTTP 500 并带 CSP(#4465); - 凭据保护:1.11.2 避免在日志中记录 feed 凭据(#1949);1.21.0 修复 API 记录密码问题(CVE-2023-22481)并提供 cli/sensitive-log.sh 帮助清除 Apache 日志中的敏感信息;1.22.0 重做可信代理逻辑(#5549)并支持安装时自动识别可信来源(#5358);
- 其他:1.20.2 修复
ext.php安全漏洞(CVE-2022-23497)并设置 ApacheTraceEnable Off;1.15.1 使用SameSite=LaxCookie 策略;1.6.3 匿名用户隐藏版本号、净化 feed 网站 URL;1.7.0 移除更新检查对写权限的依赖。
运维工具链:CLI、Docker 与数据库
CLI 工具演进(见 cli/ 目录)
1.6.0 首次引入完整命令行接口(#1095),支持安装、增删用户、actualize、导入导出,对应文档指向 cli/README.md。此后逐步扩充:
- cli/do-install.php、cli/reconfigure.php(1.6.3,更新既有安装)、cli/user-info.php(1.6.2 起,1.16.1 增加
--json、语言与邮箱输出,1.14.0 增加--header)、cli/update-user.php(1.8.0)、cli/db-optimize.php(1.9.0,SQLite/PostgreSQL 上执行VACUUM)、cli/prepare.php(1.10.1,创建./data/子目录); - 1.15.0 增加任意数据库与 SQLite 互导命令(cli/export-sqlite-for-user.php、cli/import-sqlite-for-user.php);1.17.0 重新引入
--api_password选项并修正 shebang 可移植性;1.21.0 新增 cli/access-permissions.sh 正确应用文件权限(#5062)与敏感日志清理脚本(#5001);1.20.0 允许空数据库前缀(#4488)。
Docker 部署演进(见 Docker/)
- 镜像基底:早期为 Debian/Ubuntu 系默认镜像 + Alpine 备用镜像,后来默认镜像长期基于 Debian(Buster/Bullseye/Bookworm),备用镜像基于 Alpine;开发镜像
:newest与:oldest用于测试最新/最老 PHP; - 架构:1.23.0 起用 GitHub Actions 构建
amd64、arm32v7、arm64v8多架构镜像并自动检测(#5808);1.14.3 已提供 ARM(Raspberry Pi)版本;1.22.0 默认监听所有接口含 IPv6(#5180); - 环境变量:
CRON_MIN(可选内置 cron)、DATA_PATH、LISTEN(host 网络模式下修改 Apache 内部端口)、TZ、COPY_LOG_TO_SYSLOG、COPY_SYSLOG_TO_STDERR、FRESHRSS_ENV(控制 Minz 开发模式)、TRUSTED_PROXY;1.22.1 起 cron 会导出全部环境变量以便 Kubernetes 等场景(#5772); - 其他:1.18.0 支持通过 docker-compose 自动安装并容忍数据库暂未就绪(多次重试连接)、禁用 Docker 新安装的内置更新机制(#3496);1.14.0 起默认镜像基于 Ubuntu 以获得约 3 倍性能(但体积大 2.5 倍),1.22.0 后又迁回 Debian Bookworm。
数据库与存储
- 支持范围:0.7.3 加入 SQLite(beta);1.6.0 正式支持 PostgreSQL;MySQL 要求 5.5.3+(1.5.0)、PostgreSQL 要求 9.5+(1.15.0);
- MySQL utf8mb4:1.5.0 支持 emoji 等完整 Unicode,首次需要时自动迁移;
- 容量:1.15.0 允许 MySQL/MariaDB 存储最长 16MB(压缩)的文章;1.20.0 将订阅上限提升至 5 万+(新用户或导出/导入后生效);1.23.0 将 SQL
VARCHAR文本字段扩展到最大长度(#5788)、日期字段升级为 64 位以应对 2038 年问题(#5570); - 性能:1.20.0 提供 PostgreSQL GIN
pg_trgm文本搜索索引文档(需手动添加);1.22.0 持续减少数据库锁并优化 MySQL/MariaDB 缓存值更新(#5648 等)。
工程实践与技术债演进
文档在 Misc./Compatibility 章节记录了清晰的工程演进轨迹,对理解当前代码库风格极有价值:
- PHP 版本红线:1.19.0 起要求 PHP 7.0+(弃 5.x)→ 1.21.0 要求 7.2+(弃 7.0/7.1)→ 1.23.0 要求 7.4+ 并全面启用 typed properties(#5720);PHP 8.0/8.1/8.2/8.3 兼容性逐步验证;
- 静态分析:PHPStan 级别从 Level 1(1.19.1)→ Level 5(1.19.2)→ Level 7(1.22.0)→ Level 8(1.23.0,#5946),并启用
declare(strict_types=1);(#5830);仓库中的 phpstan.dist.neon 与 phpstan-next.neon 延续了这一实践; - 前端现代化:1.14.0 将 jQuery/快捷键代码重写为原生 ES6;1.19.0 完全移除 jQuery(统计页除外)、用 ESLint 替换 JSHint、统计图改用 chart.js;1.20.1 引入 CSS 变量主题定制;
- CI/CD:Travis → GitHub Actions;1.20.0 加入 Docker 构建自动扫描漏洞;1.14.x 加入
hadolint、shellcheck、shfmt检查;1.19.2 加入 typos 拼写检查; - 库更新:PHPMailer 6.x 持续升级、lib_opml 定期更新、1.20.0 用 PhpGt/CssXPath 替换 lib_phpQuery;
- 配置与常量:1.22.0 新增
CLEANCACHE_HOURS常量(#5144),当前 constants.php 中默认值为 720(小时,即约 30 天),由 app/Utils/httpUtil.php 与 app/Controllers/feedController.php 中的cleanCache(CLEANCACHE_HOURS)调用。
升级路径与运维建议(基于文档的实践归纳)
- 跨大版本升级前先导出:文档多次强调导出/导入能力(OPML、JSON、ZIP,见 cli/ 各导出脚本与 app/Services/ExportService.php),升级到引入数据库结构变更的版本(如 1.7.0 的 PostgreSQL 唯一性修复、1.5.0 的 utf8mb4 迁移)前建议完整备份;
- 关注版本红线:PHP 最低版本随大版本上升(1.23.0 需 7.4+,typed properties 不可回退),升级前核对运行环境;PHP 8 对 MySQL 8+ 默认认证是必要前提;
- 合理利用新能力:大量订阅用 1.20.0 起的优化(图标 emoji、布局自动简化、PG 全文索引);隐私敏感场景用 force-https 列表(force-https.default.txt)与敏感日志清理脚本;
- Docker 用户:cron 刷新依赖
CRON_MIN,日志聚合依赖COPY_LOG_TO_SYSLOG/COPY_SYSLOG_TO_STDERR;反向代理场景注意TRUSTED_PROXY(1.22.0 起有重做后的语义)与X-Forwarded-Prefix(1.13.0 起支持)。
结语
CHANGELOG-old2.md 记录的九年演进,勾勒出一款自托管 RSS 聚合器在**抓取能力(XPath)、搜索表达力(布尔→括号→操作符体系)、协议兼容(GReader/Fever/WebSub)、多用户管理与安全、运维工具链(CLI/Docker)**五个维度上的持续沉淀。当前仓库中的 app/Models/Search.php、app/Models/BooleanSearch.php、cli/ 工具集、Docker/ 镜像体系与 constants.php 配置常量,正是这份历史文档的"当代实现快照";对开发者而言,这份 changelog 是理解代码设计动机的第一手材料,对运维者而言,则是制定升级与加固策略的可靠依据。