Docker 容器技术入门与实践 (三)：Docker私有仓库-程序员充电站

Docker私有仓库

前言

在之前的章节中，我们探讨了 Docker 的基本概念、镜像构建与管理以及容器的运行操作。随着容器化应用规模的扩大，集中管理、安全分发和高效协作镜像变得至关重要。Docker Hub 等公共仓库虽方便，但受限于网络、安全策略、私有镜像托管需求以及潜在的带宽和访问限制，私有 Docker 镜像仓库成为企业级容器平台不可或缺的基础设施。本文将深入介绍 Docker 私有仓库的核心概念，并以当前主流的开源企业级解决方案Harbor为例，详细阐述如何在OpenEuler操作系统上部署、配置、使用 Harbor 私有仓库，涵盖其功能特性、部署步骤、工作原理、使用场景及最佳实践。

第一部分：Docker 私有仓库概述

需求背景
- 安全隔离：企业内部应用镜像通常包含敏感代码或配置信息，直接推送至公共仓库存在泄露风险。
- 访问速度：局域网或专有网络内访问私有仓库速度远快于公网拉取。
- 带宽控制：减少对公网带宽的依赖和消耗，尤其在大规模部署时。
- 版本管理：集中存储和管理团队内部构建的所有镜像版本，便于回滚和审计。
- 协作效率：为开发、测试、运维团队提供统一的镜像分发中心。
- 合规要求：满足特定行业或企业对数据本地化存储的合规性要求。
核心概念
- Registry：Docker 镜像仓库服务的核心组件，实现了 Docker Registry API，负责存储镜像及其元数据（manifest, layers, tags 等）。Docker 官方提供了registry镜像用于搭建基础的私有仓库。
- Index：一个 Registry 实例可以包含多个仓库（Repository）。
- Repository：存储特定项目或应用所有版本镜像的集合。名称通常由<namespace>/<image_name>组成（例如library/nginx）。
- Tag：用于标识同一 Repository 中镜像的不同版本（例如latest,1.0.0,v2）。
- Manifest：描述镜像构成的 JSON 文件，包含镜像配置、层（Layer）摘要信息等。
- Blob (Layer)：镜像的每一层都是一个不可变的 Blob 对象，存储实际的文件系统变更内容。
基础 Registry vs. Harbor
- 基础 Registry (registry:2):功能简洁，仅提供最核心的镜像存储和分发 API。缺乏用户管理、UI界面、安全扫描、复制等高级功能。
- Harbor:在基础 Registry 之上构建，添加了大量企业级功能：
  - 友好的图形用户界面 (GUI)
  - 多租户（项目、用户、角色）
  - 基于角色的访问控制 (RBAC)
  - 镜像漏洞扫描 (集成 Clair/Trivy)
  - 镜像签名与验签 (Notary)
  - 镜像复制（跨实例同步）
  - LDAP/AD 集成
  - 审计日志
  - RESTful API

第二部分：Harbor 简介与核心功能

Harbor (CNCF 毕业项目) 是一个开源、可信赖、功能强大的云原生注册表项目，用于存储、签名和扫描容器镜像、Helm Chart 等符合 OCI (Open Container Initiative) 标准的制品。

主要功能特性
- 安全：
  - 用户认证与授权 (本地数据库、LDAP/AD、OIDC)
  - RBAC (项目管理员、开发者、访客等角色)
  - 镜像漏洞扫描 (CVE 检测)
  - 内容信任 (使用 Notary 签名镜像)
  - TLS 加密通信
  - 安全加固的默认配置
- 管理：
  - 多租户项目管理
  - 镜像清理策略 (按标签、数量、存储空间)
  - 垃圾回收 (清理未引用 Blob)
  - 审计日志 (操作记录)
  - 系统配置管理
- 效率：
  - 镜像复制 (Push/Pull 模式，跨数据中心同步)
  - Webhook 通知 (事件触发)
  - 标签保留策略 (防止重要标签被删除)
  - RESTful API 支持自动化
