年初帮团队搭建镜像交付链路时发现不少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_zhangexample.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。角色拉取推送编辑仓库信息管理成员Guest允许不允许不允许不允许Developer允许允许部分允许不允许Maintainer允许允许允许部分允许ProjectAdmin允许允许允许允许排查这类权限问题时我一般三步走先在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镜像地址的四段结构端口、项目名、仓库名和tagpush到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 ] }修改后重启dockersystemctl daemon-reload systemctl restart docker验证是否生效docker info | grep -A5 Insecure如果在输出里看到了registry.internal说明配置已经加载。但我要明确说一句这只适用于纯内网、低敏感度的实验环境。它意味着docker会允许对该地址使用HTTP也会跳过证书校验。一旦Harbor里存放的是正式环境配置、业务代码和敏感镜像建议别贪这个方便。生产环境一律走正规证书链。3.3 更推荐的自签证书方案让docker信任你的CAHarbor部署时通常会给自身生成自签CA然后由该CA签发Harbor域名的服务端证书。要让docker daemon信任它做法是把对应CA证书放到指定目录下/etc/docker/certs.d/registry.internal:443/ca.crt注意目录名必须与Harbor的域名和端口完全一致。之后重启dockersystemctl restart docker这时候即便不配置insecure-registriesdocker也能正常完成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.crtpodman则是读取/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配置并reloadclient_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时一层一层上传。每一层在物理上都是一个独立的blobdocker会先对层做校验、获取现状再决定是上传还是复用。之前已经存在于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/nginxsha256:0ea3b7e4316dba87822d2a549f8bc0be26009576d3841b7eff5cc68d这一步能确认整个内网分发链路的完整性也避免在环境间传递时用了错误tag。6.2 磁盘空间与GCtag删了不代表层被回收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的推送这件事可以稳定得异常安静。 
长河君 · 2026/10/21 5:20:09 · 阅读 1.2k 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_zhangexample.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。角色拉取推送编辑仓库信息管理成员Guest允许不允许不允许不允许Developer允许允许部分允许不允许Maintainer允许允许允许部分允许ProjectAdmin允许允许允许允许排查这类权限问题时我一般三步走先在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镜像地址的四段结构端口、项目名、仓库名和tagpush到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 ] }修改后重启dockersystemctl daemon-reload systemctl restart docker验证是否生效docker info | grep -A5 Insecure如果在输出里看到了registry.internal说明配置已经加载。但我要明确说一句这只适用于纯内网、低敏感度的实验环境。它意味着docker会允许对该地址使用HTTP也会跳过证书校验。一旦Harbor里存放的是正式环境配置、业务代码和敏感镜像建议别贪这个方便。生产环境一律走正规证书链。3.3 更推荐的自签证书方案让docker信任你的CAHarbor部署时通常会给自身生成自签CA然后由该CA签发Harbor域名的服务端证书。要让docker daemon信任它做法是把对应CA证书放到指定目录下/etc/docker/certs.d/registry.internal:443/ca.crt注意目录名必须与Harbor的域名和端口完全一致。之后重启dockersystemctl restart docker这时候即便不配置insecure-registriesdocker也能正常完成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.crtpodman则是读取/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配置并reloadclient_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时一层一层上传。每一层在物理上都是一个独立的blobdocker会先对层做校验、获取现状再决定是上传还是复用。之前已经存在于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/nginxsha256:0ea3b7e4316dba87822d2a549f8bc0be26009576d3841b7eff5cc68d这一步能确认整个内网分发链路的完整性也避免在环境间传递时用了错误tag。6.2 磁盘空间与GCtag删了不代表层被回收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的推送这件事可以稳定得异常安静。