Harbor镜像推送避坑指南：认证、tag命名与TLS信任全解析

年初帮团队搭建镜像交付链路时，发现不少DevOps同事在push镜像到Harbor私有仓库时都会来问同一类问题：本地构建明明一切正常，为什么push过去提示未认证；tag按Docker Hub的习惯随手一写，结果仓库里根本找不到；内网用自签证书的Harbor，客户端怎么配都报x509证书错误。这些问题看起来零散，但根子都在几个固定的关键点上。今天我就把自己在这两年里于内网Harbor环境推送镜像踩过的坑、以及最终沉淀成CI/CD流水线规范的一份可直接照做的检查清单整理出来，覆盖登录认证、tag命名、TLS信任、常见报错定位、大镜像处理以及推送后的验证清理。无论你是要自助搭一套私有镜像仓库的平台工程师，还是日常负责应用发版的开发、运维同学，这篇都能帮你在下一次push前少走几个来回。

1. 登录认证与账号权限：近一半的push失败其实都出在“没登录/没权限”

1.1 三种认证方式怎么选：个人密码、机器人账号与统一认证的取舍

很多人觉得push到Harbor不过就是执行一条docker push命令，等报错才想起来自己压根没登录。这背后的第一个关键点是：Harbor 在 push 流程里要校验的不仅是“你有账号”，还有“这个账号在目标项目里有没有 push 权限”。

日常手动操作，用个人账号密码登录最方便。管理员在Harbor Web界面创建用户后，你在客户端执行：

docker login registry.internal -u dev_zhang -p your_password

这种方式的优点是人机对应、审计日志清晰，出问题时能迅速定位到具体是谁操作的。但有个细节容易忽略：很多企业环境已经接入了企业统一身份系统，此时命令行登录时用户名可能要带域前缀，比如-u domain\dev_zhang或者-u dev_zhang@example.com，哪个格式取决于Harbor管理员当初对接系统时的配置。没用对格式，返回的依然是401。

如果是自动化流水线推送，最推荐的是Harbor 2.0之后的机器人账号。机器人账号可以精确限定在某个项目里，也可以单独赋予“只能推某几个仓库”或者“只能拉取”的最小权限，比在CI里明文存一个管理员密码安全得多。创建后在界面拿到一次性的token，注意这个token只在创建时完整展示一次，之后只能重新生成：

docker login registry.internal -u 'robot$ci-frontend' -p 'once_only_token_string'

机器人账号右侧那个过期时间也要盯一下，很多企业默认30天过期，到期后流水线就会毫无征兆地报401。我的做法是在团队日历里建一条周期性提醒，每月检查一遍所有机器人账号的有效期。

1.2 Harbor项目角色权限对照：Guest能拉不代表Developer能推

Harbor项目里默认有四个角色：Guest、Developer、Maintainer、ProjectAdmin。普通开发手动push至少要Developer，而只给了Guest权限的账号，拉取镜像没问题，一push就会收到 unauthorized 或 permission denied。

排查这类权限问题时，我一般三步走：先在Harbor界面确认账号属于哪个项目、什么角色；再确认目标镜像是否真的在这个项目下；最后确认登录的账号名没有拼写错误。这三步里最坑的是第三种：账号拼写错误时，Harbor不会提示“账号不存在”，而是直接给你一个401，容易让人误判成密码问题。

1.3 token有效期与docker login的作用范围

docker login成功后，凭证会写入~/.docker/config.json，但Harbor签发的访问token是有有效期的。Harbor对push这类操作请求会先拿basic认证换取短期token，再用token去访问Registry API。如果token过期，就会出现“登录过但push时依然401”。

遇到这种情况不用慌，重新执行一次docker login就行。平时排查时我习惯先跑一句：

docker logout registry.internal && docker login registry.internal

确保当前会话用的是最新凭证。另外要提醒的是，docker login认证的是那一台机器上的docker daemon配置，换一台机器、换一个CI Runner都得重新登录，这一条虽然基础，但在分布式构建环境里翻车频率极高。

2. tag命名与仓库地址结构：八成“找不到镜像”的误会是这里写错

2.1 Harbor镜像地址的四段结构：端口、项目名、仓库名和tag

push到Harbor的镜像地址，标准结构是：

<Harbor域名>:<端口>/<项目名>/<镜像名>:<tag>

比如：

docker tag nginx:1.25 registry.internal:443/team-frontend/nginx:1.25-live docker push registry.internal:443/team-frontend/nginx:1.25-live

这里的四段各司其职：最前面的域名和端口指向Harbor服务本身；紧随其后的team-frontend是Harbor里的项目，相当于一个命名空间分组；再往后的nginx才是镜像仓库名；冒号后面是tag。