- 可用性：
  - 支持高可用部署模式 (需结合外部数据库、Redis 和存储)
  - 可扩展的存储后端 (本地文件系统、S3、Azure Blob、GCS、Swift、MinIO 等)
  - 健康检查
核心组件
- Core Service:提供 UI、API 服务，协调其他组件。
- Registry:底层的 Docker Registry V2 服务，处理镜像存储和分发。
- Job Service:执行异步任务，如镜像复制、漏洞扫描、垃圾回收。
- Portal (UI):Harbor 的 Web 用户界面。
- Log:收集其他组件的日志 (通常集成外部日志服务)。
- Adminserver:(已弃用或功能整合) 处理配置管理。
- Notary:(可选) 提供内容信任（签名）服务。
- Trivy/Clair Adapter:(可选) 集成漏洞扫描器。
- Chartmuseum:(可选) 存储 Helm Chart (在较新版本中，Helm Chart 支持可能通过 OCI Registry 实现)。
- Redis:缓存和 Job Service 的队列存储。
- Database:存储 Harbor 的元数据（用户、项目、策略等），支持 PostgreSQL (默认)、MySQL。
- Storage:存储实际的镜像 Blob 和 Chart 文件。

第三部分：OpenEuler 系统准备

OpenEuler 是一款开源的企业级 Linux 发行版，以其高性能、高安全性、高可靠性著称，非常适合作为生产环境的基础操作系统。部署 Harbor 前需确保环境满足要求。

系统要求
- 硬件：至少 2 CPU 核心，4 GB 内存 (具体视负载而定)，充足磁盘空间 (存储镜像)。
- 软件：
  - OpenEuler 20.03 LTS SP3 / 22.03 LTS 或更高版本 (推荐 LTS 版本)。
  - Docker Engine (版本需与 Harbor 兼容，通常要求较新版本，如 20.10+)。注意：OpenEuler 默认可能使用iSulad，部署 Harbor 需要标准的 Docker Engine。
  - Docker Compose (用于单机或小规模部署)。
  - OpenSSL (用于生成证书)。
  - wget或curl(下载安装包)。

安装 Docker Engine由于 OpenEuler 默认容器运行时可能是iSulad，我们需要安装标准的 Docker CE。

# 1. 卸载可能存在的旧版本或冲突包 sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine iSulad* # 2. 安装依赖 sudo dnf install -y yum-utils device-mapper-persistent-data lvm2 # 3. 添加 Docker CE 的稳定版仓库 (请根据 OpenEuler 版本选择合适的 repo) # 例如，对于 OpenEuler 20.03 LTS SP3, 可能需要添加 CentOS 7 的 repo (需验证兼容性) # 更推荐从 Docker 官方获取适用于 OpenEuler 的包或使用其他兼容源 (如 openEuler 社区可能有维护) # 这里假设使用一个兼容的 repo (实际操作需查询当前可用源) sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 4. 安装 Docker CE sudo dnf install -y docker-ce docker-ce-cli containerd.io # 5. 启动并设置开机自启 sudo systemctl start docker sudo systemctl enable docker # 6. 验证安装 sudo docker run hello-world

安装 Docker Compose下载最新版的 Docker Compose 二进制文件。

# 获取最新版本号 (例如 v2.20.3) COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d '"' -f 4) # 下载并安装 sudo curl -L "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # 赋予执行权限 sudo chmod +x /usr/local/bin/docker-compose # 验证安装 docker-compose --version

防火墙配置Harbor 需要开放特定端口供访问。

# 查看当前防火墙状态 (假设使用 firewalld) sudo systemctl status firewalld # 如果未开启，则启动 sudo systemctl start firewalld sudo systemctl enable firewalld # 开放 Harbor 常用端口 (HTTP/HTTPS, 管理端口等) sudo firewall-cmd --permanent --add-port=80/tcp # HTTP (可选，如果只用 HTTPS) sudo firewall-cmd --permanent --add-port=443/tcp # HTTPS sudo firewall-cmd --permanent --add-port=4443/tcp # Notary (可选) sudo firewall-cmd --permanent --add-port=5432/tcp # PostgreSQL (如果使用外部数据库且需要远程管理) # 根据实际需求开放其他端口 (如 SSH 22) # 重载防火墙规则 sudo firewall-cmd --reload # 查看已开放端口 sudo firewall-cmd --list-ports

