Self-hosted Docker registry relay cache with on-demand pull-through, whitelist, 2FA, and web UI
1.2K
自托管 Docker 镜像中继缓存。部署在能访问 Docker Hub 等上游的服务器上，按需拉取并缓存镜像，让无法直接访问上游的服务器也能正常拉取。
Docker daemon 对非 localhost 的 registry 强制要求 HTTPS。直接使用 http://IP:5000 拉取会报错：
Error response from daemon: http: server gave HTTP response to HTTPS client
因此必须通过 Nginx 反向代理配置 HTTPS 才能正常使用。你需要：
mr.example.com）解析到中继服务器Nginx 配置示例：
server {
listen 443 ssl;
server_name mr.example.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
# Docker registry 不兼容 gzip
gzip off;
# 大镜像层传输超时放宽
proxy_read_timeout 300s;
proxy_send_timeout 300s;
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
server {
listen 80;
server_name mr.example.com;
return 301 https://$host$request_uri;
}
配置完成后，拉取端使用 https://mr.example.com 作为镜像地址。
如果仅在本机使用（
127.0.0.1），可以直接用 HTTP，无需 HTTPS。
国内服务器 中继服务器（部署 mirror-relay）
┌──────────┐ ┌──────────────────────────┐
│ docker │ pull mr.example.com/nginx │ Nginx (:5000) │
│ daemon │ ──────────────────────────→│ ├── / → Docker Hub │
│ │ │ ├── /ghcr/ → ghcr.io │
│ │ ←──────────────────────────│ └── /gcr/ → gcr.io │
└──────────┘ │ │
│ Web UI (:8080) │
│ Cache Manager (sidecar) │
└──────────────────────────┘
docker run -d \
--name mirror-relay \
--restart always \
-p 5000:5000 \
-p 8080:8080 \
-v ./data:/data \
ywsj/mirror-relay:latest
启动后打开 http://<你的服务器>:8080，首次会生成随机密码，在服务器上执行以下命令获取：
docker exec mirror-relay cat /data/.initial_password
登录后请立即在「设置」页面修改密码。
按照上方「重要：必须配置 HTTPS 反向代理」章节配置 Nginx + SSL 证书。
方式一：Docker Hub 镜像加速（推荐）
// /etc/docker/daemon.json
{
"registry-mirrors": ["https://mr.example.com"]
}
sudo systemctl restart docker
docker pull nginx:latest # 自动通过中继拉取
方式二：多上游显式拉取
# Docker Hub 镜像
docker pull mr.example.com/library/nginx:latest
docker pull mr.example.com/username/repo:tag
# ghcr.io 镜像
docker pull mr.example.com/ghcr/owner/repo:tag
# gcr.io 镜像
docker pull mr.example.com/gcr/namespace/repo:tag
| 功能 | 说明 |
|---|---|
| 多上游代理 | Docker Hub、ghcr.io、gcr.io，可在 Web 界面添加更多 |
| 按需缓存 | 只在被请求时拉取，不主动同步 |
| 自动清理 | 磁盘超阈值时 LRU 清理 + Registry GC |
| 白名单 | IP/CIDR 级别访问控制，Web 界面动态管理 |
| 2FA 验证 | TOTP 两步验证，防止密码泄露 |
| 暴力破解防护 | 同一 IP 连续 5 次密码错误自动锁定 |
| 管理面板 | 仪表盘、缓存列表、拉取日志、白名单管理、设置 |
| 手动 GC | 一键触发垃圾回收 |
| 缓存删除 | 支持删除指定缓存镜像 |
| 明暗主题 | 支持深色/浅色主题切换 |
| 页面 | 功能 |
|---|---|
| 仪表盘 | 服务状态、磁盘使用、拉取统计、命中率、各上游缓存大小 |
| 缓存列表 | 查看所有缓存镜像，支持搜索和按上游筛选 |
| 拉取日志 | 最近 100 条拉取记录，命中/透传/拒绝状态，来源 IP |
| 白名单 | 开关白名单模式，增删 IP/CIDR，批量导入 |
| 设置 | 清理策略、上游管理、2FA 管理、修改密码 |
10.0.0.1）和网段（10.0.0.0/24）# 添加备注10.0.0.1 # 北京服务器
192.168.1.0/24 # 内网段
| 环境变量 | 默认值 | 说明 |
|---|---|---|
MAX_DISK_PCT | 80 | 磁盘使用率阈值（%），超过触发清理 |
TARGET_DISK_PCT | 70 | 清理后目标使用率（%） |
CLEANUP_INTERVAL | 300 | 清理检查间隔（秒） |
以上配置也可在 Web 界面「设置」页面在线修改。
services:
mirror-relay:
image: ywsj/mirror-relay:latest
container_name: mirror-relay
restart: always
ports:
- "5000:5000"
- "8080:8080"
volumes:
- ./data:/data
environment:
- MAX_DISK_PCT=80
- TARGET_DISK_PCT=70
- CLEANUP_INTERVAL=300
数据保存在当前目录的 data/ 目录下，方便备份和迁移。
| 端口 | 用途 |
|---|---|
| 5000 | 拉取端口（通过 Nginx HTTPS 反代暴露） |
| 8080 | 管理面板（浏览器访问） |
MIT
Content type
Image
Digest
sha256:08a7578a7…
Size
56.6 MB
Last updated
about 22 hours ago
docker pull ywsj/mirror-relay