rssany

v0.5.4

Published

4 days ago

Universal RSS/Atom/JSON Feed pipeline — collectors turn web, feed, API, and email sources into consumable feeds

0High
0Medium
0Low

sungizhow

rss atom json-feed subscription pipeline

RSSAny - 把任何信息变成RSS订阅

按信源抓取网页 / RSS / 邮件等，解析、补全文、打标签与翻译后入库，再按需生成 RSS / Atom / JSON Feed 与 JSON API。

RSSAny 是一套自托管的订阅管线：列表 URL → 抓取与解析（规则 / LLM）→ 正文提取（自定义 / Readability / LLM）→ upsert 去重 → 固定 pipeline（打标签、翻译等）→ 对外提供 **/rss** 等输出。

官网：https://rssany.com
GitHub：https://github.com/joohw/rssany
npm：https://www.npmjs.com/package/rssany

界面预览

RSSAny Web 界面截图

功能概览

统一订阅：在 .rssany/config.json 的 sources 中配置网站列表、标准 RSS、IMAP 邮件等，由调度器按 refresh 策略拉取。
可扩展采集器：站点、RSS、邮件与 API 采集器（.rssany.js / .rssany.ts），见 采集器开发与管理。
正文与解析：在信源 fetchItems（及需要的 ctx.extractItem 等）内完成；入库后跑 pipeline。
Pipeline：app/pipeline/ 中的内置步骤及 .rssany/pipelines/ 中的用户步骤，由 .rssany/config.json 的 pipeline.steps 编排。
LLM 辅助：解析、提取、标签、翻译等可按配置走 OpenAI 兼容接口。
站点登录：需登录的站点通过 Puppeteer 管理 Cookie（与产品用户账号无关）。
可选远端投递：若 config.json 中 **deliver.url** 非空，在写库与 pipeline 完成后将条目以 **{ sourceRef, items }** JSON POST 到该 URL（由 app/deliver/post.ts 发送）；留空则仅本地消费。
Web 界面：React/Vite 构建产物由后端托管；Feeds 等需 邮箱校验；**/admin** 需 **users.role === 'admin'**（可从 **/me** 进入）。

技术栈（摘要）

| 层级 | 说明 | | --- | ------------------------------------------------------------ | | 运行时 | Node.js 20–23（见 package.json engines） | | 后端 | Hono、tsx 开发入口 | | 数据 | SQLite（Node.js 内置 node:sqlite，Node.js 20+），全局安装默认 {npm prefix}/var/rssany/data/rssany.db |

快速开始

日常使用只需 Node.js 20.x–23.x（与 package.json 的 engines 一致）；全新安装推荐当前的 Node.js 22 LTS：

全局安装（推荐）

npm install -g rssany   # 与 npm i -g rssany 相同
rssany start

macOS / Linux（系统自带 Node） 若 npm install -g 报 EACCES，先一次性配置 npm 使用用户目录（仍是 npm 命令，无需 sudo）：

npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"   # 可写入 ~/.zshrc 或 ~/.bashrc
npm install -g rssany

使用 nvm / fnm 安装的 Node 通常可直接 npm install -g rssany，无需上述配置。

如果 macOS / Linux 使用系统级 npm prefix，且确实需要管理员权限，也可以安装后把 RssAny 数据目录交还给当前用户：

sudo npm install -g rssany
rssany_npm_prefix="$(npm prefix -g)"
sudo mkdir -p "$rssany_npm_prefix/var/rssany"
sudo chown -R "$(id -u):$(id -g)" "$rssany_npm_prefix/var/rssany"
rssany start

只对可信 npm 包使用 sudo npm install -g；长期使用更推荐 nvm / fnm 或用户级 npm prefix。

安装包内已包含构建好的后端与 Web 界面；用 rssany start 后台启动，服务就绪后输出访问地址（默认 http://127.0.0.1:18473/，端口可在运行命令时当前目录下的 .env 里设置 PORT）。CLI 短暂检查约 3 秒；若进程仍在初始化，会提示后台启动中并返回，可用 rssany status 查看是否就绪。启动期间退出会报告失败；用户目录中的 rssany.log 记录各初始化阶段及耗时。用 rssany stop 关闭后台服务并输出执行状态。