大多数人第一次push失败，问题就出在“项目名”这一节。Harbor的地址里永远要有一个项目名，不可以直接写registry.internal:443/nginx:1.25。如果你这样写，Harbor会试图去找名为nginx的项目，找不到就返回401或404，很多人这时候还在拼命怀疑账号权限，其实根本就是地址格式不合法。

2.2 docker tag到底干了什么：它不产生新镜像，只是加引用

docker tag 并不会复制或者修改镜像，它只是在本地给同一个镜像加了一个新的引用名。也就是说：

docker tag nginx:1.25 registry.internal:443/team-frontend/nginx:1.25-live

执行完这条命令，本地并没有生成一份新的镜像数据，只是让 push 命令知道“该把哪个镜像推到哪里去”。理解了这一点，你就明白为什么推送前必须先用docker tag把名字补完整，而不是直接拿nginx:1.25去推。

有个相关的小技巧：如果嫌tag这一步麻烦，可以直接在构建时就指定完整地址：

docker build -t registry.internal:443/team-frontend/nginx:1.25-live .

这样构建产物直接就是带目标仓库地址的引用，后续 docker push 一步到位。在脚本尤其是CI流水线里，这条能让步骤少一个变量、少一处人为失误。

2.3 tag携带环境信息的坑：交付内容漂移是怎么发生的

不少团队习惯在tag里带上环境名，比如nginx:dev-latest、nginx:prod-latest。这个做法的初衷是区分不同环境的镜像，但实际使用中很容易造成交付内容漂移：dev环境push了一次，prod环境又从同一份代码构建了一次，两个latest内容很可能不一致，最后查问题的时候，谁都不敢确认线上跑的到底是哪次构建。

更稳妥的方式是让镜像内容与构建产物一一对应，用唯一的构建标识作为tag，例如Git提交SHA、流水线构建号：

registry.internal:443/team-frontend/nginx:git-7f3d9a2e registry.internal:443/team-frontend/nginx:build-20250601-1405

需要给人看的友好标签（比如latest或版本号）保留一份即可，但生产发布、回滚操作的依据，一律用唯一tag或者直接使用后面的digest值。这样整个交付链路里，镜像内容才能被准确追溯。

3. 网络与TLS信任：为什么本机push成功，服务器上却报x509错误

3.1 一次push请求背后的TLS握手：先过Harbor的网关层

docker在push到Harbor时，与Harbor之间要完成HTTPS/TLS握手。Harbor默认由nginx作为前置网关做TLS终结，后端的Registry服务才接受反向代理转来的请求。很多客户端报错，都发生在TLS握手这一步，而不是认证步骤。

比如你通过http://直接访问Harbor，或者给Harbor配置的是自签证书，而docker daemon默认要求安全连接，此时客户端就会拒绝通信或者报证书不可信。现象是：你在自己电脑上配置过相关证书就正常，换一台没配置过的服务器就失败，这是因为每一台机器都独立维护着自己的证书信任库和守护进程配置。

3.2 最简单但最不推荐的处理：insecure-registries

为了快速跑通流程，很多人会选择把Harbor地址加入Docker的insecure-registries列表。修改/etc/docker/daemon.json：

{ "insecure-registries": [ "registry.internal", "registry.internal:443" ] }

修改后重启docker：

systemctl daemon-reload systemctl restart docker

验证是否生效：

docker info | grep -A5 "Insecure"

如果在输出里看到了registry.internal，说明配置已经加载。

但我要明确说一句：这只适用于纯内网、低敏感度的实验环境。它意味着docker会允许对该地址使用HTTP，也会跳过证书校验。一旦Harbor里存放的是正式环境配置、业务代码和敏感镜像，建议别贪这个方便。生产环境一律走正规证书链。

3.3 更推荐的自签证书方案：让docker信任你的CA

Harbor部署时通常会给自身生成自签CA，然后由该CA签发Harbor域名的服务端证书。要让docker daemon信任它，做法是把对应CA证书放到指定目录下：

/etc/docker/certs.d/registry.internal:443/ca.crt

注意目录名必须与Harbor的域名和端口完全一致。之后重启docker：

systemctl restart docker

这时候即便不配置insecure-registries，docker也能正常完成TLS校验并push。这是内网环境里兼顾安全和易用性的通常做法，比完全跳过校验靠谱得多。

3.4 非docker客户端：containerd、podman、nerdctl的配置差异

如果你用的不是docker命令，而是Kubernetes集群底层用的containerd，或者podman、nerdctl，证书配置路径完全是另一套。

containerd从较新版本开始支持certs.d配置目录，例如/etc/containerd/certs.d/registry.internal:443/hosts.toml：

[host."https://registry.internal:443"] ca = "/etc/containerd/registry-ca.crt"

podman则是读取/etc/containers/registries.conf.d/下的配置：

[[registry]] location = "registry.internal:443" insecure = false

