dqzboy/Docker-Proxy

中文 | English

---

📝 Prerequisites

⚠️ Important: Choose an overseas server that is not blocked. Domain names do not require ICP filing in China. You can also obtain a free domain through some platforms. During one-click deployment, if you choose to install Caddy, it will automatically configure HTTPS. If you choose to deploy Nginx, you need to apply for a free SSL certificate yourself, or implement SSL encryption through other means.

Free Domain SSL Certificate Application

Method 1: Acme.sh automatically generates and renews free Let's Encrypt SSL certificates

Method 2: Host your domain on Cloudflare to enable free SSL certificates

Method 3: You can apply for a free domain certificate through third-party platforms (free ones are generally DV certificates), suitable for personal websites, blogs, and small projects

---

🔨 Features

• Zero disk cache: A single process automatically routes by Host to major public registries (Docker Hub, GHCR, Quay, K8s, MCR, Elastic, NVCR, etc.), performs server-side token authentication and streams the response without writing to disk or consuming local storage.
• One-click deployment: Interactive menu: with a single click, complete “install dependencies → start Docker image acceleration → (optional) configure Nginx/Caddy reverse proxy”.
• Optional reverse proxy: Automatically deploys Nginx or Caddy as a reverse proxy and renders the corresponding configuration (HTTPS, Host rewriting).
• Upstream account authentication: You can configure an upstream username/password; the proxy server exchanges them for a Bearer Token, enabling pulls of private Docker Hub images and mitigating official rate limits.
• HubCMD-UI management panel: Manage proxies, configure server parameters, and hot-reload directly from the web UI; includes image search, documentation tutorials, container management, monitoring, and alerting.
• System Dashboard: Real-time monitoring of server resources, container runtime status, and network traffic information
• Cross-platform images: Supports deployment on mainstream architectures such as linux/amd64 and linux/arm64.
• Daily operations management: Provides full lifecycle management including service start / stop / restart / logs / update / uninstall.
• Traffic Monitoring and Alerts: Provides detailed client-side traffic metrics for server bandwidth throughput and image pull operations, along with threshold-based monitoring and alerting.
• Registry Management: Each registry has independent configuration management, enabling online management of image proxies (registries) and service settings without the need to manually edit configuration files.
• IP Access Control: IP blacklists and whitelists to control who can pull images from this service. Supports both individual IPs and CIDR blocks.

📦 Deployment

Docker Deployment

Download docker-compose.yaml and run:

docker compose up -d

One-click deployment script

The repository includes install/DockerProxy_Install.sh, an interactive menu that completes "install dependencies → start Docker image acceleration → (optional) render Nginx/Caddy reverse proxy" in one click.

# CentOS && RHEL && Rocky
yum -y install curl
# ubuntu && debian
apt -y install curl

# Overseas environment
bash -c "$(curl -fsSL https://raw.githubusercontent.com/dqzboy/Docker-Proxy/main/install/DockerProxy_Install.sh)"

# Domestic environment (CDN acceleration)
bash -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/dqzboy/Docker-Proxy/install/DockerProxy_Install.sh)"

# Domestic GitHub proxy
bash -c "$(curl -fsSL https://ghp.ci/https://raw.githubusercontent.com/dqzboy/Docker-Proxy/main/install/DockerProxy_Install.sh)"

The script automatically: checks and installs Docker / Docker Compose; generates a random GO_PROXY_ADMIN_TOKEN and writes it to .env; optionally deploys Nginx / Caddy reverse proxy.

After deployment, visit http://<server-IP>:30080/admin to manage proxies and server parameters from the web UI.

Config persistence & upgrades (Important)

The config file is mounted on the host at ./config/go-proxy/ (inside the container: /app/config.d/config.yaml).

• On first start, if the host does not yet have a config file, the container automatically initializes one from the built-in default config — no manual creation needed.
• To restore the default config: delete ./config/go-proxy/config.yaml and recreate the container to re-seed.

---

💻 Hubcmd-UI

Default account: root / admin@123 Please change the default account and password promptly after deployment.

Image Acceleration	Image Search
Registry Management	Registry Configuration
System Dashboard	Traffic Monitoring
Access Control	Network Testing

---

🛠 Local Development

For developers participating in secondary development, debugging, or building images locally. The two sub-projects (go-proxy/ and hubcmdui/) are independent and can be run separately.

go-proxy (Go backend)

Prerequisite: Go ≥ 1.23 (explicitly required in go-proxy/go.mod as 1.23.0)

cd go-proxy
# Method A: Auto-discovers config.local.yaml > config.yaml > config.example.yaml in the current directory
go run .
# Method B: Pass an explicit config file
go run . ./config.local.yaml

After startup:

Port	Purpose	Exposure
:5000	OCI Registry reverse proxy (/v2/ main entry)	Public / behind reverse proxy
:5001	Admin API (/-/healthz, /-/config, /-/reload, /-/stats, /-/credentials)	Internal only

⚠️ About GO_PROXY_ADMIN_TOKEN: The admin API uses independent admin token authentication with strict startup validation — placeholder tokens (change-me / admin / empty string, etc.) or length < 16 will directly refuse to start. For local development, at minimum set a 16+ character random value:

export GO_PROXY_ADMIN_TOKEN="$(openssl rand -hex 16)"

hubcmdui (Web UI)

Prerequisite: Node.js ≥ 18 (20 LTS recommended)

cd hubcmdui
npm install
# Start dev server
npm run dev

Service listens on :3000 by default; admin entry at http://localhost:3000/admin; default account root / admin@123 (Password change reminder on the first login pop-up)

---

💌 Promotion

CloudCone Flexible pay-as-you-go cloud servers	DediOne Fast and reliable web hosting services	DediRock Cost-effective VPS across multiple U.S. data centers
RackNerd Overseas VPS for websites and Docker services

---

Promotion Partnerships
We only accept reputable providers with stable, long-term operations
Telegram · [email protected]

---

🤝 Contributing

Thanks to everyone who has contributed!

❤ Acknowledgements

Thanks to the following projects for their open-source contributions:

The project references the registry proxy design ideas of CNCF Distribution.

License

Docker-Proxy is available under the Apache 2 license

---

Star History