LLM 知識庫

Appearance

GitLab Runner Docker 部署 ​

以 Docker Compose 部署 GitLab Runner，並啟用 Docker-in-Docker（DinD）模式執行 CI/CD 建置任務。

概述 ​

GitLab Runner 是執行 GitLab CI/CD Pipeline job 的代理程式。將 Runner 部署為 Docker 容器，可快速在任何有 Docker 的機器上建立 CI 執行環境，且設定檔（config.toml）可持久化到宿主機目錄，方便版本管理與備份。

Docker Executor 模式下，每個 Pipeline job 都在一個全新的容器中執行，確保環境一致性與隔離性。若 Pipeline 本身需要建置 Docker Image（即 Docker-in-Docker，DinD），則必須啟用 privileged 模式並掛載 Docker socket，否則建置指令無法連線至 Docker daemon。

核心內容 ​

安裝方式：Docker Compose ​

以 Docker Compose 啟動 Runner 服務：

  • Image：gitlab/gitlab-runner（官方維護）
  • Docker socket 掛載：/var/run/docker.sock 讓 Runner 可存取宿主機的 Docker daemon
  • 設定目錄掛載：./config:/etc/gitlab-runner 讓 config.toml 持久化在宿主機

首次使用：註冊 Runner ​

Runner 容器啟動後需向 GitLab Server 完成一次性的互動式註冊。指令採問答流程，需依序輸入：

  • GitLab Server URL（例如 http://your-gitlab.com/）
  • Registration Token（從 GitLab Admin → Runners 頁面取得）
  • Runner 名稱（自訂）
  • Executor 類型（填 docker）
  • 預設 Docker Image（填 docker:latest）

config.toml 關鍵設定 ​

欄位值說明
concurrent10允許同時執行的最大 job 數
privilegedtrue必須為 true，才能在 DinD 模式執行 Docker 建置
volumes["/cache", "/var/run/docker.sock:/var/run/docker.sock"]掛載 Docker socket 才能存取宿主 Docker daemon

問題診斷： 若 privileged 或 volumes 未正確設定，Pipeline 在建置 Docker Image 時會出現 lookup docker on x.x.x.x:53: no such host 錯誤。

DinD 安全考量 ​

privileged: true 讓容器可存取宿主機的所有裝置，存在安全風險。建議：

  • 僅在受信任的內部環境使用
  • 定期輪替 Runner token
  • 避免在多租戶環境中共用同一個 privileged Runner

關鍵要點 ​

  • Docker Executor 提供乾淨的 per-job 執行環境，是最常見的 Runner 部署方式
  • privileged: true + Docker socket 掛載是 DinD 的必要條件，缺一不可
  • config.toml 修改後 Runner 會自動偵測並重新載入，無需重啟容器
  • 官方文件：https://docs.gitlab.com/runner/install/docker.html

實際應用 ​

主要用途：

  • 建置 Docker Image 並推送至 Container Registry（ACR、DockerHub 等）
  • 執行自動化測試
  • 觸發 Kubernetes 部署（搭配 kubectl 或 Helm）

若使用 Azure 環境，可搭配 Azure DevOps Pipeline 作為替代方案，或併行使用（GitLab 做程式碼管理，Azure DevOps 做部署）。

部署設定參考 ​

以下為實際部署時使用的完整設定，供日後查詢與複製使用。

環境參數 ​

項目值
Runner Imagegitlab/gitlab-runner
GitLab Server URLhttp://rdgit.wiwynn.com/
Runner ID73
Executordocker
預設 Imagedocker:latest
concurrent10

docker-compose.yml ​

yaml
services:
  gitlab_runner:
    image: gitlab/gitlab-runner
    container_name: gitlab_runner
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/etc/gitlab-runner
    command: register

完整 config.toml ​

toml
concurrent = 10
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "gitlab runner"
  url = "http://rdgit.wiwynn.com/"
  id = 73
  token = "SCnWPByo3QtH4exqsqD6"
  token_obtained_at = 2023-01-04T10:12:11Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "docker:latest"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    shm_size = 0

操作指令 ​

bash
# 首次：互動式註冊 Runner
docker run --rm -it \
  -v "$(pwd)"/config:/etc/gitlab-runner \
  gitlab/gitlab-runner register

# 正式啟動（設定完成後）
docker compose up -d

# 查看 Runner 執行狀態
docker logs -f gitlab_runner

相關概念 ​

來源 ​