自建 Harbor和配置私有仓库认证笔记

一、Harbor 简介

Harbor 是由 VMware 开源的企业级 Docker Registry 项目，提供：

• 图形化 Web UI
• 基于角色的访问控制（RBAC）
• 镜像复制（同步）
• LDAP/AD 集成
• 镜像漏洞扫描（需 Trivy）
• HTTPS 支持
• 审计日志等

适用于企业私有镜像仓库部署。

二、自建 Harbor 镜像仓库（基于 Linux）

环境要求

• 操作系统：Linux（推荐 CentOS 7/8、Ubuntu 20.04+）
• Docker：20.10+
• Docker Compose：2.0+
• 至少 4GB 内存（推荐 8GB）
• 域名（可选，但 HTTPS 强烈建议）

步骤 1：安装 Docker 和 Docker Compose

# 安装 Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

验证：

docker --version
docker-compose --version

步骤 2：下载 Harbor 安装包

前往 Harbor GitHub Releases 下载 offline installer（离线包，包含所有依赖）。

# 示例（以 v2.10.0 为例，请替换为最新版）
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar -zxvf harbor-offline-installer-v2.10.0.tgz
cd harbor

步骤 3：配置 harbor.yml

复制模板并编辑：

cp harbor.yml.tmpl harbor.yml
vim harbor.yml

关键配置项：

# 必填：访问地址（建议使用域名，如 harbor.example.com）
hostname: harbor.yourdomain.com

# HTTP/HTTPS 设置（生产环境强烈建议 HTTPS）
# 如果没有证书，可先用 HTTP（不推荐生产使用）
http:
  port: 80

# 若启用 HTTPS（推荐）：
# https:
#   port: 443
#   certificate: /your-path/harbor.yourdomain.com.crt
#   private_key: /your-path/harbor.yourdomain.com.key

# 数据库和 admin 密码
harbor_admin_password: YourStrongPassword123!

# 数据存储路径
data_volume: /data/harbor

# 其他保持默认即可

⚠️ 注意：如果使用 IP 访问（如 192.168.1.100），hostname 必须设为该 IP，且后续 Docker 客户端需配置 insecure-registries（见下文）。

步骤 4：运行安装脚本

sudo ./install.sh

安装完成后，访问 http://<your-hostname>，使用账号 admin 和你设置的密码登录。

三、配置 Docker 客户端使用私有 Harbor 仓库

场景 1：Harbor 使用 HTTP（非 HTTPS）

Docker 默认只允许 HTTPS 的 registry，若使用 HTTP，需在客户端配置信任。

在 Docker 客户端（拉取/推送镜像的机器）上操作：

编辑 Docker 配置文件：

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "insecure-registries": ["harbor.yourdomain.com", "192.168.1.100"]
}
EOF

替换为你的 Harbor 地址（域名或 IP）

重启 Docker：

sudo systemctl daemon-reload
sudo systemctl restart docker

场景 2：Harbor 使用 HTTPS（推荐）

将 Harbor 的 CA 证书（或自签名证书）添加到 Docker 客户端的信任链：

# 假设你的证书为 harbor.crt
sudo mkdir -p /etc/docker/certs.d/harbor.yourdomain.com/
sudo cp harbor.crt /etc/docker/certs.d/harbor.yourdomain.com/ca.crt

不需要配置 insecure-registries，也不需要重启 Docker（部分系统可能需要）。

四、Docker 登录 Harbor 并推送/拉取镜像

1. 登录 Harbor

docker login harbor.yourdomain.com
# 或
docker login 192.168.1.100

输入用户名（如 admin）和密码。

登录信息保存在 ~/.docker/config.json

2. 推送镜像到 Harbor

Harbor 中的镜像命名格式为：

<registry>/<project>/<image>:<tag>

示例：

# 1. 标记本地镜像
docker tag nginx:latest harbor.yourdomain.com/library/nginx:latest

# 2. 推送
docker push harbor.yourdomain.com/library/nginx:latest

⚠️ 注意：library 是 Harbor 中创建的项目名（需提前在 Web UI 中创建，并设置为公开或私有）。

3. 从 Harbor 拉取镜像

docker pull harbor.yourdomain.com/library/nginx:latest

五、Harbor 项目权限管理（简要）

1. 登录 Harbor Web UI
2. 创建项目（如 dev-team）
3. 在 成员 中添加用户或 LDAP 用户
4. 分配角色：访客（只读）、开发者（读写）、管理员（管理项目）
5. 推送镜像时使用对应项目路径：harbor.yourdomain.com/dev-team/app:1.0

六、常见问题排查

七、补充：使用 Let's Encrypt 免费证书启用 HTTPS（可选）

如果你有公网域名，可用 Certbot 获取免费证书：

# 安装 certbot
sudo yum install -y certbot

# 获取证书（需 80 端口开放）
sudo certbot certonly --standalone -d harbor.yourdomain.com

# 证书路径：
# /etc/letsencrypt/live/harbor.yourdomain.com/fullchain.pem  → certificate
# /etc/letsencrypt/live/harbor.yourdomain.com/privkey.pem   → private_key

然后在 harbor.yml 中配置 HTTPS 并重新安装：

./prepare
docker-compose down
docker-compose up -d

总结