RSSHub Admin Guide

This guide is the operational and architectural reference for RSSHub — the open-source, self-hostable feed-generation framework. It is written for the people who run it and the people who extend it: operators deploying and tuning an instance, and developers adding routes or understanding the internals.

RSSHub is a TypeScript application built on the Hono web framework. A single instance loads over 1,500 route namespaces (thousands of individual routes), each of which scrapes one source and returns a normalized feed. The same codebase runs unchanged on Node.js, Cloudflare Workers, Vercel, and Fly.io because Hono is runtime-agnostic.

If you are looking for how to consume feeds (URL structure, output formats, query parameters), see the User Guide. This guide covers everything behind the feed.

1. Executive Summary

What it does. RSSHub receives an HTTP GET for a feed path, dispatches to the matching route handler, which fetches and parses a source into a normalized data structure, then a middleware chain post-processes that data (filtering, full-text, hotlink rewriting) and renders it as RSS, Atom, JSON Feed, or RSS3.

What makes it operationally distinctive. Routes are auto-discovered from the filesystem and compiled into a static registry at build time. A single shared middleware chain implements every universal query parameter once, so all routes behave consistently. Caching is request-coalescing: concurrent requests for the same feed are serialized so the source is hit at most once per cache window.

2. Architecture

2.1 Request lifecycle

            ┌──────────────────────────────────────────────────────────────┐
  HTTP GET  │  Hono app (lib/app-bootstrap.tsx)                             │
 ─────────► │                                                              │
            │  GLOBAL MIDDLEWARE (run in order, each wraps the next):      │
            │    trimTrailingSlash → compress → jsxRenderer                 │
            │    → logger → trace → honeybadger → sentry                    │
            │    → access-control → debug → template → header               │
            │    → anti-hotlink → parameter → cache                         │
            │                          │                                    │
            │                          ▼                                    │
            │  ROUTE REGISTRY (lib/registry.ts)                             │
            │    app.basePath('/'+namespace).get(routePath, handler)        │
            │                          │                                    │
            │                          ▼                                    │
            │  ROUTE HANDLER (lib/routes/<ns>/<route>.ts)                   │
            │    fetch source → parse → return normalized Data              │
            │                          │                                    │
            │      (unwinds back up the middleware chain)                   │
            │                          ▼                                    │
            │  template middleware renders Data → RSS / Atom / JSON / RSS3  │
            └──────────────────────────────────────────────────────────────┘
                                       │
                                       ▼  Response

The chain is declared in lib/app-bootstrap.tsx. Each middleware calls await next() and then runs its post-processing as the stack unwinds — so template, header, anti-hotlink, parameter, and cache all act on the route's output after the handler returns. The route registry (lib/registry.ts) is mounted last with app.route('/', registry); the metadata API is mounted at app.route('/api', api).

2.2 The middleware chain in detail

Note

Because middleware post-processing runs as the stack unwinds, the textual order above is also the response-shaping order in reverse: the handler produces Data, then parameter filters it, then anti-hotlink rewrites media, then template serializes it. cache wraps the whole route execution to store the serialized result.

2.3 Route discovery and the registry

Routes live under lib/routes/<namespace>/. Each namespace directory contains:

• namespace.ts — exports a namespace: Namespace object (display name, source url, description, language, categories).
• One file per route — exports a route: Route object (path template, parameters, example, handler, radar rules, feature flags).

How they get loaded depends on NODE_ENV (lib/registry.ts):

For each namespace the registry creates a Hono sub-app with app.basePath('/'+namespace) and registers every route's path as a GET handler. Routes are sorted so literal path segments take priority over :parameter segments, ensuring specific paths match before catch-alls. Route handlers are lazy: the handler module is imported on first hit in production via a module() thunk.

Important

Adding or renaming a route requires rebuilding the static registry for production/worker deployments (pnpm build:routes). In development the directory scan picks up changes on restart. A route present on disk but missing from assets/build/routes.js will 404 in production.

2.4 The route contract (Route type)

Defined in lib/types.ts. Every route exports an object with these fields:

The features object signals operational requirements:

2.5 Output rendering

The template middleware (lib/middleware/template.tsx) selects the serializer from ?format=:

