實戰：把 Spring Boot 專案打包成 Image

假設你有一個再普通不過的 Spring Boot 專案：

myapp/
├── pom.xml
├── src/
│   └── main/
│       ├── java/com/example/myapp/MyappApplication.java
│       └── resources/application.yml
└── target/                  ← mvn package 之後才會出現
    └── myapp-0.0.1-SNAPSHOT.jar

關鍵認知：Spring Boot 的 jar 是「fat jar」

• mvn package 產生的那個 jar 裡面已經包含了所有相依函式庫（Spring、Jackson、JDBC driver…）和一個內嵌的 Tomcat。
• 所以執行它只需要一個 JRE：

  java -jar target/myapp-0.0.1-SNAPSHOT.jar

• 不需要安裝 Tomcat、不需要 war 檔、不需要應用伺服器。這件事大幅簡化了容器化——容器裡只要有 Java 執行環境和這個 jar 就夠了。

所以映像裡到底要放什麼？

知道目標長怎樣之後，寫 Dockerfile 就只是把這三件事翻譯成指令而已。

先做出一個能動的。在專案根目錄建立 Dockerfile：

# === 第一版：可以跑，但很多問題（等一下逐一修） ===
FROM eclipse-temurin:17-jre-jammy

WORKDIR /app

COPY target/myapp-0.0.1-SNAPSHOT.jar app.jar

EXPOSE 8080

CMD ["java", "-jar", "app.jar"]

逐行解讀（每一行都對應到前面某一章）

• FROM eclipse-temurin:17-jre-jammy：以 Eclipse Temurin 的 JRE 17 為基底（jammy ＝ Ubuntu 22.04）。用明確版本而不是 latest（ch04）。
• WORKDIR /app：設定工作目錄，之後的相對路徑以此為準（ch08）。
• COPY ...：把本機 target/ 下的 jar 複製進映像並改名 app.jar。改名是為了避免 Dockerfile 寫死版本號（不然每次改版本都要改 Dockerfile）。
• EXPOSE 8080：文件宣告，實際要靠 -p（ch07）。
• CMD [...]：exec form，讓 java 成為 PID 1，SIGTERM 收得到（ch05）。

建置與執行

# ① 先在本機打包（第一版的缺點之一，等下會解決）
mvn clean package -DskipTests

# ② 建置映像
docker build -t myapp:1.0 .

# ③ 執行
docker run -d --name myapp -p 8080:8080 myapp:1.0

# ④ 確認
docker logs -f myapp
curl http://localhost:8080/actuator/health

# ⑤ 進去看看（觀察，不要改東西）
docker exec -it myapp bash

# ⑥ 清掉
docker rm -f myapp

它現在有五個問題

1. 依賴本機環境：必須先在自己電腦上 mvn package。同事沒裝 Maven、或 JDK 版本不同，結果就不一樣——ch01 那個「在我電腦上可以跑」又回來了。
2. 映像偏大：JRE 基底約 190 MB ＋ 你的 fat jar。可以更小。
3. 快取效率差：jar 是單一檔案，改一行程式碼整個 jar 的雜湊就變了，那一層完全重建、重新推送（ch08）。
4. 以 root 執行：預設身分是 root，一旦被入侵風險極高（ch02、ch10）。
5. JVM 不知道自己被關在容器裡：記憶體設定可能出大事。這是下一張卡的主題。

這是 Java 開發者最該懂、卻最少人講清楚的一段。

問題的根源

• JVM 啟動時會自動決定 heap 的最大值（沒指定 -Xmx 時預設約為「可見記憶體的 1/4」）。
• 「可見記憶體」怎麼來的？舊版 JVM 是去讀「這台機器有多少記憶體」——於是它看到宿主機的 32 GB，決定 heap 上限 8 GB。
• 但你的容器 cgroup 只給了 512 MB（ch02）。

好消息：現代 JVM 已經看得懂 cgroup

