CI/CD 實戰教學

常見問題

CI/CD 設定中最常遇到的問題與解決方案，快速排查疑難雜症。

Pipeline 執行問題

Pipeline 沒有被觸發？

確認 .gitlab-ci.yml 存在於專案根目錄（不是子目錄）
確認 YAML 格式正確，使用 GitLab CI Lint 工具驗證（CI/CD → Pipelines → CI Lint）
確認 job 的 rules 或 only 條件符合目前的 branch / 事件
確認有可用的 Runner（Settings → CI/CD → Runners 查看狀態）

Job 一直卡在 pending 狀態？

沒有符合條件的 Runner：檢查 Runner 標籤是否與 job 的 tags 匹配
Runner 已離線：前往 Runner 機器確認服務狀態
並行限制：GitLab.com 免費方案有並行限制，等待其他 Pipeline 完成

# 重啟 GitLab Runner 服務
sudo systemctl restart gitlab-runner

# 查看 Runner 日誌
sudo journalctl -u gitlab-runner -f

Docker 建置問題

出現 "Cannot connect to the Docker daemon" 錯誤？

需要啟用 Docker-in-Docker（DinD）服務：

build-image:
  image: docker:24.0
  services:
    - docker:24.0-dind    # 必須加這個！
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t my-image .

Docker build 失敗，提示權限不足？

Runner 需要以 privileged 模式運行
在 Runner 設定中加入 privileged = true

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "my-runner"
  executor = "docker"
  [runners.docker]
    privileged = true    # 加入此行
    image = "docker:24.0"

部署問題

SSH 部署出現 Host key verification failed？

# 在 before_script 中加入目標主機的 SSH 金鑰
before_script:
  - eval $(ssh-agent -s)
  - echo "$SSH_PRIVATE_KEY" | ssh-add -
  - mkdir -p ~/.ssh
  # 方法一：掃描並加入 known_hosts
  - ssh-keyscan -H $DEPLOY_HOST >> ~/.ssh/known_hosts
  # 方法二：停用嚴格模式（較不安全，僅用於測試）
  - echo "StrictHostKeyChecking no" >> ~/.ssh/config

Registry 登入失敗（401 Unauthorized）？

確認使用 $CI_REGISTRY_USER 和 $CI_REGISTRY_PASSWORD（GitLab 自動提供）
確認專案設定中有啟用 Container Registry
如果使用 Deploy Token，確認有 read_registry 權限

部署後服務沒有更新？

# 確認 docker compose up 使用了正確的映像版本
docker compose pull     # 先拉取最新映像
docker compose up -d --no-build   # 不重新建置，使用已拉取的映像

# 確認映像版本
docker compose images

# 強制重建容器（即使映像相同）
docker compose up -d --force-recreate

更多問題可查看資源索引中的官方文件和社群論壇。