Registry 與 Image 座標：那串很長的名字在說什麼

映像名稱是一組四段式座標，完整格式長這樣：

[registry 主機]/[命名空間]/[映像名]:[標籤]

mcr.microsoft.com  /  mssql  /  server  :  2022-latest
       ①              ②        ③          ④

• ① Registry 主機：去哪個倉庫拿。mcr.microsoft.com 是微軟自家的容器倉庫（Microsoft Container Registry）。省略時預設是 docker.io（Docker Hub）。
• ② 命名空間 / 帳號：倉庫裡哪個櫃子。通常是組織或使用者名稱，例如 mssql、bitnami、你的 Docker Hub 帳號。
• ③ 映像名（Repository）：櫃子裡哪個抽屜。同一個抽屜裡放著這個軟體的所有版本。
• ④ 標籤（Tag）：抽屜裡哪一份。省略時預設是 latest。

所以為什麼 nginx 可以只寫三個字母？

因為 Docker 會自動補完：

你寫的：      nginx
實際上是：    docker.io/library/nginx:latest
              ↑          ↑       ↑      ↑
          預設 registry  官方   映像名  預設 tag
                       命名空間

library 是 Docker Hub 保留給官方映像（Official Images）的特殊命名空間——由 Docker 官方或軟體原廠維護的那批（nginx、redis、postgres、eclipse-temurin…）。這也是一個安全訊號：

• redis（＝library/redis）→ 官方維護，可信度高。
• someguy/redis → 某個路人自己建的，內容你完全不知道。名字只差一個斜線，信任等級天差地遠。

它為什麼危險？三個現實後果

1. 它可能非常舊。如果維護者發布 v2.0 時忘了同時更新 latest，那 latest 就永遠停在 v1.0。「latest 指向最新」純粹是靠維護者自律，不是機制保證。
2. 它會偷偷改變，破壞可重現性。標籤只是一個「指向某個映像的可變指標」，維護者隨時可以把它重新指到別的映像。

   你今天：   docker pull myapp:latest   → 拿到 v1.0
   （維護者推了新版，latest 被重新指向 v2.0）
   同事明天： docker pull myapp:latest   → 拿到 v2.0

   同一行指令、同一個名字、不同的東西。這正是「在我電腦上可以跑」的容器版翻版——你以為容器解決了環境不一致，結果被 latest 又打回原形。
3. 它讓回滾變得不可能。正式環境爆炸想退回上一版，但你只知道「我們部署的是 latest」——那到底是哪一版？無從查起。

實務規則

• 開發環境：用明確的次版本標籤，例如 eclipse-temurin:17.0.9_9-jre-jammy，至少 17-jre。
• 正式環境：釘死到 digest（下一張卡），或至少釘死到不會被覆寫的完整版本號。
• 你自己的映像：用不可重複的識別碼當標籤——Git commit SHA 或建置編號，例如 myapp:1.4.2、myapp:a3f91c2。這樣「正式環境跑的是哪一版程式碼」永遠有答案。

既然標籤會變，那有沒有「絕對指向同一個東西」的方式？有，就是 digest。

docker pull nginx@sha256:0d17b565c37bcbd895e9d92315a05c1c3c9a29f762b011a10c54a66cd53c9b31

digest 是什麼

• 它是映像內容（manifest）算出來的 SHA-256 雜湊值。內容決定 ID，ID 決定內容——這種設計叫做內容尋址（content-addressable）。
• 只要內容變了一個位元組，digest 就完全不同。所以 digest 無法被「重新指向」，它天生不可變。
• 拉下來之後 Docker 會重算一次雜湊比對，順便驗證了完整性——傳輸過程被竄改或損毀都會被抓出來。

標籤 vs Digest 的類比

實務怎麼用

# 查出目前 tag 對應的 digest
docker inspect --format='{{index .RepoDigests 0}}' nginx:1.25

# compose 檔釘死（正式環境建議）
services:
  app:
    image: myregistry.io/myapp@sha256:abc123...

• Kubernetes 的正式環境部署普遍要求釘 digest，理由完全一樣：保證每個節點拉到的是同一份東西。
• 缺點很明顯：難讀、難記、更新時要改一長串。所以實務上常見折衷——CI 建置時用語意化標籤，部署時把它解析成 digest 再寫進部署設定，兩全其美。

你打 docker pull nginx 之後，實際上跟 registry 進行了三輪對話：

1. 要 manifest（清單）：「請給我 nginx:latest 的清單。」
   manifest 是一份小小的 JSON，記載著：這個映像由哪幾層組成（每層的 digest 和大小）、設定檔在哪。它本身不含實際資料，就是一張目錄。
