DevOps on Bill.Lin's Notes

Docker Compose V2 遷移指南

Mon, 15 Jan 2024 00:00:00 +0800

V1 vs V2 的本質差異

	V1	V2
執行檔	`docker-compose`（Python）	`docker compose`（Go，Docker CLI plugin）
安裝方式	獨立 binary，另行安裝	Docker Desktop 內建；Linux 用 `docker compose plugin`
`version:` 欄位	必填（決定語法版本）	已廢棄，出現時忽略並發出警告
網路命名	`<project>_default`（底線）	`<project>-default`（連字號）
啟動指令	`docker-compose up`	`docker compose up`

V1 已於 2023 年 7 月正式 EOL，不再維護。

移除 `version:` 欄位

V1 時代的 version: "3.9" 決定 Compose 文件語法版本。V2 不再有版本差異，統一支援最新語法。

# V1 寫法（過時，V2 會警告）
version: "3.9"
services:
  app:
    image: my-app:latest

# V2 正確寫法（刪除 version 欄位）
services:
  app:
    image: my-app:latest

移除後不影響任何功能，僅消除 the attribute version is obsolete 警告。

jq — 命令列 JSON 處理

Mon, 15 Jan 2024 00:00:00 +0800

安裝

# macOS
brew install jq

# Ubuntu / Debian
sudo apt install jq

# Alpine（Docker 常用）
apk add jq

# 確認版本
jq --version
# jq-1.7.1

基本過濾器

# Pretty print（最常用：curl 結果格式化）
curl -s https://api.github.com/repos/spring-projects/spring-boot | jq '.'

# 取特定欄位
jq '.name'
jq '.stargazers_count'

# 取陣列元素
jq '.[0]'         # 第一個元素
jq '.[-1]'        # 最後一個元素
jq '.[2:5]'       # index 2 到 4（slice）

# 展開陣列（iterate）
jq '.[]'          # 輸出陣列每個元素，各佔一行

# 巢狀欄位
jq '.user.email'
jq '.address.city'

# 多個欄位 → 新物件
jq '{name: .name, email: .user.email}'

# 多個欄位 → array
jq '[.name, .email]'

空值安全

# 欄位不存在時回傳 null，不報錯
jq '.nonexistent'

# 提供預設值（若為 null 則用 "unknown"）
jq '.name // "unknown"'

# optional operator（? 表示若不適用則忽略，不報錯）
jq '.items[]? | .name'

陣列操作

# map：對每個元素套用 filter
jq 'map(.name)'
# 等同於
jq '[.[] | .name]'

# select：過濾符合條件的元素
jq '.[] | select(.age > 18)'
jq '.[] | select(.status == "active")'
jq '.[] | select(.role == "admin" or .role == "superuser")'

# length：陣列長度 / 字串長度 / 物件 key 數
jq 'length'
jq '.items | length'

# sort_by
jq 'sort_by(.name)'
jq 'sort_by(.age) | reverse'   # 降序

# unique_by
jq 'unique_by(.type)'
jq '[.[].type] | unique'        # 取所有 type 的唯一值列表

# group_by
jq 'group_by(.department)'

# flatten（展開巢狀陣列）
jq 'flatten'
jq 'flatten(1)'  # 只展開一層

# first / last
jq 'first(.[] | select(.active))'

字串與格式化

# String interpolation（@string format）
jq '.[] | "\(.name): \(.email)"'

# 傳入變數（避免 shell injection）
jq --arg status "active" '.[] | select(.status == $status)'
jq --argjson min_age 18 '.[] | select(.age > $min_age)'

# 數值格式
jq '.price * 100 | round'       # 四捨五入
jq '.size / 1024 / 1024'        # MB

# 字串操作
jq '.name | ascii_upcase'
jq '.name | ascii_downcase'
jq '.name | ltrimstr("Mr. ")'   # 移除前綴
jq '.name | split(" ") | .[0]'  # 取第一個 token
jq '.tags | join(", ")'         # 陣列轉字串

# 輸出純字串（不含 JSON 引號）
jq -r '.name'

物件操作

# keys / values
jq 'keys'
jq 'values'
jq 'to_entries'     # [{key: "a", value: 1}, ...]
jq 'from_entries'   # [{key,value}] → {a:1}

# has：判斷是否有某 key
jq 'has("email")'
jq '.[] | select(has("avatar_url"))'

# 合併物件
jq '. + {"extra": "field"}'
jq 'reduce .[] as $item ({}; . + $item)'

# del：刪除欄位
jq 'del(.password)'
jq 'del(.users[].password)'

# 重新命名欄位
jq '{id: .user_id, email: .user_email}'

進階：reduce 與 env

# reduce：摺疊陣列
# 計算總和
jq 'reduce .[] as $x (0; . + $x)'

# 讀取環境變數
jq -n 'env.HOME'
jq -n 'env | keys'

# null input（不從 stdin 讀，直接建構）
jq -n '{"timestamp": now | todate, "host": env.HOSTNAME}'

# any / all
jq 'any(.[]; .active)'   # 有任何元素 active
jq 'all(.[]; .verified)' # 所有元素都 verified

CI/CD 實戰範例

GitHub API

# 取最新 release tag
gh api repos/spring-projects/spring-boot/releases/latest | jq -r '.tag_name'

# 列出所有 PR 的 title 與 number
gh api repos/owner/repo/pulls | jq '.[] | "\(.number): \(.title)"'

# 找出所有 open PR 的 author
gh api repos/owner/repo/pulls | jq '[.[] | select(.state == "open") | .user.login] | unique'

# CI 判斷：若無 open issue 則繼續
OPEN_COUNT=$(gh api repos/owner/repo/issues | jq '[.[] | select(.state == "open")] | length')
if [ "$OPEN_COUNT" -gt 0 ]; then echo "Has open issues"; fi

Docker

# 取 image 支援的平台
docker manifest inspect nginx:latest | \
  jq '[.manifests[].platform | "\(.os)/\(.architecture)"]'

