# YAML 没写错，客户的第一条 GitLab 流水线照样会失败

> 自托管实例上，元凶多半是镜像仓库没启用或 Runner 不许特权模式，动笔前先问清楚。

原文: https://fdetimes.net/zh/tools/gitlab-self-managed-runners-registry-fde/

前线部署工程师（FDE）到了客户那里，很少能自己选 CI 工具。已经自行托管 GitLab 的公司，通常希望一切都在自家基础设施内运行：代码、流水线、镜像都是如此。

因此，真正有价值的能力是快速摸清客户的 GitLab，并在第一周写出一条能跑通的流水线。要打交道的有三样东西：流水线文件、Runner 和镜像仓库。在自托管实例上，每一样都有各自的卡点。

## 流水线只是一个文件，关键在于顺序

流水线在 `.gitlab-ci.yml` 中声明。如果不声明 `stages`，GitLab 会使用默认的 `.pre`、`build`、`test`、`deploy`、`.post`。`stages` 中各项的顺序决定哪些作业先运行。

条件分两层。`workflow:rules` 决定流水线是否会被创建，没有任何规则匹配时，流水线就不会运行。作业级的 rules 则决定每个作业是否会被创建。

假设你要为客户的数据团队部署一个检索增强生成（RAG）API。你希望流水线只在 main 分支上运行：先跑测试，再构建镜像并推送到镜像仓库，最后部署：

```yaml
workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

stages: [test, build, deploy]

unit-test:
  stage: test
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - pytest -q

build-image:
  stage: build
  image: docker:27.3
  services:
    - docker:27.3-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - echo "$CI_JOB_TOKEN" | docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"

deploy:
  stage: deploy
  image: alpine:3.20
  script:
    - ./deploy.sh "$CI_COMMIT_SHORT_SHA"
```

在脑子里跑一遍。向 `feature/chunking` 分支提交代码不会创建流水线，因为唯一的规则不匹配。如果你在等一条始终不出现的流水线，第一个该查的是 `workflow:rules`，而不是 Runner。

构建作业使用 GitLab 的预定义变量登录，而不是写死 `gitlab.customer.local:5050` 这样的地址。只有通过 Let's Encrypt 集成自动启用镜像仓库时，5050 才是默认端口。如果客户的管理员是手动配置的镜像仓库，主机和端口很可能不一样。

镜像名称仍遵循“仓库/命名空间/项目”的格式，因此从名称就能看出镜像属于哪个项目。docker 镜像版本已固定，并且启用了 TLS，这是 GitLab 对使用 Docker-in-Docker 的建议。

## 你的作业由哪个 Runner 来跑？

YAML 文件本身什么也不会运行。作业由 Runner 执行，Runner 是运行 GitLab Runner 应用的代理程序。GitLab Runner 是开源软件，采用 MIT 许可证，在 gitlab-org/gitlab-runner 项目中公开开发。

Runner 有三种范围：实例、群组和项目。项目 Runner 适合需要独立配置、凭据和安全控制的项目。对处理客户敏感数据的 FDE 来说，通常应该申请这一种。自托管 Runner 支持三种执行器：Shell、Docker 和 Kubernetes。

Docker 执行器在独立的容器中运行每个作业，与其他作业隔离。镜像按 `config.toml` 中设置的拉取策略拉取，默认值是 `always`。

在示例流水线里数一数：三个作业用了三个镜像，加上构建作业的 `docker:27.3-dind` 服务，一共四个镜像。在 `always` 策略下，每次推送到 main 都要拉取四次；整个团队都在提交时，这个数字会迅速翻倍增长。GitLab 的依赖代理可以缓解 Docker Hub 速率限制带来的压力。

作业量大时，值得考虑 Kubernetes 执行器，两个公开案例说明了原因。CERN 把 Runner 从 Docker 已停止开发的工具 Docker machine 迁移到 Kubernetes，可在 20 多个节点上按需从 0 扩展到 100 个 Pod。

SeatGeek 用 Kubernetes 执行器替换了 Nomad 上固定规模的 Runner，每个作业使用一个用完即弃的 Pod。它迁移了 600 多个代码仓库，并发作业数翻了一番，平均等待时间从 16 秒降到 2 秒。

