1. 项目概述为什么我们需要一个私有的镜像仓库在容器化这条路上Docker Hub 就像是我们的第一个“公共图书馆”初期用起来很方便拉取一些公开的镜像就能快速上手。但当你真正开始在企业内部或者个人项目中大规模使用容器时问题就来了镜像的安全谁来保证网络延迟导致的下载缓慢怎么解决团队内部开发的镜像如何高效共享和版本管理更别提那些涉及敏感信息的镜像你绝对不敢把它们推到公网上去。这时候一个私有的、可控的镜像仓库就成了刚需。Harbor 就是这个刚需下的明星解决方案。它最初由 VMware 中国团队开源现在已经是 CNCF 的毕业项目你可以把它理解为一个企业级的私有 Docker Registry。它不仅仅是一个存储镜像的服务器更围绕镜像的整个生命周期提供了权限控制、漏洞扫描、镜像复制、日志审计等一系列生产级功能。简单来说Harbor 让你能像管理代码一样安全、高效地管理你的容器镜像资产。对于任何正在或计划使用 Kubernetes、Docker Swarm 等编排工具的团队掌握 Harbor 的基础操作是必备技能。它能帮你搭建起从开发到部署的镜像流水线中最可靠、最安全的一环。接下来我会从一个实际使用者的角度带你从零开始把 Harbor 的“增删改查”这些基础但核心的操作彻底搞明白。2. 环境准备与快速部署在开始操作 Harbor 之前你得先把它跑起来。虽然生产环境部署涉及高可用、外部存储等复杂配置但对于学习和测试单机 Docker Compose 部署是最快、最直接的方式。2.1 部署前置条件检查部署 Harbor 前请确保你的服务器满足以下最低要求这能避免很多后续的奇怪问题。操作系统推荐 Linux如 Ubuntu 20.04/22.04 LTS, CentOS 7/8。本文以 Ubuntu 22.04 为例。Docker 与 Docker Compose这是 Harbor 运行的基础。Docker 版本建议 20.10 以上Docker Compose 建议 v2 以上。硬件资源至少 2 CPU 核心4GB 内存40GB 磁盘空间。如果开启漏洞扫描等功能需要更多资源。网络服务器需要能访问互联网以下载必要的镜像同时确保你的客户端如 CI/CD 服务器、k8s 节点能通过网络访问到 Harbor 服务器的 IP 和端口。注意如果你的服务器之前安装过旧版 Harbor 或其他 Docker Registry请务必彻底清理相关容器、镜像和卷避免端口或数据冲突。可以使用docker system prune -a和docker volume prune进行清理生产环境慎用。2.2 一键式离线安装部署实操Harbor 提供了在线和离线两种安装包。离线包包含了所有必需的镜像在内网或无外网环境部署非常方便也是我最推荐的方式。步骤一下载并解压离线安装包访问 Harbor 的 GitHub Releases 页面选择最新的稳定版本。我们以v2.10.0为例。在服务器上执行# 下载离线安装包 wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz # 解压到当前目录 tar xzvf harbor-offline-installer-v2.10.0.tgz # 进入解压后的目录 cd harbor步骤二配置harbor.yml解压后你会看到一个harbor.yml.tmpl模板文件。我们需要复制并修改它cp harbor.yml.tmpl harbor.yml用你喜欢的编辑器如vim或nano打开harbor.yml。对于基础测试你只需要关注以下几个关键配置# 设置 Harbor 服务器的主机名或 IP 地址。这是客户端访问的地址。 # 如果是本地测试可以用 localhost但其他机器访问需用 IP。 # 生产环境请配置为域名如 registry.yourcompany.com。 hostname: 192.168.1.100 # 替换为你的服务器 IP # HTTP 相关配置如果不用 HTTPS就只配这个 http: port: 8080 # Harbor Web 界面和 Registry 服务的 HTTP 端口 # HTTPS 配置生产环境强烈建议启用 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # Harbor 初始管理员密码 harbor_admin_password: Harbor12345 # 请务必修改为一个强密码 # 数据库密码用于 Harbor 内部数据库 database: password: root123 # 同样建议修改 # 数据持久化目录Harbor 的镜像、数据库等数据会存储在这里 data_volume: /data实操心得第一次部署时强烈建议先使用 HTTP 并指定一个非常用端口如 8080这样可以绕过复杂的证书配置快速验证 Harbor 是否正常工作。等基础功能跑通后再回头配置 HTTPS。很多新手卡在证书这一步导致半天无法登录。步骤三执行安装脚本配置保存后运行安装脚本sudo ./install.sh这个脚本会自动加载 Docker 镜像并根据harbor.yml的配置启动一系列容器包括核心服务、数据库、Redis、JobService 等。看到✔ ----Harbor has been installed and started successfully.----的输出就表示成功了。步骤四验证安装打开浏览器访问http://你的服务器IP:8080。你应该能看到 Harbor 的登录界面。使用默认用户名admin和你刚才在配置文件中设置的harbor_admin_password密码登录。同时在服务器上运行docker-compose ps在 harbor 目录下可以查看所有服务的状态确保都是Up (healthy)。3. Harbor 核心功能与界面操作详解登录后你会看到一个清晰的管理界面。Harbor 的核心管理单元是“项目”所有镜像都隶属于某个项目。你可以把项目理解为镜像的命名空间或分类文件夹。3.1 项目管理镜像的“家”创建项目点击顶部导航栏的“项目”。点击“新建项目”。填写项目名称例如my-application。名称通常用小写可以用-连接。访问级别这是关键设置。公开任何能访问 Harbor 的人即使未登录都可以拉取pull这个项目下的镜像但只有项目成员可以推送push。适合存放基础公共镜像。私有只有被赋予权限的用户或机器人账户才能拉取和推送。适合存放业务应用镜像。其他如存储配额、漏洞扫描策略等可以后续配置先点击“确定”。项目成员与权限 进入项目详情页在“成员”选项卡中可以添加用户或用户组并分配角色项目管理员拥有项目的全部管理权限。维护者可以推送和拉取镜像管理项目内的镜像如删除。开发者可以推送和拉取镜像。访客只能拉取镜像对于私有项目。注意事项权限管理是 Harbor 安全性的基石。遵循最小权限原则给开发者“开发者”角色即可避免赋予不必要的“项目管理员”权限。对于 CI/CD 流水线建议创建专用的“机器人账户”并赋予“开发者”角色而不是使用个人账号。3.2 用户与机器人账户管理用户管理系统管理员视角 在“系统管理” - “用户管理”中可以创建新用户。Harbor 支持数据库内置用户和对接 LDAP/AD 等外部认证源。对于小型团队内置用户足够用。创建用户时注意将其添加到相应的项目中并分配角色。机器人账户 这是 Harbor 中一个非常实用的功能专为自动化流程设计如 CI/CD。机器人账户与项目绑定拥有固定的令牌Token权限固定比使用个人用户密码更安全。进入目标项目如my-application。在“机器人账户”选项卡点击“新建机器人账户”。设置名称和过期时间建议设置一个合理的有效期如1年。勾选需要的权限通常 CI/CD 需要推送制品和拉取制品。创建成功后务必立即复制并妥善保存生成的 Token因为它只显示一次这个 Token 就是后续 Docker 客户端登录时使用的密码。3.3 镜像仓库与标签管理在项目内点击“镜像仓库”你会看到所有被推送到此项目的镜像。每个镜像仓库下会有不同的标签Tag通常对应不同的版本如v1.0.0,latest,dev。通过界面管理镜像删除镜像/标签可以删除单个标签也可以删除整个仓库及其所有标签。删除操作会真正释放磁盘空间启用垃圾回收后。复制镜像可以将一个镜像从当前 Harbor 实例复制到另一个项目甚至复制到另一个远程的 Harbor 实例。这是实现多中心镜像同步、灾备的关键功能。查看镜像信息点击镜像详情可以查看其 Manifest 信息、构建历史、以及如果启用了漏洞扫描还能看到安全扫描报告。4. Docker 客户端与 Harbor 的交互实操Harbor 界面再好看最终还是要通过 Docker 命令行来推送和拉取镜像。这是日常开发运维中最频繁的操作。4.1 客户端登录认证在能推送镜像之前你必须先让 Docker 客户端登录到你的 Harbor 服务器。# 语法docker login [OPTIONS] [SERVER] # 使用 HTTP 和非标准端口时需要明确指定服务器地址 docker login 192.168.1.100:8080执行命令后会提示你输入用户名和密码。使用你的 Harbor 用户如admin和密码或者使用机器人账户的用户名和 Token。登录成功后凭证会保存在~/.docker/config.json文件中。Docker 后续操作时会自动使用这些凭证。踩坑记录如果你配置了 HTTPS 但使用了自签名证书Docker 客户端会报错x509: certificate signed by unknown authority。有两种解决方法1将 Harbor 的 CA 证书放到 Docker 客户端的信任目录/etc/docker/certs.d/your-harbor-host/下。2更简单粗暴仅限测试环境在 Docker 守护进程配置中/etc/docker/daemon.json添加{ insecure-registries: [192.168.1.100:8080] }然后重启 Docker。生产环境切勿使用insecure-registries。4.2 镜像的推送全流程假设我们有一个本地构建好的镜像myapp:1.0想要推送到 Harbor 的my-application项目中。步骤一给镜像打上符合 Harbor 规范的 TagDocker 推送镜像时镜像名称必须包含仓库地址格式为Harbor主机地址/项目名称/镜像名:标签。# 语法docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] docker tag myapp:1.0 192.168.1.100:8080/my-application/myapp:1.0这行命令并没有移动镜像数据只是给本地镜像myapp:1.0创建了一个指向 Harbor 仓库的新别名。步骤二执行推送命令docker push 192.168.1.100:8080/my-application/myapp:1.0命令执行后Docker 会分层上传镜像。上传成功后刷新 Harbor 网页界面在my-application项目下就能看到myapp镜像及其1.0标签了。4.3 镜像的拉取与运行从 Harbor 拉取镜像和从 Docker Hub 拉取语法几乎一样只是需要指定完整路径。# 从 Harbor 拉取镜像 docker pull 192.168.1.100:8080/my-application/myapp:1.0 # 使用拉取的镜像运行容器 docker run -d -p 8080:80 --name myapp-container 192.168.1.100:8080/my-application/myapp:1.04.4 使用镜像摘要确保一致性标签如latest,v1.0是可变的今天myapp:latest指向版本 A明天可能被更新指向版本 B这可能导致生产环境发布不一致。Harbor 和 Docker 支持使用唯一的镜像摘要来拉取镜像。在 Harbor Web 界面的镜像详情中或者使用docker images --digests命令都可以看到每个镜像标签对应的摘要一串sha256:...的字符串。# 通过摘要拉取镜像确保每次拉取的都是完全相同的镜像层 docker pull 192.168.1.100:8080/my-application/myappsha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2在 CI/CD 流水线或 Kubernetes YAML 文件中使用镜像摘要而非标签是保证部署一致性的最佳实践。5. 进阶维护与故障排查指南Harbor 运行起来后还需要一些日常维护并知道如何解决常见问题。5.1 日常维护操作修改配置与重启 如果需要修改harbor.yml比如切换为 HTTPS需要先停止 Harbor更新配置然后重新准备并启动。# 进入 Harbor 安装目录 cd /path/to/harbor # 停止 Harbor 服务 docker-compose down -v # 注意-v 参数会删除数据卷除非你想彻底清除数据否则不要加 -v通常用 docker-compose down 即可。 # 修改 harbor.yml 配置文件 vim harbor.yml # 运行准备脚本应用新配置 sudo ./prepare # 重新启动 Harbor docker-compose up -d垃圾回收 当你删除镜像标签或仓库后磁盘空间并不会立即释放因为 Docker Registry 使用分层存储被删除的镜像层可能还被其他镜像引用。需要手动触发垃圾回收来清理未被引用的数据层。在 Harbor 界面“系统管理” - “垃圾回收”。点击“立即执行垃圾回收”。这个过程会在离线状态下进行期间 Registry 会变为只读无法推送和拉取镜像因此需要在维护窗口进行。数据备份与恢复 Harbor 的数据主要包括镜像数据存储在data_volume配置的目录下默认/data下的registry,chart等目录。数据库数据存储在database容器的卷中。配置文件harbor.yml。备份时需要备份整个/data目录和harbor.yml文件。恢复时将备份数据放到新环境的相同路径然后按照安装步骤执行./install.shHarbor 会自动使用已有的数据启动。5.2 常见问题与排查技巧问题一docker login失败提示Error response from daemon: Get https://.../v2/: dial tcp ...: connect: connection refused排查思路检查 Harbor 服务状态在服务器上运行docker-compose ps确认所有容器是否正常运行。特别是harbor-core,harbor-portal,registry这几个核心服务。检查防火墙确保服务器防火墙如ufw或firewalld开放了 Harbor 配置的端口如 8080。检查网络连通性从客户端使用telnet harbor_ip 8080或curl -v http://harbor_ip:8080测试网络是否可达。问题二docker push失败提示denied: requested access to the resource is denied排查思路确认登录状态运行docker login your-harbor-host重新登录或检查~/.docker/config.json文件中的认证信息是否正确。检查项目权限确认你使用的账号在目标项目中是否有“开发者”或以上权限对于私有项目。检查镜像 Tag确认你推送的镜像 Tag 格式是否正确特别是项目名称是否拼写正确。Harbor 项目名是大小写敏感的。问题三Web 界面可以访问但推送/拉取镜像非常慢排查思路检查存储后端如果使用本地磁盘检查磁盘 I/O 是否瓶颈使用iostat命令。生产环境建议使用高性能云盘或对象存储如 S3作为后端存储。启用缓存对于拉取性能可以考虑在 Harbor 前部署一个 Registry 缓存如docker/distribution配置为代理缓存模式或者使用 Docker 客户端的本地缓存机制。网络问题如果客户端与 Harbor 服务器跨地域考虑使用 Harbor 的“复制”功能在多个地域部署实例并进行镜像同步。问题四如何清理旧的镜像标签释放空间操作在 Harbor Web 界面进入项目下的镜像仓库可以手动删除不需要的标签。但请注意这并不会立即释放物理空间需要后续执行“垃圾回收”操作。自动化Harbor 自身提供了保留策略功能。你可以在项目配置中设置“标签保留规则”例如“保留最近推送的 10 个latest标签其余自动清理”。结合 Harbor API 和定时任务如 CronJob可以实现自动化的镜像生命周期管理。掌握这些基础操作和维护技巧你就能驾驭一个生产可用的 Harbor 服务了。它就像你私有云中的镜像枢纽稳稳地托住整个容器化应用的基石。
1. 项目概述为什么我们需要一个私有的镜像仓库在容器化这条路上Docker Hub 就像是我们的第一个“公共图书馆”初期用起来很方便拉取一些公开的镜像就能快速上手。但当你真正开始在企业内部或者个人项目中大规模使用容器时问题就来了镜像的安全谁来保证网络延迟导致的下载缓慢怎么解决团队内部开发的镜像如何高效共享和版本管理更别提那些涉及敏感信息的镜像你绝对不敢把它们推到公网上去。这时候一个私有的、可控的镜像仓库就成了刚需。Harbor 就是这个刚需下的明星解决方案。它最初由 VMware 中国团队开源现在已经是 CNCF 的毕业项目你可以把它理解为一个企业级的私有 Docker Registry。它不仅仅是一个存储镜像的服务器更围绕镜像的整个生命周期提供了权限控制、漏洞扫描、镜像复制、日志审计等一系列生产级功能。简单来说Harbor 让你能像管理代码一样安全、高效地管理你的容器镜像资产。对于任何正在或计划使用 Kubernetes、Docker Swarm 等编排工具的团队掌握 Harbor 的基础操作是必备技能。它能帮你搭建起从开发到部署的镜像流水线中最可靠、最安全的一环。接下来我会从一个实际使用者的角度带你从零开始把 Harbor 的“增删改查”这些基础但核心的操作彻底搞明白。2. 环境准备与快速部署在开始操作 Harbor 之前你得先把它跑起来。虽然生产环境部署涉及高可用、外部存储等复杂配置但对于学习和测试单机 Docker Compose 部署是最快、最直接的方式。2.1 部署前置条件检查部署 Harbor 前请确保你的服务器满足以下最低要求这能避免很多后续的奇怪问题。操作系统推荐 Linux如 Ubuntu 20.04/22.04 LTS, CentOS 7/8。本文以 Ubuntu 22.04 为例。Docker 与 Docker Compose这是 Harbor 运行的基础。Docker 版本建议 20.10 以上Docker Compose 建议 v2 以上。硬件资源至少 2 CPU 核心4GB 内存40GB 磁盘空间。如果开启漏洞扫描等功能需要更多资源。网络服务器需要能访问互联网以下载必要的镜像同时确保你的客户端如 CI/CD 服务器、k8s 节点能通过网络访问到 Harbor 服务器的 IP 和端口。注意如果你的服务器之前安装过旧版 Harbor 或其他 Docker Registry请务必彻底清理相关容器、镜像和卷避免端口或数据冲突。可以使用docker system prune -a和docker volume prune进行清理生产环境慎用。2.2 一键式离线安装部署实操Harbor 提供了在线和离线两种安装包。离线包包含了所有必需的镜像在内网或无外网环境部署非常方便也是我最推荐的方式。步骤一下载并解压离线安装包访问 Harbor 的 GitHub Releases 页面选择最新的稳定版本。我们以v2.10.0为例。在服务器上执行# 下载离线安装包 wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz # 解压到当前目录 tar xzvf harbor-offline-installer-v2.10.0.tgz # 进入解压后的目录 cd harbor步骤二配置harbor.yml解压后你会看到一个harbor.yml.tmpl模板文件。我们需要复制并修改它cp harbor.yml.tmpl harbor.yml用你喜欢的编辑器如vim或nano打开harbor.yml。对于基础测试你只需要关注以下几个关键配置# 设置 Harbor 服务器的主机名或 IP 地址。这是客户端访问的地址。 # 如果是本地测试可以用 localhost但其他机器访问需用 IP。 # 生产环境请配置为域名如 registry.yourcompany.com。 hostname: 192.168.1.100 # 替换为你的服务器 IP # HTTP 相关配置如果不用 HTTPS就只配这个 http: port: 8080 # Harbor Web 界面和 Registry 服务的 HTTP 端口 # HTTPS 配置生产环境强烈建议启用 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # Harbor 初始管理员密码 harbor_admin_password: Harbor12345 # 请务必修改为一个强密码 # 数据库密码用于 Harbor 内部数据库 database: password: root123 # 同样建议修改 # 数据持久化目录Harbor 的镜像、数据库等数据会存储在这里 data_volume: /data实操心得第一次部署时强烈建议先使用 HTTP 并指定一个非常用端口如 8080这样可以绕过复杂的证书配置快速验证 Harbor 是否正常工作。等基础功能跑通后再回头配置 HTTPS。很多新手卡在证书这一步导致半天无法登录。步骤三执行安装脚本配置保存后运行安装脚本sudo ./install.sh这个脚本会自动加载 Docker 镜像并根据harbor.yml的配置启动一系列容器包括核心服务、数据库、Redis、JobService 等。看到✔ ----Harbor has been installed and started successfully.----的输出就表示成功了。步骤四验证安装打开浏览器访问http://你的服务器IP:8080。你应该能看到 Harbor 的登录界面。使用默认用户名admin和你刚才在配置文件中设置的harbor_admin_password密码登录。同时在服务器上运行docker-compose ps在 harbor 目录下可以查看所有服务的状态确保都是Up (healthy)。3. Harbor 核心功能与界面操作详解登录后你会看到一个清晰的管理界面。Harbor 的核心管理单元是“项目”所有镜像都隶属于某个项目。你可以把项目理解为镜像的命名空间或分类文件夹。3.1 项目管理镜像的“家”创建项目点击顶部导航栏的“项目”。点击“新建项目”。填写项目名称例如my-application。名称通常用小写可以用-连接。访问级别这是关键设置。公开任何能访问 Harbor 的人即使未登录都可以拉取pull这个项目下的镜像但只有项目成员可以推送push。适合存放基础公共镜像。私有只有被赋予权限的用户或机器人账户才能拉取和推送。适合存放业务应用镜像。其他如存储配额、漏洞扫描策略等可以后续配置先点击“确定”。项目成员与权限 进入项目详情页在“成员”选项卡中可以添加用户或用户组并分配角色项目管理员拥有项目的全部管理权限。维护者可以推送和拉取镜像管理项目内的镜像如删除。开发者可以推送和拉取镜像。访客只能拉取镜像对于私有项目。注意事项权限管理是 Harbor 安全性的基石。遵循最小权限原则给开发者“开发者”角色即可避免赋予不必要的“项目管理员”权限。对于 CI/CD 流水线建议创建专用的“机器人账户”并赋予“开发者”角色而不是使用个人账号。3.2 用户与机器人账户管理用户管理系统管理员视角 在“系统管理” - “用户管理”中可以创建新用户。Harbor 支持数据库内置用户和对接 LDAP/AD 等外部认证源。对于小型团队内置用户足够用。创建用户时注意将其添加到相应的项目中并分配角色。机器人账户 这是 Harbor 中一个非常实用的功能专为自动化流程设计如 CI/CD。机器人账户与项目绑定拥有固定的令牌Token权限固定比使用个人用户密码更安全。进入目标项目如my-application。在“机器人账户”选项卡点击“新建机器人账户”。设置名称和过期时间建议设置一个合理的有效期如1年。勾选需要的权限通常 CI/CD 需要推送制品和拉取制品。创建成功后务必立即复制并妥善保存生成的 Token因为它只显示一次这个 Token 就是后续 Docker 客户端登录时使用的密码。3.3 镜像仓库与标签管理在项目内点击“镜像仓库”你会看到所有被推送到此项目的镜像。每个镜像仓库下会有不同的标签Tag通常对应不同的版本如v1.0.0,latest,dev。通过界面管理镜像删除镜像/标签可以删除单个标签也可以删除整个仓库及其所有标签。删除操作会真正释放磁盘空间启用垃圾回收后。复制镜像可以将一个镜像从当前 Harbor 实例复制到另一个项目甚至复制到另一个远程的 Harbor 实例。这是实现多中心镜像同步、灾备的关键功能。查看镜像信息点击镜像详情可以查看其 Manifest 信息、构建历史、以及如果启用了漏洞扫描还能看到安全扫描报告。4. Docker 客户端与 Harbor 的交互实操Harbor 界面再好看最终还是要通过 Docker 命令行来推送和拉取镜像。这是日常开发运维中最频繁的操作。4.1 客户端登录认证在能推送镜像之前你必须先让 Docker 客户端登录到你的 Harbor 服务器。# 语法docker login [OPTIONS] [SERVER] # 使用 HTTP 和非标准端口时需要明确指定服务器地址 docker login 192.168.1.100:8080执行命令后会提示你输入用户名和密码。使用你的 Harbor 用户如admin和密码或者使用机器人账户的用户名和 Token。登录成功后凭证会保存在~/.docker/config.json文件中。Docker 后续操作时会自动使用这些凭证。踩坑记录如果你配置了 HTTPS 但使用了自签名证书Docker 客户端会报错x509: certificate signed by unknown authority。有两种解决方法1将 Harbor 的 CA 证书放到 Docker 客户端的信任目录/etc/docker/certs.d/your-harbor-host/下。2更简单粗暴仅限测试环境在 Docker 守护进程配置中/etc/docker/daemon.json添加{ insecure-registries: [192.168.1.100:8080] }然后重启 Docker。生产环境切勿使用insecure-registries。4.2 镜像的推送全流程假设我们有一个本地构建好的镜像myapp:1.0想要推送到 Harbor 的my-application项目中。步骤一给镜像打上符合 Harbor 规范的 TagDocker 推送镜像时镜像名称必须包含仓库地址格式为Harbor主机地址/项目名称/镜像名:标签。# 语法docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] docker tag myapp:1.0 192.168.1.100:8080/my-application/myapp:1.0这行命令并没有移动镜像数据只是给本地镜像myapp:1.0创建了一个指向 Harbor 仓库的新别名。步骤二执行推送命令docker push 192.168.1.100:8080/my-application/myapp:1.0命令执行后Docker 会分层上传镜像。上传成功后刷新 Harbor 网页界面在my-application项目下就能看到myapp镜像及其1.0标签了。4.3 镜像的拉取与运行从 Harbor 拉取镜像和从 Docker Hub 拉取语法几乎一样只是需要指定完整路径。# 从 Harbor 拉取镜像 docker pull 192.168.1.100:8080/my-application/myapp:1.0 # 使用拉取的镜像运行容器 docker run -d -p 8080:80 --name myapp-container 192.168.1.100:8080/my-application/myapp:1.04.4 使用镜像摘要确保一致性标签如latest,v1.0是可变的今天myapp:latest指向版本 A明天可能被更新指向版本 B这可能导致生产环境发布不一致。Harbor 和 Docker 支持使用唯一的镜像摘要来拉取镜像。在 Harbor Web 界面的镜像详情中或者使用docker images --digests命令都可以看到每个镜像标签对应的摘要一串sha256:...的字符串。# 通过摘要拉取镜像确保每次拉取的都是完全相同的镜像层 docker pull 192.168.1.100:8080/my-application/myappsha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2在 CI/CD 流水线或 Kubernetes YAML 文件中使用镜像摘要而非标签是保证部署一致性的最佳实践。5. 进阶维护与故障排查指南Harbor 运行起来后还需要一些日常维护并知道如何解决常见问题。5.1 日常维护操作修改配置与重启 如果需要修改harbor.yml比如切换为 HTTPS需要先停止 Harbor更新配置然后重新准备并启动。# 进入 Harbor 安装目录 cd /path/to/harbor # 停止 Harbor 服务 docker-compose down -v # 注意-v 参数会删除数据卷除非你想彻底清除数据否则不要加 -v通常用 docker-compose down 即可。 # 修改 harbor.yml 配置文件 vim harbor.yml # 运行准备脚本应用新配置 sudo ./prepare # 重新启动 Harbor docker-compose up -d垃圾回收 当你删除镜像标签或仓库后磁盘空间并不会立即释放因为 Docker Registry 使用分层存储被删除的镜像层可能还被其他镜像引用。需要手动触发垃圾回收来清理未被引用的数据层。在 Harbor 界面“系统管理” - “垃圾回收”。点击“立即执行垃圾回收”。这个过程会在离线状态下进行期间 Registry 会变为只读无法推送和拉取镜像因此需要在维护窗口进行。数据备份与恢复 Harbor 的数据主要包括镜像数据存储在data_volume配置的目录下默认/data下的registry,chart等目录。数据库数据存储在database容器的卷中。配置文件harbor.yml。备份时需要备份整个/data目录和harbor.yml文件。恢复时将备份数据放到新环境的相同路径然后按照安装步骤执行./install.shHarbor 会自动使用已有的数据启动。5.2 常见问题与排查技巧问题一docker login失败提示Error response from daemon: Get https://.../v2/: dial tcp ...: connect: connection refused排查思路检查 Harbor 服务状态在服务器上运行docker-compose ps确认所有容器是否正常运行。特别是harbor-core,harbor-portal,registry这几个核心服务。检查防火墙确保服务器防火墙如ufw或firewalld开放了 Harbor 配置的端口如 8080。检查网络连通性从客户端使用telnet harbor_ip 8080或curl -v http://harbor_ip:8080测试网络是否可达。问题二docker push失败提示denied: requested access to the resource is denied排查思路确认登录状态运行docker login your-harbor-host重新登录或检查~/.docker/config.json文件中的认证信息是否正确。检查项目权限确认你使用的账号在目标项目中是否有“开发者”或以上权限对于私有项目。检查镜像 Tag确认你推送的镜像 Tag 格式是否正确特别是项目名称是否拼写正确。Harbor 项目名是大小写敏感的。问题三Web 界面可以访问但推送/拉取镜像非常慢排查思路检查存储后端如果使用本地磁盘检查磁盘 I/O 是否瓶颈使用iostat命令。生产环境建议使用高性能云盘或对象存储如 S3作为后端存储。启用缓存对于拉取性能可以考虑在 Harbor 前部署一个 Registry 缓存如docker/distribution配置为代理缓存模式或者使用 Docker 客户端的本地缓存机制。网络问题如果客户端与 Harbor 服务器跨地域考虑使用 Harbor 的“复制”功能在多个地域部署实例并进行镜像同步。问题四如何清理旧的镜像标签释放空间操作在 Harbor Web 界面进入项目下的镜像仓库可以手动删除不需要的标签。但请注意这并不会立即释放物理空间需要后续执行“垃圾回收”操作。自动化Harbor 自身提供了保留策略功能。你可以在项目配置中设置“标签保留规则”例如“保留最近推送的 10 个latest标签其余自动清理”。结合 Harbor API 和定时任务如 CronJob可以实现自动化的镜像生命周期管理。掌握这些基础操作和维护技巧你就能驾驭一个生产可用的 Harbor 服务了。它就像你私有云中的镜像枢纽稳稳地托住整个容器化应用的基石。
