自建私有镜像仓库与K8s集群部署全流程指南

2026年4月3日 互联网

一、私有镜像仓库建设背景

在容器化应用大规模落地的场景中，企业常面临以下痛点：公共镜像仓库下载速度慢、镜像安全难以保障、多环境镜像同步复杂。通过自建私有镜像仓库，可实现镜像集中管理、权限控制、网络加速等核心需求，为Kubernetes集群提供稳定可靠的镜像源。

二、环境准备与工具安装

1. 服务器基础配置

建议采用双节点架构：

  • 管理节点：负责镜像仓库的部署与维护
  • 计算节点：运行Kubernetes集群及业务容器

系统要求：

  • CentOS 7.6+/Ubuntu 20.04+
  • Docker 20.10+
  • 4核8G以上配置（生产环境）

2. 依赖组件安装

  1. # 安装Docker（所有节点）
  2. curl -fsSL https://get.docker.com | sh
  3. systemctl enable --now docker
  5. # 安装Docker Compose（管理节点）
  6. curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  7. chmod +x /usr/local/bin/docker-compose

三、私有镜像仓库部署

1. 仓库软件获取与解压

  1. # 下载稳定版本（示例使用v2.14.1）
  2. wget https://github.com/goharbor/harbor/releases/download/v2.14.1/harbor-online-installer-v2.14.1.tgz
  3. tar -xvzf harbor-online-installer-v2.14.1.tgz
  4. cd harbor

2. 证书配置（HTTPS安全通信）

生成自签名证书（生产环境建议使用CA证书）：

  1. openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  2.     -keyout /root/harbor.key -out /root/harbor.pem \
  3.     -subj "/CN=reg.example.com"

DNS解析配置：

  • 在DNS服务器添加A记录：reg.example.com → 192.168.4.9
  • 本地hosts文件临时解析（测试环境）： 
    1. echo "192.168.4.9 reg.example.com" >> /etc/hosts

3. 配置文件定制

修改harbor.yml核心参数：

  1. hostname: reg.example.com
  2. http:
  3.   port: 80
  4. https:
  5.   port: 443
  6.   certificate: /root/harbor.pem
  7.   private_key: /root/harbor.key
  8. # 持久化存储配置（建议使用独立存储卷）
  9. data_volume: /data/harbor

4. 部署与验证

  1. # 预处理配置
  2. ./prepare
  4. # 启动服务
  5. docker-compose up -d
  7. # 验证服务状态
  8. docker-compose ps
  9. # 正常状态应显示所有容器为"Up"

四、Kubernetes集群配置

1. 节点Docker信任配置

修改计算节点Docker配置：

  1. {
  2.   "insecure-registries": ["reg.example.com"]
  3. }

重启服务生效：

  1. systemctl restart docker
  2. docker info | grep "Insecure Registries"  # 验证配置

2. 镜像拉取认证

创建Kubernetes Secret：

  1. kubectl create secret docker-registry harbor-cred \
  2.   --docker-server=reg.example.com \
  3.   --docker-username=admin \
  4.   --docker-password=Harbor12345

在Pod配置中引用：

  1. spec:
  2.   imagePullSecrets:
  3.   - name: harbor-cred
  4.   containers:
  5.   - name: demo
  6.     image: reg.example.com/library/nginx:latest

五、应用部署实践

1. 镜像推送示例

  1. # 登录私有仓库
  2. docker login reg.example.com
  4. # 标记并推送镜像
  5. docker tag nginx:latest reg.example.com/library/nginx:latest
  6. docker push reg.example.com/library/nginx:latest

2. Kubernetes部署案例

以Uptime-Kuma监控系统为例：

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: uptime-kuma
  5. spec:
  6.   replicas: 1
  7.   selector:
  8.     matchLabels:
  9.       app: uptime-kuma
  10.   template:
  11.     metadata:
  12.       labels:
  13.         app: uptime-kuma
  14.     spec:
  15.       containers:
  16.       - name: uptime-kuma
  17.         image: reg.example.com/library/uptime-kuma:1
  18.         ports:
  19.         - containerPort: 3001
  20.         volumeMounts:
  21.         - name: data-volume
  22.           mountPath: /app/data
  23.       volumes:
  24.       - name: data-volume
  25.         persistentVolumeClaim:
  26.           claimName: uptime-pvc
  27. ---
  28. apiVersion: v1
  29. kind: Service
  30. metadata:
  31.   name: uptime-kuma
  32. spec:
  33.   selector:
  34.     app: uptime-kuma
  35.   ports:
  36.     - protocol: TCP
  37.       port: 80
  38.       targetPort: 3001
  39.   type: ClusterIP

六、运维管理最佳实践

  1. 备份策略：

    • 每日镜像元数据备份
    • 每周全量数据备份
    • 备份文件存储于对象存储服务

  2. 监控告警：

    • 监控仓库存储使用率
    • 跟踪镜像拉取成功率
    • 设置磁盘空间预警阈值

  3. 升级维护：

    • 版本升级前执行完整备份
    • 先在测试环境验证升级流程
    • 升级过程中保留旧版本容器

七、常见问题处理

  1. 证书错误处理：

    • 检查证书链完整性
    • 验证域名与证书CN匹配
    • 清除Docker证书缓存：rm -rf /etc/docker/certs.d/*

  2. 网络连接问题：

    • 检查防火墙规则是否放行443端口
    • 验证DNS解析是否正常
    • 使用curl -v https://reg.example.com测试连通性

  3. 权限拒绝错误：

    • 检查Kubernetes ServiceAccount权限
    • 验证imagePullSecret配置
    • 查看Harbor项目成员权限设置

通过完整实施上述方案，企业可构建起安全可靠的容器镜像管理体系，实现从镜像构建、存储到部署的全生命周期管控。该架构已通过多个生产环境验证，可支撑日均百万级镜像拉取请求，满足金融、制造等行业对容器化平台的高可用要求。

最新文章