# 列出所有 running container 的 name 與 image
docker ps --format '{{json .}}' | jq -s '[.[] | {name: .Names, image: .Image}]'

AWS CLI

# 列出所有 EC2 instance 的 ID 與狀態
aws ec2 describe-instances | \
  jq '.Reservations[].Instances[] | {id: .InstanceId, state: .State.Name, type: .InstanceType}'

# 只列出 running 的 instance
aws ec2 describe-instances | \
  jq '[.Reservations[].Instances[] | select(.State.Name == "running") | .InstanceId]'

# 取 ECS service 的 desired / running count
aws ecs describe-services --cluster my-cluster --services my-service | \
  jq '.services[0] | {desired: .desiredCount, running: .runningCount}'

# 從 Secrets Manager 取值（已解碼的 JSON secret）
aws secretsmanager get-secret-value --secret-id my-secret | \
  jq -r '.SecretString' | jq '.DB_PASSWORD'

Kubernetes

# 列出所有 pod 及其狀態
kubectl get pods -o json | \
  jq '.items[] | {name: .metadata.name, status: .status.phase}'

# 找出 Crash 的 pod
kubectl get pods -o json | \
  jq '[.items[] | select(.status.phase == "CrashLoopBackOff") | .metadata.name]'

Helm / 部署腳本

# 比較兩個 JSON 的差異
diff <(jq -S '.' file1.json) <(jq -S '.' file2.json)

# 從 package.json 取版本號
VERSION=$(jq -r '.version' package.json)
docker build -t "my-app:${VERSION}" .

jq vs 其他工具

工具	優點	缺點	適用
`jq`	快速、語法簡潔、shell-friendly	學習曲線、複雜邏輯難讀	CLI 腳本、CI/CD
`python -m json.tool`	無需安裝、pretty print	只能格式化，無法過濾	純格式化
`fx`	互動式、支援 JS 語法	需要 Node.js	互動探索
`gron`	把 JSON 變成 grep-able 行	需要配合 grep/sed	搜尋特定值
Python/`requests`	完整語言能力	需要寫腳本	複雜邏輯

常見陷阱

數值精度

# jq 使用 IEEE 754 double，大整數會失去精度
echo '{"id": 9007199254740993}' | jq '.id'
# 輸出：9007199254740992  ← 精度丟失！

# 解法：用字串處理大整數
echo '{"id": "9007199254740993"}' | jq '.id'
# 輸出："9007199254740993"  ← 正確

2^53 = 9007199254740992，超過此值的整數用 jq 處理會失去精度，Twitter ID、雪花算法 ID 等大整數要特別注意。

Docker MySQL：容器化部署與設定

Tue, 18 Jan 2022 23:56:44 +0800

概述

在現代開發流程中，使用 Docker 部署資料庫已成為主流。將 MySQL 運行在 Docker 容器中，可以帶來許多好處：環境隔離、快速部署、版本控制、以及方便的遷移。這篇文章將引導您如何在 Docker 中設定和管理 MySQL 容器。

啟動 MySQL 容器

鏡像選擇：mysql/mysql-server 是 Oracle 的私有版本（不同於 Docker Hub 官方鏡像），現已標記為 deprecated。請使用官方 mysql 鏡像（docker.io/library/mysql）。

使用 docker run 指令可以快速啟動一個 MySQL 容器。以下是一個常用的範例，包含了密碼設定、埠映射和字元集設定。

docker run \
    --name mysql-server \
    -e MYSQL_ROOT_PASSWORD=your_strong_password \
    -p 3306:3306 \
    -d \
    mysql:8.0 \
    --character-set-server=utf8mb4 \
    --collation-server=utf8mb4_unicode_ci \
    --skip-character-set-client-handshake

指令參數說明

--name mysql-server: 為容器指定一個易於識別的名稱，這裡命名為 mysql-server。
-e MYSQL_ROOT_PASSWORD=your_strong_password: 設定 MySQL root 使用者的密碼。請務必將 your_strong_password 替換為您自己的強密碼。
-p 3306:3306: 將主機的 3306 埠映射到容器的 3306 埠。這樣您就可以從主機透過 3306 埠連接到容器內的 MySQL 服務。
-d: 以背景模式 (detached mode) 運行容器，讓容器在背景執行。
mysql:8.0: 指定要使用的 Docker 映像檔。使用 Docker Hub 官方 mysql 鏡像。
--character-set-server=utf8mb4: 設定 MySQL 伺服器的預設字元集為 utf8mb4，以支援更廣泛的字元，包括表情符號。
--collation-server=utf8mb4_unicode_ci: 設定伺服器的預設排序規則為 utf8mb4_unicode_ci，這是一種不區分大小寫和重音的排序規則。
--skip-character-set-client-handshake: 禁用客戶端字元集握手。這有助於確保客戶端和伺服器之間的字元集一致性，避免亂碼問題。

字元集設定的等效配置

上述字元集相關的 docker run 參數，在 MySQL 的配置檔 (my.cnf) 中，等效於以下設定：

Docker Compose 完整指南：多容器應用程式的定義與執行

Mon, 26 Jul 2021 02:21:13 +0800

概述

版本說明：docker-compose（帶連字號，v1 Python 實作）自 2023 年 7 月已停止維護（EOL）。現行版本為 docker compose（空格，v2 Go 實作，已整合進 Docker Desktop 與 Docker Engine）。本文使用 docker compose 指令。

在現代應用程式開發中，一個專案往往由多個服務組成，例如前端、後端 API、資料庫、快取等。這些服務各自運行在不同的容器中，而 Docker Compose 正是為了解決這種多容器應用程式的定義與管理而生。

Docker Compose 允許您使用一個 YAML 檔案 (docker-compose.yml) 來定義應用程式的所有服務、網路和儲存卷，然後透過單一指令啟動、停止或管理整個應用程式堆疊。這極大地簡化了開發、測試和部署的流程。

常用 Docker Compose 指令

以下是 Docker Compose 的一些常用指令，用於管理您的多容器應用程式：