这里要特别注意：很多人改完containerd的配置文件没有重启节点上的containerd服务，或者忘改了certs.d却还在纠结为什么kubelet拉不了镜像。排查的顺序应该先确认客户端类型，再找到对应的配置文件，最后重启对应的守护进程。

4. 高频报错的定位链路：从401到413，每一类错误都对应一个具体诱因

4.1 401 Unauthorized / authentication required

报错信息形如：

denied: requested access to the resource is denied unauthorized: authentication required

碰到401，我的排查链表是：重新登录 → 确认账号密码 → 确认机器人账号是否过期 → 确认目标项目名是否存在。这里有个非常容易绕弯路的地方：如果你push到一个完全不存在的项目，Harbor也会返回401而不是404，它不会告诉你是“项目不存在”，而是粗略地认为“你没有访问这个资源的资格”。所以检查项目名拼写正确性，与检查登录凭证同等重要。

我见过的最典型翻车现场，是A同学把一个项目名首字母写成了大写，在Harbor界面上项目名是TeamFrontend，命令行里敲成teamfrontend，连续排查账号、密码、网络，最后才发现是大小写问题。Harbor的项目名是大小写敏感的。

4.2 403 Forbidden：权限不足与存储配额已满

403在Harbor push场景里主要有两种情况。

第一种是当前账号对目标项目没有Developer及以上的角色，只有Guest权限。这种去项目成员列表里加权限就行。

第二种是项目启用了存储配额，当项目空间已用完时，push会被拒绝。Harbor返回的报错往往会带有类似 403 或 507 的语义，界面上查看“项目 → 配额”就能看到具体使用量。排查这类问题，不要只盯着认证和权限，一定要顺手看下项目的配额使用曲线。

4.3 409 Conflict：镜像tag不可变规则触发

Harbor支持给项目设置“不可变tag”规则，比如对v.*的tag禁止覆盖。一旦push时命中了不可变规则，会返回类似：

409 conflict: immutable tag

这个机制本意是防止重要的线上tag被无意覆盖，比如保护v1.2.0这种发布tag。但很多团队配置时把规则写得太宽，把所有latest都设成了不可变，结果日常更新镜像时一push就报409。解法有三个：按实际需求收窄不可变规则的匹配范围；或者修改掉旧tag再重新push；又或者在明确确认需要覆盖时，先删除旧tag再push新tag。要注意，删除tag后镜像层并不一定立即被回收，但至少push语义上不再冲突。

4.4 413 Request Entity Too Large：前置nginx上传大小限制

Harbor的默认nginx其实允许非常大的请求体，但如果你在Harbor前面还有一层自建的反向代理、负载均衡接入层，这层nginx很可能用的还是默认的client_max_body_size 1m。基础镜像稍微大一点，push大层时就会收到413。

排查方法很直接：在报错时查看接入层nginx的error.log，看到client intended to send too large body基本就实锤了。修改对应nginx配置并reload：

client_max_body_size 1024m;

需要注意的是，Harbor自己的nginx同样也有这个参数。如果在Harbor的nginx日志里看到413，要去Harbor侧的nginx.conf中把它调大，而不仅仅是在前置层改。

4.5 x509错误：证书链路不完整或未重启守护进程

x509相关的报错常见两种。第一种是：

x509: certificate signed by unknown authority

含义是客户端不信任给Harbor签名的CA。按前面第3.3节的方法把CA安装到客户端，并重启docker守护进程即可。

第二种是：

x509: certificate is valid for xxx, not yyy

这通常是Harbor证书里没写全访问用的域名，或者访问时用了IP但证书只签了域名。确需用IP访问时，证书的Subject Alternative Name里要包含该IP地址，否则无论如何信任CA都没用。

5. 大镜像与并发推送：动不动卡住、超时，问题往往不在docker本身

5.1 分层上传的机制：为什么慢网络下大镜像推送特别痛苦

docker镜像由若干层组成，push时一层一层上传。每一层在物理上都是一个独立的blob，docker会先对层做校验、获取现状，再决定是上传还是复用。之前已经存在于Harbor的同内容层，会显示 “Layer already exists”，这部分可以跳过。真正要传的，只有Harbor上缺失的层。

理解了这一点，你就明白为什么换了一台机器构建同一个应用，push耗时比第一次还要久：因为新机器本地缓存里没有可复用的层，几乎所有层都需要完整传输。此时拿常见的docker push输出里看进度条卡在某一层迟迟不动，与其反复重试，不如确认网络带宽、观察Harbor端的CPU与磁盘IO。很多时候是存档盘IO扛不住，而不是docker本身出了问题。

5.2 流水线里的超时设置：给n层和blob上传留出足够余量

