36 lines
4.2 KiB
Markdown
36 lines
4.2 KiB
Markdown
---
|
||
name: spec-dockerfile
|
||
description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc-shared:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-dockerfile — 共用 Dockerfile 六步流程
|
||
|
||
Dockerfile 一律組織為以下**固定六步流程**，並採**多階段建置**縮小最終映像。六步是骨架，每一步的實際內容必須依專案／主程式實作決定 — 不要套用與其無關的固定樣板，也不要硬塞用不到的安裝或建置指令。
|
||
|
||
## 六步流程
|
||
|
||
1. **參數處理**：可調參數集中到檔案開頭以 `ARG` 注入（base image 版本、build flag、路徑等）；`# syntax` 指示與全域 `ARG` 置於最前。
|
||
2. **安裝套件**：先 `COPY` 相依描述檔（`package*.json`／`requirements.txt`／`go.mod go.sum`／`*.csproj` 等）再安裝，以利 layer 快取；OS 套件與語言相依在此安裝，安裝後於**同一 `RUN`** 清理快取（`apt-get clean`／`rm -rf /var/lib/apt/lists/*`、`--no-cache`）。安裝指令**二擇一寫死**（如有 lockfile 用 `npm ci`、否則 `npm install`），不得以 `A || B` fallback 串接（避免靜默吞錯、破壞可重現性）。OS 套件只在真的會用到時才安裝。
|
||
3. **複製檔案**：`COPY` 實際需要的檔案，**明列路徑、不整包 `COPY .`**（除非重整既有 Dockerfile 需保留原行為），並配合 `.dockerignore` 排除無關檔案（至少 `.git`、`.docs`、`node_modules` 等非執行必需檔）。
|
||
4. **執行程序**：build／compile／transpile（`npm run build`／`go build`／`dotnet publish` 等）與必要的權限設定（`chmod`）於此執行；不需 build 時此步只做權限設定。
|
||
5. **縮小映像檔**：多階段建置，runtime 階段改用較小基底（`*-slim`／`*-alpine`／`distroless`／`scratch`，依語言對應），只 `COPY --from=<build>` 帶入**執行所必需**的產物；**必須逐項明列路徑，不得整包搬**（整包搬等於沒有縮小）。不把 build 期 dev 相依與快取帶進最終映像；runtime 需要的 OS 執行檔於 runtime 階段安裝；同步搬移 runtime 需要的 `ENV`／`WORKDIR`／`EXPOSE`／`USER`。
|
||
6. **設定入口**：`ENTRYPOINT`／`CMD` 置於最後，語意與需求（或原檔）一致。
|
||
|
||
## base image 版本
|
||
|
||
- **預設使用固定 major tag**（如 `node:22` 與 `node:22-slim`），不用 `latest` — 避免 base 無預警跳版導致行為漂移、跨環境不一致、無法重現除錯。
|
||
- runtime 基底版號需與 build 基底一致，以**獨立的 runtime ARG** 帶入（如 `NODE_RUNTIME=22-slim`），不要用 `${VERSION}-slim` 組裝。tag 已是 `-alpine`／`-slim` 變體時，build 與 runtime **直接沿用同一 tag**、不再另組（沒有 `node:22-alpine-slim` 這種 tag）。使用者明確要求 `latest` 時，runtime 用 `node:slim`（**沒有 `node:latest-slim`**）。
|
||
|
||
## 對外契約不動（重整既有 Dockerfile 時）
|
||
|
||
- `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
|
||
- 凡無法可靠保證建置行為等價的重整（`ARG` 作用範圍跨 `FROM`、`COPY` 順序影響覆蓋、`RUN` 間狀態相依、單階段改多階段時 runtime 缺檔），先確認或標 `# 需人工確認` 退回最小重排。
|
||
|
||
## 自我檢查
|
||
|
||
1. `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）。
|
||
2. runtime 階段 `COPY --from` 帶齊執行所需全部產物（執行檔、相依、靜態資源），容器能啟動。
|
||
3. 對外契約（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`）語意一致。
|
||
4. 路徑一致：`WORKDIR`／`COPY` 落點與入口（`entrypoint.sh`／主程式路徑）對得上。
|
||
5. 若環境可執行，`docker build`（或至少 `--check`／語法檢查）驗證可建置；無法執行時說明原因並標註風險。
|