Jenkins使用Docker Hub私有镜像作为代理模板构建Pending问题排查

问题定位 #

这种情况大概率是Jenkins侧的配置问题，而非Docker Hub的问题——因为公有镜像能正常使用、本地可拉取运行私有镜像，说明Docker Hub的仓库和镜像本身是正常的，问题出在Jenkins的认证传递、镜像配置或标签匹配环节。

排查步骤 #

• 验证Docker云的凭据关联有效性
  进入「管理Jenkins」→「管理节点和云」→「配置云」，找到对应Docker云配置：

  • 确认「Docker Registry认证」已选择正确的用户名/密码凭据，且该凭据的账号拥有目标私有镜像的拉取权限
  • 点击凭据旁的「测试连接」，确认能成功连接Docker Hub

• 核对Agent模板的镜像名称准确性
  确保Agent模板中填写的镜像名完全匹配私有镜像的完整路径（例如your-dockerhub-username/private-image:latest），不能遗漏用户名/组织名部分，和本地拉取时使用的镜像名保持一致

• 查看Jenkins日志定位具体错误
  进入「管理Jenkins」→「系统日志」，或直接查看Jenkins主节点的日志文件（通常路径为/var/log/jenkins/jenkins.log），搜索docker pull、authentication、label等关键词，排查是否存在拉取镜像时的认证失败、权限不足等报错

• 在Jenkins节点上手动测试镜像拉取
  登录Jenkins主节点（或负责运行Docker Agent的节点），用Jenkins配置中相同的Docker Hub账号执行docker login，然后尝试拉取目标私有镜像：

  • 若拉取失败，检查节点网络是否能访问Docker Hub，或账号是否有镜像拉取权限
  • 若拉取成功，说明Jenkins的凭据配置未生效，需确认凭据类型为「用户名和密码」，而非其他类型

• 确认标签表达式与Agent模板标签完全匹配
  自由风格项目中的「标签表达式」必须和Docker Agent模板设置的「标签」完全一致，包括大小写、拼写，避免因标签不匹配导致Jenkins找不到可用Agent

• 检查Docker插件版本兼容性
  旧版本Docker插件可能存在私有仓库认证的bug，进入「管理Jenkins」→「插件管理」，检查Docker Plugin、Docker Pipeline Plugin等相关插件是否为最新版本，更新后重新配置测试

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