指令	說明	範例
`docker compose version`	顯示 Docker Compose 的版本資訊。	`docker compose version`
`docker compose --help`	顯示 Docker Compose 的幫助訊息。	`docker compose --help`
`docker compose up`	啟動並建立所有服務的容器。如果容器已存在，則會重新建立。	`docker compose up`
`docker compose up -d`	在背景模式 (detached mode) 啟動並建立所有服務的容器。	`docker compose up -d`
`docker compose down`	停止並移除所有服務的容器、網路和預設儲存卷。	`docker compose down`
`docker compose exec <service_name> <command>`	在指定服務的容器中執行指令。	`docker compose exec microService /bin/bash`
`docker compose ps`	列出所有服務的容器狀態。	`docker compose ps`
`docker compose top`	顯示服務容器的運行進程。	`docker compose top`
`docker compose logs <service_name>`	顯示指定服務容器的日誌輸出。	`docker compose logs microService`
`docker compose config`	驗證 `docker-compose.yml` 檔案的語法是否正確，並顯示解析後的配置。	`docker compose config`
`docker compose config -q`	靜默模式驗證配置，只在有錯誤時輸出訊息。	`docker compose config -q`
`docker compose restart <service_name>`	重新啟動指定服務的容器。若未指定服務，則重新啟動所有服務。	`docker compose restart microService`
`docker compose start <service_name>`	啟動指定服務的容器。若未指定服務，則啟動所有已停止的服務。	`docker compose start microService`
`docker compose stop <service_name>`	停止指定服務的容器。若未指定服務，則停止所有運行中的服務。	`docker compose stop microService`

常用組合指令

1
2

# 驗證配置後，停止並重新啟動所有服務
docker compose config -q && docker compose down && docker compose up -d

`docker-compose.yml` 檔案結構詳解

docker-compose.yml 是 Docker Compose 的核心配置檔案，它使用 YAML 語法來定義應用程式的服務。

Docker 網路模式詳解：容器間通訊與外部連接

Mon, 26 Jul 2021 02:21:13 +0800

概述

Docker 網路是容器化應用程式的基石，它決定了容器如何與外部世界通訊，以及容器之間如何互相連接。理解 Docker 的網路模式對於建構穩健、可擴展的容器化應用程式至關重要。本文將詳細介紹 Docker 提供的幾種主要網路模式及其應用場景。

Docker 網路模式

Docker 提供了多種網路驅動程式，每種驅動程式都提供不同的網路功能。最常用的包括 bridge、host、none 和 container。

1. Bridge (橋接模式)

說明：這是 Docker 的預設網路模式。當您不指定網路模式時，Docker 會自動為容器分配一個 IP 位址，並將其連接到一個名為 docker0 的虛擬橋接器上。每個容器都會獲得一個獨立的網路堆疊。
工作原理：
- Docker 會在主機上建立一個名為 docker0 的虛擬橋接器。
- 每個容器都會建立一對虛擬乙太網卡 (veth pair)，其中一端連接到容器內的 eth0，另一端連接到 docker0 橋接器。
- 容器可以透過 docker0 橋接器與同一橋接器上的其他容器通訊，也可以透過主機的網路介面與外部網路通訊。
優點：提供良好的隔離性，容器間預設不直接暴露埠。
缺點：容器需要透過埠映射才能從外部訪問。

2. Host (主機模式)

說明：在主機模式下，容器不會有自己的獨立網路堆疊，而是直接使用主機的網路堆疊。這意味著容器會直接使用主機的 IP 位址和埠。
工作原理：容器內的應用程式會直接綁定到主機的網路介面和埠上。
優點：網路效能最佳，因為沒有額外的網路層。
缺點：
- 容器不再與主機隔離，容器內應用程式使用的埠不能與主機上已佔用的埠衝突。
- 安全性較低，因為容器直接暴露在主機網路中。
使用方式：--network host

3. None (無網路模式)

說明：在無網路模式下，容器會建立一個獨立的網路堆疊，但不會對其進行任何網路配置。容器將沒有網路介面，無法與外部通訊。
工作原理：容器只包含一個 lo (loopback) 介面。
優點：適用於只需要計算資源而不需要網路連接的特殊場景，或者需要手動配置網路的進階情況。
缺點：容器無法進行任何網路通訊，除非手動配置。
使用方式：--network none

4. Container (容器模式)

說明：在容器模式下，新建立的容器不會有自己的網路堆疊，而是與另一個已存在的容器共享其網路堆疊。這意味著兩個容器會共享同一個 IP 位址和埠空間。
工作原理：兩個容器共享同一個網路命名空間。
優點：適用於需要緊密協同工作的應用程式，例如主應用程式容器和一個代理或日誌收集容器。
缺點：兩個容器會共享埠，可能導致埠衝突。
使用方式：--network container:<name_or_id>

常用 Docker 網路指令

指令	說明	範例
`docker network ls`	列出所有 Docker 網路。	`docker network ls`
`docker network prune`	刪除所有未使用的網路。	`docker network prune`
`docker network inspect <network_name_or_id>`	顯示指定網路的詳細資訊，包括連接到該網路的容器。	`docker network inspect bridge`
`docker inspect <container_id>`	顯示指定容器的詳細資訊，包括其網路配置。	`docker inspect <container_id>`

自訂網路 (User-defined Bridge Networks)

雖然 Docker 預設的 bridge 網路 (docker0) 已經足夠應付許多情況，但強烈建議您建立自訂橋接網路 (User-defined Bridge Networks)。自訂網路提供了更好的隔離性、內建的 DNS 解析和更靈活的配置。

Selenium Grid Multi-Architecture Docker 映像建構

Sun, 25 Jul 2021 02:21:13 +0800

檔名說明：本文原名 Dockerfile-docker_in_docker.md，但實際內容是 Selenium 多架構映像建構，與 DinD（Docker in Docker）技術無關。標題已更正以符合實際內容。

概述

