从入门到实战：Harbor 私有镜像仓库完全使用指南

从入门到实战Harbor 私有镜像仓库完全使用指南前言在容器化盛行的今天Docker 镜像的管理与分发变得至关重要。Harbor 作为一个开源的云原生容器镜像仓库不仅提供了安全的镜像存储和访问控制还集成了漏洞扫描、内容签名和复制等功能成为企业内网搭建私有仓库的首选。本文将从零开始详细介绍 Harbor 的核心使用方法包括如何上传/拉取镜像、配置 HTTP 访问、设置代理缓存以加速 Docker Hub 镜像获取并解答常见问题。无论你是运维新手还是开发老手都能通过本文快速掌握 Harbor 的日常操作。环境说明Harbor 地址10.xx.xx.xxHTTP 协议默认端口 80Docker 版本20.10操作系统LinuxCentOS/Ubuntu 均可注意如果您的 Harbor 配置了 HTTPS操作步骤基本一致只需将地址中的http://改为https://且无需配置insecure-registries。一、准备工作让 Docker 信任 HTTP 仓库由于我们的 Harbor 仅支持 HTTP 协议而 Docker 默认要求仓库使用 HTTPS因此需要将 Harbor 地址添加到 Docker 的「非安全仓库」列表中。1.1 修改 Docker 配置文件编辑/etc/docker/daemon.json如不存在则新建{insecure-registries:[10.xx.xx.xx]}如果还想将 Harbor 作为镜像加速器拉取公共镜像时优先从 Harbor 拉取可以添加registry-mirrors字段{insecure-registries:[10.xx.xx.xx],registry-mirrors:[http://10.xx.xx.xx]}1.2 重启 Docker 服务sudosystemctl daemon-reloadsudosystemctl restartdocker1.3 验证配置dockerinfo|grep-A5Insecure Registries输出应包含10.xx.xx.xx。二、登录 Harbor使用docker login命令登录 Harbor用户名和密码与 Harbor Web 控制台一致默认管理员为admin密码为Harbor12345建议首次登录后修改。dockerlogin-uadmin-pHarbor1234510.41.87.240输入用户名和密码看到Login Succeeded即表示成功。提示如果遇到dial tcp 10.xx.xx.xx:xx: connect: connection refused错误说明 Docker 仍尝试使用 HTTPS 连接请检查insecure-registries配置是否正确并重启 Docker。三、推送镜像到 Harbor推送镜像需要三个步骤标记本地镜像 → 推送 → 验证。3.1 标记镜像假设本地有一个ubuntu:latest镜像需要为其打上 Harbor 的完整标签格式为Harbor地址/项目名/镜像名:标签。# 查看本地镜像dockerimages# 打标签项目名假设为 myprojectdockertag ubuntu:latest10.xx.xx.xx/myproject/ubuntu:latest3.2 推送镜像dockerpush10.xx.xx.xx/myproject/ubuntu:latest推送过程中会显示每一层的上传进度完成后会输出镜像摘要。3.3 验证命令行再次运行docker images可以看到本地多了一个 Harbor 地址前缀的镜像。Web 控制台访问http://10.xx.xx.xx进入myproject项目即可看到ubuntu仓库及latest标签。常见错误denied: requested access to the resource is denied项目不存在或用户无写入权限。请在 Harbor 中创建项目并将当前用户加入项目成员角色至少为「开发者」。http: server gave HTTP response to HTTPS clientinsecure-registries未正确配置检查并重启 Docker。四、从 Harbor 拉取镜像在内网其他机器上只要配置了相同的insecure-registries并登录 Harbor就可以直接拉取镜像。4.1 拉取命令dockerpull10.xx.xx.xx/myproject/ubuntu:latest4.2 利用镜像加速器实现「无感拉取」如果你在daemon.json中配置了registry-mirrors: [http://10.41.87.240]那么当执行docker pull ubuntu:latest时Docker 会优先从 Harbor 拉取相当于将 Harbor 作为 Docker Hub 的镜像缓存。但请注意这只对拉取有效推送仍必须写完整地址。五、进阶配置代理缓存Proxy Cache加速 Docker Hub当团队频繁拉取 Docker Hub 镜像时配置代理缓存可以大幅提升速度并节省公网带宽。Harbor 的代理缓存功能会自动将拉取的镜像存储在本地后续拉取直接从 Harbor 返回。5.1 创建 Docker Hub 端点管理员操作登录 Harbor Web 控制台进入系统管理 → 仓库管理。点击新建端点选择提供商Docker Hub。名称dockerhub-proxyURL自动填充https://registry-1.docker.io访问 ID/密码可选建议填写 Docker Hub 账号密码或访问令牌以提高拉取速率限额。点击测试连接通过后保存。5.2 创建代理缓存项目进入项目→新建项目。填写项目名称如docker-hub并开启代理缓存开关。选择上一步创建的端点dockerhub-proxy点击确定。5.3 通过 Harbor 拉取 Docker Hub 镜像现在你可以通过以下命令拉取任何 Docker Hub 镜像Harbor 会自动从 Docker Hub 拉取并缓存# 拉取官方镜像dockerpull10.xx.xx.xx/docker-hub/library/nginx:latest# 拉取第三方镜像如 bitnami/redisdockerpull10.xx.xx.xx/docker-hub/bitnami/redis:latest首次拉取可能稍慢后续拉取将瞬间完成。六、常见问题与解决方案Q1为什么docker push时必须写完整的 Harbor 地址这是 Docker 的设计机制决定的。镜像的全名本身就包含了仓库地址Docker 根据地址判断推送到哪里。不写地址默认推送到 Docker Hub。Q2能否让docker push也默认推送到 Harbor不能直接默认但可以通过脚本或别名简化操作。例如定义一个 shell 变量exportHARBOR10.xx.xx.xx/myprojectdockertag ubuntu:latest${HARBOR}/ubuntu:latestdockerpush${HARBOR}/ubuntu:latestQ3Harbor 的 Web 登录密码和docker login密码是同一个吗是的完全一致。默认管理员账号密码为admin/Harbor12345。Q4配置了insecure-registries后仍然报 HTTPS 错误请检查是否在registry-mirrors中也写了http://10.41.87.240这可能导致混淆。建议保持insecure-registries只写 IPregistry-mirrors只写公网加速器如https://docker.xuanyuan.me。Q5代理缓存项目能否推送自己的私有镜像不能。代理缓存项目只能拉取并缓存上游镜像不允许推送。私有镜像应存放在普通项目中。七、总结通过本文你应该已经掌握了 Harbor 的核心使用技能配置 Docker 客户端以支持 HTTP 仓库登录 Harbor 并推送/拉取镜像利用代理缓存功能加速 Docker Hub 镜像获取解决常见错误。Harbor 的功能远不止于此还包括镜像复制、漏洞扫描、机器人账户等高级特性值得深入探索。希望本文能帮助你顺利搭建起高效的私有镜像分发体系提升团队容器化应用的交付效率。参考资料Harbor 官方文档Docker Registry 配置版权声明本文为原创技术文章转载请注明出处。如有疑问或建议欢迎留言交流。