CI流水线里给 docker push 步骤设置超时，很多人按构建阶段同样时长来设，这是不对的。构建可能只花两分钟，但一个三GB镜像在低带宽内网推完可能需要十分钟甚至更久。我的建议是给push步骤单独留出比预期更宽裕的超时，至少按“blob总大小除以上行带宽再乘以1.5”来估算。

举一个实测过的例子：某系统镜像总大小2.8GB，内网上传带宽约30MB/s，理论上需要95秒左右。但实际因为分层校验、压缩格式转换、Harbor端存储写入的额外消耗，最终耗时超过三分钟。若当时流水线设置5分钟超时，会非常勉强。把push超时放宽到8分钟后，问题就再没出现过。

5.3 并发推多个镜像到同一个Harbor：控制节奏比一味加并行更有效

在平台化改造前，我们团队曾试过在流水线里并行推送多个微服务镜像到同一Harbor。并发量一上去，Harbor后端存储层和数据库压力立刻显现，表现为大量超时和部分manifest上传失败。原因不复杂：Harbor的元数据记录、blob指纹去重以及存储写入都需要时间，并发突增时这些环节的压力会线性放大。

后来我们的策略是：流水线内同一时间的镜像推送并发数控制在2到3个，并且错开大镜像的推送时机。这一改动牺牲了一点点流水线总时长，但换来的是推送成功率从95%出头提升到接近100%。如果你的团队同样因为并发推送而频繁失败，先试试降低并发数，而不是升级Harbor所在节点配置。

5.4 断网与重试：docker push的断点续传能力比想象中好

docker push在实现上本身支持对未完成的blob上传做校验，网络中断后重新执行同一个push，已经上传完成的层会被标记为已存在，不需要重新传输。这让“重试”变得很廉价。

但有一个前提：中断后不要删除Harbor中那个半成品项目数据，也不要手动在Harbor里去清理所谓“上传残留”。保留这些未完成的blob，重试时反而能加速。当然，等整个push真正成功后，Harbor的垃圾回收机制会负责把这些临时数据清理掉。

6. 推送完成后的验证与清理：别以为push完就结束了

6.1 用digest精确锁定交付产物

每次docker push成功后，末尾会输出一行类似：

digest: sha256:0ea3b7e4316dba87822d2a549f8bc0be26009576d3841b7eff5cc68d

这个sha256值是镜像manifest的摘要，哪怕tag被覆盖，只要digest不变，镜像内容就不会变。在发布、回滚、审计的场景里，记录和传递这个digest比记录tag更有说服力。

验证时可以在其他机器上直接按digest拉取：

docker pull registry.internal:443/team-frontend/nginx@sha256:0ea3b7e4316dba87822d2a549f8bc0be26009576d3841b7eff5cc68d

这一步能确认整个内网分发链路的完整性，也避免在环境间传递时用了错误tag。

6.2 磁盘空间与GC：tag删了不代表层被回收

Harbor的Web界面上“删除仓库”或“删除tag”实际是在元数据层面删除了引用。那些被删除tag所引用的镜像层，在Harbor执行GC之前仍然占据存储空间。这一点在日常维护中最容易被忽略，等磁盘报警时才发现Harbor数据目录已经膨胀到需要做大规模清尾。

Harbor的GC操作在“管理 → 垃圾清理”里执行。官方建议在GC期间将仓库置于只读模式，实际操作时意味着它会短暂影响pull和push，所以最好放在业务低峰期，并且提前和团队同步“当前不要推送”。如果直接手动删掉Harbor数据目录下的文件，会破坏blob索引关系，可能造成仓库不可用，这个方向千万不要碰。

6.3 定期轮换机器人账号与检查保留策略

Harbor的“保留策略”能按规则自动清理旧tag，比如只保留最近5个版本、按周或按月保留某批镜像。启用后，日常“镜像堆积导致空间慢慢吃紧”的问题能得到很大缓解。创建规则时我习惯先设置成“模拟运行”模式，观察一轮会不会误删需要保留的tag，确认无误后再正式启用定时执行。

另外，机器人账号的定期轮换这块，我的做法是把创建、过期与轮换记录全部纳入团队维护表，每月抽查一次过期token是否已清理干净。这样可以避免后续半年后，突然有旧流水线带着早已过期的token跑到半夜报401，然后大家还得花小半天时间翻日志找出是哪条流水线在调用。

在实际维护Harbor这套镜像交付链路的过程中，我最大的体会是：push报错里十之七八都能落到“登录凭证、tag写法、TLS配置、项目配额”这四类根因上。与其每次遇到报错临时看一篇帖子，不如把这套排查顺序固化到团队的文档和检查清单里。先把insecure-registries、自签证书、不可变tag这些容易反复踩的配置一次性处理干净，再把唯一tag和digest验证的习惯落地到每条流水线中，Harbor的推送这件事可以稳定得异常安静。