第四部分：Harbor 部署实践 (OpenEuler)

我们采用 Harbor 官方推荐的离线安装包方式进行部署。这种方式包含了所有必要的镜像和配置模板。

下载 Harbor 离线安装包访问 Harbor GitHub Releases 页面 (https://github.com/goharbor/harbor/releases) 下载适合 OpenEuler 架构 (通常是 x86_64) 的最新稳定版离线包 (如harbor-offline-installer-v2.10.0.tgz)。

# 创建安装目录 sudo mkdir -p /opt/harbor cd /opt/harbor # 下载 (替换为实际版本和 URL) sudo wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz # 解压 sudo tar xzvf harbor-offline-installer-v2.10.0.tgz cd harbor

准备 TLS 证书 (HTTPS 强烈推荐)生产环境必须使用 HTTPS 保障安全。可以使用自签名证书或从受信任 CA 获取证书。

自签名证书 (测试/内部用):

# 创建证书存放目录 sudo mkdir -p /data/cert cd /data/cert # 生成 CA 私钥 sudo openssl genrsa -out ca.key 4096 # 生成 CA 证书 (有效期 10 年) sudo openssl req -x509 -new -nodes -sha512 -days 3650 \ -subj "/C=CN/ST=State/L=City/O=Org/OU=Unit/CN=Harbor-CA" \ -key ca.key \ -out ca.crt # 生成服务器私钥 sudo openssl genrsa -out harbor.yourdomain.com.key 4096 # 替换 yourdomain.com # 生成证书签名请求 (CSR) sudo openssl req -sha512 -new \ -subj "/C=CN/ST=State/L=City/O=Org/OU=Unit/CN=harbor.yourdomain.com" \ # 替换 -key harbor.yourdomain.com.key \ -out harbor.yourdomain.com.csr # 生成 x509 v3 扩展文件 (解决 Docker 客户端不信任问题) cat > v3.ext <<-EOF authorityKeyIdentifier=keyid,issuer basicConstraints=CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment extendedKeyUsage = serverAuth subjectAltName = @alt_names [alt_names] DNS.1=harbor.yourdomain.com # 替换 DNS.2=yourhostname # 替换为实际主机名 (可选) IP.1=192.168.1.100 # 替换为 Harbor 服务器 IP (可选) EOF # 使用 CA 签署服务器证书 sudo openssl x509 -req -sha512 -days 3650 \ -extfile v3.ext \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -in harbor.yourdomain.com.csr \ -out harbor.yourdomain.com.crt # 将服务器证书和私钥转换为 Docker 客户端可用的格式 (.cert 文件通常包含证书链) # 将 .crt 文件内容复制到 .cert 文件 (如果只有单证书) sudo cp harbor.yourdomain.com.crt harbor.yourdomain.com.cert # 或者将 .crt 和 CA 证书合并 (如果 Docker 客户端需要信任 CA) # sudo cat harbor.yourdomain.com.crt ca.crt > harbor.yourdomain.com.cert

重要：将自签名 CA 证书 (ca.crt) 分发并信任到所有需要使用 Harbor 的 Docker 客户端机器上 (通常放入/etc/docker/certs.d/harbor.yourdomain.com/ca.crt或/etc/pki/ca-trust/source/anchors/并执行update-ca-trust)。

受信任 CA 证书：向 Let's Encrypt、企业内 CA 或商业 CA 申请证书，获得yourdomain.com.crt(或包含证书链的bundle.crt) 和yourdomain.com.key。确保证书的 Common Name (CN) 或 Subject Alternative Name (SAN) 包含 Harbor 的访问域名。

配置 Harbor修改 Harbor 的配置文件harbor.yml。

sudo cp harbor.yml.tmpl harbor.yml sudo vi harbor.yml

关键配置项 (根据实际情况修改)：

# 主机名 - 必须与证书的 CN 或 SAN 匹配，也是客户端访问的地址 hostname: harbor.yourdomain.com # 替换 # HTTP 端口 (可选，禁用则设为空) http: port: 80 # HTTPS 端口 https: port: 443 certificate: /data/cert/harbor.yourdomain.com.cert # 替换为你的证书路径 (.cert 或 .crt) private_key: /data/cert/harbor.yourdomain.com.key # 替换为你的私钥路径 # 管理员初始密码 (务必修改!) harbor_admin_password: Harbor12345 # 强烈建议修改为强密码 # 数据库配置 (单机部署默认使用内置 PostgreSQL) database: password: root123 # 建议修改内置数据库密码 max_idle_conns: 50 max_open_conns: 100 # 数据存储路径 (默认 /data) data_volume: /data # 启用 Trivy 漏洞扫描器 (可选) trivy: enabled: true # github_token: # 如果需要扫描私有镜像可能需要 token # 如果需要内容信任 (Notary) notary: enabled: false # 根据需求启用 # 外部 URL (用于 UI 和 Email 中的链接) external_url: https://harbor.yourdomain.com # 替换 # 邮件配置 (可选，用于通知) email: enabled: false # smtp_server: smtp.example.com # smtp_port: 25 # username: user@example.com # password: pass # from: from@example.com # ssl_mode: true/false # 其他高级配置如复制策略、清理策略、日志等可根据需求调整

安装 Harbor执行安装脚本。脚本会解析harbor.yml，拉取所需镜像 (离线包已包含)，并启动容器。
```
sudo ./install.sh
```
安装成功后会看到类似输出：
```
[Step 0]: checking if docker is installed ... ... ✔ ----Harbor has been installed and started successfully.----
```
验证 Harbor 服务
- 检查容器状态：
```
sudo docker compose ls # 或 sudo docker-compose ps
```
  应看到harbor-portal,harbor-core,harbor-db,redis,registry,registryctl,harbor-jobservice,harbor-log(及可选的trivy-adapter,notary-server,notary-signer) 等容器处于running状态。
- 访问 Web UI：在浏览器中打开https://harbor.yourdomain.com(或http://如果未启用 HTTPS)。使用用户名admin和你在harbor.yml中设置的harbor_admin_password登录。
- Docker 客户端测试登录 (在已信任 CA 的客户端机器上)：
```
docker login harbor.yourdomain.com
```
  输入用户名密码 (如admin和其密码)。

第五部分：Harbor 使用与管理

基本概念与 UI 导航
- 项目 (Project):镜像存储的逻辑单元，是访问控制的基本单位。每个项目下有多个仓库 (Repository)。建议按团队或应用创建项目 (如team-alpha,project-webapp)。
- 仓库 (Repository):属于某个项目，存放特定镜像的所有版本。名称格式为<project_name>/<image_name>(如team-alpha/backend-api)。
- 标签 (Tag):标识镜像版本。Harbor UI 提供标签管理视图。
- 成员 (Member):项目成员及其角色 (项目管理员、维护者、开发者、访客)。RBAC 控制成员对项目内镜像的操作权限。
- 审计日志 (Audit Log):记录用户在 Harbor 上的关键操作 (创建项目、推送/拉取镜像、删除等)。
- 系统管理:管理员 (admin) 可以进行全局配置、用户管理、系统设置、垃圾回收、查看日志等。
操作实践
- 创建项目：登录 UI ->Projects->New Project。设置项目名称 (需唯一)、访问级别 (公开Public或私有Private)。私有项目需要用户权限才能访问。
- 推送镜像到 Harbor：
  1. 登录 Docker 客户端到 Harbor：
```
docker login harbor.yourdomain.com
```
  2. 给本地镜像打标签，指定目标项目/仓库：
```
docker tag your-local-image:tag harbor.yourdomain.com/project-name/repo-name:tag # 例如: docker tag nginx:latest harbor.yourdomain.com/library/nginx:latest
```
  3. 推送镜像：
```
docker push harbor.yourdomain.com/project-name/repo-name:tag
```
  4. 在 Harbor UI 的对应项目下查看新推送的镜像和标签。
- 从 Harbor 拉取镜像：
```
docker pull harbor.yourdomain.com/project-name/repo-name:tag
```
- 用户管理：
  - 本地用户：Administration->Users->New User。设置用户名、邮箱、密码、权限 (普通用户或管理员)。
  - LDAP/AD 集成：Administration->Configuration->Authentication。选择 LDAP/AD 模式，配置服务器地址、Base DN、Bind DN、密码、属性映射等。测试成功后保存。用户登录时将使用 LDAP/AD 凭证。
- 漏洞扫描 (启用 Trivy 后)：在镜像仓库视图或标签视图，点击Scan按钮触发扫描。扫描完成后查看报告，了解镜像中的 CVE 漏洞及严重性。
- 垃圾回收：Administration->Garbage Collection。设置策略后执行 GC，删除未被任何 Manifest 引用的 Blob (层) 以释放存储空间。注意：执行 GC 期间 Registry 可能暂时不可写。
- 清理策略：Project-> 选择项目 ->Configuration->Cleanup Policy。设置规则自动清理旧标签 (按数量、按时间、保留最新latest等)。

内容信任 (Notary)如果启用 Notary，可以进行镜像签名和验签。

签名镜像：

# 配置 Docker 客户端信任 Harbor Notary 服务 export DOCKER_CONTENT_TRUST=1 export DOCKER_CONTENT_TRUST_SERVER=https://harbor.yourdomain.com:4443 # 替换 # 推送镜像时会自动签名 docker push harbor.yourdomain.com/project-name/repo-name:signed-tag

拉取并验签：

export DOCKER_CONTENT_TRUST=1 docker pull harbor.yourdomain.com/project-name/repo-name:signed-tag # 会自动验证签名

镜像复制用于在不同 Harbor 实例间同步镜像。配置在Administration->Registries(目标 Registry) 和Replication(策略)。
- 创建目标 Registry 连接 (类型 Harbor, URL, 凭证)。
- 创建复制策略：选择源资源 (项目、仓库、标签过滤器)，选择目标 Registry 和项目，设置触发模式 (手动、定时、事件驱动)。

第六部分：应用场景与最佳实践

典型应用场景
- 企业内部 CI/CD 流水线：Jenkins/GitLab CI 构建镜像后自动推送到私有 Harbor，供后续测试和部署环节拉取。
- 开发团队协作：开发人员共享基础镜像和应用镜像。
- 生产环境部署：Kubernetes (kubelet) 或 Docker Swarm 直接从私有 Harbor 拉取镜像部署服务。
- 混合云/多数据中心：通过 Harbor 的复制功能同步镜像，实现灾备或就近访问。
- 安全合规：集中进行漏洞扫描，确保部署的镜像符合安全基线；审计镜像操作历史。
- Helm Chart 仓库：存储和管理 Helm Chart (通过 OCI 特性或 Chartmuseum)。
最佳实践
- 强制 HTTPS：生产环境禁用 HTTP，仅使用 HTTPS。
- 强密码策略：为admin用户设置强密码，定期更换。
- 最小权限原则：使用 RBAC，为不同用户/团队分配精确的项目权限 (访客只读，开发者可推送，管理员管理项目)。
- 启用漏洞扫描：集成 Trivy 或 Clair，并将其作为 CI/CD 流水线或部署前置检查的一部分。
- 定期垃圾回收：设置计划任务或在存储空间紧张时手动执行 GC。
- 标签管理策略：使用清理策略自动删除过时的、临时的或测试用的镜像标签，避免存储膨胀。避免过度使用latest。
- 备份：定期备份 Harbor 的数据卷 (/data默认包含数据库数据、Redis 数据、镜像存储) 和配置文件 (harbor.yml)。Harbor 也提供数据库 dump 工具。
- 监控与告警：监控 Harbor 容器状态、API 响应时间、存储空间、CPU/内存使用率。配置 Webhook 接收关键事件通知。
- 高可用考虑：对于生产关键系统，考虑部署 Harbor HA 集群 (需要外部高可用数据库、Redis 和共享存储如 NFS/Ceph/S3)。
- 存储后端：根据性能和可靠性需求选择合适的存储后端 (本地 SSD 性能好但扩展性差；S3/MinIO 扩展性好)。确保存储有备份和冗余。

第七部分：故障排除与维护

常见问题
- 无法登录 UI / Docker 无法登录：检查网络、防火墙、域名解析 (或/etc/hosts)、证书信任 (Docker 客户端)、密码是否正确、Harbor 服务是否正常运行 (docker compose ps)。
- 推送镜像失败：
  - 网络问题 (访问 Registry 端口)。
  - 证书问题 (客户端不信任 CA 或 CN/SAN 不匹配)。检查客户端信任的 CA 证书，检查harbor.yml中hostname和证书是否匹配。
  - 权限不足 (用户不是项目成员或角色无推送权限)。
  - 存储空间不足 (查看数据卷/data空间)。
- 拉取镜像慢：检查网络带宽、Harbor 服务器性能、存储性能。考虑使用镜像缓存或复制到边缘节点。
- 漏洞扫描失败：检查 Trivy 适配器容器日志 (docker logs <trivy-adapter-container-id>)，网络是否通 (访问 Trivy DB 源)，是否需配置代理或 GitHub Token。
- Harbor 容器启动失败：查看具体容器的日志 (docker logs <container-id>)。常见原因：配置文件harbor.yml语法错误、端口冲突、依赖服务 (数据库/Redis) 启动失败、存储权限问题 (/data目录权限需对容器用户开放)。
日志查看
- Harbor 各组件的日志默认输出到标准输出，可通过docker logs <container-name>查看。
- 日志文件也持久化在数据卷/var/log/harbor/(或harbor.yml中log_location指定路径) 下，按组件分文件。
升级 Harbor
1. 备份数据库 (pg_dump) 和配置文件 (harbor.yml)。
2. 停止 Harbor (docker compose down)。
3. 下载新版本的离线安装包。
4. 解压新包，将旧harbor.yml和data目录 (或其中的secret等关键子目录) 复制到新目录。
5. 根据新版本的 Release Notes 检查harbor.yml的变更，必要时更新配置。
6. 在新目录执行sudo ./install.sh。安装脚本会自动迁移数据库和配置。
备份与恢复
- 数据库备份：使用pg_dump备份 PostgreSQL 数据库 (或mysqldump如果使用 MySQL)。
- 配置文件备份：harbor.yml。
- 数据卷备份：/data目录下的registry(镜像 Blob)、database(PostgreSQL 数据 - 但更推荐pg_dump)、redis、ca_download(证书) 等子目录。确保备份时 Harbor 已停止或使用存储快照功能。
- 恢复：停止 Harbor，恢复数据库、配置文件、数据卷，然后重新安装 (sudo ./install.sh)。

总结

部署 Harbor 作为 Docker 私有仓库是构建企业级容器平台的关键一步。通过在 OpenEuler 系统上实施 Harbor，我们获得了安全、高效、可控的镜像管理能力。本文详细介绍了 Harbor 的功能、在 OpenEuler 上的部署步骤、核心概念、日常操作、应用场景以及运维最佳实践。掌握 Harbor 的使用，能够极大地提升容器化应用的开发、交付和运维效率，并满足安全合规要求。随着容器技术的深入发展，Harbor 作为 CNCF 毕业项目，将持续演进，提供更强大的云原生制品管理能力。