2. 要 config（設定檔）：記載 CMD、ENV、USER、WORKDIR、架構等 metadata。
3. 逐層下載：比對本機已有哪些層（digest 相同就跳過，顯示 Already exists），只下載缺的。ch03 講的分層下載，就發生在這一步。

多架構映像：一個名字，好幾種 CPU 版本

問題來了：nginx:latest 要給 Intel/AMD 的 x86 伺服器用，也要給 M 系列 Mac 和樹莓派的 ARM 用。同一個名字，怎麼可能同時是兩種東西？

答案是 manifest list（又稱 image index）——一份「清單的清單」：

nginx:latest  (manifest list)
  ├── linux/amd64   → 指向 A 這份 manifest
  ├── linux/arm64   → 指向 B 這份 manifest
  └── linux/arm/v7  → 指向 C 這份 manifest

你 pull 的時候，Docker 會自動報上自己的作業系統與 CPU 架構，registry 就給對應的那份。所以你的 M1 Mac 拿到 arm64 版、公司的 x86 伺服器拿到 amd64 版——同一行指令，各取所需。

exec format error

# 指定單一目標架構
docker build --platform linux/amd64 -t myapp:1.0 .

# 一次建出多架構並推送（需要 buildx）
docker buildx build --platform linux/amd64,linux/arm64 \
  -t myregistry.io/myapp:1.0 --push .

推送的關鍵觀念只有一個：映像的名字就是它的位址。要推到哪裡，就得先把名字改成那個位址。

四個步驟

# ① 建置（本機名稱，還沒有 registry 位址）
docker build -t myapp:1.0 .

# ② 重新命名成「目的地座標」——這步是關鍵
docker tag myapp:1.0 yourname/myapp:1.0
#          ↑本機名     ↑帳號/映像名:版本

# ③ 登入
docker login

# ④ 推送
docker push yourname/myapp:1.0

• 推到非 Docker Hub 的 registry，名字前面要加主機：

  docker tag myapp:1.0 myharbor.company.com/team/myapp:1.0
  docker push myharbor.company.com/team/myapp:1.0

• docker tag 不會複製任何資料，只是替同一個映像多取一個名字（多一個指標）——所以它是瞬間完成的。

認證憑證存在哪裡（安全提醒）

• docker login 之後，憑證預設存在 ~/.docker/config.json，而且可能只是 base64 編碼，不是加密。任何能讀到這個檔案的人就拿到了你的推送權限。
• 正式環境的正解：用 credential helper（例如 docker-credential-ecr-login），或在 CI 用短期權杖（AWS ECR 的登入權杖 12 小時就過期）。

Docker Hub 的拉取次數限制（會突然咬你一口）

• Docker Hub 對匿名拉取有次數上限（以來源 IP 計算）。公司或 CI 環境常常是一整棟樓共用一個對外 IP——於是額度很快用完，CI 突然開始噴 toomanyrequests: You have reached your pull rate limit。
• 對策：登入後拉（額度較高）、在內網架 pull-through cache（本地鏡像快取）、或把常用映像複製一份到公司自己的 registry。

docker pull 這個動作的本質是：從網路上下載一整套別人準備的檔案系統，然後在你的機器上執行它。用這個角度想，就知道該謹慎了。

四個實務原則

1. 優先用官方或已驗證的映像。Docker Hub 上有 Official Image（library/ 命名空間）與 Verified Publisher 標記；沒有這兩者的映像，等於來路不明的執行檔。
2. 釘死版本，並定期更新。這兩件事看似矛盾，其實是一體兩面：釘死是為了可重現，定期更新是為了修補漏洞。作法是把「更新基底映像版本」變成一個明確的、有人負責的動作（例如 Dependabot 自動送 PR），而不是靠 latest 隨機決定。
3. 掃描漏洞。基底映像帶著整套系統函式庫，舊版本必然累積 CVE：

   docker scout cves myapp:1.0     # Docker 內建
   trivy image myapp:1.0           # 業界常用的開源工具

   接到 CI 裡，有高風險漏洞就擋下建置。
4. 用小的基底映像。ubuntu 基底裝了幾百個套件，每個都是潛在漏洞；alpine 或 distroless 只有必要的東西，攻擊面小一個數量級（ch10 詳談，含 Java 的選擇建議）。

進階：怎麼確認映像沒被掉包？

• digest 保證完整性（內容沒被改），但不保證來源（不能證明是誰做的）。
• 要證明來源，需要簽章：現代作法是 Sigstore / cosign，發布者用私鑰簽映像，你用公鑰驗證。
• 再上一層是 SBOM（軟體物料清單）：映像附上一份「我裡面裝了哪些套件與版本」的清單，出漏洞時能立刻查出自己是否受影響。