Docker Compose exec 進入互動式 shell
使用 docker compose exec 在執行中的服務容器開啟 shell;若服務已停止,改用 docker compose run 建立新容器,映像沒有 bash 時請改用 sh。
使用 docker compose exec 取得互動式 shell
docker compose exec web bash 會在已以 web 服務執行中的容器內開啟互動式 shell。exec 後面的名稱是 compose.yaml 中的服務名稱,不是容器名稱。如果映像沒有 bash,請改用 sh。
docker compose ps
docker compose exec web bash先執行 docker compose ps。輸出應列出 web,其狀態為 running。接著,第二個命令會將提示字元帶到容器內;輸入 exit 或按 Ctrl-D 即可返回主機。離開後服務仍會繼續執行,因為 exec 會在主要程序旁啟動第二個程序。關閉 shell 不會影響 PID 1(process id 1),也就是容器建立時預定執行的程序。
這是進入容器的兩種方式之一。exec 會加入已存在的容器。docker compose run 則會依相同的服務定義建立新容器。本指南幾乎所有其他內容,都是由這項差異延伸而來。
為什麼 Compose 中的 -it 可選,但使用原生 docker 時卻是必要的
兩個旗標會控制工作階段的互動功能。-i 會保持 stdin 開啟,讓您輸入的內容傳送至程序。-t 會配置虛擬終端機(TTY),讓 shell 顯示提示字元並處理方向鍵。原生 docker exec 預設會關閉這兩項功能,因此您看到的每個範例都會寫入 docker exec -it。docker compose exec 會替您同時開啟兩者,因此 docker compose exec -it web bash 與 docker compose exec web bash 的作用相同。Compose 仍接受 -it,讓熟悉舊用法的使用者可以繼續使用。
您能在幾秒內察覺缺少 TTY。shell 會執行,但不會顯示提示字元,Ctrl-C 也無法傳送至程序。相反地,若您必須要求 Compose 不配置 TTY,則有專用旗標,並在後文另有專節說明。
映像沒有 bash 時的處理方式
對以 Alpine 為基礎的映像要求 bash,執行會像這樣失敗:
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknown這不是 exec 本身的問題。訊息表示在容器的 PATH 所列目錄中找不到 bash;對 shell 而言,這幾乎總是表示映像未包含該 shell。Alpine 內建 BusyBox,會以 /bin/sh 提供 ash,完全不含 bash,因此應改為要求 sh:
docker compose exec web sh以 Debian 和 Ubuntu 為基礎的映像,包括 -slim 標籤,確實包含 bash。bash 也提供命令歷程記錄與較完整的自動完成功能。因此先嘗試 bash,失敗後再改用 sh。幾乎所有通用用途的映像都包含 sh。
有些映像完全不含 shell。Distroless 映像,以及以 FROM scratch 建置的映像,只刻意保留應用程式二進位檔及其函式庫。原因是不存在的 shell 無法被攻擊者利用。在這類映像中,sh 會顯示相同訊息而失敗,沒有其他 shell 可嘗試。有兩種方式可行。Google 的 distroless 映像提供加入 BusyBox shell 的 :debug 標籤,暫時切換至該標籤即可進入容器。或者,在目標容器的 namespace 中啟動另一個容器:
CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot現在,netshoot 的工具會對應至應用程式的網路,因此 curl localhost:8080 和 ss -lntp 的行為會如同在應用程式容器內執行。你看到的檔案系統屬於 netshoot,而不是應用程式。由於共用 process namespace,/proc/1/root/ 會指向目標程序的檔案系統;但 ls /proc/1/root/ 仍必須通過核心的 ptrace 權限檢查。兩個程序都以 root 身分執行仍不足以通過檢查:檢查也會考量憑證、capability、目標程序的 dumpable 屬性及安全性模組。dumpable 值不是 1 時,會阻擋存取,除非呼叫端在目標的 user namespace 中具備 CAP_SYS_PTRACE。Docker 預設不會授予 SYS_PTRACE。將 --cap-add SYS_PTRACE 加入 docker run 行可處理憑證與 dumpability 檢查,但安全性模組仍可能拒絕存取。
服務未執行時,請使用 docker compose run --rm
exec 需要容器正在執行。若指定已停止的服務,指令會拒絕執行:
service "web" is not running它不會替你啟動任何項目。docker compose run 會:
docker compose run --rm web bashrun 會根據 web 服務定義建立新容器,使用相同的映像、環境變數、磁碟區與網路,並以你輸入的指令取代該服務的命令。--rm 會在你離開時刪除該容器。省略 --rm 時,殘留容器會以 myproject-web-run-4f1c2b 等名稱累積。docker compose ps -a 會列出這些容器,而 docker compose rm 會連同該服務的其他已停止容器一併移除。
run 有兩個容易令人意外的行為。除非加入 --service-ports,或使用 -p 手動對映連接埠,否則它不會發布服務的連接埠。這是刻意設計的:如果第一個容器仍占用主機的 8080 埠,第二個容器再繫結相同埠號就會因 bind: address already in use 而失敗。它也會先啟動服務在 depends_on 中列出的所有項目,然後才顯示 shell,因此快速查看容器內容可能會啟動資料庫與快取服務。--no-deps 可略過此行為。
run 會經過映像的 ENTRYPOINT,但 exec 不會。exec 會直接在現有容器中啟動你的命令,因此 entrypoint script 不會接收到該命令。在 run 中,你的 bash 會作為該 script 的引數傳入。許多官方映像會以 exec "$@" 結束 entrypoint,因此指令會直接傳遞,你就能取得 shell。若 script 會自行解析引數,則會以其他方式處理這些引數;此時可在該次執行中取代 entrypoint:
docker compose run --rm --entrypoint sh web這是指令在 exec 下可正常運作、在 run 下卻出現不同結果的最常見原因。command 與 entrypoint 的區分說明了每次執行時,你取代的是映像設定中的哪一部分。
exec 或 run:如何選擇
- exec 需要容器正在執行。run 不需要,而且 run 可能會啟動相依服務。
- exec 會看到目前的即時程序清單與檔案狀態,包括應用程式啟動後寫入的內容。run 會從映像檔取得乾淨且可寫入的層,但 named volumes 與 bind mounts 仍會公開服務現有的資料。
- exec 會略過 entrypoint。run 會執行 entrypoint。
- 除非傳入
--rm,否則 run 會保留容器。
使用 exec 查看實際執行狀況。針對同一環境建立用完即丟的副本、執行一次性的遷移命令,或實際服務無法持續執行足夠時間以便使用 exec 進入時,請使用 run --rm。
實用的 exec 旗標:使用者、工作目錄與複本
大多數映像檔會切換至非 root 使用者,因此若要在 exec shell 中安裝診斷工具,必須使用以下方式:
E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)-u root會在同一個容器中提供 root shell:
docker compose exec -u root web sh-w /srv/app只會為該命令設定工作目錄。-e KEY=value會將環境變數加入目前的工作階段,不會加入服務。服務執行多個複本時,--index 2會決定你要進入哪個容器。若你要追查掛載目錄的檔案擁有權問題,容器映像檔中的 PUID 與 PGID 說明了為何決定寫入權限的是數值 ID,而不是使用者名稱。
在資料庫容器內取得 psql 或 mysql shell
用戶端已經包含在資料庫映像檔中,因此不需要在主機上安裝,也不需要發布連接埠:
docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -pPostgres 映像檔包含 psql,MySQL 映像檔包含 mysql,MariaDB 映像檔包含 mariadb。連線是在容器內建立,因此即使 compose 檔案完全沒有發布資料庫連接埠,也能正常運作。在 Docker 的預設 bridge 網路上,這是較安全的配置:外部主機無法直接連入未發布的資料庫連接埠,但 Docker 主機與同一網路上的容器仍然可以連線。
有一個陷阱曾讓許多人花上一個下午排查。Docker 看到命令之前,shell 就會先在主機上展開變數。因此,當該變數只存在於容器內時,-U "$POSTGRES_USER" 會傳送空字串。使用單引號,並在容器內啟動 shell,才能在正確的位置展開變數:
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'不要在這裡直接使用沒有命令的 docker compose run --rm db。這會針對同一個資料卷啟動第二個 Postgres 伺服器,而該伺服器會拒絕啟動:
FATAL: lock file "postmaster.pid" already exists鎖定檔案正在發揮作用,因為兩個伺服器同時寫入同一個資料目錄會造成資料損毀。資料庫執行期間,請使用 exec 進入正在執行的容器。資料庫是否應該納入 Compose 是另一項決策,在 Docker 或主機上執行資料庫說明了其中的取捨。
啟動時需要主控台的服務:stdin_open 與 tty
exec 與 run 適用於您手動開啟的 shell。主要程序本身需要互動的服務,必須在 compose 檔案中設定兩個鍵:
services:
console:
image: python:3.12-slim
command: python
stdin_open: true
tty: truestdin_open: true 是 docker run -i,而 tty: true 是 docker run -t。未設定這兩個鍵時,容器會立即啟動並以代碼 0 結束,docker compose ps -a 會顯示 Exited (0)。這不是當機。python 的 stdin 沒有終端機時會立即讀到檔案結尾,然後正常結束;對於沒有人輸入內容的程式而言,這是正確行為。
設定這兩個鍵後,連接至執行中的程序:
docker attach $(docker compose ps -q console)按下 Ctrl-P 再按 Ctrl-Q 可離開連線,同時讓程序繼續執行。只有在容器同時開啟 TTY 與 stdin 時,這組按鍵才有效。相反地,Ctrl-C 會將中斷訊號(SIGINT)傳送至 PID 1。只有程式設計為收到 SIGINT 時結束,才會因此停止服務;Linux 不會為 PID 1 提供預設的訊號處理,因此不要用 Ctrl-C 來離開連線。
一般服務應將這兩個鍵維持關閉。Web 伺服器不會讀取 stdin,而 tty: true 會讓許多程式切換為彩色輸出及行緩衝,因為程式會判定有人正在查看輸出,導致 docker compose logs 充滿跳脫序列。
腳本在 cron 和 CI 中執行 exec 失敗的原因:-T 旗標
在終端機中可正常執行的 exec 命令,透過腳本、cron 工作、持續整合(CI)執行器或管線執行時,可能會失敗:
the input device is not a TTY當 Compose 自身的輸出連到終端機時,會要求配置 pseudo terminal。如果 stdin 也不是終端機,該要求會在命令執行前失敗。新版 Docker CLI 原始碼將相同的失敗描述為 cannot attach stdin to a TTY-enabled container because stdin is not a terminal。目前的 Compose 會在輸出重新導向或透過管線傳送時自行略過此要求,而 cron 通常就是這種情況。部分較早版本無論情況都會提出要求;即使在目前版本中,直接於提示字元輸入 cat dump.sql | docker compose exec db psql 仍會觸發這個問題。-T 可在所有情況下關閉此要求,因此應在腳本中加入這個旗標,不要依賴自動判斷:
0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump-T 之所以重要,還有第二個原因。TTY 會在位元組串流輸出前重新處理內容,因此壓縮傾印若經過 TTY,抵達目的地時可能已損壞。對任何重新導向或透過管線傳送的輸出,都應明確傳入 -T。
cron 還有兩個細節需要注意。請搭配絕對路徑傳入 -f,因為 cron 會從家目錄執行工作,而該目錄沒有 compose 檔案;Compose 便會以 no configuration file provided: not found 停止。exec 會回傳所執行命令的結束碼,因此失敗的 pg_dump 會在 set -e 下使腳本失敗,而不是寫入空的備份並回報成功。其他日常使用的命令整理於 Compose 命令速查表,建議與這些腳本一同備查。
為什麼在容器內進行的變更會消失
你使用 exec 安裝工具、編輯設定檔並修正問題,但一週後修正內容卻消失了。這是容器的可寫入層依設計運作的結果。docker compose up -d 對映像標籤或服務定義進行任何變更後,都會刪除舊容器,並根據映像建立新容器;所有手動編輯內容也會隨舊容器一併消失。
docker compose restart 則不同。它會停止並重新啟動同一個容器,因此手動編輯內容仍會保留。這就是為什麼手動修正看似可以維持數週,卻會在無關的更新期間消失。Named volumes 和 bind mounts 在這兩種操作中都能保留,因為其資料位於容器外部;bind mounts 與 named volumes 說明了應如何為預計保留的資料選擇其中一種。
因此,請將 exec shell 視為用來讀取和測試的環境。確認修正方式後,請將它寫入可持久保存的位置:將套件寫入 Dockerfile,將設定寫入 compose file。接著執行 docker compose up -d 套用變更,再使用另一個 exec 確認新容器確實包含該修正。
FAQ
docker compose exec 與 docker compose run 有何差異?
exec 會在已執行的容器中、主要程序之外執行命令,並略過映像的 entrypoint。run 會使用相同的服務定義建立新容器,並沿用相同的映像、環境、磁碟區與網路;它會將命令傳遞給 entrypoint,並先啟動任何 depends_on 服務。除非加入 --service-ports 或 -p 對映,否則 run 也不會發布該服務的連接埠。使用 exec 檢查正在執行的服務。服務停止時,或需要獨立容器時,使用 run --rm;但請注意,命名磁碟區與 bind mount 會共用。
為何 docker compose exec 回報服務未執行?
exec 會連接至現有容器,無法建立容器,因此服務停止或當機時會回報 service "web" is not running。檢查 docker compose ps -a,此命令會列出已結束的容器,狀態可能顯示為 Exited (1);再讀取 docker compose logs web,瞭解服務停止的原因。若仍要取得 shell,請執行 docker compose run --rm --entrypoint sh web。這會依相同的服務定義建立全新容器,但不會執行有問題的啟動命令。
映像沒有 bash 時,如何開啟 shell?
docker compose exec web bash 失敗並顯示 exec: "bash": executable file not found in $PATH,表示在容器的 PATH 所列目錄中找不到 bash;這幾乎總是表示該映像未包含 bash。以 Alpine 為基礎建置的映像通常都是如此。請使用 docker compose exec web sh,因為 BusyBox 提供 /bin/sh。若映像沒有任何 shell,exec 無法開啟 shell,但仍可執行映像內包含的可執行檔。若發布者提供映像的 :debug 標籤,請改用該標籤;或者使用 docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot 在目標容器的 namespace 中啟動除錯容器,其中 $CID 來自 docker compose ps -q web。
為何我在 cron 中執行 exec 命令時,會收到「輸入裝置不是 TTY」?
當輸出傳送至終端機時,docker compose exec 會要求配置 pseudo terminal;如果 stdin 也不是終端機,該要求就會失敗。目前的 Compose 在輸出重新導向時會自行略過此要求,而 cron 通常就是如此;但較早的版本不論情況都會提出要求,從互動式 shell 將輸入透過 pipe 傳給 exec 也會觸發此問題。加入 -T 將其關閉:docker compose exec -T db pg_dump -U postgres app。對任何重新導向或透過 pipe 傳送的輸出,也請使用 -T,因為 TTY 會改變位元組串流並破壞二進位傾印。在 cron 中,另請以絕對路徑搭配 -f 指定 compose 檔案,否則 Compose 會結束並顯示 no configuration file provided: not found。
使用 exec 在容器內進行的變更,重新啟動後是否仍會保留?
這些變更會在 docker compose restart 後保留,因為該操作會重用相同的容器。在任何映像或設定變更後執行 docker compose up -d 時,這些變更就會遺失,因為該操作會依映像重新建立容器,並捨棄其可寫入層。寫入命名磁碟區或 bind mount 的資料在這兩種情況下都會保留,因為資料位於容器外部。使用 exec 進行診斷性變更,然後將永久版本寫入 Dockerfile 或 compose 檔案。