Proxy Worker

English | 简体中文

A Cloudflare Workers proxy service for GitHub file downloads and Docker registry mirror traffic.

Endpoints

Route	URL
Global Cloudflare	https://proxy.starudream.cn
Tencent Cloud EO for mainland China	https://proxy.52xckl.cn

The examples below use https://proxy.starudream.cn by default. For mainland China networks, replace the domain with https://proxy.52xckl.cn.

GitHub Proxy

The GitHub proxy downloads allowlisted GitHub release, archive, and raw files.

Full URL

Append the GitHub URL to the proxy endpoint:

curl -L https://proxy.starudream.cn/github/https://github.com/k3s-io/k3s/releases/download/v1.33.1%2Bk3s1/k3s

The /github/ prefix can also be omitted:

curl -L https://proxy.starudream.cn/https://github.com/k3s-io/k3s/releases/download/v1.33.1%2Bk3s1/k3s

Short Path

The proxy supports owner/repo/releases/..., owner/repo/archive/..., and owner/repo/raw/... paths:

curl -L https://proxy.starudream.cn/k3s-io/k3s/raw/refs/tags/v1.33.1%2Bk3s1/install.sh

curl -L https://proxy.starudream.cn/fatedier/frp/releases/download/v0.62.1/frp_0.62.1_linux_amd64.tar.gz

The current GitHub allowlist is maintained in src/settings.json.

Workers Logs records a structured github proxy completed event after an allowed GitHub request receives its upstream response. The owner, repository, resource, path, upstreamHost, status, and redirected fields describe the proxied request without recording URL query parameters.

Docker Proxy

The Docker proxy can be used as a registry mirror. Put the image path after the proxy domain:

docker pull proxy.starudream.cn/docker.io/library/hello-world:latest

Mainland China route:

docker pull proxy.52xckl.cn/docker.io/library/hello-world:latest

Docker Hub Defaults

docker.io is the default registry, and library is the default namespace. These three forms are equivalent:

docker pull proxy.starudream.cn/docker.io/library/hello-world:latest
docker pull proxy.starudream.cn/library/hello-world:latest
docker pull proxy.starudream.cn/hello-world:latest

All of them proxy to:

docker.io/library/hello-world:latest

Other Registries

Put the registry explicitly at the beginning of the image path:

docker pull proxy.starudream.cn/ghcr.io/home-assistant/home-assistant:latest
docker pull proxy.starudream.cn/registry.k8s.io/pause:3.10
docker pull proxy.starudream.cn/mcr.microsoft.com/dotnet/runtime:9.0
docker pull proxy.starudream.cn/quay.io/prometheus/prometheus:latest

Currently supported registries:

Registry	Allowlist Required
docker.io	Yes
gcr.io	Yes
ghcr.io	Yes
quay.io	Yes
registry.k8s.io	No
mcr.microsoft.com	No
docker.elastic.co	No

Registries that require an allowlist only proxy image repositories configured in src/settings.json.

Upstream Priority

After the allowlist check, image pull requests use SparkCR first and fall back to the configured source registry when SparkCR is unavailable or returns an unsuccessful response.

SparkCR manifests and uncached blobs are streamed through the Worker. Redirects for cached blobs are returned directly to Docker, so the blob data does not pass through the Worker. A response that fails after streaming has started cannot be retried through the source registry.

Workers Logs records a structured docker upstream selected event for each manifest, blob, tag list, or referrers request. The registry, repository, resource, upstream, upstreamHost, and status fields identify the selected upstream. Manifest events also include reference; upstream is either spark or origin. Origin events include fallbackReason and, when available, acceleratorStatus. Token and registry probe requests are not recorded by this custom log.

Automatic invocation logs are disabled; Workers Logs retains the GitHub and Docker structured application events described above.

Configuration

Main configuration lives in src/settings.json:

• github.owners: GitHub owners allowed by the proxy.
• github.repositories: GitHub repositories allowed by the proxy.
• docker.accelerator: Preferred Docker accelerator, authentication, and timeout settings.
• docker.registries: Docker registry upstreams and allowlist policies.
• docker.repositories: Docker image repositories that require allowlisting.

Sort and deduplicate the configuration:

pnpm sort:settings

Sorting rules:

• Arrays are deduplicated.
• Rules containing * are placed first.
• Other entries are sorted alphabetically.

Deployment

This project deploys to Cloudflare Workers with Wrangler:

pnpm deploy

GitHub Actions runs the deployment workflow after pushes to the master branch.

License