The middleware also normalizes data before rendering: collapses whitespace, trims titles to TITLE_LENGTH_LIMIT, strips Unicode control characters from descriptions, converts dates to ISO-8601 for non-RSS formats, and computes the RSS <ttl>.

2.6 The metadata API (/api)

Mounted at /api, built with @hono/zod-openapi (lib/api/index.ts). It powers the documentation site, RSSHub Radar, and external tooling:

3. System Requirements

Tip

Start with the lightweight default image (no bundled browser) and add a separate headless-browser container only when you actually need a requirePuppeteer route. It keeps memory and image size down.

4. Configuration Reference

All configuration is via environment variables, parsed once in lib/config.ts. Values are read from process.env (and a .env file via dotenv). Booleans accept true/1 for true and false/0/empty for false. This section is the authoritative, source-derived reference.

Note

Defaults below are exactly as coded in lib/config.ts. An empty "Default" cell means the value is unset/optional unless noted.

4.1 Application

4.2 Network

4.3 Caching

RSSHub caches route output to avoid re-scraping sources. The cache key is xxhash64(path + format + limit), so different formats and limits cache independently.

Warning

Setting CACHE_TYPE='' (empty) disables caching entirely. The instance will re-scrape on every request — heavy load on both RSSHub and the source sites, and it lowers the RSS <ttl> to 1 minute. Only do this for debugging.

4.4 Proxy

For reaching sources that are geo-blocked or rate-limited. Configure either a single URI, a list, or discrete parts.

4.5 Access control

Important

ACCESS_KEY is the only built-in authentication. It gates feed access, not the /api metadata endpoints' shape — but those run behind the same middleware, so a set key protects them too (except the always-open paths). It does not encrypt anything; treat the key as a shared secret and serve over HTTPS.

4.6 Logging, errors, and observability

Caution

Leaving DEBUG_INFO=true on a public instance exposes a debug panel and /metrics with route hit/error counts and recently-requested paths. For a hardened public deployment set DEBUG_INFO=false, which also disables /metrics.

4.7 Feed behavior

Note

The hotlink template only accepts a fixed allowlist of URL properties (hash, host, hostname, href, origin, password, pathname, port, protocol, search, searchParams, username). An unknown property throws Invalid URL property. This validation is the guardrail that makes user-supplied templates safe-ish — but keep ALLOW_USER_HOTLINK_TEMPLATE=false unless you need it.

4.8 OpenAI / AI features (the chatgpt parameter)

4.9 Folo integration

4.10 Remote configuration

Warning

REMOTE_CONFIG loads configuration over the network at boot. If the fetch fails the instance logs an error and continues with local config. Only point it at a source you fully control and serve it over HTTPS — it can inject any setting, including credentials and proxies.

4.11 Route-specific credentials (per-site)

Beyond the operational settings above, lib/config.ts defines ~150 site-specific variables that supply cookies, tokens, API keys, or login credentials to individual routes. A route's docs (and its features.requireConfig) tell you which it needs. These follow consistent naming conventions:

A handful use a dynamic suffix so you can supply several accounts for the same source. The suffix after the prefix becomes a lookup key:

Tip

For the complete, current list of which routes need which variable, consult each route's page on docs.rsshub.app or the source of truth — the ConfigEnvKeys union and the matching config object in lib/config.ts. Provide only the credentials for routes you actually use; every credential variable is optional.

Caution

