RSSHub-Gateway

One gateway, many feeds. RSSHub-Gateway is a production-ready reverse proxy for RSSHub and Upvote RSS that keeps feed URLs stable while scaling horizontally.

Why teams use it: - Keep a single stable feed URL across multiple upstreams - Route by prefix with per-group load balancing and health checks - Enforce gateway auth while staying RSSHub-compatible - Observe everything with metrics, pprof, and structured logs - Reload safely and cache responses in memory or Redis

中文说明

Highlights

• Multi-backend routing: /rsshub/ for RSSHub, /upvote/ for Upvote RSS
• Prefix-based grouping with longest-match selection and per-group LB
• Short subscriptions: /short/{name} with method 301/302/proxy
• Gateway auth: ?key= or ?code=md5(path+key) + RSSHub code injection
• Health checks + passive eject + retry + fallback
• Prometheus metrics, pprof, JSON access/event logs
• SIGHUP config reload with rollback on failure
• Response cache (memory/redis) + auto reload polling
• Built-in docs: / (README) and /wiki (Qoder RepoWiki)

Tip: in a deployed instance, open /wiki to read the full project guide.

Core Concepts

• Routes and groups: longest-prefix match, per-group LB, optional strip_prefix
• Upstreams: active health probes + passive eject ensure safe failover
• Auth: gateway key/code validation with RSSHub code injection only when needed
• Short links: internal or external targets with safe query passthrough
• Observability: metrics, pprof, and JSON access logs out of the box

Typical Use Cases

• One stable URL for multiple RSSHub clusters
• Fast failover across upstreams without changing feed URLs
• Short, memorable subscription links for feed readers

Architecture

Request flow stays simple: authenticate, route by prefix, pick upstream, proxy.

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 redirect (external)
        G->>G: Resolve short + strip key/code
        G-->>C: 301 Location: https://fearnation.club/rss/?...
    else short proxy (external)
        G->>G: Resolve short + strip key/code
        G->>E: Proxy request (UA + SNI)
        E-->>G: Response
        G-->>C: Response
    else normal proxy
        C->>G: GET /rsshub/path?key=...
        G->>G: Validate key/code
        G->>R: Select group by prefix
        R-->>G: Group name
        G->>LB: Pick upstream
        LB-->>G: Upstream
        G->>G: Remove key/code, inject upstream code (rsshub)
        G->>U: Proxy request
        U-->>G: Response
        G-->>C: Response
    end

Try It in 60 Seconds

Build locally and run with the sample config:

# build
make build

# run
./rsshub-gateway serve -c config.example.yaml

Docker

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

Prebuilt images: - docker pull nerdneils/rsshub-gateway:latest - docker pull ghcr.io/nerdneilsfield/rsshub-gateway:latest

To use a custom config:

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

Deployment Example (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

Configuration

The full schema lives in config.example.yaml.

Authentication

Gateway access supports both key and code styles:

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

Migration note (code auth): If you previously used ?code= with /latepost/..., update the path to /rsshub/latepost/... and compute md5("/rsshub/latepost/4"+ACCESS_KEY). Key-based access is unchanged.

Short Subscriptions

Short entries support method: 301|302|proxy. Redirects append the original query string; external targets strip key/code to avoid leaking credentials. Proxy mode forwards the request directly (internal targets keep key/code, external targets strip them).

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

Upstream injection rules: - Remove client key and code - Inject code=md5(path+upstream_access_key) for RSSHub only

Routing and Load Balancing

• Match allow/deny by prefix, deny overrides allow
• Choose longest prefix, then higher priority, then config order
• Use wrr or hash per group
• Strip service prefix (like /rsshub or /upvote) before proxying when configured

Health Checks

Active health checks call /healthz on each upstream. If the upstream requires an ACCESS_KEY, the gateway automatically appends ?key=<upstream_access_key>.

If you use Docker Compose, update healthcheck like this:

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

Metrics

Metrics endpoint (requires access key):

GET /metrics?accesskey=<METRICS_ACCESS_KEY>

Pprof

Pprof endpoint (requires access key):

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

Logging

Access logs are JSON per request. Event logs include health changes, ejections, and reload outcomes.

Reload

Send SIGHUP to reload config without downtime:

kill -HUP <pid>

Development

make test
make cover

Release

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

License

MIT