Jenkins无法识别本地Docker Registry中的镜像，如何解决？

针对你遇到的Jenkins无法拉取本地Docker Registry镜像的问题，按以下步骤逐一排查：

1. 验证Jenkins节点能否手动拉取镜像 #

在运行Jenkins构建的节点（master或agent）上执行以下命令，确认镜像可正常访问：

docker pull localhost:5000/rocky-8:latest

如果命令失败，说明问题不在Jenkins配置，而是节点与Registry的连通性或镜像本身的问题：

• 检查Registry状态：用docker ps确认registry容器正在运行，再执行curl http://localhost:5000/v2/_catalog验证Registry能返回镜像列表，最后用curl http://localhost:5000/v2/rocky-8/tags/list确认latest标签的镜像确实存在。
• 若Jenkins是容器化部署：localhost:5000对Jenkins容器来说指向的是容器内部而非宿主机，此时需改用宿主机的局域网IP（例如192.168.1.100:5000），或者将Jenkins容器与Registry容器加入同一个Docker网络，用Registry容器名作为地址（例如registry:5000）。

2. 配置Docker允许访问不安全Registry #

本地Registry默认使用HTTP协议，Docker默认会拒绝从非HTTPS的非可信Registry拉取镜像。需在Jenkins节点的Docker配置中添加localhost:5000为不安全Registry：

• Linux节点：编辑/etc/docker/daemon.json（无则新建），添加：

  {
    "insecure-registries": ["localhost:5000"]
  }
  

• 重启Docker服务：systemctl restart docker
• 验证配置：执行docker info | grep Insecure，确认localhost:5000出现在不安全Registry列表中。

3. 检查Jenkins Docker Agent基础配置 #

如果使用Jenkins Docker插件，需确保：

• Jenkins节点的Docker客户端能正常连接Docker daemon：执行docker ps验证是否能获取容器列表。
• Jenkins全局配置中，Docker服务器URL设置正确（通常为unix:///var/run/docker.sock），且运行Jenkins的用户有访问Docker socket的权限。

4. 排查并行阶段的Agent网络问题 #

你的并行阶段使用agent { docker { ... } }会让Jenkins启动新Docker容器作为阶段专属agent，需确认：

• 新容器所在网络能访问Registry：若Registry在宿主机，容器默认使用bridge网络，此时不能用localhost，必须用宿主机IP访问Registry。

临时测试方案 #

可在Check Docker阶段添加拉取镜像的命令，提前验证连通性，缩小问题范围：

stage('Check Docker') {
    steps {
        echo 'Checking if Docker exists...'
        sh 'docker --version'
        sh 'docker pull localhost:5000/rocky-8:latest'
    }
}

如果此阶段失败，可直接定位到节点的Docker与Registry的连通问题，而非后续阶段的配置问题。

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