安装

无需克隆仓库，即可安装最新发布版本：

curl -fsSL https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.sh | sh -s -- --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
oci-mirror-proxy version

更新已有安装：

curl -fsSL https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.sh | sh -s -- update --prefix "$HOME/.local"

在 Linux 上，以 root 权限运行安装脚本。脚本会启动代理、设置开机自启并自动接入本机 Docker，无需额外配置：

curl -fsSL https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.sh | sudo sh -s -- --service
# 更新系统安装并重启服务：
curl -fsSL https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.sh | sudo sh -s -- update --prefix /usr/local --service

脚本会下载对应的 Linux、macOS 或 FreeBSD 二进制文件，并校验 SHA256。当没有匹配的二进制文件，或指定了 --build 时，会使用 Go 1.26.8 或更新版本（也可通过 Go 工具链自动下载）构建发布源码。使用 --version v1.0.1 可选择指定版本。

预编译程序支持以下平台：Linux 支持 amd64、arm64、armv7、riscv64；macOS、FreeBSD 和 Windows 支持 amd64、arm64。Windows 使用 .zip，其他系统使用 .tar.gz。

Windows 用户可下载并检查 PowerShell 安装脚本后，在 PowerShell 中执行，需要时确认 Windows 管理员授权提示：

Invoke-WebRequest https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.ps1 -OutFile install.ps1
.\install.ps1
# 更新安装并重启服务：
.\install.ps1 update

安装器会启动 Windows 后台服务、设置开机自启、自动接入 Docker Desktop 并加入 PATH，无需额外配置 Docker。 打开新终端后即可直接运行 oci-mirror-proxy；更新会保留已有配置。需要 .NET Framework 4.x。

故障排查与服务管理见运维指南。 其他安装选项可运行 Get-Help .\install.ps1 -Full 查看。

--service 选项支持 Linux 的 systemd/OpenRC 和 macOS 的 launchd 系统服务。 不带 --service 的 sudo 安装会以经过验证的原用户身份初始化用户配置。 服务管理与历史权限问题的修复参见 macOS 安装指南。

如需使用下载镜像，将 DOWNLOAD_BASE_URL 设为镜像仓库根 URL（需保持相同的 /releases 和 /archive 布局）。通过管道执行脚本时，应将变量传给 sh，而不只是传给 curl：

curl -fsSL https://git.zmide.com/bin/oci-mirror-proxy/raw/branch/master/install.sh | DOWNLOAD_BASE_URL=https://mirror.example.com/bin/oci-mirror-proxy sh -s -- --prefix "$HOME/.local"

默认安装目录为 /usr/local，需要写入权限。现有配置会保留；不使用 --service 时，不会安装或重启服务。不带 --service 更新后，需要手动重启正在运行的代理。

更新与卸载复制标题链接

sh install.sh update --prefix "$HOME/.local"
sudo sh install.sh update --prefix /usr/local --service
sh install.sh uninstall --prefix "$HOME/.local"
sudo sh install.sh uninstall --prefix /usr/local

.\install.ps1 update
.\install.ps1 uninstall

更新会保留已有配置。如果自动接入 Docker 未能完成，脚本会保留已安装的代理并给出恢复提示。 Docker 不会自动重启；如需重启，请按脚本输出操作。

支持 Windows PowerShell 5.1 和 PowerShell 7。Registry 兼容性警告本身不表示安装失败： Docker Desktop 的镜像加速设置仅支持 Docker Hub，因此可能跳过其他 registry。 提示等待重启表示配置已保存但尚未生效；安装器不会自动重启 Docker 或中断运行中的容器。

卸载服务前会先从当前 Docker 用户的配置中移除本代理，保留其他镜像源和设置；清理失败则中止卸载。 如需明确保留 Docker 设置，使用 Windows 的 -SkipDocker 或 Unix 的 --skip-docker。 代理配置、缓存和日志会保留。仅卸载二进制时不会修改 Docker 设置。 手动恢复方法见运维指南。

更多选项见 sh install.sh --help 或 Get-Help .\install.ps1 -Full。

Docker 部署复制标题链接

Docker Engine 和 macOS Docker Desktop 用户可通过 docker-compose.yaml 部署。准备好可写的 配置目录后，执行 docker compose up -d --no-build。镜像支持 amd64/arm64，默认 采用 bridge 网络并仅向主机回环地址发布端口，无需挂载 Docker socket。配置初始化、本地构建、 宿主机 dockerd 接入方法见 Docker 部署指南。

从源码构建复制标题链接

make build                                   # 生成 dist/oci-mirror-proxy

dist/oci-mirror-proxy init                    # 写入用户配置文件
dist/oci-mirror-proxy serve &                 # 在后台运行代理

dist/oci-mirror-proxy upstream add \
  --id mirror-a --url https://mirror-a.example.com

sudo dist/oci-mirror-proxy dockerd plan       # 预览变更，不写入任何文件
sudo dist/oci-mirror-proxy dockerd apply      # 写入 dockerd 配置
dist/oci-mirror-proxy doctor                  # 检查代理、dockerd 和配置

examples/config.example.yaml 提供了完整配置及各选项说明；中文字段说明见配置参考。