Harbor 私有镜像仓库建设与 CI/CD 集成2

1. 项目背景与目标

背景：解决官方 Docker Hub 访问慢、公司代码泄露风险、镜像管理混乱及删除困难等问题。
目标：
1. 构建高可用、支持 HTTPS 的企业级 Harbor 仓库。
2. 实现从旧版 Registry 到 Harbor 的平滑迁移。
3. 集成 Docker Compose 实现镜像自动构建、打标、推送流水线。
4. 建立主从同步机制保障跨地域/灾备能力。

2. 技术选型

组件	选型版本	理由
轻量级仓库	`registry:3.0.0`	仅用于学习或极简环境，内存占用 <20MB。
企业级仓库	`Harbor v2.14.0`	功能完善 (RBAC, 复制, 扫描)，避免 v2.15.0 Bug。
编排工具	`Docker Compose`	Harbor 原生依赖，用于服务编排与生命周期管理。
负载均衡	`Keepalived + Nginx`	实现 Harbor 双机热备与 VIP 漂移。
存储后端	`Local/NFS/S3`	生产环境推荐对接对象存储以实现高可用。

3. 实施阶段一：轻量级 Registry 快速验证 (POC)

适用场景：开发测试环境，无需认证，快速搭建。

3.1 部署命令

# 1. 拉取并运行 (host 模式，数据持久化)
docker run -d --network host --restart=always --name oldboyedu-registry \
  -v /var/lib/registry:/var/lib/registry \
  registry:3.0.0

# 2. 验证端口
ss -ntl | grep 5000

3.2 客户端配置 (关键)

由于默认 HTTP 协议，客户端必须配置 insecure-registries。

# 编辑 /etc/docker/daemon.json
{
  "insecure-registries": ["10.0.0.93:5000"]
}
# 重启生效
systemctl restart docker

3.3 核心操作流

# 1. 打标
docker tag alpine:3.20.2 10.0.0.93:5000/oldboyedu-linux/alpine:3.20.2

# 2. 推送
docker push 10.0.0.93:5000/oldboyedu-linux/alpine:3.20.2

# 3. 删除镜像 (需手动清理元数据 + 垃圾回收)
docker exec oldboyedu-registry rm -rf /var/lib/registry/docker/registry/v2/repositories/oldboyedu-linux
docker exec oldboyedu-registry registry garbage-collect /etc/distribution/config.yml

# 注意：若删除后推送失败 (缓存 Bug)，需重启容器
docker restart oldboyedu-registry

4. 实施阶段二：Harbor 企业级仓库部署 (生产标准)

适用场景：生产环境，需认证、HTTPS、项目管理。

4.1 安装准备

# 1. 下载与解压 (推荐 v2.14.0)
wget https://github.com/goharbor/harbor/releases/download/v2.14.0/harbor-offline-installer-v2.14.0.tgz
tar xf harbor-offline-installer-v2.14.0.tgz -C /usr/local/
cd /usr/local/harbor

# 2. 配置文件 (harbor.yml)
cp harbor.yml{.tmpl,}
vim harbor.yml
# 修改项:
# hostname: 10.0.0.91 (或域名)
# harbor_admin_password: 1 (生产请改强密码)
# data_volume: /var/lib/harbor
# 注释掉 https 相关配置 (若暂未申请证书)

4.2 安装与验证

# 1. 执行安装脚本
./install.sh

# 2. 检查服务状态 (所有容器需为 Up/healthy)
docker-compose ps -a

# 3. 访问 WebUI
# https://10.0.0.91/harbor/projects (admin / 1)

4.3 客户端对接 Harbor

# 1. 配置 insecure (若未配 HTTPS)
echo '{"insecure-registries": ["10.0.0.91"]}' > /etc/docker/daemon.json
systemctl restart docker

# 2. 登录仓库
docker login -u admin -p 1 10.0.0.91

# 3. 推送流程
docker tag mysql:8.0.36-oracle 10.0.0.91/oldboyedu-db/mysql:8.0.36-oracle
docker push 10.0.0.91/oldboyedu-db/mysql:8.0.36-oracle

5. 实施阶段三：高级功能与迁移

5.1 旧 Registry 迁移至 Harbor

