概览

为 dockerd 提供的本地只读镜像仓库代理。它位于 dockerd 与用户选择的一个或多个 Registry v2 镜像源之间，补充 dockerd 内置镜像源机制所缺少的能力：

• 运行时管理。 无需重启 dockerd，即可添加、移除和禁用上游镜像源。
• 故障隔离。 无响应或故障镜像源只会消耗一次超时等待，随后熔断器将其移出候选列表，直到探测成功。
• 可选竞速。 通过对冲请求，使用最先返回有效响应的镜像源。
• 镜像层断点续传。 传输中断后，可从同一字节偏移量切换到另一个镜像源继续下载，摘要仍由 daemon 校验。
• 安全回退。 代理无法处理请求时，dockerd 会回退到官方仓库，因此代理不会让原本可用的镜像拉取变得不可用。

支持 dockerd 的两种镜像存储后端：containerd（hosts.toml）和传统 graphdriver（daemon.json，仅限 docker.io）。

Preview复制标题链接

本次预览中通过本项目耗时 508.0 秒， 直接使用镜像站耗时 740.3 秒：速度约为 1.46 倍，总耗时减少 31.4%。

直接使用镜像站 · 740.3 秒	通过 oci-mirror-proxy · 508.0 秒
asciinema 录制	asciinema 录制

GIF 为加速预览，原始录制保留真实时间。 录制说明提供了录制工具和背景信息。

项目状态复制标题链接

支持的功能：用于拉取的仓库 API、故障转移、熔断、对冲请求、blob 断点续传、令牌和 Basic 认证、管理套接字、配置重载，以及支持还原的 dockerd 配置管理。

暂不支持：推送、本地 blob 缓存、密钥链后端和指标导出。

环境要求复制标题链接

• 构建需要 Go 1.26 或更新版本。
• 支持本机 Linux Docker Engine 或 macOS/Windows Docker Desktop（Linux 容器模式）。对于 rootless dockerd，操作者需要确保其网络命名空间能够访问代理监听地址，详见运维指南。

安全注意事项复制标题链接

• 仓库 API 不提供认证，因此默认监听 127.0.0.1。将 listen 设为非回环地址会向网络暴露未经认证的镜像拉取接口。
• 凭据不会直接写入配置文件：密码使用 env:NAME 或 file:/path 等引用。日志和 %v 输出中的敏感信息会被脱敏。
• 客户端的 Authorization 请求头不会被转发到上游。
• 管理套接字通过文件权限保护：目录权限为 0700，套接字权限为 0600。
• 镜像配置以实际文件为准，不依赖安装状态。仅在有变更时备份并原子替换；revert 只移除目标代理条目，保留其他配置。

自动配置、生效及撤销参见自动配置 Docker。