一、前提准备

1. GitLab Runner 安装与配置
2. 使用 Docker executor，并开启特权模式（privileged = true），以支持 Docker-in-Docker（DinD）或挂载宿主机 Docker socket。
3. Runner 配置示例（/etc/gitlab-runner/config.toml）：

[[runners]]
  name = "docker-runner"
  url = "https://gitlab.example.com/"
  token = "YOUR_RUNNER_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "docker:20.10.16"
    privileged = true             # 必须
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]

4. 在 GitLab 项目中配置 CI/CD 变量
5. HARBOR_REGISTRY：你的 Harbor 域名，例如 harbor.example.com
6. HARBOR_PROJECT：Harbor 中的项目名，如 my-app
7. HARBOR_USERNAME / HARBOR_PASSWORD：用于登录 Harbor 的账号凭证
8. （可选）IMAGE_NAME、IMAGE_TAG：自定义镜像名称和标签

二、.gitlab-ci.yml 示例

stages:
  - build
  - push

variables:
  DOCKER_DRIVER: overlay2
  # 镜像全路径
  IMAGE: "$HARBOR_REGISTRY/$HARBOR_PROJECT/$CI_PROJECT_NAME"

before_script:
  # 登录 Harbor
  - echo "$HARBOR_PASSWORD" | docker login -u "$HARBOR_USERNAME" --password-stdin "$HARBOR_REGISTRY"

build-image:
  stage: build
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  script:
    # 构建镜像并打上 commit SHA 作为 tag
    - docker build -t "$IMAGE:$CI_COMMIT_SHORT_SHA" .
    # 另打一个 latest tag
    - docker tag "$IMAGE:$CI_COMMIT_SHORT_SHA" "$IMAGE:latest"
  artifacts:
    expire_in: 1h
    reports:
      dotenv: .env   # 如果需要传递变量到后续阶段

push-image:
  stage: push
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  script:
    # 将两种 tag 的镜像推送到 Harbor
    - docker push "$IMAGE:$CI_COMMIT_SHORT_SHA"
    - docker push "$IMAGE:latest"

要点说明：

• DinD 服务：通过 services: - docker:dind 启动 Docker-in-Docker 容器，Runner 以特权模式连接它执行构建与推送。
• 登录凭证：在 before_script 中使用 CI 变量安全登录 Harbor。
• 多标签管理：同时推送基于 commit SHA 的不可变 tag 和 latest。
• 缓存与加速：可根据需要挂载 /cache 卷或配置 registry mirror，加快依赖下载。

三、流水线执行流程

1. 触发：每次 git push 或合并请求（MR）时，GitLab 自动触发 CI。
2. Build 阶段：
3. 启动 DinD 服务
4. docker build 构建镜像
5. 为镜像打上 SHA 和 latest 标签
6. Push 阶段：
7. 已登录的 Runner 将镜像推送到 Harbor
8. 完成后，你可以在 Harbor UI 中看到新镜像

四、常见问题与优化

• 登录失败：确认 CI 变量无误，Harbor 支持的认证方式（如 LDAP、OIDC）是否与凭证匹配。
• 构建超时：在项目设置中适当增加 pipeline 超时时间，或拆分镜像层次以复用缓存。
• 安全加固：尽量使用专用的 CI 账号和最小权限，避免在脚本中硬编码密码。
• 多架构镜像：可引入 Docker Buildx，通过 docker buildx 构建多平台镜像并推送。