数据目录：全局安装时落在 npm prefix 下的 var/rssany/（例如 ~/.local/var/rssany/ 或 nvm 的 .../node/v22.x/var/rssany/），与 lib/node_modules/rssany 同级，升级 npm 包不会覆盖配置与数据库。源码开发时使用仓库内 .rssany/。可用 CLI 参数 --user-dir <path>（简写 --dir <path>）或环境变量 RSSANY_USER_DIR 覆盖，CLI 参数优先。
从 ~/.rssany 迁移：若新目录尚不存在且旧目录有数据，首次启动会自动迁移。
可选配置：在启动 rssany start 时的当前目录放置 .env（可参考仓库里的 .env.example），用于 JWT、OAuth、SMTP、LLM（如 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL）等。
重置全部本地数据（结束占用 PORT 的进程并删除用户目录，慎用）：执行 rssany reset；可用 rssany reset --user-dir <path> 指定目标，也可在含 .env 的目录下运行以读取 PORT / RSSANY_USER_DIR。

CLI 名为 rssany；裸 rssany 与 rssany start 一样会启动服务。使用 rssany --help 查看用法，rssany --version 查看版本；这两个命令不会启动服务。CLI 与后端读取同一份当前目录下的 .env，已设置的环境变量优先于 .env，--user-dir 参数优先级最高。

指定用户数据目录启动时，首次启动会在该目录初始化 config.json、data/、cache/、collectors/ 和 pipelines/：

rssany --user-dir /srv/rssany-data start
# 也可写成
rssany start --dir /srv/rssany-data

Windows PowerShell 示例：

rssany start --user-dir 'D:\rssany-data'

--user-dir / --dir 是全局参数，同样适用于 status、stop、reset、crawl 和 update。如果希望在有旧 ~/.rssany 数据时初始化一个全新实例，请先创建目标目录，避免触发自动迁移。

从源码运行（开发 / 贡献）

需要 npm：

npm install
cp .env.example .env   # 按需修改

开发：

npm run dev

运行 npm run dev 会同时启动 React Vite（固定 18373）和支持热重启的开发后端（固定 18374）。React 页面使用 HMR，后端由 tsx watch 在源码变化时自动重启；Ctrl+C 会同时清理两个进程。正式服务仍使用 18473。

也可分步运行：一个终端执行 npm run dev:frontend，另一个终端执行 npm run dev:backend。

生产（本仓库）：npm run build:all && npm start。

重置本地数据（与全局安装的 rssany reset 逻辑相同）：npm run reset。

发布到 npm 时 prepublishOnly 会执行 build:all（后端 vite build + React/Vite 前端构建）。

数据流（简图）

config.json sources / 信源采集器
  → 调度器触发 fetchItems
  → upsertItems
  → pipeline（每条一次）
  → [可选] deliver.url POST（出站，非入站 API）

消费侧：RSS/XML、**/api/***、Web UI。

常用 HTTP 能力

Agent Skill

GET /api/skill：返回官方 SKILL.md、版本和完整文件清单。
GET /api/skill.zip：下载可直接解压到 Agent skills 目录的完整知识包。
Web UI 的 /skill 页面支持复制核心说明和下载 ZIP；知识包覆盖 HTTP API、本地 MCP、采集器开发、配置、运维、排错与架构。

RSS 输出

按条件从库中生成：支持 search、tags、lng、limit 等查询参数；可用 subscribed=1 限定为 config.json 的 sources 中出现的 ref。
按 URL 即时抓取：GET /rss/https://example.com/...（具体行为以路由实现为准）。

配置

采集器（SiteCollector / Collector）：目录约定、listUrlPattern / pattern、fetchItems、与 config.json 中 sources 的关系等，见 docs/collectors.md。

Pipeline（固定代码）

**app/pipeline/**，通过 **.rssany/config.json** 配置步骤，例如：

{
  "pipeline": {
    "steps": [
      { "id": "tagger", "enabled": true },
      { "id": "translator", "enabled": false }
    ]
  },
  "deliver": {
    "url": ""
  }
}

deliver.url 非空时会对处理完成的条目向该 URL 发起出站 POST；留空则不投递。

`config.json` 的 `sources` 片段示例

{
  "sources": [
    { "ref": "https://example.com/feed.xml", "label": "Example", "refresh": "1h" }
  ]
}

合法 refresh 取值包括：10min、30min、1h、6h、12h、1day（默认）、3day、7day。

仓库目录（摘要）

├── app/                 # 后端：路由、feeder、scraper、pipeline、db、auth…
│   └── collectors/builtin/ # 内置信源 *.rssany.js
├── docs/                # 用户文档（如 collectors.md）
└── webui-react/         # React + Vite 前端

~/.rssany/               # 运行时用户数据（首次启动创建；或 RSSANY_USER_DIR）
    ├── config.json      # sources、sites、tags、pipeline、deliver、llm 等统一配置
    ├── data/rssany.db   # SQLite 主库
    ├── cache/
    └── collectors/         # 用户采集器覆盖内置

更细的模块说明见 AGENTS.md（与代码迭代同步，若有出入以代码为准）。

许可证

MIT