• JDK 10 起（並回溯到 8u191+）內建容器感知，會去讀 cgroup 限制而不是宿主機記憶體。
• 你用 JDK 17 的話，這個問題預設已經解決。可以驗證：

  docker run --rm -m 512m eclipse-temurin:17-jre java -XX:+PrintFlagsFinal -version | grep MaxHeapSize
  # 應該顯示約 128 MB（512 的 1/4），而不是宿主機的 1/4

但預設值仍然不夠好：1/4 太保守

容器裡通常只跑你一個應用，把 75% 留著不用太浪費。正確作法是用比例而非固定值：

ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 -XX:InitialRAMPercentage=50.0"
ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]

還有一個常被忽略的重點：heap 不等於容器記憶體用量

JVM 除了 heap 還要用：metaspace（類別資訊）、執行緒堆疊（每條約 1 MB）、JIT 編譯的程式碼快取、直接記憶體（NIO buffer）、GC 自己的結構。

• 所以 MaxRAMPercentage=75 留 25% 給這些「非 heap」開銷，是經驗上合理的起點。
• 設成 100 保證會被 OOMKilled。
• 容器記憶體上限也不要開太小：Spring Boot 應用實務上建議至少 512 MB，小於這個常常啟動就掛。

排查流程

docker inspect myapp --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
#  true 137  → 確定是被 OOM Killer 殺的

docker stats myapp        # 即時看「已用 / 上限」

# 讓 JVM 在真的 OOM 時留下證據
ENV JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/heapdump.hprof"
docker cp myapp:/tmp/heapdump.hprof ./     # 撈出來分析

解決第一版的問題 ①（依賴本機 Maven）與 ②（映像大）。核心概念：在映像裡編譯，但編譯環境不進最終映像。

# syntax=docker/dockerfile:1

# ========== 第 1 階段：建置（用完就丟）==========
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /build

# 先只複製 pom.xml，讓依賴下載可以被快取（ch08 第一設計原則）
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 mvn dependency:go-offline -B

# 再複製原始碼（常變動的放後面）
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 mvn clean package -DskipTests -B

# ========== 第 2 階段：執行（這才是最終映像）==========
FROM eclipse-temurin:17-jre-jammy
WORKDIR /app

# 建立非 root 使用者（ch10 會深入）
RUN groupadd -r spring && useradd -r -g spring spring

