Harbor与容器镜像仓库生产运维
容器镜像仓库既是软件交付入口，也是生产依赖。Harbor页面能够登录、镜像可以推送，并不代表已经具备生产能力。真正的仓库运维包括身份权限、制品不可变、漏洞治理、容量回收、复制容灾、备份恢复、升级回滚和审计。
本文面向自建Harbor的运维与平台团队。不同Harbor版本、安装方式和存储后端存在差异，部署前应查看当前版本官方文档和升级说明。示例中的域名、账号和项目名均为占位符。
一、理解Harbor的数据边界
Harbor不是单一目录，至少包含：
| 组件或数据 | 作用 | 备份关注点 |
|---|---|---|
| Registry/对象存储 | 镜像层与OCI制品 | 数据量最大，需一致性和完整性 |
| PostgreSQL | 项目、用户、制品元数据、策略 | 必须与制品数据协调恢复 |
| Redis | 会话、缓存和任务状态 | 多数场景可重建，但会影响任务与登录 |
| Job Service | 复制、扫描、GC等任务 | 日志、任务状态和并发能力 |
| Core/Portal | API、认证和页面 | 配置、证书与外部依赖 |
| Trivy等扫描器 | 漏洞数据库和扫描任务 | 离线库更新、缓存和资源消耗 |
只备份镜像目录不能恢复完整Harbor，只备份数据库也无法找回镜像层。备份方案必须明确各组件的一致性级别和恢复顺序。
二、生产架构选择
单机部署
适合实验、小规模内部使用和非关键环境。优点是简单，缺点是主机、磁盘、数据库和入口都可能成为单点。即使单机部署，也应使用HTTPS、独立数据盘、定期备份和容量告警。
Kubernetes高可用部署
适合已有成熟Kubernetes平台的团队，通常需要：
- 高可用Ingress或Gateway入口；
- 外部或高可用PostgreSQL；
- 受支持的高可用Redis方案；
- ReadWriteMany共享存储或对象存储；
- 多副本Core、Portal、Registry和Job Service；
- 反亲和、PodDisruptionBudget和资源限制；
- 外部监控、日志和备份系统。
把Harbor部署到Kubernetes不自动等于高可用。底层数据库、Redis、对象存储、DNS和入口仍需逐项消除单点。
三、HTTPS与外部地址
仓库应使用固定域名和受信任证书。external_url、入口证书、Docker客户端访问地址和Token服务地址必须一致。常见检查：
curl -vk https://harbor.example.com/api/v2.0/ping
docker login harbor.example.com
openssl s_client -connect harbor.example.com:443 \
-servername harbor.example.com -showcerts </dev/null
不要长期要求所有客户端配置“不安全仓库”。私有CA应将根证书通过配置管理分发到Docker、containerd、Kubernetes节点和CI Runner的正确证书目录。
四、项目、账号与权限
建议按团队、环境或业务域划分项目，并明确：
- 谁能创建项目；
- 谁能推送、删除和修改策略；
- 生产镜像是否允许覆盖同名Tag；
- CI使用Robot Account还是人员账号；
- Robot Account的项目范围、权限和有效期；
- 人员离职、团队调整和密钥泄露时如何回收；
- 管理员操作是否转发到审计平台。
CI/CD不应使用系统管理员账号。机器人凭据应最小权限、可轮换、可追踪，且不能写进Dockerfile、镜像层、公开流水线日志或仓库源码。
五、Tag策略与制品不可变
latest适合提示“默认版本”，不适合作为生产部署唯一依据。推荐组合：
业务版本：orders:2.4.1
提交版本：orders:git-a18c4e2
环境标签：orders:staging（可变，仅供流程使用）
生产部署：使用digest固定 sha256:...
生产项目可启用Tag不可变规则，防止相同版本被覆盖。部署系统记录镜像Digest，才能证明运行制品与扫描、签名和发布审批对应的是同一个对象。
六、保留策略与垃圾回收
删除Tag或制品后，底层Blob不一定立即释放，需要执行垃圾回收。正确顺序：
- 设计保留策略，明确哪些制品可删除；
- 先运行规则模拟或在测试项目验证；
- 检查多架构镜像、签名、附件和无Tag制品；
- 执行保留策略；
- 先运行GC Dry Run评估回收对象；
- 在低峰期执行GC并监控任务；
- 对比仓库逻辑容量、对象存储和磁盘实际容量。
保留策略示例：
- 生产Release永久或按合规周期保留；
- 每个仓库保留最近20个成功构建；
- 带
keep、release-*标签的制品排除清理； - 分支构建保留30天；
- 未完成上传和无Tag制品按单独策略处理。
不要在磁盘已满时才第一次运行GC。GC本身需要任务资源和安全窗口，磁盘完全耗尽可能导致数据库、任务或上传先失败。
七、容量模型
镜像仓库容量不能简单用“镜像数量×平均大小”估算，因为层可复用、Tag可共享Manifest、扫描和任务日志也会占空间。建议跟踪：
- Registry或对象存储已用容量与增长速度；
- 每日推送、拉取和删除量；
- 项目配额和前十名仓库；
- 未标记制品、上传残留和GC可回收空间；
- 数据库、任务日志和漏洞库容量；
- 备份存储空间与保留周期；
- 跨站复制产生的出口带宽。
容量告警应同时包含绝对剩余空间和预计耗尽时间。只有百分比会低估大盘增长，也会让小盘过早告警。
八、漏洞扫描与处置
扫描结果是风险输入，不是自动删除依据。建议流程：
- 扫描器漏洞库保持更新并监控更新时间；
- 推送后扫描，发布前再次检查策略；
- 结合严重度、可利用性、运行组件和暴露面排序；
- 关联基础镜像、软件包、业务负责人和运行集群；
- 修复后重新构建，而不是直接修改已发布镜像；
- 对暂时无法修复的漏洞记录缓解措施和到期时间；
- 避免因扫描器不可用而默认放行所有生产制品。
应区分“镜像里存在软件包”与“运行时真正加载且可达”。但也不能用“暂未发现利用路径”长期忽略关键漏洞。
九、复制与容灾
Harbor可以配置Push或Pull复制。复制设计应明确：
- 源与目标谁是权威仓库；
- 项目和路径是否保持一致，是否启用Flatten；
- Tag覆盖策略和冲突处理；
- 触发方式、重试、带宽限制和并发；
- 目标站点的账号、配额和证书；
- 多架构Manifest、签名和OCI附件是否完整；
- 复制延迟RPO与站点切换RTO。
复制成功不等于容灾可用。至少应定期从目标仓库拉取镜像、验证Digest、在隔离集群启动服务，并演练DNS、客户端配置和凭据切换。
十、备份与恢复
备份前建议将仓库设置为只读或建立明确的一致性窗口，避免数据库元数据与制品层不同步。Kubernetes部署可结合Velero和存储快照，但要理解快照通常只是崩溃一致性，不一定是应用一致性。
备份范围至少包括：
- Harbor配置、证书和密钥；
- PostgreSQL数据库；
- Registry文件系统或对象存储；
- Helm values、Kubernetes资源和外部依赖配置；
- 机器人账号与外部身份配置的恢复资料；
- 版本号、镜像、升级历史和恢复文档。
恢复演练需要验证：
能否登录
能否浏览项目和制品
能否按digest拉取关键镜像
能否推送新镜像
扫描、复制、保留和GC任务是否恢复
审计日志和外部认证是否正常
没有恢复演练的备份只能证明“产生过文件”，不能证明可用。
十一、升级策略
升级前：
- 阅读目标版本升级说明和兼容矩阵；
- 确认当前版本支持直接升级，不能随意跨越多个大版本；
- 备份数据库、制品和配置；
- 清理失败任务并检查磁盘空间；
- 在副本环境恢复备份并演练升级；
- 冻结推送或设置只读；
- 记录旧版本部署文件和回滚路径。
升级后应执行API、登录、推送、拉取、扫描、复制、GC和Webhook全链路测试。仅页面能打开并不足以确认升级成功。
十二、监控与告警
生产Harbor建议监控：
- API、Registry和Portal可用性及延迟；
- 推送、拉取成功率和错误码；
- 数据库连接、慢查询和容量；
- Redis可用性与延迟；
- Job Service队列、失败任务和执行时长；
- Registry存储容量、对象数量和增长率；
- 扫描器状态、漏洞库更新时间和扫描积压；
- 复制延迟与失败；
- 证书到期、Token服务和外部认证；
- 审计日志转发中断。
探测应包含一次真实的认证和Manifest读取，而不只是TCP端口连通。
十三、常见故障定位
推送失败
检查客户端错误、入口上传大小、超时、Registry日志、Token权限、项目配额和存储空间。大镜像失败而小镜像成功时，重点检查代理限制和链路超时。
页面能登录但拉取失败
检查external_url、证书信任、Token服务返回地址、客户端时间、项目权限和Registry后端。
删除后空间没有下降
确认保留策略是否真正删除制品、GC是否运行、共享Blob是否仍被引用，以及查看的是文件系统、PVC还是对象存储指标。
复制积压
检查Job Service并发、目标端限速、证书与凭据、过滤规则、带宽和失败重试。避免重复创建规则导致同一制品并行复制。
十四、上线检查清单
- [ ] 使用固定域名、受信任TLS证书和正确external_url；
- [ ] 项目、人员和Robot Account执行最小权限；
- [ ] 生产部署使用Digest，关键Tag启用不可变；
- [ ] 保留策略与GC先经过Dry Run和测试项目验证；
- [ ] 漏洞库、扫描积压和发布门禁均有监控；
- [ ] Registry、数据库、配置和证书都纳入备份；
- [ ] 备份已在隔离环境完成恢复和拉取验证；
- [ ] 跨站复制的Digest、凭据和切换流程已演练；
- [ ] 容量同时监控百分比、增长率和预计耗尽时间；
- [ ] 升级、回滚、只读窗口和版本兼容路径明确；
- [ ] API、推送、拉取、任务和外部认证均有可用性探测。