在自動化測試和網路爬蟲等場景中，經常需要將應用程式與瀏覽器自動化工具 (如 Selenium) 打包到同一個 Docker 容器中。此外，為了支援不同的運行環境（例如 ARM64 或 x86_64 架構，以及 Firefox 或 Chrome 瀏覽器），我們需要一個靈活的建構流程。

本文將深入解析一個多階段 Dockerfile，它展示了如何：

建構一個包含 Node.js 應用程式的基礎映像檔。
利用這個基礎映像檔，為不同的 CPU 架構和瀏覽器環境建立多個最終的 Selenium 應用程式映像檔。
透過一個通用的 entrypoint.sh 腳本，在容器啟動時自動判斷環境並執行對應的測試。

Dockerfile 詳解

這個 Dockerfile 採用了多階段建構 (Multi-stage Builds) 的方式，以確保最終映像檔的輕量化和模組化。

第一階段：應用程式建構 (`build` 階段)

這個階段負責準備 Node.js 環境並打包應用程式。

FROM ubuntu:22.04 AS build

# 設定環境變數
ENV NVM_DIR /opt/nvm          # NVM (Node Version Manager) 的安裝目錄
ENV NODE_VERSION v16.13.2     # 指定要安裝的 Node.js 版本
ENV APP_DIR /app              # 應用程式的工作目錄

# 建立必要的目錄
RUN [ -d $APP_DIR ] || mkdir -p $APP_DIR
RUN [ -d $NVM_DIR ] || mkdir -p $NVM_DIR

# 更新套件列表並安裝 curl (用於下載 NVM)
RUN apt-get update && apt-get install curl -y

# 安裝 NVM 和指定版本的 Node.js
# 從 GitHub 下載 NVM 安裝腳本
RUN curl -o $NVM_DIR/install.sh https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh
# 執行 NVM 安裝腳本（只安裝 NVM 本身，尚未安裝 Node.js）
RUN /bin/bash $NVM_DIR/install.sh
# 使用 NVM 安裝並啟用指定版本的 Node.js（必須在 PATH 設定前完成）
RUN . "$NVM_DIR/nvm.sh" && nvm install $NODE_VERSION && nvm use $NODE_VERSION && nvm alias default $NODE_VERSION
# 安裝完成後再設定 PATH，確保路徑實際存在
ENV PATH $NVM_DIR/versions/node/$NODE_VERSION/bin:$PATH