# 只從建置階段複製「成品」，Maven、原始碼、.m2 通通不會進來
COPY --from=builder --chown=spring:spring /build/target/*.jar app.jar

USER spring
EXPOSE 8080

ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0"
ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]

關鍵在 COPY --from

四個立刻拿到的好處

1. 任何有 Docker 的機器都能建置，不必先裝 Maven 或特定 JDK。ch01 的環境一致性，這次連建置過程也涵蓋了。
2. 最終映像只有 JRE ＋ 你的 jar（約 200 MB），而不是 800 MB。
3. CI 友善：`docker build` 一行搞定，不需要在 CI 裡另外配置 Java 環境。
4. 安全：原始碼、建置工具、Maven 憑證都不在最終映像裡——攻擊面小很多。

那個 ENTRYPOINT 為什麼要用 sh -c？

• 因為要展開 $JAVA_OPTS 這個變數，而 exec form 不經過 shell 就不會展開。
• 但注意前面加了 exec——這讓 java 取代 shell、繼承 PID 1，訊號才收得到（ch05、ch08）。少了這個 exec，前面所有的優雅關機設定都白費。
• 如果你不需要動態調整 JVM 參數，最乾淨的寫法還是純 exec form：ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "/app/app.jar"]。

鐵律：映像只有一份，環境差異全部靠外部注入。絕對不要為 dev / test / prod 各建一個映像——那樣你正式環境跑的，就不是你測過的那個東西。

Spring Boot 的環境變數對應規則（relaxed binding）

Spring Boot 會自動把環境變數對應到設定屬性，規則很單純：點改成底線、全部大寫。

spring.datasource.url        →  SPRING_DATASOURCE_URL
spring.datasource.username   →  SPRING_DATASOURCE_USERNAME
spring.jpa.hibernate.ddl-auto →  SPRING_JPA_HIBERNATE_DDLAUTO   （連字號直接去掉）
server.port                  →  SERVER_PORT

docker run -d \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e SPRING_DATASOURCE_URL='jdbc:sqlserver://sqlserver:1433;databaseName=mydb' \
  -e SPRING_DATASOURCE_USERNAME=sa \
  -e SPRING_DATASOURCE_PASSWORD="$DB_PASSWORD" \
  myapp:1.0

設定的優先順序（高到低）

1. 指令列參數（--spring.datasource.url=...）
2. 環境變數 ← 容器化的主要管道
3. 外部設定檔（掛進去的 application.yml）
4. jar 內的 application-{profile}.yml
5. jar 內的 application.yml（只放各環境共通的預設值）

密碼絕對不要用這三種方式

• ❌ 寫在 application.yml 裡打包進 jar（永久留在映像層，ch03）。
• ❌ 寫在 Dockerfile 的 ENV（docker inspect 就看得到）。
• ❌ 寫死在 docker-compose.yml（這份檔案會進版控）。

正確作法（由簡到嚴謹）：

• 開發：.env 檔（務必加進 .gitignore）＋ compose 的 ${VAR} 展開。
• 正式：容器平台的 secret 機制（Docker Swarm secrets、K8s Secret）或雲端服務（AWS Secrets Manager、Parameter Store，見 AWS ch10）。

日誌與時區兩個小坑

• 日誌印到 stdout（ch05）：Spring Boot 預設就是，不要去設定 file appender。
• 時區：容器預設 UTC，你的資料庫時間會差 8 小時。

  ENV TZ=Asia/Taipei

  （更嚴謹的做法是全系統統一用 UTC，只在顯示層轉換。）

解決第一版的問題 ③（快取效率差）。這是 Spring Boot 官方提供的進階技巧。

問題回顧

fat jar 是單一檔案，裡面 95% 是不常變的第三方函式庫、5% 是你的程式碼。但 Docker 的層是以檔案為單位——你改一行程式碼，整個 60 MB 的 jar 雜湊就變了，那一層完全重建、推送時整個 60 MB 重傳。

解法：Spring Boot 的 layertools 把 jar 拆成四層

java -Djarmode=layertools -jar app.jar list

dependencies           ← 第三方函式庫（幾乎不變，最大）
spring-boot-loader     ← Spring Boot 載入器（幾乎不變）
snapshot-dependencies  ← SNAPSHOT 版依賴（偶爾變）
application            ← 你自己的程式碼與資源（每次都變，最小）

照這個順序複製到映像，每一個變成獨立的層——於是改程式碼時，只有最後那個幾 MB 的 application 層需要重建與推送。

最終版 Dockerfile（可以直接拿去用）

# syntax=docker/dockerfile:1

# ========== 階段 1：編譯 ==========
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /build
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 mvn dependency:go-offline -B
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 mvn clean package -DskipTests -B

# ========== 階段 2：拆解 fat jar ==========
FROM eclipse-temurin:17-jre-jammy AS extractor
WORKDIR /extract
COPY --from=builder /build/target/*.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract

# ========== 階段 3：最終映像 ==========
FROM eclipse-temurin:17-jre-jammy
WORKDIR /app

RUN groupadd -r spring && useradd -r -g spring spring

# 依「變動頻率由低到高」逐層複製 —— ch08 的第一設計原則
COPY --from=extractor --chown=spring:spring /extract/dependencies/ ./
COPY --from=extractor --chown=spring:spring /extract/spring-boot-loader/ ./
COPY --from=extractor --chown=spring:spring /extract/snapshot-dependencies/ ./
COPY --from=extractor --chown=spring:spring /extract/application/ ./

USER spring
EXPOSE 8080
ENV TZ=Asia/Taipei

HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
  CMD wget -qO- http://localhost:8080/actuator/health || exit 1

# 注意：分層之後不能再用 -jar，要用 Spring Boot 的啟動類別
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", \
            "org.springframework.boot.loader.launch.JarLauncher"]