在極狐 GitLab（或 GitLab）上跑 CI 任務時，可以用官方提供的 Runner，也可以在自己的服務器（這里是阿里云的 ECS） 上裝自定義Runner，把任務放到自己機器上執(zhí)行。
概念理解
GitLab CI Runner：用來執(zhí)行 CI/CD 流水線里定義的 job 的程序。流水線觸發(fā)后，由 Runner 拉取代碼、按 .gitlab-ci.yml 里的步驟在指定環(huán)境里執(zhí)行（如 build、test、deploy），可以理解成運行在服務器上的任務執(zhí)行器。
Runner 與標簽（tags）：一個 GitLab 項目/實例下可以有多個 Runner。在 CI 里通過 tags 指定用哪類 Runner 跑某個 job；只有「帶對應 tag」的 Runner 會接這個 job。例如給自建 Runner 打上 node、docker，在 job 里寫 tags: [node] 就會用這臺自建 Runner 跑。
Docker in Docker（DinD）：在Docker容器內(nèi)部運行Docker守護進程的方式，允許在單個容器中運行多個Docker服務，比如容器里運行在 CI job 里再跑 Docker（例如構建鏡像）時，會用到 DinD 服務。
配置步驟
1. 安裝啟動 gitlab-runner
可用 uname -a 確認系統(tǒng)架構，使用不同的安裝方法，在創(chuàng)建 runner 的時候可以找到具體配置方法，這里是以 CentOS7 為例：
# 下載極狐 GitLab 提供的 Runner 二進制（amd64）
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.gitlab.cn/latest/binaries/gitlab-runner-linux-amd64
# 賦予可執(zhí)行權限
sudo chmod +x /usr/local/bin/gitlab-runner
# 創(chuàng)建專用系統(tǒng)用戶
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
# 以 gitlab-runner 用戶安裝并啟動服務
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
2. 創(chuàng)建自定義 Runner
在項目或群組/實例的 CI/CD → Runners 里新增 Runner，設置名稱和要綁定的 tags（如 node、docker）
創(chuàng)建完成后頁面上會給出 registration token，后面 gitlab-runner register 會使用上。
自建 Runner 這里的標簽（tag）按需填寫，CI job 中只有配置符合的 tags 標簽時才會使用對應的 Runner，后續(xù)也可以編輯。
3. 注冊 Runner
在已安裝 gitlab-runner 的 服務器上執(zhí)行注冊，按提示填寫 runner 名稱、url、選擇執(zhí)行器等。
# 交互式注冊（將 <runner-token> 換成上一步拿到的 token）
gitlab-runner register \
--url https://jihulab.com \
--token <runner-token>
# 按提示：輸入 Runner 描述名、選擇 executor（如 docker）、默認鏡像等
# 執(zhí)行器類型可查：https://docs.gitlab.cn/docs/runner/executors/#compatibility-chart
# 注冊完成后，可前臺跑一次，確認能拉取到作業(yè)（調(diào)試用）
gitlab-runner run
4.確認 Runner 狀態(tài)
在 CI/CD → Runners 里看該 Runner 是否顯示為綠色在線。綠色表示已連上并可接收 job。
5. 使用 Runner
在 .gitlab-ci.yml 里給 job 加上 tags，即可讓該 job 只由帶對應 tag 的自建 Runner 執(zhí)行。
build-job:
stage: build
tags:
- node # 與自建 Runner 上配置的標簽一致
問題踩坑
gitlab-runner 用戶不在 Docker 組
按官方文檔只做默認安裝時，gitlab-runner 用戶通常不在 docker 組里，用 Docker 執(zhí)行器或在 job 里執(zhí)行 docker 命令會權限不足。需要把該用戶加入 docker 組并重新登錄會話后重啟服務。
# 將 gitlab-runner 加入 docker 組
sudo usermod -aG docker gitlab-runner
# 停止 Runner，以便后續(xù)用新組權限啟動
sudo gitlab-runner stop
# 退出當前 SSH 會話再重連，或執(zhí)行下面命令使組生效后再啟動
exec su - $USER
# 重新啟動 Runner
sudo gitlab-runner start
Docker 執(zhí)行器 + DinD 的 TLS 端口不一致
使用 Docker 執(zhí)行器且在 job 里需要構建鏡像（會用到 DinD）時，阿里云等環(huán)境里 Docker 的 DinD 可能只監(jiān)聽 2376（TLS），而 GitLab CI 配置時默認連 2375（非 TLS），會導致 job 里連不上 DinD 服務。解決辦法是在 Runner 配置里關閉 TLS 校驗并清空 TLS 證書目錄環(huán)境變量，并視情況加長等待時間。
編輯 /etc/gitlab-runner/config.toml，在對應 [[runners]] 下增加或修改如下（name、url、id、token 等按實際填寫）：
[[runners]]
name = "node_runner"
url = "https://jihulab.com"
id = 42515
token = "xxxx"
token_obtained_at = 2026-02-15T12:08:08Z
token_expires_at = 0001-01-01T00:00:00Z
executor = "docker"
# 關閉 DinD 的 TLS，避免只開 2376 時連不上
environment = ["DOCKER_TLS_CERTDIR="]
[runners.cache]
MaxUploadedArchiveSize = 0
[runners.cache.s3]
[runners.cache.gcs]
[runners.cache.azure]
[runners.docker]
tls_verify = false
image = "node:22"
# DinD 場景下通常需要開啟，非必要勿開，會有權限安全問題
privileged = true
disable_entrypoint_overwrite = false
oom_kill_disable = false
# 網(wǎng)絡或 DinD 啟動慢時可適當加大
wait_timeout = 60
disable_cache = false
修改后執(zhí)行 sudo gitlab-runner restart 使配置生效。