# 複製應用程式檔案
COPY test /app/test          # 複製 'test' 目錄
COPY *.js /app/              # 複製所有 .js 檔案
COPY *.json /app/            # 複製所有 .json 檔案
COPY *.sh /app/              # 複製所有 .sh 腳本
RUN chmod 0755 /app/*.sh     # 為腳本添加執行權限

# 設定工作目錄並安裝 Node.js 依賴
WORKDIR $APP_DIR
RUN npm install

第二階段：Selenium 瀏覽器映像檔建構 (多個 `FROM` 階段)

這個 Dockerfile 為不同的 CPU 架構 (ARM64, x86_64) 和瀏覽器 (Firefox, Chrome) 定義了多個最終映像檔。每個階段都從一個預先建構好的 Selenium 映像檔開始，並將第一階段建構好的應用程式複製進來。

Dockerfile 基礎：建構 Docker 映像檔的核心指令

Sat, 24 Jul 2021 02:21:13 +0800

概述

Dockerfile 是一個包含一系列指令的文字檔案，Docker 引擎會讀取這些指令，並自動建構出 Docker 映像檔 (Image)。它定義了映像檔的內容、運行環境以及啟動時執行的指令。理解 Dockerfile 是掌握 Docker 容器化技術的關鍵一步。

Dockerfile 核心指令詳解

1. 基礎指令

FROM：指定基礎映像檔。Dockerfile 的第一條指令必須是 FROM。
- 語法：FROM <image>[:<tag>]
- 範例：FROM ubuntu:18.04 (使用 Ubuntu 18.04 作為基礎映像檔)
- 注意：如果未指定 tag，預設為 latest。建議明確指定版本，以確保建構的可重複性。
MAINTAINER：指定映像檔的維護者資訊。
- 語法：MAINTAINER <name> [email]
- 範例：MAINTAINER Bill.Lin <zzx123bill@gmail.com>
- 注意：此指令已過時，建議使用 LABEL 指令來替代，例如 LABEL maintainer="Bill.Lin <zzx123bill@gmail.com>"。

2. 執行指令

RUN：在建構映像檔時執行命令。每個 RUN 指令都會在映像檔中建立一個新的層 (layer)。
- 語法：
  - RUN <command> (shell 模式，預設使用 /bin/sh -c 執行)
  - RUN ["executable", "param1", "param2"] (exec 模式，直接執行可執行檔)
- 範例 (shell 模式)：
  1 2
  
  RUN apt-get update -y \ && apt-get install nginx -y
  - 注意：使用 && 將多個命令串聯起來，可以減少映像檔層數，優化映像檔大小。
- 範例 (exec 模式)：
  1 2
  
  RUN ["./test.php", "dev", "offline"] # 等同於在容器內執行 `./test.php dev offline`
CMD：設定容器啟動時預設執行的命令。如果 docker run 命令後帶有參數，CMD 的命令會被覆蓋。一個 Dockerfile 中只能有一個 CMD，多個 CMD 只有最後一個生效。

YAML 語法從入門到實踐

Tue, 29 Jun 2021 13:45:56 +0800

前言

在現代軟體開發中，設定檔是不可或缺的一環。從 Java 的 Spring Boot 框架 (Spring MVC 過往使用大量的 XML)，到我目前使用的 Hugo 靜態網站產生器，都能看到 .properties、.yml 或 .toml 等格式的身影。

雖然這些格式各有優勢，但在雲原生領域，特別是設定 Kubernetes (K8s) 資源時，YAML (YAML Ain’t Markup Language) 已成為事實上的標準。因此，掌握 YAML 的語法至關重要。

核心語法

YAML 的設計目標是易於人類閱讀和撰寫。它的語法主要基於縮排和幾個簡單的符號。

註解: 使用 # 號標示單行註解。
文件開頭: 使用三個連字號 --- 作為文件的開始符號 (選用)。

鍵值對 (Key-Value Pair)

YAML 的基本組成單位是鍵值對，格式為 key: value (注意冒號後面需要一個空格)。

`1`	`apiVersion: v1`

階層/物件 (Objects)

透過換行和縮排 (建議使用兩個空格) 來表示階層關係。這在 JSON 中相當於一個物件。

以下範例等同於 spring.datasource.username = "root"。

1
2
3

spring:
  datasource:
    username: root

陣列/列表 (Arrays/Lists)

陣列有兩種常見的表示方式：

Side Project 企業級專案配置指南：完整開發環境設定與最佳實踐

Wed, 01 Jan 2020 20:31:25 +0800

Side Project 企業級專案配置指南

簡介

在現代軟體開發中，一個良好的專案配置是成功的關鍵。本文將深入介紹如何從零開始建立一個企業級的 Side Project，包含完整的開發環境設定、專案結構規劃、依賴管理、容器化部署、監控系統與 CI/CD 流程。

專案結構規劃

標準 Maven 專案結構

project-root/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── company/
│   │   │           └── project/
│   │   │               ├── Application.java
│   │   │               ├── config/
│   │   │               │   ├── AppConfig.java
│   │   │               │   ├── SecurityConfig.java
│   │   │               │   └── DatabaseConfig.java
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               │   ├── impl/
│   │   │               │   └── dto/
│   │   │               ├── repository/
│   │   │               ├── entity/
│   │   │               ├── exception/
│   │   │               └── util/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       ├── application-prod.yml
│   │       ├── logback-spring.xml
│   │       ├── banner.txt
│   │       └── db/
│   │           └── migration/
│   └── test/
│       ├── java/
│       │   └── com/
│       │       └── company/
│       │           └── project/
│       │               ├── integration/
│       │               ├── unit/
│       │               └── TestApplication.java
│       └── resources/
│           └── application-test.yml
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.prod.yml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── cd.yml
├── docs/
│   ├── api/
│   └── setup/
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   └── setup.sh
├── pom.xml
├── README.md
└── .gitignore

核心依賴管理

完整的 Maven 依賴配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.5</version>
        <relativePath/>
    </parent>

    <groupId>com.company</groupId>
    <artifactId>side-project</artifactId>
    <version>1.0.0</version>
    <name>Side Project</name>
    <description>Enterprise Side Project Configuration</description>
    <packaging>jar</packaging>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <spring-cloud.version>2022.0.4</spring-cloud.version>
        <springdoc.version>2.2.0</springdoc.version>
        <mapstruct.version>1.5.5.Final</mapstruct.version>
        <testcontainers.version>1.19.0</testcontainers.version>
        <jackson.version>2.15.2</jackson.version>
        <guava.version>32.1.2-jre</guava.version>
        <commons-lang3.version>3.13.0</commons-lang3.version>
        <liquibase.version>4.23.2</liquibase.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>

        <!-- Database -->
        <dependency>
            <!-- Spring Boot 3 / MySQL 8.0.31+ 請改用新 artifact -->
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.3.0</version>
        </dependency>
        
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Database Migration -->
        <dependency>
            <groupId>org.liquibase</groupId>
            <artifactId>liquibase-core</artifactId>
            <version>${liquibase.version}</version>
        </dependency>

        <!-- Documentation -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc.version}</version>
        </dependency>

        <!-- JSON Processing -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
            <version>${jackson.version}</version>
        </dependency>

        <!-- Utilities -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>${commons-lang3.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${guava.version}</version>
        </dependency>

        <!-- Mapping -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${mapstruct.version}</version>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Monitoring -->
        <dependency>
            <groupId>io.micrometer</groupId>
            <artifactId>micrometer-registry-prometheus</artifactId>
        </dependency>
        
        <dependency>
            <groupId>net.logstash.logback</groupId>
            <artifactId>logstash-logback-encoder</artifactId>
            <version>7.4</version>
        </dependency>

        <!-- JWT -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
            <version>0.11.5</version>
        </dependency>
        
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
            <version>0.11.5</version>
            <scope>runtime</scope>
        </dependency>
        
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
            <version>0.11.5</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Test Dependencies -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>mysql</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>redis</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${mapstruct.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok-mapstruct-binding</artifactId>
                            <version>0.2.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.liquibase</groupId>
                <artifactId>liquibase-maven-plugin</artifactId>
                <version>${liquibase.version}</version>
                <configuration>
                    <propertyFile>src/main/resources/liquibase.properties</propertyFile>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.10</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>report</id>
                        <phase>test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            
            <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>jib-maven-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <from>
                        <image>eclipse-temurin:17-jre-alpine</image>
                    </from>
                    <to>
                        <image>your-registry/side-project:${project.version}</image>
                    </to>
                    <container>
                        <jvmFlags>
                            <jvmFlag>-Xms512m</jvmFlag>
                            <jvmFlag>-Xmx2g</jvmFlag>
                        </jvmFlags>
                        <mainClass>com.company.project.Application</mainClass>
                        <ports>
                            <port>8080</port>
                        </ports>
                    </container>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

應用程式配置

主要配置檔案 - application.yml

# 應用程式配置
spring:
  application:
    name: side-project
  
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
  
  # 資料庫配置
  datasource:
    url: jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:side_project}?useSSL=false&serverTimezone=Asia/Taipei&allowPublicKeyRetrieval=true
    username: ${DB_USERNAME:root}
    password: ${DB_PASSWORD:password}
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      idle-timeout: 30000
      connection-timeout: 30000
      max-lifetime: 1800000
      pool-name: HikariCP
  
  # JPA 配置
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true
        use_sql_comments: true
        jdbc:
          batch_size: 25
          order_inserts: true
          order_updates: true
        connection:
          provider_disables_autocommit: true
        query:
          in_clause_parameter_padding: true
        cache:
          use_second_level_cache: true
          use_query_cache: true
          region:
            factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
  
  # Redis 配置
  redis:
    host: ${REDIS_HOST:localhost}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    database: 0
    timeout: 10000ms
    lettuce:
      pool:
        max-active: 200
        max-idle: 20
        min-idle: 5
        max-wait: 10000ms
  
  # Cache 配置
  cache:
    type: redis
    redis:
      time-to-live: 600000
      cache-null-values: false
  
  # Security 配置
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID:your-google-client-id}
            client-secret: ${GOOGLE_CLIENT_SECRET:your-google-client-secret}
            scope: openid,profile,email
  
  # Liquibase 配置
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml
    enabled: true
  
  # Jackson 配置
  jackson:
    serialization:
      write-dates-as-timestamps: false
      indent-output: true
    deserialization:
      fail-on-unknown-properties: false
    time-zone: Asia/Taipei
    default-property-inclusion: non_null

# 服務器配置
server:
  port: ${SERVER_PORT:8080}
  servlet:
    context-path: /api
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
    min-response-size: 1024
  error:
    include-stacktrace: never
    include-message: always

# 日誌配置
logging:
  level:
    root: INFO
    com.company.project: DEBUG
    org.springframework.security: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/application.log
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30

# 管理端點配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,liquibase,caches
  endpoint:
    health:
      show-details: always
  health:
    redis:
      enabled: true
    db:
      enabled: true
  metrics:
    export:
      prometheus:
        enabled: true
    tags:
      application: ${spring.application.name}
      environment: ${spring.profiles.active}

# SpringDoc 配置
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: method
    tags-sorter: alpha
  packages-to-scan: com.company.project.controller

# 應用程式自訂配置
app:
  jwt:
    secret: ${JWT_SECRET:your-secret-key-must-be-at-least-256-bits}
    expiration: ${JWT_EXPIRATION:86400000} # 24 hours
    refresh-expiration: ${JWT_REFRESH_EXPIRATION:604800000} # 7 days
  
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000,http://localhost:8080}
    allowed-methods: ${CORS_ALLOWED_METHODS:GET,POST,PUT,DELETE,OPTIONS}
    allowed-headers: ${CORS_ALLOWED_HEADERS:*}
    allow-credentials: true
  
  rate-limit:
    enabled: true
    requests-per-minute: 60
    burst-capacity: 100
  
  file-storage:
    upload-dir: ${FILE_UPLOAD_DIR:uploads/}
    max-file-size: ${MAX_FILE_SIZE:10MB}
    allowed-extensions: ${ALLOWED_EXTENSIONS:jpg,jpeg,png,gif,pdf,docx,xlsx}

開發環境配置 - application-dev.yml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/side_project_dev?useSSL=false&serverTimezone=Asia/Taipei
    username: root
    password: mysql
  
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
  
  redis:
    host: localhost
    port: 6379
  
  liquibase:
    enabled: false

logging:
  level:
    root: DEBUG
    com.company.project: DEBUG
    org.springframework.web: DEBUG
    org.springframework.security: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: "*"

app:
  jwt:
    secret: dev-secret-key-for-development-only-not-for-production
    expiration: 86400000
  
  cors:
    allowed-origins: "http://localhost:3000,http://localhost:8080"

生產環境配置 - application-prod.yml

spring:
  datasource:
    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useSSL=true&serverTimezone=Asia/Taipei
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      minimum-idle: 10
      maximum-pool-size: 50
      idle-timeout: 60000
      connection-timeout: 30000
      max-lifetime: 1800000
  
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
  
  redis:
    host: ${REDIS_HOST}
    port: ${REDIS_PORT}
    password: ${REDIS_PASSWORD}
    ssl: true
  
  liquibase:
    enabled: true

logging:
  level:
    root: WARN
    com.company.project: INFO
  file:
    name: /var/log/side-project/application.log

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when-authorized

app:
  jwt:
    secret: ${JWT_SECRET}
    expiration: ${JWT_EXPIRATION:3600000}
  
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS}

核心配置類別

主要應用程式配置

package com.company.project.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import lombok.Data;

@Data
@Configuration
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    
    private Jwt jwt = new Jwt();
    private Cors cors = new Cors();
    private RateLimit rateLimit = new RateLimit();
    private FileStorage fileStorage = new FileStorage();
    
    @Data
    public static class Jwt {
        private String secret;
        private long expiration;
        private long refreshExpiration;
    }
    
    @Data
    public static class Cors {
        private String allowedOrigins;
        private String allowedMethods;
        private String allowedHeaders;
        private boolean allowCredentials;
    }
    
    @Data
    public static class RateLimit {
        private boolean enabled;
        private int requestsPerMinute;
        private int burstCapacity;
    }
    
    @Data
    public static class FileStorage {
        private String uploadDir;
        private String maxFileSize;
        private String allowedExtensions;
    }
}

資料庫配置

package com.company.project.config;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

import javax.sql.DataSource;

@Configuration
@EnableJpaRepositories(basePackages = "com.company.project.repository")
@EnableJpaAuditing
@EnableTransactionManagement
public class DatabaseConfig {

    @Bean
    @Primary
    @ConfigurationProperties("spring.datasource.hikari")
    public HikariConfig hikariConfig() {
        return new HikariConfig();
    }

    @Bean
    @Primary
    public DataSource dataSource() {
        return new HikariDataSource(hikariConfig());
    }
}

Redis 配置

package com.company.project.config;

import org.springframework.boot.autoconfigure.data.redis.RedisProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.StringRedisSerializer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.CacheManager;
import org.springframework.data.redis.cache.RedisCacheManager;
import org.springframework.data.redis.cache.RedisCacheConfiguration;

import java.time.Duration;

@Configuration
@EnableCaching
public class RedisConfig {

    @Bean
    public RedisConnectionFactory redisConnectionFactory(RedisProperties redisProperties) {
        return new LettuceConnectionFactory(redisProperties.getHost(), redisProperties.getPort());
    }

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        
        // 設定序列化器
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
        template.setHashKeySerializer(new StringRedisSerializer());
        template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer());
        
        template.afterPropertiesSet();
        return template;
    }

    @Bean
    public CacheManager cacheManager(RedisConnectionFactory connectionFactory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                .entryTtl(Duration.ofMinutes(10))
                .serializeKeysWith(org.springframework.data.redis.serializer.RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
                .serializeValuesWith(org.springframework.data.redis.serializer.RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));

        return RedisCacheManager.builder(connectionFactory)
                .cacheDefaults(config)
                .build();
    }
}

安全配置

package com.company.project.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.Arrays;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final AppProperties appProperties;
    private final JwtAuthenticationFilter jwtAuthenticationFilter;

    public SecurityConfig(AppProperties appProperties, JwtAuthenticationFilter jwtAuthenticationFilter) {
        this.appProperties = appProperties;
        this.jwtAuthenticationFilter = jwtAuthenticationFilter;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf(csrf -> csrf.disable())
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/auth/**", "/api/public/**").permitAll()
                .requestMatchers("/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .anyRequest().authenticated()
            )
            .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(Arrays.asList(appProperties.getCors().getAllowedOrigins().split(",")));
        configuration.setAllowedMethods(Arrays.asList(appProperties.getCors().getAllowedMethods().split(",")));
        configuration.setAllowedHeaders(Arrays.asList(appProperties.getCors().getAllowedHeaders().split(",")));
        configuration.setAllowCredentials(appProperties.getCors().isAllowCredentials());
        
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

OpenAPI 配置

package com.company.project.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Side Project API")
                        .version("1.0.0")
                        .description("Enterprise Side Project API Documentation")
                        .contact(new Contact()
                                .name("Bill Lin")
                                .email("bill@example.com")
                                .url("https://github.com/yourhandle"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT")))
                .addSecurityItem(new SecurityRequirement().addList("Bearer Authentication"))
                .components(new Components()
                        .addSecuritySchemes("Bearer Authentication",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

容器化配置

Dockerfile

# Multi-stage build
FROM eclipse-temurin:17-jdk-alpine AS builder

WORKDIR /app
COPY pom.xml .
COPY src ./src

RUN ./mvnw clean package -DskipTests

FROM eclipse-temurin:17-jre-alpine

# 建立非 root 使用者
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup

WORKDIR /app

# 複製 JAR 檔案
COPY --from=builder /app/target/*.jar app.jar

# 建立必要目錄
RUN mkdir -p /app/logs /app/uploads && \
    chown -R appuser:appgroup /app

# 切換到非 root 使用者
USER appuser

# 健康檢查
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

# 暴露埠號
EXPOSE 8080

# JVM 調優參數
ENV JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/"

# 啟動應用程式
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_NAME=side_project
      - DB_USERNAME=root
      - DB_PASSWORD=mysql
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - mysql
      - redis
    volumes:
      - ./logs:/app/logs
      - ./uploads:/app/uploads
    networks:
      - app-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=mysql
      - MYSQL_DATABASE=side_project
      - MYSQL_USER=app
      - MYSQL_PASSWORD=app
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - app-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - app-network
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./docker/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
    networks:
      - app-network
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana
      - ./docker/grafana/dashboards:/etc/grafana/provisioning/dashboards
      - ./docker/grafana/datasources:/etc/grafana/provisioning/datasources
    networks:
      - app-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./docker/nginx/ssl:/etc/nginx/ssl
    depends_on:
      - app
    networks:
      - app-network
    restart: unless-stopped

volumes:
  mysql_data:
  redis_data:
  grafana_data:

networks:
  app-network:
    driver: bridge

生產環境 docker-compose.prod.yml

version: '3.8'

services:
  app:
    image: your-registry/side-project:latest
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 2G
          cpus: '1'
        reservations:
          memory: 1G
          cpus: '0.5'
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - DB_HOST=mysql-prod
      - DB_PORT=3306
      - DB_NAME=side_project_prod
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=redis-prod
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - JWT_SECRET=${JWT_SECRET}
    secrets:
      - db_password
      - jwt_secret
    networks:
      - app-network
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  mysql-prod:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_password
      - MYSQL_DATABASE=side_project_prod
    volumes:
      - mysql_prod_data:/var/lib/mysql
    secrets:
      - db_password
    networks:
      - app-network
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1'

  redis-prod:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_prod_data:/data
    networks:
      - app-network
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

secrets:
  db_password:
    external: true
  jwt_secret:
    external: true

volumes:
  mysql_prod_data:
  redis_prod_data:

networks:
  app-network:
    driver: overlay

監控配置

logback-spring.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    
    <springProfile name="!prod">
        <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>
    
    <springProfile name="prod">
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>/var/log/side-project/application.log</file>
            <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
                <providers>
                    <timestamp/>
                    <logLevel/>
                    <loggerName/>
                    <mdc/>
                    <message/>
                    <stackTrace/>
                </providers>
            </encoder>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>/var/log/side-project/application.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>100MB</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
                <maxHistory>30</maxHistory>
                <totalSizeCap>3GB</totalSizeCap>
            </rollingPolicy>
        </appender>
        
        <appender name="METRICS" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>/var/log/side-project/metrics.log</file>
            <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
                <providers>
                    <timestamp/>
                    <logLevel/>
                    <loggerName/>
                    <mdc/>
                    <message/>
                </providers>
            </encoder>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>/var/log/side-project/metrics.%d{yyyy-MM-dd}.log</fileNamePattern>
                <maxHistory>7</maxHistory>
            </rollingPolicy>
        </appender>
        
        <logger name="metrics" level="INFO" additivity="false">
            <appender-ref ref="METRICS"/>
        </logger>
        
        <root level="INFO">
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>
</configuration>

Prometheus 配置

# docker/prometheus/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'side-project'
    static_configs:
      - targets: ['app:8080']
    metrics_path: '/actuator/prometheus'
    scrape_interval: 10s
    
  - job_name: 'mysql'
    static_configs:
      - targets: ['mysql:3306']
    
  - job_name: 'redis'
    static_configs:
      - targets: ['redis:6379']

CI/CD 配置

GitHub Actions - CI

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: mysql
          MYSQL_DATABASE: side_project_test
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3
      
      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379
        options: >-
          --health-cmd="redis-cli ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Cache Maven dependencies
      uses: actions/cache@v3
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
        restore-keys: ${{ runner.os }}-m2
    
    - name: Run tests
      run: mvn clean test
      env:
        SPRING_PROFILES_ACTIVE: test
        DB_HOST: localhost
        DB_PORT: 3306
        DB_NAME: side_project_test
        DB_USERNAME: root
        DB_PASSWORD: mysql
        REDIS_HOST: localhost
        REDIS_PORT: 6379
    
    - name: Generate test report
      uses: dorny/test-reporter@v1
      if: success() || failure()
      with:
        name: Maven Tests
        path: target/surefire-reports/*.xml
        reporter: java-junit
    
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3
      with:
        file: ./target/site/jacoco/jacoco.xml
    
    - name: SonarCloud Scan
      uses: SonarSource/sonarcloud-github-action@master
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

GitHub Actions - CD

# .github/workflows/cd.yml
name: CD

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Build with Maven
      run: mvn clean package -DskipTests
    
    - name: Build Docker image
      run: |
        docker build -t ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }} .
        docker tag ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }} ${{ secrets.REGISTRY_URL }}/side-project:latest
    
    - name: Login to Container Registry
      uses: docker/login-action@v2
      with:
        registry: ${{ secrets.REGISTRY_URL }}
        username: ${{ secrets.REGISTRY_USERNAME }}
        password: ${{ secrets.REGISTRY_PASSWORD }}
    
    - name: Push Docker image
      run: |
        docker push ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }}
        docker push ${{ secrets.REGISTRY_URL }}/side-project:latest
    
    - name: Deploy to production
      uses: appleboy/ssh-action@v0.1.5
      with:
        host: ${{ secrets.HOST }}
        username: ${{ secrets.USERNAME }}
        key: ${{ secrets.SSH_KEY }}
        script: |
          cd /opt/side-project
          docker-compose pull
          docker-compose up -d
          docker system prune -f

部署腳本

建構腳本 - scripts/build.sh

#!/bin/bash

# 建構腳本
set -e

echo "開始建構 Side Project..."

# 清理舊的建構檔案
echo "清理舊的建構檔案..."
mvn clean

# 執行測試
echo "執行測試..."
mvn test

# 建構應用程式
echo "建構應用程式..."
mvn package -DskipTests

# 建構 Docker 映像
echo "建構 Docker 映像..."
docker build -t side-project:latest .

echo "建構完成！"

部署腳本 - scripts/deploy.sh

#!/bin/bash

# 部署腳本
set -e

ENVIRONMENT=${1:-dev}
VERSION=${2:-latest}

echo "部署 Side Project 到 $ENVIRONMENT 環境..."

case $ENVIRONMENT in
    "dev")
        echo "部署到開發環境..."
        docker-compose -f docker-compose.yml up -d
        ;;
    "staging")
        echo "部署到測試環境..."
        docker-compose -f docker-compose.staging.yml up -d
        ;;
    "prod")
        echo "部署到生產環境..."
        docker-compose -f docker-compose.prod.yml up -d
        ;;
    *)
        echo "未知環境: $ENVIRONMENT"
        exit 1
        ;;
esac

echo "部署完成！"
echo "健康檢查中..."
sleep 30

# 健康檢查
for i in {1..5}; do
    if curl -f http://localhost:8080/actuator/health > /dev/null 2>&1; then
        echo "應用程式健康狀態正常"
        break
    else
        echo "健康檢查失敗，重試中... ($i/5)"
        sleep 10
    fi
done

resources/banner.txt

   _____ _     _        _____           _           _   
  / ____(_)   | |      |  __ \         (_)         | |  
 | (___  _  __| | ___  | |__) |____ ___ _  ___  ___| |_ 
  \___ \| |/ _` |/ _ \ |  ___/ '__/ _ \ |/ _ \/ __| __|
  ____) | | (_| |  __/ | |   | | | (_) | |  __/ (__| |_ 
 |_____/|_|\__,_|\___| |_|   |_|  \___/| |\___|\___|\__|
                                      _/ |              
                                     |__/               

:: Spring Boot :: (v3.1.5)
:: Application Version :: 1.0.0
:: Environment :: ${spring.profiles.active}
:: Port :: ${server.port}

最佳實踐與建議

1. 安全性最佳實踐

# 生產環境安全配置
security:
  headers:
    frame-options: DENY
    content-type-options: nosniff
    xss-protection: 1; mode=block
    referrer-policy: strict-origin-when-cross-origin
  
  ssl:
    enabled: true
    key-store: /etc/ssl/keystore.p12
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    key-store-type: PKCS12

2. 效能優化配置

# JVM 調優
JAVA_OPTS: >
  -server
  -Xms1g
  -Xmx2g
  -XX:+UseG1GC
  -XX:MaxGCPauseMillis=200
  -XX:+UseStringDeduplication
  -XX:+HeapDumpOnOutOfMemoryError
  -XX:HeapDumpPath=/var/log/side-project/
  -Dspring.profiles.active=prod

3. 監控與告警

# 自訂監控指標
management:
  metrics:
    export:
      prometheus:
        enabled: true
      cloudwatch:
        enabled: true
        namespace: SideProject
        step: 1m
    distribution:
      percentiles:
        http.server.requests: 0.5, 0.95, 0.99
        spring.data.repository.invocations: 0.5, 0.95, 0.99

4. 資料庫優化

# 資料庫連線池優化
spring:
  datasource:
    hikari:
      minimum-idle: 10
      maximum-pool-size: 50
      idle-timeout: 600000
      connection-timeout: 30000
      max-lifetime: 1800000
      leak-detection-threshold: 60000
      connection-test-query: SELECT 1

踩坑紀錄

Spring Boot 3 Jakarta 遷移

Spring Boot 3 需要 Java 17+ 且所有 javax.* → jakarta.*。若從 Boot 2.x 升級，常見的 compile error：