docker debug

說明進入任何容器或映像檔的 shell。這是使用 `docker exec` 進行除錯的替代方案。
用法debug [選項] {容器|映像檔}

說明

注意事項

Docker Debug 需要 專業版、團隊版或商業版訂閱。您必須 登入 才能使用此指令。

Docker Debug 是一個 CLI 指令，可協助您遵循最佳實務，讓您的映像檔保持精簡且安全。使用 Docker Debug，您可以在映像檔只包含執行應用程式所需的最低限度內容時對其進行除錯。它允許您建立和使用精簡映像檔或容器，這些映像檔或容器通常難以除錯，因為所有工具都已被移除。例如，雖然典型的除錯方法（如 docker exec -it my-app bash）可能無法在精簡容器上運作，但 docker debug 可以運作。

使用 docker debug，您可以進入任何容器或映像檔的除錯 shell，即使它們不包含 shell。您不需要修改映像檔即可使用 Docker Debug。然而，使用 Docker Debug 仍然不會修改您的映像檔。Docker Debug 搭載了自己的工具箱，您可以輕鬆自訂。該工具箱預先安裝了許多標準 Linux 工具，例如 vim、nano、htop 和 curl。使用內建的 install 指令新增 https://search.nixos.org/packageshttps://search.nixos.org/packages範例。

  • uninstall [tool1] [tool2]：解除安裝 Nix 套件。
  • entrypoint：列印、檢查或執行進入點，請參閱 範例。
  • builtins：顯示自訂內建工具。

    • 注意事項

    對於映像檔和已停止的容器，所有變更在離開 shell 時都會被捨棄。這些變更在任何時候都不會影響實際的映像檔或容器。存取執行中或暫停的容器時，所有檔案系統變更都會直接反映在容器中。實際的映像檔或容器永遠不會看到 /nix 目錄。

    選項

    選項預設值說明
    --shellauto選擇 shell。支援：bash、fish、zsh、auto。
    -c, --command執行指定的指令，而不是啟動互動式工作階段，請參閱範例。
    --host要連線的 Docker Daemon socket。例如：ssh://root@example.org、unix:///some/path/docker.sock，請參閱範例。

    範例

    除錯沒有 shell 的容器（精簡容器）

    hello-world 映像檔非常簡單，只包含 /hello 二進位檔。這是一個精簡映像檔的良好範例。它沒有其他工具，也沒有 shell。

    從 hello-world 映像檔執行容器

    $ docker run --name my-app hello-world

    容器會立即退出。若要在容器內取得除錯 shell，請執行

    $ docker debug my-app

    除錯 shell 可讓您檢查檔案系統

    docker > ls
dev  etc  hello  nix  proc  sys

    檔案 /hello 是執行容器時執行的二進位檔。您可以直接執行它來確認這一點

    docker > /hello

    執行二進位檔後，它會產生相同的輸出。

    除錯（精簡）映像檔

    您可以直接執行以下指令來除錯映像檔

    $ docker debug hello-world
...
docker > ls
dev  etc  hello  nix  proc  sys

    您甚至不需要拉取映像檔，因為 docker debug 會像 docker run 指令一樣自動執行此操作。

    修改執行中容器的檔案

    Docker debug 可讓您修改任何執行中容器中的檔案。此工具箱預先安裝了 vim 和 nano。

    執行 nginx 容器並更改預設的 index.html

    $ docker run -d --name web-app -p 8080:80 nginx
d3d6074d0ea901c96cac8e49e6dad21359616bef3dc0623b3c2dfa536c31dfdb

    要確認 nginx 正在執行，請開啟瀏覽器並瀏覽至 http://localhost:8080。您應該會看到預設的 nginx 頁面。現在，使用 vim 更改它

    vim /usr/share/nginx/html/index.html

    將標題更改為「歡迎使用我的應用程式！」並儲存檔案。現在，在瀏覽器中重新載入頁面，您應該會看到更新後的頁面。

    使用 install 指令管理您的工具箱

    內建的 install 指令可讓您從 https://search.nixos.org/packages 將任何工具新增到工具箱。請記住，新增工具永遠不會修改實際的映像檔或容器。工具只會新增到您的工具箱。執行 docker debug，然後安裝 nmap

    $ docker debug nginx
...
docker > install nmap
Tip: You can install any package available at: https://search.nixos.org/packages.
installing 'nmap-7.93'
these 2 paths will be fetched (5.58 MiB download, 26.27 MiB unpacked):
/nix/store/brqjf4i23fagizaq2gn4d6z0f406d0kg-lua-5.3.6
/nix/store/xqd17rhgmn6pg85a3g18yqxpcya6d06r-nmap-7.93
copying path '/nix/store/brqjf4i23fagizaq2gn4d6z0f406d0kg-lua-5.3.6' from 'https://cache.nixos.org'...
copying path '/nix/store/xqd17rhgmn6pg85a3g18yqxpcya6d06r-nmap-7.93' from 'https://cache.nixos.org'...
building '/nix/store/k8xw5wwarh8dc1dvh5zx8rlwamxfsk3d-user-environment.drv'...

