docker push 指令：推送映像檔到 Registry（--all-tags、docker login）

Q: 推送映像檔前為什麼要加上 Registry 標籤？

docker tag 建立指向來源映像檔的目標名稱；範例把 alpine:3.23 標記成 localhost:5000/tools/alpine:3.23，再推送該名稱。

Q: docker push --all-tags 會推送哪些標籤？

它會推送指定 Repository 的所有標籤。範例中 tools/alpine 的 3.23 與 latest 都被推送。

Q: 推送到 Docker Hub 出現 insufficient_scope 怎麼辦？

表示你沒有權限推送到這個 Repository。範例中的 docker.io/library/alpine 是 Docker 官方映像檔的命名空間，任何個人帳號都不能推送。要推送到 Docker Hub，先執行 docker login，再把映像檔標記成 你的帳號/名稱:標籤 後推送，見 [推送到 Docker Hub](/zh-tw/docker/docker-hub/)。

docker push 將映像檔上傳到 Registry，通常先用 docker tag 設定目標名稱；Docker Hub 的使用方式見 Docker Hub。

語法

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
docker push [OPTIONS] NAME[:TAG]
docker login [OPTIONS] [SERVER]

參數

參數	說明
`-a, --all-tags`	推送映像檔的所有標籤
`--platform 字串`	推送指定平台的 manifest 作為單一平台映像檔；不會推送 image index，因此其他 manifest（包括 attestations）不會保留。格式為 `os[/arch[/variant]]`，例如 `linux/amd64`
`-q, --quiet`	隱藏詳細輸出
`-p, --password 字串`	密碼或 Personal Access Token（PAT）；使用 `-` 從 stdin 讀取
`--password-stdin`	從 stdin 讀取密碼或 Personal Access Token（PAT）
`-u, --username 字串`	使用者名稱

docker login 未指定伺服器時，預設使用 Docker Hub。docker tag 的目標名稱格式為 TARGET_IMAGE[:TAG]。

範例

以下範例使用本機 Registry 的 localhost:5000，將 alpine:3.23 標記到 tools/alpine Repository。

建立目標標籤

$ docker tag alpine:3.23 localhost:5000/tools/alpine:3.23

$ docker tag alpine:3.23 localhost:5000/tools/alpine:latest

$ docker images localhost:5000/tools/alpine
IMAGE                                ID             DISK USAGE   CONTENT SIZE   EXTRA
localhost:5000/tools/alpine:3.23     ff7f0c727dd7       26.6MB         8.21MB        
localhost:5000/tools/alpine:latest   ff7f0c727dd7       26.6MB         8.21MB

兩個標籤都指向相同映像檔 ID。
目標名稱包含 Registry 主機與連接埠、Repository，以及各自的標籤。

推送單一標籤與所有標籤

$ docker push localhost:5000/tools/alpine:3.23
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Pushed
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push localhost:5000/tools/alpine:latest
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push --all-tags localhost:5000/tools/alpine
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

單一標籤推送會回報 digest；後續推送相同 Layer 時會顯示 Layer already exists。
--all-tags 對 tools/alpine 一次推送 3.23 和 latest。
Info 提示：alpine:3.23 是多平台映像檔，但本機只有部分平台的內容，所以只推送了目前可用的單一平台（digest 從 ff7f0c… 變成單一平台的 3d6794…）。推送成功，只是 Registry 裡的這個標籤只有一個平台。要推送多平台映像檔，見多平台映像檔。

查看 Registry 標籤並辨識錯誤

$ wget -qO- http://localhost:5000/v2/tools/alpine/tags/list
{"name":"tools/alpine","tags":["3.23","latest"]}

$ docker push localhost:5000/tools/missing:1.0
The push refers to repository [localhost:5000/tools/missing]
tag does not exist: localhost:5000/tools/missing:1.0

$ docker push docker.io/library/alpine:3.23
The push refers to repository [docker.io/library/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Layer already exists
failed commit on ref "manifest-sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306": server message: insufficient_scope: authorization failed

Registry 的標籤清單確認 3.23 和 latest 都存在；推送不存在的本機標籤會回報 tag does not exist。
推送到 Docker Hub 的 docker.io/library/alpine 時，最後出現 insufficient_scope: authorization failed：library/ 是官方映像檔的命名空間，沒有人能推送。
推送到 Docker Hub 要先 docker login（參數見上表），並把映像檔標記成自己帳號底下的名稱，例如 你的帳號/alpine:3.23。

動手練習

練習：把本機 alpine:3.23 標記為 localhost:5000/tools/alpine:latest，再推送 tools/alpine 的所有標籤。

答案

docker tag alpine:3.23 localhost:5000/tools/alpine:latest
docker push --all-tags localhost:5000/tools/alpine

常見問題

推送映像檔前為什麼要加上 Registry 標籤？

docker tag 建立指向來源映像檔的目標名稱；範例把 alpine:3.23 標記成 localhost:5000/tools/alpine:3.23，再推送該名稱。

`docker push --all-tags` 會推送哪些標籤？

它會推送指定 Repository 的所有標籤。範例中 tools/alpine 的 3.23 與 latest 都被推送。

推送到 Docker Hub 出現 insufficient_scope 怎麼辦？

表示你沒有權限推送到這個 Repository。範例中的 docker.io/library/alpine 是 Docker 官方映像檔的命名空間，任何個人帳號都不能推送。要推送到 Docker Hub，先執行 docker login，再把映像檔標記成 你的帳號/名稱:標籤 後推送，見 [推送到 Docker Hub](/zh-tw/docker/docker-hub/)。

推送成功後出現單一平台 Info 是失敗嗎？

範例已回報標籤的 digest，接著顯示只有可用的單一平台映像檔被推送；這是 Info 提示，不代表該次推送失敗。

更新於 2026年10月26日