BringCDN Serve

中文文档

BringCDN Serve is a configurable CDN origin service for CNB, GitHub, and npm assets. It provides jsDelivr-compatible resource URLs, directory browsing, static access control, response rewriting, and brandable package pages in one deployable service.

• Serve CNB repositories, GitHub repositories, and npm packages through one HTTP service.
• Browse repository and package directories with a shared, configurable page template.
• Proxy files from provider sources with GET, HEAD, range requests, CORS headers, and timing headers.
• Resolve CNB and GitHub Git LFS pointers server-side so clients receive the actual object.
• Support jsDelivr-compatible /gh/, /github/, and /npm/ resource paths.
• Rewrite textual responses with configurable replacement rules.
• Strip noisy upstream response headers by default, including common Cloudflare headers.
• Configure site name, footer, ICP filing, police filing, badge image/API, and landing text from environment variables.
• Protect selected static file extensions with header, query, cookie, or bearer-token checks.

• /cnb/{repo-path}@{ref}/{path}
• /gh/{owner}/{repo}@{ref}/{path} or /gh/{owner}/{repo}/{path}
• /github/{owner}/{repo}@{ref}/{path} or /github/{owner}/{repo}/{path}
• /npm/{package}@{version-or-tag}/{path} or /npm/{package}/{path}
• /npm/@{scope}/{package}@{version-or-tag}/{path} or /npm/@{scope}/{package}/{path}

Directory URLs ending with / render templates/index.html. File URLs return the provider asset body; only textual responses are rewritten when REWRITE_ENABLED=true. Versionless npm URLs redirect to latest; npm dist-tags and simple major/minor aliases such as @latest, @next, @18, and @18.2 resolve to concrete package versions.

CNB and GitHub routes are enabled only when their tokens are configured:

• CNB_TOKEN: enables /cnb/ and is sent as the raw Authorization header value.
• GITHUB_TOKEN: enables /gh/ and /github/, sent as Bearer <token>.
• NPM_TOKEN: optional. Public npm works without it; set it for private registries/packages or registry authentication.

Do not commit .env because it contains secrets.

Copy .env.example to .env and adjust values:

cp .env.example .env

The app loads .env from the working directory first. Real process environment variables take precedence over .env.

Important variables:

• PORT / ADDR: listen port or address.
• TEMPLATE_PATH: directory page template, default templates/index.html.
• USER_AGENT: outbound provider request User-Agent.
• CNB_API_BASE_URL: default https://api.cnb.cool.
• CNB_WEB_BASE_URL: default https://cnb.cool, used for repository links in pages.
• GITHUB_API_BASE_URL: default https://api.github.com.
• GITHUB_LFS_BASE_URL: default https://github.com, used for Git LFS batch download resolution.
• GITHUB_RAW_BASE_URL: default https://raw.githubusercontent.com.
• NPM_REGISTRY_URL: default https://registry.npmjs.org.
• STRIP_RESPONSE_HEADERS: comma-separated response headers to remove.

These fields are rendered only when configured:

• SITE_NAME
• SITE_HOME_URL
• LANDING_TEXT
• FOOTER_LOGO_SRC
• FOOTER_NAME
• FOOTER_COPYRIGHT
• ICP_TEXT
• ICP_URL
• POLICE_TEXT
• POLICE_URL
• BADGE_HTML
• BADGE_SVG
• BADGE_IMG_SRC
• BADGE_HREF
• BADGE_TITLE
• BADGE_ALT

Branding values support placeholders:

{site_name}, {home_url}, {provider}, {kind}, {provider_key}, {resource}, {resource_url}, {ref}, {path}

{provider_key} maps GitHub to gh, so a badge API like this:

BADGE_IMG_SRC=https://cdn.bring.cool/cdn-cgi/package/{provider_key}/{resource}

renders GitHub resources as:

https://cdn.bring.cool/cdn-cgi/package/gh/dler-io/Rules

Textual response rewriting is controlled by:

REWRITE_ENABLED=true
REWRITE_TEXTUAL_TYPES=text/,application/javascript,application/json,text/css,image/svg+xml
REWRITE_PAIRS=cdn.jsdelivr.net=>cdn.bring.cool||fastly.jsdelivr.net=>cdn.bring.cool

REWRITE_PAIRS format is from=>to||from=>to. Empty replacements are allowed.

Non-text responses are streamed unchanged. Proxied responses include:

• bring-upstream-ms
• bring-rewrite-ms

Static resource access control applies to configured extensions:

• STATIC_ACCESS_ENABLED: default true.
• STATIC_ACCESS_EXTS: comma-separated file extensions.
• STATIC_ACCESS_HEADER: default bring-origin.
• STATIC_ACCESS_VALUES: comma-separated allowed values, default EdgeoneBackSource.
• STATIC_ACCESS_QUERY: query parameter name, default bring-origin.
• STATIC_ACCESS_COOKIE: cookie name, default bring-origin.
• STATIC_ACCESS_BEARER_TOKENS: comma-separated allowed bearer tokens.

go run .

Then open:

http://127.0.0.1:8080/npm/is-number@7.0.0/

CNB and GitHub routes require their corresponding tokens in .env.

Build the image:

docker build -t docker.cnb.cool/bring/project/bringcdn/serve:latest .

Run the prebuilt image with environment variables:

docker run --rm -p 8080:8080 \
  -e SITE_NAME=BringCDN \
  -e GITHUB_TOKEN=github_pat_xxx \
  -e CNB_TOKEN=your_cnb_token \
  docker.cnb.cool/bring/project/bringcdn/serve:latest

Or mount a local .env file:

docker run --rm -p 8080:8080 \
  -v "$PWD/.env:/app/.env:ro" \
  docker.cnb.cool/bring/project/bringcdn/serve:latest

go test ./...