Docker搭建Harbor私有镜像仓库（命令行模式）全流程指南

一、引言：为何选择Harbor？

在容器化部署日益普及的今天，私有镜像仓库成为企业保障镜像安全、控制访问权限的核心基础设施。Harbor作为VMware开源的企业级Registry解决方案，不仅提供基础的镜像存储功能，还集成了用户认证、权限管理、镜像复制、漏洞扫描等高级特性。相比原生Docker Registry，Harbor的Web界面和API设计更符合企业级需求，而通过Docker命令行部署则能快速实现轻量化安装，尤其适合开发测试环境或资源受限的场景。

二、环境准备：前置条件检查

1. 硬件要求

最低配置：2核CPU、4GB内存、20GB磁盘空间（生产环境建议翻倍）
网络要求：开放80（HTTP）、443（HTTPS）、22（若启用SSH）端口

2. 软件依赖

Docker引擎：版本≥19.03（通过docker version验证）
Docker Compose：版本≥1.25（通过docker-compose version验证）
操作系统：CentOS 7/8、Ubuntu 18.04/20.04等主流Linux发行版

3. 域名与证书（HTTPS场景）

若需启用HTTPS，需提前准备：

域名（如harbor.example.com）
SSL证书（PEM格式，包含全链证书和私钥）
修改本地/etc/hosts文件映射域名到服务器IP

三、命令行部署四步曲

步骤1：下载Harbor安装包

# 选择最新稳定版（示例为v2.9.0）
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz
tar -xzf harbor-offline-installer-v2.9.0.tgz
cd harbor

步骤2：配置harbor.yml

编辑harbor.yml文件，关键配置项如下：

hostname: harbor.example.com  # 必须与域名一致
http:
  port: 80
https:
  port: 443
  certificate: /path/to/your/cert.pem
  private_key: /path/to/your/key.pem
harbor_admin_password: Harbor12345  # 默认管理员密码
database:
  password: root123  # 数据库密码

注意事项：

生产环境必须启用HTTPS
密码需满足复杂度要求（至少8位，含大小写字母和数字）
配置修改后需执行./prepare命令重新生成配置

步骤3：执行安装命令

# 安装前确保Docker服务已启动
sudo systemctl start docker
# 运行安装脚本（自动拉取依赖镜像并启动容器）
sudo ./install.sh

预期输出：

[Step 0]: checking installation environment ...
[Step 1]: loading Harbor images ...
[Step 2]: preparing environment ...
[Step 3]: starting Harbor ...
Created symlink /etc/systemd/system/docker.service.d → /etc/systemd/system/docker.service.wants.
✅ --Harbor has been installed and started successfully.--

步骤4：验证部署结果

# 检查容器运行状态
docker-compose ps
# 预期输出（所有服务显示Up状态）
Name                     Command                  State                    Ports
-----------------------------------------------------------------------------------------------------
harbor-core         /harbor/entrypoint.sh            Up (healthy)
harbor-db           /docker-entrypoint.sh            Up (healthy)   5432/tcp
harbor-jobservice   /harbor/entrypoint.sh            Up (healthy)
harbor-log          /bin/sh -c /usr/local/bin/ ...   Up (healthy)   127.0.0.1:1514->10514/tcp
harbor-portal       nginx -g daemon off;             Up (healthy)   8080/tcp
nginx               nginx -g daemon off;             Up (healthy)   0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp
redis               redis-server /etc/redis.conf     Up (healthy)   6379/tcp
registry            /home/harbor/entrypoint.sh       Up (healthy)   5000/tcp
registryctl         /home/harbor/start.sh            Up (healthy)

四、进阶配置与管理

1. 用户与项目管理

# 登录Harbor（首次登录需修改默认密码）
docker login harbor.example.com
# 通过API创建项目（需获取管理员Token）
curl -u "admin:Harbor12345" -X POST "https://harbor.example.com/api/v2.0/projects" -H "accept: application/json" -d '{"project_name": "devops", "public": false}'

2. 镜像操作示例

# 推送镜像到Harbor
docker tag nginx:latest harbor.example.com/devops/nginx:v1
docker push harbor.example.com/devops/nginx:v1
# 从Harbor拉取镜像
docker pull harbor.example.com/devops/nginx:v1

3. 备份与恢复

# 备份数据库（需进入harbor-db容器）
docker exec -it harbor-db bash
pg_dump -U postgres -h 127.0.0.1 registry > /tmp/registry.sql
exit
# 从容器拷贝备份文件到宿主机
docker cp harbor-db:/tmp/registry.sql ./

五、常见问题解决方案

问题1：端口冲突

现象：Error starting userland proxy: listen tcp 0.0.0.0 bind: address already in use
解决：

# 查找占用端口的进程
sudo lsof -i :80
# 终止冲突进程或修改Harbor配置使用其他端口

问题2：证书验证失败

现象：x509: certificate signed by unknown authority
解决：

# 将证书添加到Docker信任链
sudo mkdir -p /etc/docker/certs.d/harbor.example.com
sudo cp your_cert.pem /etc/docker/certs.d/harbor.example.com/ca.crt
sudo systemctl restart docker

问题3：性能优化建议

存储驱动：生产环境建议使用overlay2驱动
资源限制：通过docker-compose.yml为各服务设置CPU/内存限制
日志轮转：配置logrotate管理日志文件大小

六、升级与卸载指南

升级步骤

# 1. 备份当前数据
./prepare --conf ./harbor.yml.bak
# 2. 下载新版本安装包
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
# 3. 修改配置文件后执行
sudo ./install.sh --with-notary --with-clair  # 按需添加组件

完全卸载

# 停止并删除容器
docker-compose down -v
# 删除持久化数据（谨慎操作！）
sudo rm -rf /data/database /data/registry

七、总结与最佳实践

安全优先：始终启用HTTPS，定期轮换证书和密码
监控告警：集成Prometheus+Grafana监控仓库指标
高可用方案：主从部署+对象存储（如MinIO）作为后端
CI/CD集成：在Jenkins/GitLab中配置Harbor作为可信镜像源

通过本文的命令行部署方案，开发者可在30分钟内完成Harbor私有仓库的搭建，为容器化应用提供安全可靠的镜像管理环境。实际生产环境中，建议结合企业LDAP/OAuth2进行统一认证，并定期执行漏洞扫描确保镜像安全。

Docker搭建Harbor私有镜像仓库全攻略：命令行模式详解