These variables hold real account credentials. Inject them as secrets (Docker secrets, wrangler secret put, your platform's secret store), never bake them into an image or commit them. A leaked *_COOKIE is a full session hijack of that account.

5. Deployment

The same build runs on several targets. The npm scripts (package.json) define each path.

5.1 Docker (recommended)

Single container, in-memory cache:

docker run -d --name rsshub -p 1200:1200 --restart always diygod/rsshub

Production stack with Redis and a headless browser — docker-compose.yml ships in the repo:

services:
    rsshub:
        image: diygod/rsshub
        restart: always
        ports:
            - '1200:1200'
        environment:
            NODE_ENV: production
            CACHE_TYPE: redis
            REDIS_URL: 'redis://redis:6379/'
            PLAYWRIGHT_WS_ENDPOINT: 'ws://browserless:3000'
        healthcheck:
            test: ['CMD', 'curl', '-f', 'http://localhost:1200/healthz']
            interval: 30s
            timeout: 10s
            retries: 3
        depends_on:
            - redis
            - browserless
    browserless:
        image: browserless/chrome
        restart: always
    redis:
        image: redis:alpine
        restart: always
        volumes:
            - redis-data:/data
volumes:
    redis-data:

docker compose up -d

[+] Running 3/3
 ✔ Container rsshub-redis-1        Started
 ✔ Container rsshub-browserless-1  Started
 ✔ Container rsshub-rsshub-1       Started

Tip

The image tag diygod/rsshub:chromium-bundled ships Chromium inside the RSSHub container, so you can drop the separate browserless service (and its PLAYWRIGHT_WS_ENDPOINT) at the cost of more memory and a larger image. The docker-compose.yml comments mark exactly which lines to remove for the bundled approach.

The image exposes 1200, runs npm run start under dumb-init as PID-1, and defaults to TZ=Asia/Shanghai — override TZ if you want local timestamps.

5.2 Cloudflare Workers

RSSHub builds a Worker bundle (wrangler.toml, dist-worker/worker.mjs). Caching uses a KV namespace, and a Browser binding provides Playwright.

npm run worker-deploy   # builds the worker bundle, then `wrangler deploy`

Important

On Workers, set sensitive config with wrangler secret put <KEY> (e.g. ACCESS_KEY, GITHUB_ACCESS_TOKEN), not in [vars]. The Workers Paid plan is recommended — the Free plan caps CPU at 10 ms/request, which is too tight for many routes; the Paid plan allows 30 s. Browser-dependent routes (requirePuppeteer) need the Browser binding, which is Paid-only. The Worker uses the nodejs_compat flag plus Node shims in lib/shims/ — some Node-only operations (child process, vm) are deliberately unsupported there.

5.3 Vercel

vercel.json declares the Hono framework preset. Build with npm run vercel-build (which runs build:routes then tsdown --config tsdown-vercel.config.ts). Connect the repo to Vercel and set environment variables in the project dashboard.

5.4 Fly.io

fly.toml is preconfigured: internal port 1200, forced HTTPS, autoscaling with suspend, and a /healthz health check.

fly deploy

5.5 From source / npm

pnpm install
pnpm build        # build:routes + tsdown
pnpm start        # NODE_ENV=production node dist/index.mjs

For development with hot reload and the directory-scan route loader:

pnpm dev          # tsx watch lib/index.ts, NODE_ENV=dev

RSSHub is also published as a library (rsshub on npm, IS_PACKAGE mode) for embedding the feed engine into another app.

6. Operations

6.1 Health and observability

OpenTelemetry is built in (the trace middleware and @opentelemetry/* deps). Configure histogram buckets via OTEL_SECONDS_BUCKET / OTEL_MILLISECONDS_BUCKET. Errors can be shipped to Honeybadger (HONEYBADGER_API_KEY) and/or Sentry (SENTRY).

6.2 Logs

Winston handles logging at LOGGER_LEVEL. By default RSSHub writes log files; set NO_LOGFILES=true to log to console only (recommended for containers, where you want stdout capture). SHOW_LOGGER_TIMESTAMP=true adds timestamps if your log shipper does not.

docker logs -f rsshub

6.3 Caching operations

• Pick Redis for any multi-instance or production deployment so the cache is shared and survives restarts. In-memory caching is per-process and lost on restart.
• The request-coalescing lock (cache.ts) means a cold-cache feed that is requested concurrently makes the source call once; the other requests wait up to CACHE_REQUEST_TIMEOUT then either serve the now-warm cache or receive RequestInProgressError (503).
• Cache keys include format and limit, so ?format=json and ?format=rss of the same route are cached separately.
• To force a route to bypass caching, a handler can set Cache-Control: no-cache; the cache middleware then skips storing it.

6.4 Startup checklist

• [ ] Choose CACHE_TYPE (redis for production) and provide REDIS_URL.
• [ ] Set DEBUG_INFO=false for a hardened public instance.
• [ ] Set ACCESS_KEY if the instance is private.
• [ ] Configure a proxy (PROXY_URI/PROXY_URIS) if your sources need one.
• [ ] Provide only the route credentials you need, as secrets.
• [ ] Decide on headless-browser strategy (none / sidecar browserless / bundled image).
• [ ] Confirm GET /healthz returns success.
• [ ] If self-building for production/Workers, run pnpm build:routes so the static registry is current.

7. Security

Important

RSSHub is a server that fetches arbitrary external URLs on behalf of requests. Treat it as an outbound proxy and harden accordingly.

Error handling and status codes

The central error handler (lib/errors/index.tsx) maps failures to HTTP statuses and reports to Honeybadger/Sentry when configured:

In production, error responses show only error.message (not the stack); non-production shows the stack. Requesting ?format=json returns the error as JSON instead of an HTML page.

8. Codebase Map (for contributors)

lib/
  app-bootstrap.tsx     Hono app + global middleware chain
  app.ts                Entry that loads request-rewriter then the app
  index.ts / server.ts  Node server entry (@hono/node-server)
  worker.ts             Cloudflare Workers entry
  config.ts             ALL environment configuration (source of truth)
  registry.ts           Route auto-discovery + Hono mounting
  types.ts              Route / Namespace / APIRoute / Data type contracts
  middleware/           The 14-stage chain (access-control, parameter, cache, …)
  views/                RSS / Atom / JSON / RSS3 renderers (JSX)
  api/                  Public metadata API (namespace, category, radar, route)
  utils/                Shared helpers: got/ofetch HTTP, cache, playwright,
                        proxy, header-generator, parse-date, render, …
  routes/<namespace>/   1,500+ source integrations (namespace.ts + route files)
  routes-deprecated/    Legacy routes kept for backward compatibility
  shims/                Node-API shims for the Workers runtime
scripts/workflow/       build-routes / build-docs / format-description tooling
assets/build/           Generated static route registry (routes.js / routes.json)

Adding a route (high level)

1. Create lib/routes/<namespace>/namespace.ts (if the namespace is new) exporting a Namespace.
2. Create a route file exporting route: Route — fill path, name, maintainers, example, parameters, and an async handler(ctx) that returns normalized Data (title, link, item[]).
3. Add radar rules so RSSHub Radar can auto-detect the feed from the source URL.
4. If the route needs credentials, read them from config (add the key to lib/config.ts) and set features.requireConfig.
5. Mark features.requirePuppeteer if you drive a headless browser, features.nsfw if applicable.
6. Run pnpm build:routes and test with pnpm dev.

Note

Handlers return data, not a serialized feed. The shared middleware chain handles output format, filtering, limiting, caching, and hotlink rewriting — so a route author never re-implements those. This separation is why every route supports the same universal parameters automatically.

9. Known Limitations & Improvement Areas

Note

These are observations from the source at the documented commit, not defects. They are the natural trade-offs of a community-scale scraping framework.

• Source fragility. Each route depends on an external site's structure; sites change and routes break. The this route is empty guard and the maintainers list mitigate this, but breakage is inherent. A route-status dashboard (/api/route/status) helps operators spot failures.
• Credential sprawl. ~150 site-specific credential variables live in one config.ts union. It is exhaustive and well-organized, but onboarding a credential-heavy deployment means consulting per-route docs. A generated "which routes need which env var" matrix would help operators.
• Workers runtime gaps. The Cloudflare Workers target relies on shims (lib/shims/) that explicitly throw for child_process, vm, and some xxhash APIs. Routes depending on those Node features will fail on Workers — there is no static guard preventing such a route from being deployed to a Worker; it surfaces at request time.
• Headless-browser cost. requirePuppeteer routes need Chromium, which dominates memory and image size. The split (sidecar vs. bundled image vs. remote endpoint) is flexible but adds operational decisions.
• Cache coalescing timeout. Under a cold cache and high concurrency for the same heavy route, waiters can hit RequestInProgressError (503) after CACHE_REQUEST_TIMEOUT. Tuning that value trades responsiveness against duplicate upstream load.
• Regex engine choice. re2 (default) is safe but lacks some PCRE features; regexp is full-featured but exposes the instance to ReDoS from user-supplied filter patterns. There is no per-request engine override — it is instance-wide.