v1.2.0 - Production-ready Docker Hub mirror docs and secure deployment

Docker Image Proxy v1.2.0

这是一个面向生产使用的 Docker Hub pull-through cache 发布版本，目标是帮助国内 Docker 服务器和 Kubernetes 节点更稳定地拉取 Docker Hub 镜像，同时保留足够清晰的安全边界和运维路径。

这个项目适合谁

• 国内服务器拉取 Docker Hub 镜像慢、不稳定，想自建一个可控 mirror 的团队。
• Kubernetes 集群需要统一给 Docker CRI、containerd、k3s 或 RKE2 配置 Docker Hub 镜像加速。
• 希望用海外源站 + CDN 发布镜像加速入口，同时做好源站保护、WAF 放行和回源鉴权的人。
• 想要一个可以直接复制到 /data/docker-image-proxy/ 的 Docker Compose 部署包，而不是零散命令片段。

v1.2.0 重点变化

1. 生产文档完成拆分

原来的长篇方案已经拆分为可独立阅读的专题文档：

• docs/architecture.md：架构设计、适用边界和生产约束。
• docs/source-deployment.md：海外源站部署、入口模式和本机验证。
• docs/cdn-acceleration.md：CDN 选型、缓存、Range、Header 和上线验证。
• docs/security-hardening.md：源站安全组、WAF、回源鉴权、限流和密钥管理。
• docs/validation.md：源站、CDN、Docker、Kubernetes 端到端验证。

Docker Registry Mirror 自建方案（生产可用）.md 现在是方案入口和阅读路径，不再把所有内容塞到一个超长文档里。

2. Docker Hub 上游认证改为生产必填

部署包默认要求在 .env 中填写：

REGISTRY_PROXY_USERNAME=replace-with-dockerhub-username
REGISTRY_PROXY_PASSWORD=replace-with-dockerhub-access-token

安装脚本会在未填写 Docker Hub 用户名或 Access Token 时直接退出，避免服务以匿名回源方式悄悄上线后触发 Docker Hub 拉取限流。

3. CDN 和安全配置更完整

文档覆盖：

• 下载加速、全站加速、DCDN、CloudFront、Cloudflare 的选型建议。
• /v2/*/blobs/* 长缓存和 /v2/*/manifests/* 不缓存或短缓存策略。
• Range、If-Range、Accept、Authorization 等 Docker Registry 关键 Header。
• WAF/Bot 对 /v2/ 跳过 JS Challenge、验证码、浏览器校验的规则。
• 源站只允许 CDN 回源 IP，或使用回源 Header / Authenticated Origin Pulls 加固。

4. README 增加徽章和更清晰入口

README 顶部增加 release、stars、issues、registry、compose、Kubernetes、CDN 和 docs 徽章，方便新用户快速判断项目状态和能力范围。

当前固定镜像

registry:3.1.1@sha256:1be55279f18a2fe1a74edf2664cac61c1bea305b7b4642dab412e7affdcb3e33
nginx:1.30.3-alpine@sha256:0d3b80406a13a767339fbe2f41406d6c7da727ab89cf8fae399e81f780f814d1

快速开始

把 deploy/ 同步到服务器：

mkdir -p /data/docker-image-proxy
cd /data/docker-image-proxy
cp .env.example .env
sed -i "s/replace-with-64-hex-chars/$(openssl rand -hex 32)/" .env

编辑 .env，填写 Docker Hub 专用账号和 Access Token，然后启动：

chmod +x ./scripts/install-or-update.sh
./scripts/install-or-update.sh

默认只监听：

127.0.0.1:5000

生产发布给国内服务器时，请先配置 HTTPS/CDN 或受控直连入口，不要把未保护的 HTTP mirror 直接暴露公网。

重要安全提醒

• 本项目只代理 Docker Hub，不透明加速 registry.k8s.io、quay.io、ghcr.io 或私有仓库。
• Docker Hub token 建议使用专用低权限账号生成，不要使用个人主账号密码。
• 如果 Docker Hub 账号能访问私有镜像，必须先给 mirror 做访问控制。
• 公开文档只应使用模拟值，例如 203.0.113.10、mirror.example.com、replace-with-dockerhub-access-token。
• 不要提交真实 .env、服务器 IP、SSH 信息、Docker Hub token、回源密钥或证书私钥。

推荐阅读路径

1. README.md：先看仓库能力和快速部署。
2. docs/README.md：按目标选择文档。
3. docs/source-deployment.md：部署源站。
4. docs/cdn-acceleration.md + docs/security-hardening.md：配置 CDN 和安全。
5. docs/client-usage.md：配置 Docker/Kubernetes 客户端。
6. docs/validation.md：做真实拉取验证。

欢迎反馈

如果这个仓库帮你节省了搭建 Docker Hub mirror 的时间，欢迎 Star、提交 Issue 或 PR。也欢迎补充更多 CDN 厂商、更多 Kubernetes 发行版和真实生产验证经验，让它帮助更多人。

v1.1.0

docs: add access control and rate limiting guidance