## 自托管 GitLab 上的三个陷阱

第一个陷阱是镜像仓库。在 Omnibus 安装中，只有使用内置的 Let's Encrypt 集成时，镜像仓库才会在 5050 端口上自动启用；否则需要管理员手动配置并启用。在确认镜像仓库正在运行之前，不要写 `docker push` 作业。

第二个陷阱是特权模式。上面的 `build-image` 作业使用了 Docker-in-Docker，这要求 Runner 以特权模式运行。GitLab 警告，这种模式实际上会关闭容器的安全机制，让宿主机面临权限提升的风险。

在银行或医院，答案很可能是不行。这时就得和客户的基础设施团队一起重新设计镜像构建作业，而且这件事要在承诺交付日期之前弄清楚。

第三个陷阱是与订阅层级挂钩的功能。GitLab 的对比表列出了一些仅在部分 Self-Managed 层级提供的功能，例如容器镜像仓库的依赖代理、Geo 和灾难恢复。依赖这些功能之前，先问清客户用的是哪个层级。

**要点:** 好的 CI 修复不会把重复劳动转嫁给别人。

GitLab 的解决方案架构师提醒，为某个团队优化 Runner 资源，可能会把重复的杂活推给开发者。他们建议的问题值得随身带着：这个修复会不会给任何人制造重复劳动？

对 FDE 来说，这个问题分量更重。你离开之后，要和这条流水线长期共处的是客户。

## 先学什么

按你在客户那里遇到问题的顺序来学。先学 `stages` 和 `rules` 的语法，因为正如 `feature/chunking` 的例子所示，“流水线没跑”这类问题通常就出在这里。接着学习如何用 Docker 执行器注册项目 Runner。最后学会阅读 `config.toml`，并按镜像仓库的格式给镜像命名。

面试 FDE 岗位时，可以直接问：公司的客户自托管工具的比例大概有多高？答案能告诉你将在谁的基础设施里工作，也能让面试官看出你理解这份工作的实际内容。

简历上，一句具体的描述比一串工具名更有分量，例如：“编写了一条在专用项目 Runner 上运行的三阶段 GitLab 流水线，并在构建镜像前与客户安全团队就特权模式达成一致”。

在客户现场，第一条流水线也是在检验你是否理解他们的基础设施。写下第一行 YAML 之前，先仔细问清镜像仓库、Runner 和特权模式。

**本周动手试试:**

- 在自己的机器上安装使用 Docker 执行器的 GitLab Runner，将其注册为项目 Runner，并运行本文中的三阶段流水线
- 打开 Runner 的 config.toml，找到正在使用的拉取策略，数一数一条流水线（含服务）要拉取多少个镜像
- 为客户的 GitLab 管理员拟好五个问题：镜像仓库是否启用、使用哪个端口、Runner 是什么范围、用哪种执行器、是否允许特权模式

## 信源

- [Runners | GitLab Docs](https://docs.gitlab.com/ci/runners/)

- [CI/CD YAML syntax reference | GitLab Docs](https://docs.gitlab.com/ci/yaml/)

- [GitLab container registry administration | GitLab Docs](https://docs.gitlab.com/administration/packages/container_registry/)

- [GitLab container registry | GitLab Docs](https://docs.gitlab.com/user/packages/container_registry/)

- [Docker executor | GitLab Runner docs](https://docs.gitlab.com/runner/executors/docker/)

- [Use Docker-in-Docker | GitLab Docs](https://docs.gitlab.com/ci/docker/docker_in_docker/)

- [GitLab Runner project (gitlab-org/gitlab-runner)](https://gitlab.com/gitlab-org/gitlab-runner)

- [Self-Managed Feature Comparison | GitLab](https://about.gitlab.com/pricing/feature-comparison/)

- [GitLab Runners and Kubernetes: A Powerful Duo for CI/CD](https://kubernetes.web.cern.ch/blog/2023/12/06/gitlab-runners-and-kubernetes-a-powerful-duo-for-ci/cd/)

- [CI Runner Re-architecture (SeatGeek Chairnerd)](https://chairnerd.seatgeek.com/ci-runner-rearchitecture)

- [A story of runner scaling | GitLab Blog](https://about.gitlab.com/blog/a-story-of-runner-scaling/)
