What it is

一个轻量的 Registry 加速代理

只做一件事：把拉取请求转发给对应的上游仓库，不囤镜像，也不管容器。

定位	多上游 Docker Registry 加速代理，自己的服务器、自己的域名
缓存	不缓存镜像层，流式转发；磁盘里只有 SQLite 元数据（拉取记录）
入口	一个域名：Docker Hub 走 `registry-mirrors`，其他上游用路径前缀
管理	内置统计网页；没有 Docker socket，也没有容器管理
技术	Go 编写，Docker Compose 部署，MIT 开源

Features

轻、省心、看得见

流式转发，零层缓存

镜像层边下边转，不落盘，不必为缓存预留磁盘空间。

一个域名，多个上游

Docker Hub 通过 registry-mirrors 保持原镜像名；ghcr.io、quay.io 等在域名后加路径前缀。

九类上游开箱即用

Docker Hub、GHCR、Quay、GCR、registry.k8s.io、MCR、NVCR、Elastic、公共 ECR，可以关闭，也能自己加。

拉取统计控制台

分析看板、上游仓库分析、镜像列表和事件记录，支持亮色与暗色主题。

上游凭据可选

默认匿名拉取公开镜像；填上各上游的用户名和令牌，就能拉私有镜像，或避开 Docker Hub 的限流。

客户端登录鉴权

可以开启 pull_auth，只有 docker login 过本代理的客户端才能拉取，避免被陌生人蹭用。

数据面与管理面分离

数据面默认只监听 127.0.0.1:5000，由 TLS 反代对外发布；管理面 :5001 默认不对公网开放。

不碰 Docker socket

不挂载 docker.sock，也不管理任何容器，权限边界一目了然。

免费开源

以 MIT 协议开源，中英文 README、安装指南和排障文档都在 GitHub 上。

Upstreams

支持的上游仓库

在域名后面加上对应的路径前缀，代理会据此选择上游，并在转发前去掉前缀。

上游	路径前缀	拉取示例
Docker Hub	`docker.io`，另可用 mirrors（无前缀）	`docker pull nginx`
GHCR	`ghcr.io`	`docker pull reg.example.com/ghcr.io/owner/app:tag`
Quay.io	`quay.io`	`docker pull reg.example.com/quay.io/org/img:tag`
GCR	`gcr.io`	`docker pull reg.example.com/gcr.io/project/img:tag`
Kubernetes	`registry.k8s.io`、`k8s.gcr.io`	`docker pull reg.example.com/registry.k8s.io/pause:3.9`
Microsoft MCR	`mcr.microsoft.com`	`docker pull reg.example.com/mcr.microsoft.com/...`
NVIDIA NGC	`nvcr.io`	`docker pull reg.example.com/nvcr.io/...`
Elastic	`docker.elastic.co`	`docker pull reg.example.com/docker.elastic.co/...`
AWS 公共 ECR	`public.ecr.aws`	`docker pull reg.example.com/public.ecr.aws/...`

说明：表中的 reg.example.com 只是示例，请换成你自己的域名。上游默认匿名拉取；需要私有镜像或想避开限流时，在 .env 里填对应的用户名和令牌。不需要的上游把 enabled 设为 false 即可关闭。

How it works

三步用起来

部署代理

克隆仓库，填好环境变量，一条 Docker Compose 命令启动。

配域名和 HTTPS

域名解析到代理机，用 Caddy 或 Nginx 反代到 127.0.0.1:5000，再把同一个域名写进 config.yaml。

改客户端配置

Docker Hub 在 daemon.json 里加一行 mirror；其他仓库在镜像名前加你的域名。

Client usage

客户端怎么用

下面的 reg.example.com 都换成你自己的域名。

Docker Hub：registry-mirrors

镜像名完全不用改。把下面的 JSON 写进 /etc/docker/daemon.json：

{
  "registry-mirrors": ["https://reg.example.com"]
}

systemctl restart docker   # Linux
docker pull nginx:alpine

如果入口是纯 HTTP，还需要把它加进 insecure-registries。

其他上游：路径前缀

在同一个域名后面加上上游的前缀：

docker pull reg.example.com/ghcr.io/owner/app:tag
docker pull reg.example.com/quay.io/prometheus/prometheus:latest
docker pull reg.example.com/registry.k8s.io/pause:3.9

代理按前缀选择上游，并在请求真实仓库前去掉前缀。

不要用 /etc/hosts 把 ghcr.io 这类官方域名劫持到代理上，证书对不上会导致 TLS 失败。

Deploy

快速部署

需要 64 位 Linux 主机（或本机 Docker Desktop）、Docker 与 Docker Compose v2，以及能访问上游仓库的出站 HTTPS。

获取代码

克隆仓库并进入目录，后面的命令都在这个目录里执行。
```
git clone https://github.com/AlexWuYh/easy-docker-proxy.git
cd easy-docker-proxy
```

准备环境变量

复制模板，再生成随机的管理令牌和统计页密码写入 .env。统计页账号默认是 admin，密码就是 PROXY_WEB_PASSWORD。

cp .env.example .env

# 生成随机的管理令牌和统计页密码
EDP_ADMIN_TOKEN="$(openssl rand -hex 32)"
EDP_WEB_PASSWORD="$(openssl rand -base64 24 | tr -d '\n')"

# 写入 .env
sed -i.bak -e "s|^PROXY_ADMIN_TOKEN=.*|PROXY_ADMIN_TOKEN=$EDP_ADMIN_TOKEN|" \
  -e "s|^PROXY_WEB_PASSWORD=.*|PROXY_WEB_PASSWORD=$EDP_WEB_PASSWORD|" .env
rm -f .env.bak

# 清掉当前终端里的明文变量
unset EDP_ADMIN_TOKEN EDP_WEB_PASSWORD

填入你的域名

复制业务配置，再把 dockerhub 的 hosts 改成你自己的域名（不要带 https://）。

cp configs/config.docker.yaml configs/config.yaml

registries:
  - name: dockerhub
    hosts:
      - "reg.example.com"   # ← 换成你的真实域名
    path_prefixes:
      - "docker.io"

启动

在仓库根目录执行，第一次会先构建镜像。

docker compose --env-file .env -f deploy/docker-compose.yaml up -d --build

数据面	默认只在主机 `127.0.0.1:5000` 监听，通过 TLS 反代对外发布
管理面	`:5001`，默认不对公网开放
HTTPS	推荐用已有的 Caddy 反代到 `127.0.0.1:5000`
统计页	把 `127.0.0.1:5001` 映射出来，打开 `/stats/login.html`

域名要自己准备：文档里的 reg.example.com 只是示例。先注册域名，把 A / AAAA（或 CNAME）解析到代理机，再把真实域名写进 Caddy / Nginx 和 config.yaml 的 hosts。解析生效前，客户端会拉取失败。

完整的安装、配置和排障说明见安装与配置指南、排障文档。

Screenshots

统计控制台

谁在拉、拉了什么、哪个上游出错，一个网页看清。截图为演示数据，点击可看大图。

easy-docker-proxyEDP