🐳 從零打造 GitLab + Docker 自動部署環境：CI Runner、Registry、Compose 一條龍實戰

🐳 從零打造 GitLab + Docker 自動部署環境：CI Runner、Registry、Compose 一條龍實戰

本篇將從零開始，帶你打造一套「企業實際會使用」的 GitLab CI/CD 自動部署架構，整合：

• ✔ GitLab Runner（Docker Executor）
• ✔ GitLab Registry（安全私有 Image 儲存庫）
• ✔ Docker Compose（服務自動部署）
• ✔ CI/CD 自動建置 + 推送 + 部署

這是企業環境最常見、最穩定、最完整的一條龍部署流程。

---

📌 第一章：架構總覽（Architecture Overview）

整個流程如下：

1. 開發者 Push Code → GitLab
2. CI Pipeline 自動建置 Docker Image
3. Push 到 GitLab Registry（版本標籤、短 SHA ID）
4. 部署階段 SSH 到部署伺服器
5. Docker Compose 自動更新服務

架構圖（簡化）：

Developer → GitLab Repo → CI Pipeline → Docker Build
                                      ↓ Push
                             GitLab Registry
                                      ↓ Deploy
                                Production Server
                             Docker Compose Up -d

---

📌 第二章：準備環境

2.1 安裝 Docker（部署機）

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

2.2 安裝 Docker Compose

apt install docker-compose-plugin -y

2.3 在部署機建立專案目錄

mkdir -p /srv/myapp
cd /srv/myapp

建立基本 docker-compose.yml：

version: "3"

services:
  app:
    image: registry.example.com/mygroup/myapp:latest
    restart: always
    ports:
      - "3000:3000"

---

📌 第三章：設定 GitLab Registry（私有 Image 儲存庫）

3.1 登入 Registry

GitLab 每個專案都自帶 Registry。

docker login registry.example.com

GitLab CI 中會使用：

• $CI_REGISTRY
• $CI_REGISTRY_USER
• $CI_REGISTRY_PASSWORD

這些變數 GitLab 會自動提供。

---

📌 第四章：安裝 GitLab Runner（Docker Executor）

4.1 安裝 Runner

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | bash
apt install gitlab-runner -y

4.2 註冊 Docker Runner

gitlab-runner register \
  --executor docker \
  --docker-image docker:24 \
  --description "docker-runner"

Runner 會使用 docker:dind 來建置 docker image。

---

📌 第五章：撰寫 .gitlab-ci.yml（CI/CD 核心）

以下是完整可直接使用的示範檔案。

5.1 .gitlab-ci.yml

stages:
  - build
  - push
  - deploy

variables:
  IMAGE_NAME: $CI_REGISTRY_IMAGE/app

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHORT_SHA .
  artifacts:
    expire_in: 1 hour

push_image:
  stage: push
  image: docker:24
  services:
    - docker:24-dind
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
    - docker tag $IMAGE_NAME:$CI_COMMIT_SHORT_SHA $IMAGE_NAME:latest
    - docker push $IMAGE_NAME:$CI_COMMIT_SHORT_SHA
    - docker push $IMAGE_NAME:latest

deploy_prod:
  stage: deploy
  before_script:
    - 'which ssh-agent || ( apt update -y && apt install openssh-client -y )'
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$DEPLOY_SERVER_KNOWN_HOSTS" > ~/.ssh/known_hosts
  script:
    - ssh root@$DEPLOY_SERVER "docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY"
    - ssh root@$DEPLOY_SERVER "cd /srv/myapp && docker compose pull && docker compose up -d"
  only:
    - main

這個 Pipeline 能做到：

• ✔ Docker Build
• ✔ 推送至專案 Registry
• ✔ SSH 部署至 Production Server
• ✔ 使用 docker-compose 自動重啟服務

---

📌 第六章：部署機設定 SSH 部署金鑰

在 GitLab Repository → Settings → CI/CD → Variables 中新增：

• SSH_PRIVATE_KEY
• DEPLOY_SERVER_KNOWN_HOSTS

部署機需加入 GitLab 認證金鑰：

mkdir ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys

貼上 GitLab CI 使用的 public key。

---

📌 第七章：部署更新流程示意

當你 Push Code 或 Merge Request 進 main 時：

1. GitLab Runner 建置 Docker Image
2. 把 Image 推送到 GitLab Registry
3. CI 用 SSH 連到部署主機
4. 部署主機執行 docker compose pull && up -d
5. 服務立即更新（零中斷）

---

📌 第八章：最佳實務（企業部署建議）

• 🐳 使用 docker:stable 或 docker:24 版本建置環境
• 🔐 使用 GitLab CI Masked Variables 保護密碼
• 🚀 部署只允許 main / master branch
• 📦 將 docker-compose.yml 版本管理
• 📝 開發與正式環境使用不同的環境變數（.env.prod）

---

📌 結語

本篇示範的 GitLab + Docker 自動部署流程，是企業最常用的 DevOps 基礎架構。 透過 CI Runner、Registry、SSH 以及 Docker Compose，你可以打造完整、可重現、可擴充的自動化部署流程。

下一篇將推出： 《GitLab CI/CD 進階篇：Artifacts、Stages、Canary Deployment、Blue-Green Release 實戰》

---