Docker CI/CD on Spring Booot

本文件透過 Campus Activity Backend 專案的容器化架構、本地開發環境、生產部署方式，說明Spring Boot CI/CD 流程。

註: Campus Activity Backend是第一個嘗試使用Docker CICD的專案，值得紀念!!

系統概述

相關檔案一覽

Dockerfile 映像建置

採用 多階段建置（Multi-stage Build），分為建置階段與執行階段。

flowchart LR
    A[builder<br/>eclipse-temurin:25-jdk-alpine] -->|gradle build| B[app.jar]
    B --> C[production<br/>eclipse-temurin:25-jre-alpine]
    C --> D[最終映像<br/>非 root 使用者執行]

建置

1. 複製 Gradle Wrapper、build.gradle、settings.gradle、子模組
2. 預先下載依賴（獨立 Layer，利於 Docker Cache）
3. 複製 src/ 並執行 ./gradlew build -x test -x spotlessCheck
4. 產出 build/libs/*.jar

執行

1. 使用較小的 JRE 映像（25-jre-alpine）
2. 建立非 root 使用者 spring
3. 複製 JAR 為 /app/app.jar
4. 以 spring 使用者執行，監聽 8080

本地手動建置

docker build -t campus-activity_app:local .Code language: CSS (css)

建置.dockerignore

以下內容不會進入映像建置上下文：

• .gradle/、build/（各模組 build 目錄）
• IDE 設定（.idea/、.vscode/）
• .git/
• application-local.yml、日誌檔

Docker Compose 環境

開發環境（docker-compose.yml）

適用於本地開發，支援 Gradle bootRun 熱重載 與 遠端除錯。

開發環境特點：

• 原始碼掛載至 /workspace，修改後可即時重載
• 開放 JDWP 除錯埠（預設 5005）
• SPRING_JPA_HIBERNATE_DDL_AUTO 預設 update（自動同步 Schema）
• Gradle Cache 使用 Named Volume campus-activity_gradle_cache

啟動步驟：

cp .env.example .env
# 編輯 .env 填入實際密碼與設定

docker compose build --no-cache
docker compose up -d

# 或建置並啟動
docker compose up -d --buildCode language: CSS (css)

驗證：

• Swagger UI：http://localhost:8080/api/swagger-ui/index.html
• Adminer：http://localhost:8888
• 資料庫連線：jdbc:mysql://localhost:3306/campus-activity?serverTimezone=Asia/Taipei&useSSL=false&allowPublicKeyRetrieval=true

生產環境（docker-compose.prod.yml）

適用於伺服器部署，從 Harbor 拉取已建置好的映像。

生產環境特點：

• 使用預先建置並推送至 Harbor 的映像，不本地編譯
• SPRING_JPA_HIBERNATE_DDL_AUTO=validate（禁止自動修改 Schema）
• 啟用 SPRING_PROFILES_ACTIVE=server，載入 application-server.yml
• 日誌寫入 Volume campus-activity_app_logs（/app/logs）
• 容器日誌採 json-file，單檔上限 10MB、保留 3 個檔案

部署步驟：

# 設定生產環境變數（見第 5 節）
export APP_TAG=v1.0.0
export SPRING_PROFILES_ACTIVE=server
# ... 其他變數

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -dCode language: PHP (php)

環境變數

開發環境（.env.example）

生產環境

docker-compose.prod.yml 額外需求

應用程式注入的環境變數

Compose 會將以下變數傳入 app 容器：

SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD
SPRING_JPA_HIBERNATE_DDL_AUTO
SPRING_SERVER_HOST / SPRING_SERVER_PORT
SPRING_APP_UPLOAD_PATH
SPRING_DATA_REDIS_HOST
TZ

生產環境另需透過 Secret 管理注入 SSO、JWT 等敏感設定（見 application.yml 中的 ${SSO_CLIENT_SECRET} 等）。

開發與生產差異對照

CI/CD 流程（建議）

目前儲存庫尚未納入 .gitlab-ci.yml。依專案使用的 GitLab 與 Harbor 基礎設施，建議採用以下 Pipeline 流程。

flowchart LR
    A[Push / MR] --> B[Build & Test]
    B --> C[Docker Build]
    C --> D[Push to Harbor]
    D --> E{分支判斷}
    E -->|main / tag| F[Deploy 生產]
    E -->|develop| G[Deploy 測試]

映像標籤

建議 .gitlab-ci.yml 範本

不過目前(2026/06)的CICD還不是很完善，以下為AI建議檔案範本:

stages:
  - test
  - build
  - deploy

variables:
  IMAGE_NAME: harbor.ntubimdbirc.tw/campus-activity/campus-activity_app
  DOCKER_TLS_CERTDIR: ""

test:
  stage: test
  image: eclipse-temurin:25-jdk-alpine
  script:
    - chmod +x ./gradlew
    - ./gradlew test spotlessCheck --no-daemon
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH

docker-build-push:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  before_script:
    - docker login -u "$HARBOR_USER" -p "$HARBOR_PASSWORD" harbor.ntubimdbirc.tw
  script:
    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHORT_SHA .
    - docker tag $IMAGE_NAME:$CI_COMMIT_SHORT_SHA $IMAGE_NAME:latest
    - docker push $IMAGE_NAME:$CI_COMMIT_SHORT_SHA
    - docker push $IMAGE_NAME:latest
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy-production:
  stage: deploy
  script:
    - ssh deploy@$PROD_SERVER "
        cd /opt/campus-activity &&
        export APP_TAG=$CI_COMMIT_SHORT_SHA &&
        docker compose -f docker-compose.prod.yml pull &&
        docker compose -f docker-compose.prod.yml up -d"
  environment:
    name: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manualCode language: PHP (php)

GitLab CI/CD 變數

需在 GitLab 設定

生產 Profile 設定重點

啟用 server Profile 時，載入 application-server.yml：

網路架構

開發環境

┌─────────────────────────────────────────────┐
│  campus-network (bridge)                    │
│                                             │
│  ┌──────┐  ┌───────┐  ┌─────┐  ┌────────┐ │
│  │ app  │──│  db   │  │redis│  │adminer │ │
│  │:8080 │  │:3306  │  │:6379│  │ :8888  │ │
│  └──┬───┘  └───────┘  └─────┘  └────────┘ │
│     │                                       │
└─────┼───────────────────────────────────────┘
      │ :8080, :5005 對外映射
      ▼
   開發者本機Code language: CSS (css)

生產環境

┌──────────────────────────────┐
│  Docker Network              │
│  ┌──────┐      ┌──────┐     │
│  │ app  │──────│  db  │     │
│  │:8080 │      │:3306 │     │
│  └──┬───┘      └──────┘     │
└─────┼────────────────────────┘
      │ SERVER_PORT 對外映射
      ▼
   反向代理 / 負載平衡器

維運操作

常用指令

# 查看服務狀態
docker compose ps
docker compose -f docker-compose.prod.yml ps

# 查看應用程式日誌
docker compose logs -f app
docker compose -f docker-compose.prod.yml logs -f app

# 重啟應用程式（不影響資料庫）
docker compose restart app

# 停止並移除容器（保留 Volume）
docker compose down

# 停止並移除容器與 Volume（⚠️ 會刪除資料庫資料）
docker compose down -vCode language: PHP (php)

健康檢查

滾動更新

透過一邊淘汰舊版本、一邊換上新版本達到零停機時間（Zero Downtime）

export APP_TAG=v1.0.1
docker compose -f docker-compose.prod.yml pull app
docker compose -f docker-compose.prod.yml up -d appCode language: JavaScript (javascript)

原始碼索引