docker > nmap --version
Nmap version 7.93 ( https://nmap.org )
Platform: x86_64-unknown-linux-gnu
Compiled with: liblua-5.3.6 openssl-3.0.11 libssh2-1.11.0 nmap-libz-1.2.12 libpcre-8.45 libpcap-1.10.4 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select

    您可以透過在不同的映像檔中取得除錯 shell 來確認 nmap 現在是您工具箱的一部分

    $ docker debug hello-world
...
docker > nmap --version

Nmap version 7.93 ( https://nmap.org )
Platform: x86_64-unknown-linux-gnu
Compiled with: liblua-5.3.6 openssl-3.0.11 libssh2-1.11.0 nmap-libz-1.2.12 libpcre-8.45 libpcap-1.10.4 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select

docker > exit

    nmap 仍然存在。

    瞭解容器的預設啟動指令（進入點）

    Docker Debug 附帶一個內建工具 entrypoint。進入 hello-world 映像檔並確認進入點為 /hello

    $ docker debug hello-world
...
docker > entrypoint --print
/hello

    entrypoint 指令會評估基礎映像檔的 ENTRYPOINT 和 CMD 陳述式，並讓您列印、檢查或執行產生的進入點。然而，要理解 瞭解 CMD 和 ENTRYPOINT 如何互動 中的所有情況可能很困難，在這些情況下，entrypoint 可以提供幫助。

    使用 entrypoint 來調查從 Nginx 映像檔執行容器時實際發生了什麼事

    $ docker debug nginx
...
docker > entrypoint
Understand how ENTRYPOINT/CMD work and if they are set correctly.
From CMD in Dockerfile:
 ['nginx', '-g', 'daemon off;']

From ENTRYPOINT in Dockerfile:
 ['/docker-entrypoint.sh']

By default, any container from this image will be started with following   command:

/docker-entrypoint.sh nginx -g daemon off;

path: /docker-entrypoint.sh
args: nginx -g daemon off;
cwd:
PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Lint results:
 PASS: '/docker-entrypoint.sh' found
 PASS: no mixing of shell and exec form
 PASS: no double use of shell form

Docs:
- https://docker-docs.dev.org.tw/reference/dockerfile/#cmd
- https://docker-docs.dev.org.tw/reference/dockerfile/#entrypoint
- https://docker-docs.dev.org.tw/reference/dockerfile/#understand-how-cmd-and-entrypoint-interact

    輸出告訴您，在 nginx 映像檔啟動時，會執行指令碼 /docker-entrypoint.sh，參數為 nginx -g daemon off;。您可以使用 --run 選項來測試進入點

    $ docker debug nginx
...
docker > entrypoint --run
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2024/01/19 17:34:39 [notice] 50#50: using the "epoll" event method
2024/01/19 17:34:39 [notice] 50#50: nginx/1.25.3
2024/01/19 17:34:39 [notice] 50#50: built by gcc 12.2.0 (Debian 12.2.0-14)
2024/01/19 17:34:39 [notice] 50#50: OS: Linux 5.15.133.1-microsoft-standard-WSL2
2024/01/19 17:34:39 [notice] 50#50: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/19 17:34:39 [notice] 50#50: start worker processes
2024/01/19 17:34:39 [notice] 50#50: start worker process 77
...

    這會在您的除錯 shell 中啟動 nginx，而無需實際執行容器。您可以按 Ctrl+C 來關閉 nginx。

    直接執行指令（例如，用於腳本）

    使用 --command 選項直接評估指令，而不是啟動互動式工作階段。例如，這類似於 bash -c "arg1 arg2 ..."。以下範例會在 nginx 映像檔中執行 cat 指令，而不會啟動互動式工作階段。

    $ docker debug --command "cat /usr/share/nginx/html/index.html" nginx

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="https://nginx.dev.org.tw/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

    使用 --host 選項進行遠端除錯

    以下範例顯示如何使用 --host 選項。第一個範例使用 SSH 以 root 使用者身分連線到 example.org 的遠端 Docker 執行個體，並在 my-container 容器中取得 shell。

    $ docker debug --host ssh://root@example.org my-container

    以下範例連線到不同的本機 Docker Engine，並在 my-container 容器中取得 shell。

    $ docker debug --host=unix:///some/path/docker.sock my-container