1. 项目概述为什么我们需要一个私有的Docker镜像仓库在容器化开发和部署已经成为主流的今天Docker镜像的管理与分发效率直接关系到整个团队的研发流程。如果你还在频繁地从Docker Hub拉取公共镜像或者通过docker save和docker load命令在开发、测试、生产环境之间手动搬运镜像包那么你很可能正在经历一些“成长的烦恼”网络拉取速度慢如蜗牛尤其是在某些网络环境下公共镜像的安全性和稳定性无法完全掌控内部构建的镜像缺乏一个统一、安全的分发中心。这时搭建一个私有的Docker Registry就从一个“可选项”变成了“必选项”。简单来说私有Docker Registry就是你团队内部的“Docker Hub”。它允许你在内网或可控的网络环境中存储、管理和分发Docker镜像。结合WebUI如Harbor它还能提供镜像漏洞扫描、权限管理、项目隔离、镜像复制等企业级功能。无论是为了提升CI/CD流水线的效率保障内部镜像的安全还是仅仅为了在离线环境下也能顺畅工作私有Registry都是容器化架构中不可或缺的一块基石。接下来我将基于一个稳定、功能丰富的方案记录从零开始搭建私有Docker Registry并集成WebUI管理界面的全过程其中会穿插大量我踩过的坑和总结出的最佳实践。2. 方案选型与核心组件解析在开始动手之前明确技术选型至关重要。市面上主流的私有Registry方案有好几种我们需要根据团队规模、安全要求和运维复杂度来做出选择。2.1 核心组件Registry vs. Harbor最基础的私有仓库是Docker官方提供的开源项目registry:2。它非常轻量只提供了最核心的镜像存储和分发API符合OCI Distribution Spec。如果你只需要一个简单的、内网可用的镜像仓库它完全够用。通过Docker命令就能一键拉起。但是它没有图形界面管理镜像全靠命令行缺乏权限控制、漏洞扫描等高级功能。对于绝大多数团队我强烈推荐使用Harbor。Harbor是一个由VMware开源的企业级Registry服务器它在原生Docker Distribution的基础上增加了以下关键功能友好的Web管理界面可视化地浏览、搜索、删除镜像管理项目和成员。基于角色的访问控制RBAC可以精细地控制哪个用户或机器人账号能对哪个项目进行拉取/推送操作。镜像漏洞扫描集成Trivy或Clair等扫描器自动检测镜像中的安全漏洞并生成报告。镜像复制支持在不同Harbor实例之间同步镜像适用于多数据中心或灾备场景。Helm Chart仓库不仅可以存Docker镜像还能作为Helm Chart的私有仓库。考虑到功能的完备性和未来的可扩展性本次搭建将选择Harbor作为我们的核心方案。它同样是以容器方式部署管理起来非常方便。2.2 环境与依赖准备在部署Harbor之前我们需要确保宿主机环境满足要求。以下是我的环境清单和检查要点操作系统我选用的是Ubuntu 22.04 LTS。CentOS 7/8、RHEL等主流Linux发行版均可。确保系统已更新到最新稳定版。Docker与Docker ComposeHarbor通过Docker Compose编排多个容器服务。Docker版本需在17.06.0-ce以上。安装后务必将当前用户加入docker用户组避免每次命令都要sudo。Docker ComposeHarbor的离线安装包自带特定版本的Compose文件但为了日常管理建议独立安装v2以上的版本。硬件资源CPU最低2核建议4核以上。内存最低4GB建议8GB。如果开启漏洞扫描等功能需要更多内存。磁盘镜像仓库是吃存储的大户。需要根据镜像数量和大小预估。至少预留100GB以上并规划好存储路径如挂载独立的大容量数据盘。文件系统推荐ext4或xfs。网络与域名为Harbor准备一个域名例如harbor.yourcompany.com。如果没有DNS服务器可以在部署Harbor的服务器以及所有需要访问它的客户端包括CI/CD服务器、开发机的/etc/hosts文件中添加解析记录。确保服务器防火墙开放了Harbor所需的端口默认是80和443如果启用HTTPS。注意生产环境强烈建议配置HTTPS。Harbor默认安装脚本会生成自签名证书但浏览器和Docker客户端会报警告。对于内部可信环境可以将自签名证书导入到客户端系统信任库对于更正式的环境建议使用Let‘s Encrypt或内部CA签发的证书。3. Harbor的安装与配置实战我将以离线安装的方式部署Harbor这种方式更稳定不依赖外网下载。3.1 下载与解压安装包首先访问Harbor的GitHub Release页面下载对应版本的离线安装包文件名为harbor-offline-installer-version.tgz。假设我们下载的是harbor-offline-installer-v2.10.0.tgz。# 1. 下载安装包 (请替换为实际版本号) # wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz # 2. 解压到指定目录我习惯放在 /opt 下 sudo tar xzvf harbor-offline-installer-v2.10.0.tgz -C /opt cd /opt/harbor解压后目录下会有一个关键的配置文件harbor.yml.tmpl我们需要复制并修改它。3.2 关键配置文件详解harbor.yml是Harbor的核心配置文件每一个参数都影响着部署行为。cp harbor.yml.tmpl harbor.yml vim harbor.yml下面是我修改的几个核心部分并附上解释# 设置访问Harbor的主机名。这里我使用IP你也可以用域名。 hostname: 192.168.1.100 # 替换为你的服务器IP或域名 # HTTP相关配置如果不用HTTPS就保留这个 http: port: 80 # HTTPS配置生产环境推荐。需要提前准备好证书文件(.crt)和私钥文件(.key)。 # https: # port: 443 # certificate: /your/certificate/path/server.crt # private_key: /your/certificate/path/server.key # Harbor管理员初始密码。首次登录WebUI时使用。 harbor_admin_password: Harbor12345 # 务必修改为一个强密码 # Harbor的数据持久化目录。确保该路径有足够磁盘空间和写入权限。 data_volume: /data/harbor # 我通常挂载一个独立数据盘到这里 # 日志相关配置 log: level: info # 日志级别debug, info, warning, error, fatal local: rotate_count: 50 # 保留50个日志文件 rotate_size: 200M # 每个日志文件最大200M location: /var/log/harbor # 日志存储路径 # 数据库配置使用内置PostgreSQL一般无需修改 database: password: root123 max_idle_conns: 50 max_open_conns: 100 # 外部数据库配置如果你有现成的PostgreSQL可以配置此项避免Harbor自带数据库容器 # external_database: # harbor: # host: harbor_db_host # port: harbor_db_port # db_name: harbor_db_name # username: harbor_db_username # password: harbor_db_password # ssl_mode: disable # max_idle_conns: 50 # max_open_conns: 100 # 外部Redis配置类似数据库可使用外部Redis # external_redis: # host: redis_host # port: 6379 # password: # registry_db_index: 1 # jobservice_db_index: 2 # chartmuseum_db_index: 3 # trivy_db_index: 5 # idle_timeout_seconds: 30 # 邮件通知配置当有镜像被推送、删除或漏洞扫描完成时发送邮件 email: smtp_host: smtp.yourcompany.com smtp_port: 465 username: noreplyyourcompany.com password: your_email_password ssl: true from: Harbor Admin noreplyyourcompany.com identity: # 是否启用漏洞扫描Trivy trivy: ignore_unfixed: false # 是否忽略未修复的漏洞 skip_update: false # 在离线环境需设置为true并手动更新漏洞库 offline_scan: false # 离线扫描模式 security_check: vuln # 扫描类型vuln漏洞、misconfig配置错误 insecure: false # 是否跳过TLS验证 # 作业服务配置 jobservice: max_job_workers: 10 # 最大并发作业数影响镜像复制、扫描等任务的并发度 # 通知Webhook可集成到钉钉、企业微信等 notification: webhook_job_max_retry: 3 # 认证模式默认使用数据库存储用户可对接LDAP/AD auth_mode: db_auth # 是否允许自注册生产环境建议关闭 self_registration: off # 创建项目时是否默认所有人都有访问权限生产环境建议关闭 project_creation_restriction: adminonly实操心得第一次搭建时可以先使用HTTP和默认配置快速启动验证基本功能。确认无误后再关闭服务配置HTTPS证书和更严格的安全策略如关闭自注册。data_volume路径一定要提前规划好最好是一个独立的、大容量的挂载点避免将来镜像堆满系统盘。3.3 执行安装脚本配置好harbor.yml后就可以运行安装脚本了。安装脚本会执行以下操作加载Docker镜像、生成配置文件、初始化数据库、启动所有容器。# 在 /opt/harbor 目录下执行 sudo ./install.sh安装过程会在终端输出日志等待几分钟直到看到✔ ----Harbor has been installed and started successfully.----这样的成功提示。安装完成后可以使用docker-compose ps命令查看所有容器是否都处于Up (healthy)状态。cd /opt/harbor sudo docker-compose ps你应该能看到一长串服务包括nginx、portal、core、jobservice、registry、redis、database、trivy-adapter等状态都应该是健康的。3.4 访问WebUI与初始设置在浏览器中访问你配置的hostname如http://192.168.1.100。首次访问会跳转到登录页面。用户名admin密码你在harbor.yml中配置的harbor_admin_password例如Harbor12345。登录成功后我建议立即进行以下几项操作修改管理员密码在“系统管理” - “用户管理”中点击admin用户修改默认密码。创建一个新项目这是推送镜像的基本单位。点击“项目” - “新建项目”例如创建一个名为library的公共项目公开勾选或private-app这样的私有项目。可选创建机器人账号为了在CI/CD流水线中安全地推送镜像应该使用机器人账号Robot Account而非个人账号。在项目页面进入“机器人账户”标签页创建一个具有“推送和拉取”权限的账号系统会生成一个令牌Token这个令牌就是密码务必妥善保存因为它只显示一次。4. 客户端配置与镜像推送拉取实战仓库搭好了接下来就要让Docker客户端知道怎么使用它。4.1 配置Docker客户端信任私有仓库由于我们可能使用了HTTP或自签名HTTPSDocker客户端默认是不信任这类仓库的需要显式告知。对于Linux/macOS系统编辑Docker守护进程配置文件/etc/docker/daemon.json如果不存在则创建{ insecure-registries: [192.168.1.100:80] // 如果是HTTP需要这样配置 // 如果使用了自签名HTTPS则需要将CA证书放到指定位置并配置 registry-mirrors 或直接使用域名访问这里不配置 insecure-registries }重要提示insecure-registries仅用于测试或高度可信的内网环境。在生产环境务必配置有效的HTTPS证书。修改后重启Docker服务使配置生效sudo systemctl daemon-reload sudo systemctl restart docker对于Windows Docker Desktop在设置Settings- Docker Engine中修改daemon.json文件添加insecure-registries配置然后点击“Apply Restart”。4.2 登录私有仓库在命令行中使用docker login命令登录到你的Harbor。# 格式docker login [OPTIONS] [SERVER] docker login 192.168.1.100:80 # HTTP # 或 docker login harbor.yourcompany.com # HTTPS输入用户名admin或你创建的其他用户和密码。登录成功后凭证会保存在~/.docker/config.json文件中。4.3 镜像的推送与拉取全流程现在我们来完成一个完整的“构建 - 打标签 - 推送 - 拉取”的闭环。步骤1从现有镜像打标签假设我们本地有一个nginx:latest镜像想推送到Harbor的library项目中。# 给本地镜像打上符合私有仓库规范的标签 # 格式docker tag SOURCE_IMAGE[:TAG] HARBOR_HOST[/PROJECT]/REPOSITORY[:TAG] docker tag nginx:latest 192.168.1.100:80/library/nginx:latest步骤2推送镜像到私有仓库docker push 192.168.1.100:80/library/nginx:latest推送过程中终端会显示上传进度。完成后你可以在Harbor的WebUI中进入library项目看到刚刚推送的nginx镜像。步骤3从私有仓库拉取镜像在另一台配置好仓库地址并已登录的机器上可以直接拉取。docker pull 192.168.1.100:80/library/nginx:latest步骤4使用镜像拉取成功后就可以像使用任何其他Docker镜像一样使用它了。docker run -d -p 8080:80 --name my-nginx 192.168.1.100:80/library/nginx:latest4.4 使用机器人账号进行自动化推送在CI/CD脚本中使用交互式密码登录是不现实的。这时就需要用到之前创建的机器人账号令牌。# 使用机器人账号登录令牌作为密码 echo “你的机器人令牌” | docker login 192.168.1.100:80 --username “robot$project名账号名” --password-stdin # 后续的 tag 和 push 操作与普通账号无异 docker tag myapp:latest 192.168.1.100:80/private-app/myapp:${CI_COMMIT_SHA} docker push 192.168.1.100:80/private-app/myapp:${CI_COMMIT_SHA}踩坑记录机器人账号的用户名格式是robot$project_nameaccount_name这个格式很容易写错。务必从Harbor WebUI上创建时复制完整的用户名而不是自己拼接。5. 运维、升级与故障排查指南将Harbor部署起来只是第一步日常的运维保障其稳定运行同样重要。5.1 日常运维命令Harbor通过Docker Compose管理所有运维操作都应在/opt/harbor目录下进行。启动Harborsudo docker-compose up -d停止Harborsudo docker-compose down这会停止并删除容器但数据卷会保留查看日志查看所有服务日志sudo docker-compose logs跟踪特定服务如core日志sudo docker-compose logs -f core重启单个服务sudo docker-compose restart core查看服务状态sudo docker-compose ps5.2 数据备份与恢复备份Harbor的数据主要存在于两部分数据库存储在database容器内部或你配置的外部PostgreSQL中。镜像文件存储在data_volume配置的目录下如/data/harbor具体在registry和chart子目录中。最可靠的备份方式是备份整个数据卷目录tar czvf harbor-data-backup-$(date %Y%m%d).tar.gz /data/harbor使用pg_dump备份Harbor数据库如果使用内置数据库需要进入容器执行。Harbor官方也提供了更完善的 备份脚本和文档 。恢复恢复时需要先停止Harbor恢复数据文件然后重新运行./install.sh脚本它会识别已有的数据并初始化。5.3 版本升级Harbor的升级通常遵循以下步骤阅读目标版本的 Release Notes 和 升级指南 确认兼容性和注意事项。务必进行完整备份。停止当前Harborsudo docker-compose down下载新版本的离线安装包并解压。将旧版本的harbor.yml配置文件复制到新版本目录并根据新版本的模板调整可能变更的配置项。在新版本目录下运行升级脚本sudo ./upgrade.sh升级脚本会自动处理数据库迁移等操作。完成后使用docker-compose up -d启动。血泪教训升级前一定要备份并且最好在测试环境先演练一遍。我曾遇到过因跨越大版本升级导致数据库模式不兼容如果没有备份恢复起来会非常麻烦。5.4 常见问题与排查技巧在实际运营中你可能会遇到以下问题问题1推送镜像时报错 “http: server gave HTTP response to HTTPS client”原因Docker客户端试图用HTTPS协议与你的HTTP仓库通信。解决确保已在客户端的daemon.json中正确配置了insecure-registries并重启了Docker服务。问题2拉取/推送镜像速度非常慢原因可能是网络问题或者存储后端如磁盘IO性能瓶颈。排查在服务器上docker pull一个公共镜像测试基础网络和Docker守护进程是否正常。检查Harbor服务器磁盘IO使用率iostat -x 1。查看nginx或registry容器的日志看是否有错误或警告。问题3WebUI可以访问但docker login失败原因认证服务core可能有问题或者密码错误。排查检查core容器日志sudo docker-compose logs core | grep -i error确认数据库连接是否正常。可以进入postgresql容器连接数据库查看用户表。如果你修改了配置确保执行了sudo docker-compose up -d重启服务使配置生效。问题4磁盘空间不足原因镜像和垃圾数据不断累积。解决在WebUI上手动删除不需要的镜像标签或整个仓库。启用垃圾回收Garbage Collection。在Harbor WebUI的“系统管理” - “垃圾回收”中可以设置策略并立即运行。GC会删除那些没有被任何标签引用的镜像层Blobs释放空间。重要GC期间Registry会进入只读模式应安排在业务低峰期进行。问题5漏洞扫描器Trivy无法更新漏洞库原因服务器无法访问外网GitHub等。解决对于离线环境需要在能联网的机器上手动下载Trivy的漏洞数据库然后通过Harbor的“系统管理” - “漏洞数据库”页面进行离线更新。搭建和维护一个私有Docker Registry尤其是像Harbor这样功能全面的系统初期需要投入一些学习成本。但一旦它稳定运行起来为团队带来的效率提升和安全保障是巨大的。从手忙脚乱地传镜像包到一键部署、自动扫描这种体验的提升是革命性的。最关键的是把镜像资产掌握在自己手里心里踏实。