Docker Registry无法绑定主机IP:5000 跨主机推送镜像报错

算力阿峰

2026-8-29

问题原因

两个报错均由http.addr配置与Docker容器网络机制不匹配导致：

配置为localhost:5000时，Registry进程仅在容器内部的回环网卡上监听端口，该地址仅容器内部可访问，即使配置了-p 5000:5000端口映射，宿主机、外部局域网主机的流量也无法转发到容器内的监听服务，因此外部推送时触发连接失败报错。
配置为192.168.1.149:5000时，该IP属于宿主机的局域网网卡地址，并非容器内部持有的网卡IP，Registry启动时尝试绑定不存在的地址，直接触发地址分配失败的致命错误。

另外原启动命令存在重复挂载风险：先将宿主机/etc/docker/registry目录整体挂载到容器同路径，后续又单独挂载当前目录下的config.yml到容器内配置文件路径，若两个位置的配置文件版本不一致，很容易出现配置覆盖、实际加载配置不符合预期的问题。

解决步骤

修改config.yml中的监听地址配置，让Registry监听容器内所有网卡的5000端口，其余原有配置（TLS、存储、日志等）保持不变即可：

http:
  addr: 0.0.0.0:5000
  tls:
    certificate: /etc/docker/registry/server-cert.pem
    key: /etc/docker/registry/server-key.pem
  headers:
    X-Content-Type-Options: [nosniff]
  http2:
    disabled: false

清理旧的异常容器，重新启动Registry：

# 删除原有错误配置的容器
sudo docker rm -f registry

# 启动新容器，注意确认config.yml的本地路径正确，避免重复挂载导致的配置覆盖
sudo docker run -d -p 5000:5000 --restart=always --name registry \
  -v /etc/docker/registry:/etc/docker/registry \
  -v /path/to/your/modified/config.yml:/etc/docker/registry/config.yml \
  registry:2

可用性验证

在Registry所在宿主机执行curl https://127.0.0.1:5000/v2/，返回空JSON对象{}即代表容器内服务启动正常。
在推送端主机执行curl https://192.168.1.149:5000/v2/，同样返回{}即可正常执行镜像推送命令。

注：若使用自签名证书，需提前在推送端Docker的证书目录/etc/docker/certs.d/192.168.1.149:5000/下放置对应CA证书，重启Docker后生效，已按官方文档完成证书配置可跳过该检查。

内容的提问来源于stack exchange，提问作者Chris Moran