RSSHub-Gateway

一个入口，掌控多套 RSSHub 与 Upvote RSS。RSSHub-Gateway 是面向生产的 反向代理与调度层，保持 RSSHub 路由兼容，同时实现可观测与可运维。

为什么团队选它： - 一个稳定入口覆盖多套上游实例 - 前缀路由 + 组内负载均衡 + 健康检查 - 网关鉴权兼容 RSSHub code 机制 - Prometheus + pprof + JSON 结构化日志 - 热加载 + 缓存，适合长期运行

English README

亮点一览

• 多后端路由：/rsshub/ -> RSSHub，/upvote/ -> Upvote RSS
• 路由分组：按前缀 allow/deny，最长前缀优先
• 订阅缩写：/short/{name} 支持 method: 301|302|proxy
• 网关鉴权：?key= 或 ?code=md5(path+key)
• 健康检查 + 被动剔除 + 重试 + fallback
• Prometheus 指标、pprof 调试、JSON 结构化日志
• SIGHUP 热加载（失败回滚）
• 响应缓存（memory/redis）+ 自动轮询重载
• 内置文档：/ 首页与 /wiki RepoWiki

提示：在已部署的实例中访问 /wiki 可阅读完整项目指南。

核心概念

• 路由与分组：最长前缀匹配、组内负载均衡、可选 strip_prefix
• 上游池：主动健康检查 + 被动剔除，保障快速故障切换
• 鉴权：网关 key/code 校验，RSSHub 才注入上游 code
• 短链：内部/外部目标，安全拼接查询参数
• 可观测：指标、pprof、访问日志开箱即用

典型场景

• 用一个稳定入口承载多个 RSSHub 集群
• 上游不稳时自动切换，订阅地址不变
• 用短链接管理订阅入口，方便分发

架构示意

请求流程很简单：鉴权 → 前缀路由 → 选 upstream → 转发。

flowchart LR
    Client -->|HTTP| Gateway
    Gateway -->|/short/*| Short
    Short -->|301/302| Redirect
    Redirect --> Target
    Short -->|proxy internal| Router
    Short -->|proxy external| External
    Gateway --> Router
    Router --> Group
    Group --> LB
    LB --> RSSHub
    LB --> Upvote
    Gateway -->|/metrics| Prometheus
    Gateway -->|logs| Logger

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant R as Router
    participant LB as Load Balancer
    participant U as Upstream
    participant E as External

    C->>G: GET /short/fearnation?key=...
    alt short 重定向（外部）
        G->>G: 解析 short + 去除 key/code
        G-->>C: 301 Location: https://fearnation.club/rss/?...
    else short 代理（外部）
        G->>G: 解析 short + 去除 key/code
        G->>E: 代理请求（UA + SNI）
        E-->>G: 响应
        G-->>C: 返回
    else 业务代理
        C->>G: GET /rsshub/path?key=...
        G->>G: 校验 key/code
        G->>R: 前缀选组
        R-->>G: 组名
        G->>LB: 选 upstream
        LB-->>G: upstream
        G->>G: 删除 key/code，注入 upstream code（rsshub）
        G->>U: 代理转发
        U-->>G: 响应
        G-->>C: 返回
    end

60 秒上手

本地构建并用示例配置启动：

# 构建
make build

# 运行
./rsshub-gateway serve -c config.example.yaml

Docker

docker build -t rsshub-gateway:latest .
docker run --rm -p 8080:8080 rsshub-gateway:latest

预构建镜像： - docker pull nerdneils/rsshub-gateway:latest - docker pull ghcr.io/nerdneilsfield/rsshub-gateway:latest

自定义配置文件：

docker run --rm -p 8080:8080 \
  -v "$(pwd)/config.example.yaml:/app/config.yaml:ro" \
  rsshub-gateway:latest \
  /app/rsshub-gateway serve -c /app/config.yaml

部署示例（Docker Compose）

services:
  rsshub-gateway:
    image: ghcr.io/nerdneilsfield/rsshub-gateway:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    command: ["/app/rsshub-gateway", "serve", "-c", "/app/config.yaml"]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3

配置

完整配置见 config.example.yaml。

鉴权

网关支持两种访问方式：

http://127.0.0.1:8080/rsshub/latepost/4?key=ACCESS_KEY
http://127.0.0.1:8080/rsshub/latepost/4?code=md5(path+ACCESS_KEY)
http://127.0.0.1:8080/upvote/?platform=reddit&key=ACCESS_KEY

迁移说明（code 方式）： 如果之前用 ?code= 访问 /latepost/...，需要改成 /rsshub/latepost/...， 并按 md5("/rsshub/latepost/4"+ACCESS_KEY) 计算。key 方式不变。

上游注入规则： - 删除客户端 key 与 code - 仅 RSSHub 注入 code=md5(path+upstream_access_key)

订阅缩写

short 入口支持 method: 301|302|proxy。 重定向会把原始 query 追加到目标 URL；外部目标会剥离 key/code 以避免泄露。proxy 会直接转发请求（内部目标保留 key/code，外部目标剥离 key/code）。

GET /short/latepost?key=ACCESS_KEY
-> 301 Location: /rsshub/latepost/4?key=ACCESS_KEY

GET /short/reddit-top?sort=top&key=ACCESS_KEY
-> 302 Location: https://example.com/rss?platform=reddit&sort=top

GET /short/cdt?key=ACCESS_KEY
-> proxy https://chinadigitaltimes.net/chinese/feed

路由与负载均衡

• allow/deny 前缀匹配，deny 优先
• 最长前缀优先，其次 priority，再按配置顺序
• 每组 wrr 或 hash 二选一
• 若配置 strip_prefix，转发前剥离服务前缀（如 /rsshub 或 /upvote）

健康检查

主动健康检查请求 /healthz。当 RSSHub 设置 ACCESS_KEY 时，健康检查会 自动追加 ?key=<upstream_access_key>。

Docker Compose 建议：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:1200/healthz?key=${ACCESS_KEY}"]

指标

访问方式（带 accesskey）：

GET /metrics?accesskey=<METRICS_ACCESS_KEY>

pprof

访问方式（带 accesskey）：

GET /debug/pprof/?accesskey=<PPROF_ACCESS_KEY>

日志

访问日志为 JSON，每请求一条；事件日志记录健康变更、剔除和重载等事件。

热加载

kill -HUP <pid>

开发

make test
make cover

发布

goreleaser release --snapshot --clean --skip-publish

License

MIT