15.9.2 私有仓库搭建与配置（Registry/Harbor）

私有镜像仓库用于在内网安全、稳定地存储与分发镜像，常见实现包括官方 Registry 与企业级 Harbor。Registry 轻量、部署简单，适合小规模；Harbor 提供权限、审计、扫描与复制等企业特性，适合生产环境。

原理草图：镜像推送/拉取与仓库组件

Registry 搭建与配置（单机示例）#

1）安装与运行

# 1. 创建数据目录
sudo mkdir -p /data/registry

# 2. 拉取官方镜像
docker pull registry:2

# 3. 运行（映射 5000 端口，持久化数据）
docker run -d --name registry \
  -p 5000:5000 \
  -v /data/registry:/var/lib/registry \
  --restart=always \
  registry:2

# 4. 验证服务
curl -s http://127.0.0.1:5000/v2/ | jq .
# 预期：返回 {} 或空 JSON 对象

命令解释
- -p 5000:5000：暴露 Registry API 默认端口。
- -v /data/registry:/var/lib/registry：镜像层存储持久化。
- /v2/：Registry V2 API 健康检查入口。

2）TLS 与基础认证（生产必做）

生成自签证书并启用 htpasswd 认证（示例域名：reg.example.com）：

# 1. 生成证书
sudo mkdir -p /etc/registry/certs /etc/registry/auth
openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout /etc/registry/certs/registry.key \
  -x509 -days 365 \
  -out /etc/registry/certs/registry.crt \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=Ops/OU=Dev/CN=reg.example.com"

# 2. 创建认证文件（用户名: devops）
docker run --rm --entrypoint htpasswd \
  httpd:2 -Bbn devops 'StrongPassw0rd' \
  | sudo tee /etc/registry/auth/htpasswd

# 3. 运行带 TLS + 基础认证的 Registry
docker run -d --name registry \
  -p 5000:5000 \
  -v /data/registry:/var/lib/registry \
  -v /etc/registry/certs:/certs \
  -v /etc/registry/auth:/auth \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/registry.key \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  --restart=always \
  registry:2

客户端信任证书（Docker）：

sudo mkdir -p /etc/docker/certs.d/reg.example.com:5000
sudo cp /etc/registry/certs/registry.crt \
  /etc/docker/certs.d/reg.example.com:5000/ca.crt

sudo systemctl restart docker

3）推送/拉取验证

# 登录
docker login reg.example.com:5000
# 用户名: devops
# 密码: StrongPassw0rd

# 打标签并推送
docker pull nginx:1.25
docker tag nginx:1.25 reg.example.com:5000/base/nginx:1.25
docker push reg.example.com:5000/base/nginx:1.25

# 拉取验证
docker rmi reg.example.com:5000/base/nginx:1.25
docker pull reg.example.com:5000/base/nginx:1.25

4）垃圾回收（删除后释放空间）

# 1. 开启删除功能（registry config.yml）
cat >/etc/registry/config.yml <<'EOF'
version: 0.1
storage:
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true
http:
  addr: :5000
EOF

# 2. 以配置文件运行
docker run -d --name registry \
  -p 5000:5000 \
  -v /data/registry:/var/lib/registry \
  -v /etc/registry/config.yml:/etc/docker/registry/config.yml \
  --restart=always \
  registry:2

# 3. 执行垃圾回收（需要停写入）
docker exec -it registry registry garbage-collect /etc/docker/registry/config.yml

Registry 常见排错
- x509: certificate signed by unknown authority
解决：在客户端安装 CA 证书并重启 Docker。
- denied: requested access to the resource is denied
解决：确认 docker login 与仓库权限，镜像命名符合 reg.example.com:5000/namespace/name:tag。
- manifest unknown
解决：确认镜像标签存在，重新 docker push。

---

Harbor 搭建与配置（离线安装包示例）#

1）准备与安装

# 1. 下载离线安装包并解压
tar zxvf harbor-offline-installer-v2.8.0.tgz
cd harbor

# 2. 复制并编辑配置
cp harbor.yml.tmpl harbor.yml
sed -i 's/hostname: reg.mydomain.com/hostname: harbor.example.com/' harbor.yml

# 3. 配置证书路径（确保证书已签发）
# harbor.yml 中关键项：
# https:
#   port: 443
#   certificate: /data/certs/harbor.crt
#   private_key: /data/certs/harbor.key

# 4. 启动 Harbor
./install.sh --with-trivy

# 5. 访问 UI
# https://harbor.example.com
# 默认管理员：admin/Harbor12345（首次登录请立即修改）

Harbor 组件与目录结构

harbor/
├── harbor.yml                 # 主配置
├── common/                    # 组件配置与证书
├── data/                      # 持久化数据
├── docker-compose.yml         # 组件编排
└── logs/                      # 日志

2）配置外部数据库与存储（示意）

# harbor.yml 样例片段（关键项）
database:
  type: external
  external:
    host: 10.0.0.10
    port: 5432
    username: harbor
    password: HarborDBPass
    db_name: registry

storage_service:
  filesystem:
    rootdirectory: /data/harbor

3）创建项目、权限与机器人账号

步骤：UI -> Projects -> New Project
- Project Name: base
- Access Level: Private
- 成员角色：Developer(推送)、Guest(拉取)
- Robot Account：用于 CI/CD 免交互登录

4）镜像复制（跨机房示例）

UI -> Administration -> Registries
- 添加目标仓库（目标 Harbor/Registry）
- 创建 Replication Rule：
  - Source: harbor.example.com
  - Destination: harbor-dr.example.com
  - Trigger: Manual/Scheduled
  - Filter: project=base, tag=*

Harbor 常见排错
- UI 无法访问：检查 docker ps 组件状态、nginx 端口、证书路径。
- jobservice 任务失败：检查 logs/jobservice.log 与权限配置。
- 扫描失败：确认 Trivy 数据库更新与网络访问，检查 scanner 容器日志。

---

客户端配置与使用建议#

Docker / Containerd 信任证书

# Docker 证书目录
sudo mkdir -p /etc/docker/certs.d/harbor.example.com
sudo cp /data/certs/harbor.crt /etc/docker/certs.d/harbor.example.com/ca.crt
sudo systemctl restart docker

命名规范与版本策略

# 推荐命名：<registry>/<project>/<app>:<semver>
docker tag app:1.2.3 harbor.example.com/base/app:1.2.3
docker push harbor.example.com/base/app:1.2.3

---

运维要点（备份/监控/高可用）#

备份与恢复要点

# 备份 Harbor 数据（简化示例）
tar zcvf /backup/harbor-data-$(date +%F).tgz /data/harbor /data/database

# 恢复：
# 停止 Harbor -> 恢复数据 -> 启动 Harbor

监控指标建议
- 存储容量与增长率
- 复制任务成功率
- 扫描失败率
- API 请求延迟

---

练习与实操任务#

1. 部署 Registry，开启 TLS 与 htpasswd 认证，推送 nginx:1.25 并成功拉取。
2. 在 Harbor 创建私有项目 base，配置机器人账号并用于 CI 推送。
3. 配置跨站点复制规则，并手动触发一次复制任务。
4. 模拟证书不信任错误，修复后重新登录并推送镜像。

---

快速检查清单（上线前）#

• [ ] 证书与域名正确，客户端已信任
• [ ] 认证与权限策略已启用
• [ ] 数据目录已持久化
• [ ] 备份策略与恢复演练完成
• [ ] 监控与日志可用