Docker搭建Harbor私有镜像仓库全攻略（命令行模式）

2025年11月15日 互联网

Docker搭建Harbor私有镜像仓库全攻略（命令行模式）

在容器化技术日益普及的今天，私有镜像仓库成为企业保障镜像安全、加速部署效率的关键基础设施。Harbor作为CNCF（云原生计算基金会）毕业的开源项目，凭借其强大的权限管理、镜像复制、漏洞扫描等功能，成为众多企业的首选。本文将详细阐述如何通过命令行模式，使用Docker快速搭建Harbor私有镜像仓库，为开发者及企业用户提供一套可复制、易操作的解决方案。

一、环境准备：确保基础条件满足

1.1 硬件与软件要求

  • 硬件：至少4GB内存（推荐8GB以上），20GB以上可用磁盘空间，确保网络连接稳定。
  • 软件：Docker（版本18.09或更高）、Docker Compose（用于编排Harbor服务）、Git（用于获取Harbor安装文件）。

1.2 系统兼容性

Harbor支持在Linux（如Ubuntu、CentOS）及macOS上运行，Windows用户可通过WSL2或Docker Desktop for Windows进行。本文以Ubuntu 20.04 LTS为例，其他系统可参照调整。

二、安装Docker与Docker Compose

2.1 安装Docker

  1. # 更新软件包索引
  2. sudo apt-get update
  4. # 安装依赖
  5. sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
  7. # 添加Docker官方GPG密钥
  8. curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  10. # 添加Docker APT仓库
  11. sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
  13. # 安装Docker CE
  14. sudo apt-get update
  15. sudo apt-get install -y docker-ce docker-ce-cli containerd.io
  17. # 验证安装
  18. sudo docker run hello-world

2.2 安装Docker Compose

  1. # 下载最新版Docker Compose
  2. sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  4. # 赋予执行权限
  5. sudo chmod +x /usr/local/bin/docker-compose
  7. # 验证安装
  8. docker-compose --version

三、下载并配置Harbor

3.1 获取Harbor安装文件

  1. # 克隆Harbor仓库（或直接下载release包）
  2. git clone https://github.com/goharbor/harbor.git
  3. cd harbor
  5. # 切换到稳定版本（如2.4.0）
  6. git checkout v2.4.0

3.2 配置Harbor

编辑harbor.yml文件，主要修改以下参数：

  1. # 主机名，需为FQDN或IP，确保可访问
  2. hostname: your-harbor-domain.com
  4. # HTTP/HTTPS配置，生产环境建议启用HTTPS
  5. https:
  6.   certificate: /path/to/your/certificate.pem
  7.   private_key: /path/to/your/private_key.pem
  9. # Harbor管理员密码
  10. harbor_admin_password: Harbor12345
  12. # 数据库配置（默认使用内置PostgreSQL）
  13. database:
  14.   password: root123
  15.   # 如需外部数据库，取消注释并配置
  16.   # external_database:
  17.   #   harbor:
  18.   #     host: your-db-host
  19.   #     port: 5432
  20.   #     db_name: harbor
  21.   #     username: harbor
  22.   #     password: your-db-password
  23.   #     ssl_mode: disable

3.3 生成配置文件

  1. # 生成配置文件（包括Docker Compose文件）
  2. ./prepare

四、启动Harbor服务

4.1 使用Docker Compose启动

  1. # 启动Harbor所有服务
  2. docker-compose up -d
  4. # 检查服务状态
  5. docker-compose ps

4.2 验证Harbor运行

访问https://your-harbor-domain.com（或HTTP端口，根据配置），使用默认管理员账号admin和配置的密码登录，确认Harbor界面可正常访问。

五、配置客户端使用Harbor

5.1 配置Docker信任Harbor

  1. # 编辑或创建/etc/docker/daemon.json，添加insecure-registries（如使用HTTP）
  2. {
  3.   "insecure-registries": ["your-harbor-domain.com"]
  4. }
  6. # 重启Docker服务
  7. sudo systemctl restart docker

5.2 登录Harbor

  1. # 使用docker login命令登录Harbor
  2. docker login your-harbor-domain.com
  3. # 输入用户名和密码

5.3 推送与拉取镜像

  1. # 标记本地镜像
  2. docker tag your-image:tag your-harbor-domain.com/your-project/your-image:tag
  4. # 推送镜像到Harbor
  5. docker push your-harbor-domain.com/your-project/your-image:tag
  7. # 从Harbor拉取镜像
  8. docker pull your-harbor-domain.com/your-project/your-image:tag

六、高级配置与优化

6.1 启用HTTPS

生产环境强烈建议启用HTTPS，通过配置harbor.yml中的https部分，并准备有效的SSL证书和私钥。

6.2 配置镜像复制

Harbor支持镜像复制功能，可将镜像同步至其他Harbor实例或云存储，实现高可用和灾难恢复。在Harbor Web界面或通过API配置复制规则。

6.3 集成LDAP/AD认证

对于企业环境，可集成LDAP或Active Directory进行用户认证，简化用户管理。在harbor.yml中配置LDAP相关参数。

6.4 定期维护与备份

  • 日志管理：定期清理Harbor日志，避免磁盘空间耗尽。
  • 数据库备份：定期备份Harbor数据库，确保数据安全。
  • 升级Harbor：关注Harbor官方发布的新版本，及时升级以获取新功能和安全补丁。

七、常见问题与解决方案

7.1 端口冲突

确保Harbor使用的端口（如80、443、4443）未被其他服务占用，可通过修改harbor.yml中的port参数调整。

7.2 数据库连接失败

检查数据库配置是否正确，包括主机名、端口、用户名、密码及SSL模式。如使用外部数据库，确保数据库服务已启动且网络可达。

7.3 镜像推送/拉取失败

  • 检查Docker是否信任Harbor（insecure-registries配置）。
  • 确认登录Harbor成功，且具有推送/拉取权限。
  • 检查网络连接，确保客户端可访问Harbor服务器。

八、总结与展望

通过本文的详细步骤，开发者及企业用户已能够成功使用Docker命令行模式搭建Harbor私有镜像仓库。Harbor不仅提供了安全的镜像存储解决方案，还通过丰富的功能如权限管理、镜像复制、漏洞扫描等，助力企业实现高效的容器化部署。未来，随着容器技术的不断发展，Harbor将持续演进，为用户提供更加稳定、安全、易用的私有镜像仓库服务。

最新文章