利用 Harbor 复制规则 (Replication) 功能，无需停机。

配置源仓库：Harbor WebUI -> 系统管理 -> 仓库管理 -> 新建仓库 (类型选 Docker Registry，填旧仓库 IP)。
创建复制规则：WebUI -> 复制管理 -> 新建规则 (源：旧仓库，目标：Harbor 项目，模式：手动/定时)。
执行复制：触发规则，等待同步完成。

5.2 Harbor 主从同步 (异地容灾)

架构：主节点 (91) <-推送-> 从节点 (92)。
配置：在从节点 Harbor 配置复制规则，源为主节点，触发模式设为“基于事件 (Event Based)”。
验证：主节点 Push 镜像，从节点自动拉取同步。

5.3 启用 HTTPS (安全加固)

# 1. 放置证书
unzip harbor.yinzhengjie.com_nginx.zip -d /usr/local/harbor/

# 2. 修改 harbor.yml
hostname: harbor.yinzhengjie.com
https:
  port: 443
  certificate: /usr/local/harbor/.../harbor.yinzhengjie.com_bundle.crt
  private_key: /usr/local/harbor/.../harbor.yinzhengjie.com.key

# 3. 重生成配置并重启
./prepare
./install.sh

6. 实施阶段四：自动化构建与推送 (CI/CD 集成)

目标：通过 docker-compose 一键完成 Build & Push。

6.1 项目结构

project/
├── web.dockerfile       # 多阶段构建或基础镜像定义
├── docker-compose.yaml  # 编排与构建配置
└── index.html           # 业务文件

6.2 核心配置文件 (`docker-compose.yaml`)

services:
  web01:
    build:
      context: .
      dockerfile: web.dockerfile
      args:
        data: "production-v1"  # 动态构建参数
    image: harbor.yinzhengjie.com/oldboyedu-lb/homework:prod-v1
    container_name: web-prod-01
    
  web02:
    build:
      context: .
      dockerfile: web.dockerfile
      args:
        data: "production-v2"
    image: harbor.yinzhengjie.com/oldboyedu-lb/homework:prod-v2
    container_name: web-prod-02

6.3 自动化执行脚本

#!/bin/bash
set -e

HARBOR_URL="harbor.yinzhengjie.com"
USER="admin"
PASS="1"

echo " 登录 Harbor..."
docker login -u $USER -p $PASS $HARBOR_URL

echo " 构建镜像..."
docker-compose build

echo " 推送镜像..."
docker-compose push

echo " 退出登录..."
docker logout $HARBOR_URL

echo " 完成！"

7. 实施阶段五：高可用 (HA) 架构

方案：Keepalived + 双 Harbor 节点 + 共享存储 (或复制模式)。

7.1 Keepalived 配置要点

VIP: 10.0.0.99
检测脚本: 监测 Harbor Nginx 端口 (8443/80)。
模式: nopreempt (非抢占模式)，防止网络抖动导致 VIP 频繁漂移。

7.2 故障切换验证

访问 https://10.0.0.99 确认正常。
关闭 Master 节点 (init 0)。
观察 VIP 是否漂移到 Backup 节点 (ip addr show)。
验证 Push/Pull 操作是否中断。

8. 常见故障排查 (Troubleshooting)

现象	错误信息	解决方案
协议不匹配	`http: server gave HTTP response to HTTPS client`	客户端 `/etc/docker/daemon.json` 添加 `insecure-registries`。
权限拒绝	`unauthorized: unauthorized to access repository`	执行 `docker login` 重新认证；检查项目是否为“公开”。
删除无效	删除镜像后 Pull 报 `manifest unknown`	Registry 缓存 Bug，执行 `docker restart` 重启容器。
证书报错	浏览器拦截 HTTPS 访问	自签名证书需在浏览器输入 `thisisunsafe` 强制信任。
项目删不掉	WebUI 删除项目按钮灰色	必须先删除项目下所有镜像，清空回收站。

9. 项目交付物清单

Harbor 运行环境：双节点部署，HTTPS 开启，VIP 浮动正常。
镜像资产：核心业务镜像已推送到 Harbor 仓库。
自动化脚本：build_push.sh 脚本，支持一键编译推送。
运维文档：包含账号权限规划、备份策略及故障处理手册。