在Jenkins里构建镜像成功，但推送到Harbor时失败，错误信息往往直接指向认证或权限，但也可能藏在镜像命名这类细节里。先别急着改Jenkins配置，我会按下面的顺序确认现象边界。
先确认现象边界
打开Jenkins任务的控制台输出，找到docker push那一段，看返回的状态码和消息。常见的几种：401 unauthorized表示认证失败；403 denied表示权限不足；Name invalid或repository name does not match则与镜像名或tag有关。同时确认执行节点是否真的连得上Harbor，用curl或telnet测一下Harbor的仓库端口，避免把网络问题误判成认证问题。
这一步的验证方式很直接：在Jenkins节点上手动执行一次docker login和docker push，如果手动操作正常，问题基本就在Jenkins侧的配置；如果手动也失败，问题在Harbor侧或镜像本身。
认证配置是首个排查点
推送失败时，首先应排查Jenkins中配置的Harbor凭据是否正确。常见错误是密码中包含特殊字符但未做转义，或者在凭据管理中选择了错误的类型。建议在Jenkins的凭据管理中新建一个用户名密码类型的凭据，并在推送命令中显式引用该凭据的ID，避免直接在脚本中硬编码密码。此外，Harbor如果开启了LDAP或OIDC认证，凭据可能不再适用，需要确认使用的账号是否具备推送权限。可以通过在Jenkins执行节点上手动执行docker login命令，输入相同账号密码，验证凭据本身是否有效。
手动登录这一步很重要。在节点上执行docker login的时候，注意观察有没有提示“WARNING: Using --password via the CLI is insecure”，如果脚本里用了-docker.password，建议改用凭据管理或docker login的--password-stdin。另外，如果Harbor开启了LDAP/OIDC，但Jenkins里用的是本地用户，也会出现认证失败。需要结合Harbor的认证模式确认该账号的有效性。登录成功后，再执行docker push，如果仍然失败，就进入下一步。
项目权限与配额问题
即使登录成功，推送镜像时仍可能因项目权限不足而失败。Harbor中的项目分为公开和私有，用户必须拥有对应项目的推送权限。在Harbor控制台中，进入项目成员管理，查看当前账号的角色是否为开发者或更高权限，项目管理员才能推送镜像。如果使用机器人账号，需确认该账号已被添加至目标项目并授予推送权限。另外，Harbor的复制规则或配额限制也会导致推送被拒，检查项目存储配额是否已用满，以及是否存在阻止推送的保留规则。
这里容易误判的一点是，登录用的账号可能属于多个项目，但在目标项目下没有成员角色。Harbor的角色是项目级别的，不是全局的。确认角色后，还要看一眼项目的配额使用情况。如果项目配额已满，push会提示“quota exceeded”，需要清理旧镜像或者扩大配额。保留规则（Retention Policy）也可能在后台删除或阻止某些tag的推送，检查是否有针对该项目的保留规则。
镜像命名与tag的细节
镜像推送失败还可能源于镜像名或tag不符合Harbor的仓库命名规范。Harbor要求镜像名只能包含小写字母、数字以及短横线、下划线、点号等字符，且仓库名中不能出现连续的斜杠。构建时如果镜像名带有大写字母，推送时会被Harbor拒绝。通常建议在Jenkins脚本中将镜像tag设置为构建号或Git提交ID，例如${BUILD_NUMBER}，并确保target路径为harbor.example.com/project/image:tag。若镜像tag中包含特殊字符如冒号以外的内容，也可能导致解析异常，建议先手动docker tag并推送验证。
在实际排查中，很多错误消息不会直接说大小写问题，而是显示“Name is invalid”或“repository name component must match ...”。可以先在本地执行docker images查看镜像名，手动docker tag成一个合规的名字再推送。例如：
docker tag myApp:latest harbor.example.com/dev/myapp:${BUILD_NUMBER}
docker push harbor.example.com/dev/myapp:${BUILD_NUMBER}如果手动推送成功，那就把镜像名和tag的生成逻辑写进Jenkinsfile，确保在构建阶段就使用小写和不含特殊字符的tag。
执行环境与插件配置
如果上面三步都查过，还要看Jenkins执行环境本身。使用CloudBees Docker Build and Publish插件时，需要检查Registry URL填的是不是Harbor地址，以及凭据是否绑定到了该插件。用自由风格Job执行docker push时，确认执行节点上Docker CLI可用，并且当前用户有权限执行docker命令。多节点环境下，每个节点都需要单独登录，否则会出现部分节点成功、部分失败的情况。
一个容易忽视的坑是DOCKER_CONFIG环境变量。Jenkins工作空间或系统配置里如果改了DOCKER_CONFIG，docker login生成的config.json会写到别的目录，导致push时找不到认证信息。建议在Jenkinsfile里显式指定一个固定的配置目录，例如：
DOCKER_CONFIG="${WORKSPACE}/.docker"
docker login --username ... --password-stdin harbor.example.com这里要注意，不要把密码写在命令行里，用--password-stdin从文件或环境变量读取。
建议的处理顺序与验证方法
按经验，推荐的排查顺序是：先手动登录验证凭据，再检查Harbor项目成员角色和配额，然后检查镜像名和tag，最后看执行节点Docker配置。每一步都有明确的验证动作：手动登录成功、角色显示为开发者或以上、镜像名全小写、docker push成功。
- 在Jenkins执行节点手动执行docker login，确认凭据有效。
- 在Harbor控制台检查目标项目成员列表和配额。
- 手动docker tag并推送一个合规的镜像名，排除命名问题。
- 检查DOCKER_CONFIG和插件配置，必要时在脚本中显式设置。
做完这些，通常能定位到具体原因。如果仍然失败，就要去看Harbor的日志，例如通过docker logs harbor-core查看拒绝请求的原因，但这一步需要你具备Harbor服务端的访问权限。
在处理过程中，不要一上来就重试十几次。先做一次最小化验证，也就是手动推送一个已知合规的镜像，能成功再回Jenkins调整。回滚也比较容易：如果改了Jenkins脚本，回退到上一个版本即可；如果改了Harbor项目权限，记得恢复原角色。后续维护上，建议在Jenkins中统一使用凭据ID，不要硬编码密码，并定期检查Harbor的配额和保留策略，避免镜像增长把空间占满。