# Docker 從入門到實戰 [](https://creativecommons.org/licenses/by-nc-sa/4.0/) [](https://github.com/yeasy/docker_practice) [](https://github.com/yeasy/docker_practice/releases) [](https://yeasy.gitbook.io/docker_practice) [](https://github.com/yeasy/docker_practice/releases/latest) [](https://docs.docker.com/engine/release-notes/) > 從零開始，系統掌握 Docker 容器技術的核心概念、原理與實戰技巧

graph LR
    Start[Docker 學習入口] --> Ch1[第1章：Docker 簡介]

    Ch1 --> Role1["運維新手<br/>第1-4章"]
    Ch1 --> Role2["開發者<br/>第1-3章 → 第5-8章"]
    Ch1 --> Role3["DevOps 工程師<br/>第1章 → 第9-14章 → 第18章"]
    Ch1 --> Role4["架構師<br/>第1章 → 第15-21章"]

    Role1 --> End1["掌握基本操作"]
    Role2 --> End2["構建與部署應用"]
    Role3 --> End3["自動化與運維"]
    Role4 --> End4["設計容器方案"]

brew tap yeasy/tap && brew install mdpress
mdpress serve

docker run -it --rm -p 4000:80 ccr.ccs.tencentyun.com/dockerpracticesig/docker_practice:vuepress

1.1 快速上手

版本說明：本節示例基於 Docker v29.x 編寫。示例中使用的 nginx:alpine 映像檔標籤為演示用途，請查閱 Docker Hub - nginx 確認最新可用版本。

本節將透過一個簡單的 Web 應用例子，帶你快速體驗 Docker 的核心流程：構建映像檔、執行容器。

為什麼選擇 Nginx + HTML 作為入門例子？

在學習 Docker 之前，我們先來理解為什麼這個例子是最適合初學者的。Docker 的核心價值在於一致性交付——無論你在本地、雲端還是他人的機器上執行容器，應用的行為都是完全一致的。這個 Nginx + 靜態 HTML 的例子之所以被廣泛採用，是因為它展現了 Docker 工作流的三個核心階段：

1. 映像檔定義（Image Layer）：透過 Dockerfile 描述如何把應用打包成一個自包含的單元
2. 映像檔構建（Build）：執行 docker build，Docker 根據 Dockerfile 逐層構建映像檔
3. 容器執行（Runtime）：透過 docker run 啟動容器例項，應用真正開始提供服務

Nginx 是一個輕量級、使用廣泛的 Web 伺服器，學習完這個例子後，你可以輕鬆擴充套件到部署 Node.js、Python、Go 等任何語言的應用。

1.1.1 準備程式碼

建立一個名為 hello-docker 的資料夾，並在其中建立一個 index.html 檔案：

<h1>Hello, Docker!</h1>

1.1.2 編寫 Dockerfile

在同級目錄下建立一個名為 Dockerfile (無字尾) 的檔案：

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

1.1.3 構建映像檔

開啟終端，進入該目錄，執行構建命令：

$ docker build -t my-hello-world .

• docker build：構建命令
• -t my-hello-world：給映像檔起個名字 (標籤)
• .：指定上下文路徑為當前目錄

1.1.4 執行容器

使用剛才構建的映像檔啟動一個容器：

$ docker run -d -p 8080:80 my-hello-world

• docker run：執行命令
• -d：後臺執行
• -p 8080:80：將宿主機的 8080 埠對映到容器的 80 埠

1.1.5 訪問測試

開啟瀏覽器訪問 http://localhost:8080，你應該能看到 “Hello, Docker!”。

1.1.6 清理

停止並刪除容器：

# 檢視正在執行的容器 ID

$ docker ps

# 停止容器

$ docker stop <CONTAINER_ID>

# 刪除容器

$ docker rm <CONTAINER_ID>

恭喜！你已經完成了第一次 Docker 實戰。接下來請閱讀 Docker 核心概念做深入瞭解。

1.2 什麼是 Docker

Docker 是徹底改變了軟體開發和交付方式的革命性技術。本節將從核心概念、與傳統虛擬機器的對比、技術基礎以及歷史生態等多個維度，帶你深入理解什麼是 Docker。

1.2.1 一句話理解 Docker

Docker 是一種輕量級的虛擬化技術，它讓應用程式及其依賴環境可以被打包成一個標準化的單元，在任何地方都能一致地執行。 如果用一個生活中的類比：Docker 之於軟體，就像集裝箱之於貨物。

在集裝箱發明之前，貨物的運輸是一件麻煩的事情——不同的貨物需要不同的包裝、不同的裝卸方式，換一種運輸工具就要重新裝卸。集裝箱的出現改變了這一切：無論裡面裝的是什麼，集裝箱的外形是標準的，可以用同樣的方式裝卸、堆放和運輸。

Docker 做的事情類似：無論你的應用是用 Python、Java、Node.js 還是其他語言寫的，無論它需要什麼樣的依賴庫和環境，一旦被打包成 Docker 映像檔，就可以用同樣的方式在任何支援 Docker 的機器上執行。

1.2.2 Docker 的核心價值

筆者認為，Docker 解決的是軟體開發中最古老的問題之一：“在我機器上明明能跑啊！”

flowchart LR
    subgraph Dev ["開發環境"]
        direction TB
        A["Python 3.14<br/>Ubuntu 24.04<br/>特定版本的庫"] --> B["執行正常"]
    end
    subgraph Prod ["生產環境"]
        direction TB
        C["Python 3.11<br/>Ubuntu 22.04<br/>不同版本的庫"] --> D["執行失敗！"]
    end
    A -.->|不一致| C

有了 Docker：

flowchart LR
    subgraph Dev ["開發環境"]
        direction TB
        A["Docker 映像檔<br/>(包含所有依賴)"] --> B["執行正常"]
    end
    subgraph Prod ["生產環境"]
        direction TB
        C["同一個映像檔<br/>(完全一致)"] --> D["執行正常！"]
    end
    A == 一致 ==> C

1.2.3 Docker vs 虛擬機器

很多人第一次接觸 Docker 時會問：“這不就是虛擬機器嗎？” 答案是：不是，而且差別很大。

傳統虛擬機器

傳統虛擬機器技術是虛擬出一套完整的硬體，在其上執行一個完整的作業系統，再在該系統上執行應用：

Docker 容器

而 Docker 容器內的應用直接執行於宿主的核心，容器內沒有自己的核心，也沒有進行硬體虛擬：

關鍵區別

特性	Docker 容器	傳統虛擬機器
啟動速度	秒級	分鐘級
資源佔用	MB 級別	GB 級別
效能	接近原生	有明顯損耗
隔離級別	程序級隔離	完全隔離
單機數量	可執行上千個	通常幾十個

筆者經常用這個類比來解釋：虛擬機器像是每個應用都住在一棟獨立的房子裡 (有自己的地基、水電系統)，而容器像是大家住在同一棟公寓樓裡的不同房間 (共享地基和水電系統，但各自獨立)。

1.2.4 Docker 的技術基礎

Docker 使用 Go 語言開發，基於 Linux 核心的以下技術：

• Namespace：實現資源隔離 (程序、網路、檔案系統等)
• Cgroups：實現資源限制 (CPU、記憶體、I/O 等)
• Union FS：實現分層儲存 (如 OverlayFS)

如果你對這些底層技術感興趣，可以閱讀本書的底層實現章節。

Docker 架構演進

Docker 的底層實現經歷了多次演進：

flowchart LR
    subgraph Timeline
        direction LR
        LXC["LXC<br/>(2013)"] --> libcontainer["libcontainer<br/>(2014)"]
        libcontainer --> runC["runC<br/>(2015)"]
        runC --> containerd["containerd + runC<br/>(現在)"]
        runC --> OCI["OCI<br/>標準化"]
    end

• LXC (2013)：Docker 最初基於 Linux Containers
• libcontainer (2014，Docker 0.9)：Docker 自研的容器執行時
• runC (2015，Docker 1.11 整合)：捐獻給 OCI 的標準容器執行時
• containerd：高階容器執行時，管理容器生命週期

runc 是一個 Linux 命令列工具，用於根據 OCI 容器執行時規範建立和執行容器。

containerd 是一個守護程式，它管理容器生命週期，提供了在一個節點上執行容器和管理映像檔的最小功能集。

1.2.5 Docker 的歷史與生態

Docker 最初是 dotCloud 公司創始人 Solomon Hykes 在法國期間發起的一個公司內部專案，於 2013 年 3 月以 Apache 2.0 授權協議開源。

Docker 的發展歷程：

• 2013 年 3 月：開源釋出
• 2013 年底：dotCloud 公司改名為 Docker，Inc。
• 2015 年：成立開放容器聯盟 (OCI)，推動容器標準化
• 至今：GitHub 專案超過 7 萬星標

Docker 的成功推動了整個容器生態的發展，催生了 Kubernetes、Podman 等眾多相關專案。筆者認為，Docker 最大的貢獻不僅是技術本身，更是它 讓容器技術從系統管理員的工具變成了每個開發者都能使用的標準工具。

1.3 為什麼要用 Docker

在回答 “為什麼用 Docker” 之前，筆者想先問一個問題：你有沒有經歷過這些情境？

1.3.1 沒有 Docker 的世界

在 Docker 出現之前，軟體開發和運維面臨著諸多棘手的問題。我們先來看看以下三個典型的痛點情境。

情境一：“在我電腦上明明能跑”

週五下午 5:00
├── 開發者：程式碼寫完了，本地測試透過，提交！🎉
├── 週一早上 9:00
│   └── 測試："這個功能在測試環境跑不起來"
└── 開發者："不可能，在我電腦上明明能跑啊……"

筆者統計過，這個問題通常由以下原因導致：

• Python/Node/Java 版本不一致
• 依賴庫版本不一致
• 作業系統配置不一致
• 某些環境變數沒有設定
• “哦，忘了說我本地裝了個 XXX”

情境二：環境配置的噩夢

新同事入職
├── Day 1：領電腦，配環境
├── Day 2：繼續配環境，遇到問題
├── Day 3：換種方法配環境
├── Day 4：問老同事怎麼配的，他也忘了
└── Day 5：終於能跑起來了！但不知道為什麼……

情境三：伺服器遷移的恐懼

運維："我們需要把服務遷移到新伺服器"
開發："舊伺服器上的配置文件在哪？"
運維："當時是一個已經離職的同事配的……"
所有人：😱

1.3.2 Docker 如何解決這些問題

Docker 的出現為上述問題提供了完美的解決方案。它透過 “一次構建，到處執行” 的核心理念，從根本上改變了軟體交付的方式。

核心理念：一次構建，到處執行

flowchart LR
    dev["開發團隊"] -->|建立| img["Docker 映像檔"]
    img -->|測試團隊驗證| test["測試團隊"]
    test -- "有問題<br/>反饋修改和更新" --> dev
    test -- "沒問題<br/>釋出" --> prod["生產環境"]

1.3.3 Docker 的核心優勢

除了解決上述痛點，Docker 還擁有諸多顯著的技術優勢，包括環境一致性、秒級啟動、高效的資源利用等。

1. 環境一致性

Docker 映像檔包含了應用執行所需的 一切：程式碼、執行時、系統工具、庫、配置。這意味著：

• ✅ 開發環境和生產環境完全一致
• ✅ 不會再有 “在我機器上能跑” 的問題
• ✅ 新人入職，一條命令就能啟動開發環境

## 新同事入職第一天

$ git clone https://github.com/company/project.git
$ docker compose up

## 完整的開發環境就準備好了

...

2. 秒級啟動

傳統虛擬機器啟動需要幾分鐘 (引導作業系統)，而 Docker 容器啟動通常只需要 幾秒甚至幾百毫秒。

筆者實測資料：

啟動內容	虛擬機器	Docker 容器
空系統	~60 秒	~0.5 秒
MySQL	~90 秒	~3 秒
完整 Web 應用	~120 秒	~5 秒

這個差異對以下情境尤為重要：

• CI/CD 流水線：每次構建節省幾分鐘，一天累積下來就是幾小時
• 彈性擴容：流量高峰時能快速啟動更多例項
• 開發體驗：快速重啟服務進行除錯

3. 資源效率

Docker 容器共享宿主機核心，無需為每個應用執行完整的作業系統。以一臺 64GB 記憶體的物理伺服器為例：

• 傳統虛擬機器方案：每個虛擬機器都需要執行完整的作業系統（每個額外佔用如 2GB 記憶體），產生大量資源開銷，實際可用於應用的記憶體可能只有約 18GB。
• Docker 方案：容器直接共享宿主機系統，只需付出很少的基礎開銷（OS 及引擎約 4GB），即可將約 60GB 的記憶體全部用於實際應用。

flowchart TD
    subgraph VM ["傳統虛擬機器方案 ❌"]
        direction TB
        Server1["物理伺服器 (64GB 記憶體)"]
        subgraph VMs ["可用應用記憶體: 約 18GB"]
            direction LR
            VM1["VM 1: 應用 1<br/>(含 2GB OS)"]
            VM2["VM 2: 應用 2<br/>(含 2GB OS)"]
            VM3["VM 3: 應用 3<br/>(含 2GB OS)"]
        end
        Server1 --- VMs
    end

    subgraph Docker ["Docker 方案 ✅"]
        direction TB
        Server2["物理伺服器 (64GB 記憶體)<br/>含約 4GB OS及引擎配置"]
        subgraph Containers ["可用應用記憶體: 約 60GB"]
            direction LR
            C1["容器 1: 應用 1<br/>(按需分配)"]
            C2["容器 2: 應用 2<br/>(按需分配)"]
            C3["容器 3: 應用 3<br/>(按需分配)"]
        end
        Server2 --- Containers
    end

4. 持續交付和部署

Docker 完美契合 DevOps 的工作流程：

flowchart LR
    A["程式碼提交<br/>(Git push)"] --> B["自動構建映像檔<br/>(docker build)"]
    B --> C["自動測試<br/>(容器內執行測試)"]
    C --> D["自動部署<br/>(容器滾動更新)"]

使用 Dockerfile 定義映像檔構建過程，使得：

• 構建過程 可重複、可追溯
• 任何人都能從程式碼重建完全相同的映像檔
• 配合 GitHub Actions 等 CI 系統實現自動化

5. 輕鬆遷移

Docker 可以在幾乎任何平臺上執行：

• ✅ 本地開發機 (macOS、Windows、Linux)
• ✅ 公有云 (AWS、Azure、GCP、阿里雲、騰訊雲)
• ✅ 私有云和自建資料中心
• ✅ 邊緣裝置和 IoT

同一個映像檔，在任何地方執行結果都一致。 這讓應用遷移變得前所未有的簡單。

6. 微服務架構的基石

現代微服務架構幾乎都依賴容器技術。Docker 讓你可以：

• 隔離服務：每個服務執行在獨立容器中，互不干擾
• 獨立擴充套件：哪個服務負載高，就單獨擴充套件哪個
• 獨立部署：更新一個服務不影響其他服務
• 技術多樣：不同服務可以用不同語言和框架

flowchart TD
    subgraph Microservices ["微服務架構示例"]
        direction TB
        subgraph AppLayer ["應用層"]
            direction LR
            Frontend["前端容器<br/>(Node.js)"]
            API["API 容器<br/>(Python)"]
            Worker["Worker 容器<br/>(Go)"]
        end
        Redis["Redis 容器"]
        DB["PostgreSQL 容器"]

        Frontend --> API
        API --> Redis
        API --> DB
        Worker --> Redis
        Worker --> DB
    end

1.3.4 Docker 不適合的情境

筆者認為，技術選型要客觀。Docker 並非銀彈，以下情境可能不太適合：

• 需要完全隔離的情境：容器共享宿主機核心，隔離性不如虛擬機器。如果需要執行不受信任的程式碼，虛擬機器可能更安全。
• 需要特殊核心的情境：容器使用宿主機核心。如果應用需要特定版本的核心或核心模組，可能需要虛擬機器。
• Windows 原生應用：雖然 Docker 支援 Windows 容器，但生態不如 Linux 容器成熟。傳統 Windows 應用的容器化仍有挑戰。
• 桌面應用：Docker 主要面向伺服器端應用。桌面 GUI 應用的容器化雖然可行，但通常得不償失。

1.3.5 與傳統虛擬機器的對比總結

關於容器與虛擬機器的詳細特性對比，請參閱 1.2.3 Docker vs 虛擬機器 中的對比表。總結來說：

• 效能差異：虛擬機器通常有 5-20% 的效能損耗，而容器接近原生效能。
• 最佳情境：Docker 容器適合微服務、CI/CD、開發環境；虛擬機器適合多租戶、高安全需求情境。

本章小結

• Docker 是一種輕量級虛擬化技術，核心價值是 環境一致性
• 與虛擬機器相比，Docker 更輕量、更快速、資源利用率更高
• Docker 基於 Linux 核心的 Namespace、Cgroups 和 Union FS 技術
• Docker 推動了容器技術的標準化 (OCI) 和生態發展

Docker 的核心價值可以用一句話概括：讓應用的開發、測試、部署保持一致，同時極大提高資源利用效率。 筆者認為，對於現代軟體開發者來說，Docker 已經不是 “要不要學” 的問題，而是 必備技能。無論你是前端、後端、運維還是全棧開發者，掌握 Docker 都能讓你的工作更高效。

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

2.1 映像檔

版本說明：本節示例基於 Docker v29.x 編寫。示例中使用的映像檔標籤（如 ubuntu:24.04、nginx:latest）為演示用途，建議查閱 Docker Hub 或相應映像檔的官方頁面確認最新可用版本。

Docker 映像檔作為容器執行的基石，其設計理念和實現機制至關重要。本節將深入探討映像檔的本質、與作業系統的關係、內容構成以及核心的分層儲存機制。

2.1.1 一句話理解映像檔

Docker 映像檔是一個只讀的模板，包含了執行應用所需的一切：程式碼、執行時、庫、環境變數和配置檔案。 如果用一個類比：映像檔就像是一張光碟或 ISO 檔案。你可以用同一張光碟在不同電腦上安裝系統，而光碟本身不會被修改。同樣，一個映像檔可以建立多個容器，而映像檔本身保持不變。

2.1.2 映像檔與作業系統的關係

我們都知道，作業系統分為 核心 和 使用者空間：

flowchart TD
    subgraph UserSpace ["使用者空間"]
        direction TB
        App["應用程式、工具、庫、配置檔案...<br/>（這部分被打包成 Docker 映像檔）"]
    end

    subgraph KernelSpace ["Linux 核心"]
        direction TB
        Kernel["容器共享宿主機的核心"]
    end

    UserSpace --- KernelSpace

對於 Linux 而言，核心啟動後會掛載 root 檔案系統來提供使用者空間支援。Docker 映像檔 本質上就是一個 root 檔案系統。

例如，官方映像檔 ubuntu:24.04 包含了一套完整的 Ubuntu 24.04 最小系統的 root 檔案系統——但 不包含 Linux 核心 (因為容器共享宿主機的核心)。

2.1.3 映像檔包含什麼？

Docker 映像檔是一個特殊的檔案系統，包含：

內容型別	示例
程式檔案	應用二進位制檔案、Python/Node 直譯器
庫檔案	libc、OpenSSL、各種依賴庫
配置檔案	nginx.conf、my.cnf 等
環境變數	PATH、LANG 等預設值
後設資料	啟動命令、暴露埠、資料卷定義

關鍵特性：

• ✅ 映像檔是 只讀 的
• ✅ 映像檔 不包含 動態資料
• ✅ 映像檔構建後 內容不會改變

2.1.4 分層儲存：映像檔的核心設計

映像檔的分層儲存機制是 Docker 最具創新性的特性之一。透過 Union FS 技術，Docker 能夠高效地構建和管理映像檔。

為什麼需要分層？

筆者認為，分層儲存是 Docker 最巧妙的設計之一。

假設你有三個應用，都基於 Ubuntu 執行：

flowchart TD
    subgraph Traditional ["傳統方式（不分層）總計: 1.5GB ❌"]
        direction LR
        AppA_Trad["App A<br/>Ubuntu 500MB"]
        AppB_Trad["App B<br/>Ubuntu 500MB"]
        AppC_Trad["App C<br/>Ubuntu 500MB"]
    end

    subgraph DockerLayered ["Docker 分層方式 總計: 620MB ✅"]
        direction TB
        subgraph Apps ["應用層"]
            direction LR
            AppA["App A 50MB"]
            AppB["App B 30MB"]
            AppC["App C 40MB"]
        end
        Ubuntu["Ubuntu<br/>（共享）500MB"]

        AppA --> Ubuntu
        AppB --> Ubuntu
        AppC --> Ubuntu
    end

分層是如何工作的？

筆者用一個更貼近最佳實務的 Dockerfile 來解釋分層：

FROM ubuntu:24.04                              # 第 1 層：基礎系統（約 78MB）
RUN apt-get update && apt-get install -y nginx # 第 2 層：更新索引並安裝 nginx
COPY app.conf /etc/nginx/                      # 第 3 層：複製配置檔案

這裡特意把 apt-get update 和 apt-get install 放在同一個 RUN 裡，避免構建快取導致包索引過期。

構建後的映像檔結構：

flowchart TD
    Layer3["第 3 層: COPY app.conf (只讀)<br/>← 最新新增的層"]
    Layer2["第 2 層: nginx 安裝檔案與包索引 (只讀)"]
    Layer1["第 1 層: Ubuntu 基礎系統 (只讀)<br/>← 基礎映像檔層"]

    Layer3 --> Layer2 --> Layer1

每一層的特點：

• 只讀：構建完成後不可修改
• 可共享：多個映像檔可以共享相同的層
• 有快取：未變化的層不會重新構建

分層儲存的 “陷阱”

⚠️ 筆者特別提醒：理解這一點可以幫你避免構建出臃腫的映像檔。關鍵原理：每一層的檔案變化會被記錄，但 刪除操作只是標記，不會真正減小映像檔體積。

## 錯誤示範 ❌

FROM ubuntu:24.04
RUN apt-get update
RUN apt-get install -y build-essential  # 安裝編譯工具（約 200MB）
RUN make && make install                  # 編譯應用
RUN apt-get remove build-essential        # 試圖刪除編譯工具

## 結果：映像檔仍然包含 200MB 的編譯工具！

## 正確做法 ✅

FROM ubuntu:24.04
RUN apt-get update && \
    apt-get install -y build-essential && \
    make && make install && \
    apt-get remove -y build-essential && \
    apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*

## 在同一層完成安裝、使用、清理

2.1.5 檢視映像檔的構建歷史

## 檢視映像檔的歷史（每層的構建記錄）

$ docker history nginx:latest

IMAGE          CREATED       CREATED BY                                      SIZE
a6bd71f48f68   2 weeks ago   CMD ["nginx" "-g" "daemon off;"]                0B
<missing>      2 weeks ago   STOPSIGNAL SIGQUIT                              0B
<missing>      2 weeks ago   EXPOSE map[80/tcp:{}]                           0B
<missing>      2 weeks ago   ENTRYPOINT ["/docker-entrypoint.sh"]            0B
<missing>      2 weeks ago   COPY 30-tune-worker-processes.sh /docker-ent…   4.62kB
...

需要注意：docker history 展示的是映像檔的構建歷史。像 CMD、ENTRYPOINT、EXPOSE、STOPSIGNAL 這類 0B 項主要是映像檔配置後設資料，並不等同於新增了可見的檔案系統內容；真正佔用空間的通常是 RUN、COPY、ADD 等帶來的檔案變化。

2.1.6 映像檔的標識

Docker 映像檔有多種標識方式：

1. 映像檔名稱和標籤

格式：[倉庫地址/]倉庫名[:標籤]

## 完整格式

registry.example.com/myproject/myapp:v1.2.3

## 簡寫（使用 Docker Hub）

nginx:1.28
ubuntu:24.04

## 省略標籤（預設使用 latest）

nginx  # 等同於 nginx:latest

2. 映像檔 ID：Content-Addressable 標識

每個映像檔有一個基於內容計算的唯一 ID：

$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
nginx        latest    a6bd71f48f68   2 weeks ago    187MB
ubuntu       24.04     ca2b0f26964c   3 weeks ago    78.1MB

3. 映像檔摘要

更精確的標識，基於映像檔內容的 SHA256 雜湊：

$ docker images --digests
REPOSITORY  TAG     DIGEST                                                                    IMAGE ID
nginx       latest  sha256:6db391d1c0cfb30588ba0bf72ea999404f2764184d8b8d10d89e8a9c6... a6bd71f48f68

💡 筆者建議：在生產環境使用映像檔摘要而非標籤，因為標籤可以被覆蓋，但摘要是不可變的。

2.1.7 映像檔的來源

Docker 映像檔可以透過以下方式獲取：

方式	說明	示例
從 Registry 拉取	最常用的方式	docker pull nginx
從 Dockerfile 構建	自定義映像檔	docker build -t myapp .
從容器提交	儲存容器狀態 (不推薦)	docker commit
從檔案匯入	離線傳輸	docker load < image.tar

2.2 容器

容器是 Docker 技術的核心，是應用實際執行的載體。本節將從容器的本質、與虛擬機器的區別、儲存層機制以及生命週期管理等方面，全面解析 Docker 容器。

2.2.1 一句話理解容器

容器是映像檔的執行例項。如果把映像檔比作程式，那麼容器就是程序。 用物件導向程式設計的術語來說：映像檔是類 (Class)，容器是物件 (Instance)。

• 一個映像檔可以建立多個容器
• 每個容器相互獨立，互不影響
• 容器可以被建立、啟動、停止、刪除、暫停

2.2.2 容器的本質

💡 筆者認為，理解這一點是理解 Docker 的關鍵：容器的本質是一個特殊的程序。

flowchart TD
    subgraph NormalProcess ["普通程序"]
        direction TB
        N1["• 共享系統資源<br/>• 共享網路<br/>• 共享檔案系統"]
    end

    subgraph ContainerProcess ["容器程序 (執行在宿主機核心上)"]
        direction TB
        C1["• 獨立程序空間<br/>• 獨立網路環境<br/>• 獨立檔案系統<br/>• 獨立使用者空間"]
    end

這種隔離主要透過 Linux 核心的 Namespace 實現，資源限制通常與 cgroups 配合。具體表現為：

• 程序空間：容器看不到宿主機上的其他程序。
• 網路：在預設網路模式下，容器通常擁有獨立的網路名稱空間，並可分配獨立 IP；使用 host 或 container: 等模式時則例外。
• 檔案系統：容器擁有獨立的 root 目錄。
• 使用者：預設情況下，容器內的 root 仍是 uid 0，但通常只擁有受限 capabilities；如果啟用 userns-remap 或 rootless 等機制，還會進一步對映為宿主機上的低許可權使用者。

2.2.3 容器 vs 虛擬機器：核心區別

很多初學者會混淆容器和虛擬機器。筆者用一張圖來說明：

flowchart TD
    subgraph VM ["虛擬機器 (每個 VM 執行完整 OS)"]
        direction TB
        subgraph VMApp ["應用層"]
            VA[App A] & VB[App B]
        end
        subgraph VMGuest ["Guest OS (完整系統)"]
            G1[Guest OS] & G2[Guest OS]
        end
        V[Hypervisor]
        VMH[Host OS]
        VMHW[Hardware]
        VMApp --> VMGuest --> V --> VMH --> VMHW
    end

    subgraph Container ["容器 (所有容器共享宿主機核心)"]
        direction TB
        subgraph CApp ["應用層"]
            CA[App A] & CB[App B]
        end
        subgraph CContainer ["隔離層"]
            CC1[Container 僅應用] & CC2[Container 僅應用]
        end
        CE[Docker Engine]
        CH[Host OS]
        CHW[Hardware]
        CApp --> CContainer --> CE --> CH --> CHW
    end

特性	容器	虛擬機器
隔離級別	作業系統級 (Namespaces/cgroups)	硬體虛擬化級 (Hypervisor)
啟動時間	通常更快	通常更慢
資源佔用	通常更低	通常更高
執行開銷	通常更接近原生	通常有更高虛擬化開銷
核心	共享宿主機核心	各自獨立核心

2.2.4 容器的儲存層

理解容器的儲存層機制對於資料的持久化和映像檔的最佳化至關重要。本節將介紹容器的可寫層以及 Copy-on-Write 機制。

映像檔層 + 容器層

當容器執行時，Docker 會在映像檔的只讀層之上建立一個 可寫層 (容器儲存層)：

flowchart TD
    ContainerLayer["容器儲存層（可讀寫）<br/>容器執行時建立，記錄檔案變化"]
    ImageLayerN["映像檔第 N 層（只讀）"]
    ImageLayerN1["映像檔第 N-1 層（只讀）"]
    Dots["..."]
    ImageLayer1["映像檔第 1 層（只讀）<br/>基礎映像檔層"]

    ContainerLayer --> ImageLayerN --> ImageLayerN1 --> Dots --> ImageLayer1

Copy-on-Write：寫時複製

當容器需要修改映像檔層中的檔案時：

1. Docker 將該檔案 複製 到容器儲存層
2. 在容器層中進行修改
3. 原始映像檔層保持不變

讀取檔案：直接從映像檔層讀取（共享，高效）
修改檔案：複製到容器層，然後修改（只有這個容器能看到修改）

⚠️ 容器儲存層的生命週期

筆者特別強調：這是新手最容易踩的坑！容器儲存層與容器生命週期繫結。容器刪除，資料就沒了！

## 建立容器，寫入資料

$ docker run -it ubuntu bash
root@abc123:/# echo "important data" > /data.txt
root@abc123:/# exit

## 刪除容器

$ docker rm abc123

## 資料丟了！沒有任何辦法恢復！

正確的資料持久化方式

按照 Docker 最佳實務，容器儲存層應該保持 無狀態。需要持久化的資料應該使用：

方式	說明	適用情境
資料卷 (Volume)	Docker 管理的儲存	資料庫、應用資料
繫結掛載 (Bind Mount)	掛載宿主機目錄	開發時共享程式碼

## 使用資料卷（推薦）

$ docker run -v mydata:/var/lib/mysql mysql

## 使用繫結掛載

$ docker run -v /host/path:/container/path nginx

這些位置的讀寫 會跳過容器儲存層，直接寫入宿主機，效能更好，也不會隨容器刪除而丟失。

2.2.5 容器的生命週期

掌握容器的生命週期對於管理和除錯 Docker 應用非常重要。如圖 2-1 所示，這裡先聚焦最常見的建立、執行、暫停、停止和刪除流轉；Docker CLI 中還可能看到 restarting、removing、dead 等狀態。

stateDiagram-v2
    direction TB
    [*] --> Created : docker create
    Created --> Running : docker start
    Running --> Stopped : docker stop
    Running --> Paused : docker pause
    Paused --> Running : docker unpause

    Created --> Deleted : docker rm
    Stopped --> Deleted : docker rm
    Paused --> Deleted : docker rm

    Deleted --> [*]

圖 2-1：容器生命週期狀態流轉圖

常用生命週期命令如下：

## 建立並啟動容器（最常用）

$ docker run nginx

## 分步操作

$ docker create nginx    # 建立容器（不啟動）
$ docker start abc123    # 啟動容器

## 停止容器

$ docker stop abc123     # 優雅停止（傳送 SIGTERM，等待後傳送 SIGKILL）
$ docker kill abc123     # 強制停止（直接傳送 SIGKILL）

## 暫停/恢復（不常用，但有時有用）

$ docker pause abc123    # 暫停容器內所有程序
$ docker unpause abc123  # 恢復

## 刪除容器

$ docker rm abc123       # 刪除已停止的容器
$ docker rm -f abc123    # 強制刪除執行中的容器

2.2.6 容器與程序的關係

核心概念：容器的生命週期 = 主程序 (PID 1) 的生命週期

## 主程序執行，容器執行

## 主程序退出，容器停止

這就是為什麼：

## 這個容器會立即退出（bash 沒有輸入就退出了）

$ docker run ubuntu

## 這個容器會持續執行（官方 nginx 映像檔讓 nginx 在前臺執行）

$ docker run nginx

官方 nginx 映像檔預設使用 nginx -g 'daemon off;'，讓主程序保持在前臺執行，這樣容器才會持續處於執行狀態。

詳細解釋請參考後臺執行章節。

2.2.7 容器的隔離性

Docker 容器透過以下 Namespace 實現隔離：

Namespace	隔離內容	效果
PID	程序 ID	容器內 PID 1 是應用程序，看不到宿主機其他程序
NET	網路	獨立的網路棧、IP 地址、埠
MNT	檔案系統	獨立的根目錄和掛載點
UTS	主機名	獨立的主機名和域名
IPC	程序間通訊	獨立的訊號量、訊息佇列
USER	使用者	獨立的使用者和組 ID

想深入瞭解？請閱讀底層實現 - 名稱空間。

2.3 倉庫

版本說明：本節示例基於 Docker v29.x 和常見映像檔版本編寫。示例中的版本號（如 nginx:1.28、mysql:8.4、mysql:5.7 等）為演示用途。實際使用時請訪問 Docker Hub 官方頁面 或相應映像檔的釋出頁確認最新可用版本和標籤。

Docker Registry 是映像檔分發和管理的核心元件。本節將介紹 Registry 的基本概念、公共和私有服務的選擇，以及映像檔的安全管理。

2.3.1 一句話理解 Registry

Docker Registry 是儲存和分發 Docker 映像檔的服務，類似於程式碼的 GitHub 或包管理的 npm。

映像檔構建完成後，可以在當前機器上執行。但如果需要在其他伺服器上使用這個映像檔，就需要一個集中的儲存和分發服務——這就是 Docker Registry。

2.3.2 核心概念

要熟練使用 Docker Registry，首先需要理清它與倉庫 (Repository)、標籤 (Tag) 之間的關係。

Registry、倉庫、標籤的關係

Docker Registry 中可以包含多個 Repository，每個 Repository 可以包含多個 Tag。如圖 2-2 所示，它們之間具有清晰的層級關係。

flowchart TB
    subgraph Registry ["Docker Registry（如 Docker Hub）"]
        direction TB
        subgraph RepoNginx ["Repository（倉庫）: nginx"]
            direction LR
            N1(":latest (tag)")
            N2(":1.28 (tag)")
            N3(":1.26 (tag)")
            N4(":alpine (tag)")
            N5("...")
            N1 ~~~ N2 ~~~ N3 ~~~ N4 ~~~ N5
        end
        subgraph RepoMysql ["Repository（倉庫）: mysql"]
            direction LR
            M1(":latest")
            M2(":8.0")
            M3(":5.7")
            M4("...")
            M1 ~~~ M2 ~~~ M3 ~~~ M4
        end
        RepoNginx ~~~ RepoMysql
    end

圖 2-2：Registry、Repository 與 Tag 的層級關係

相關基本概念具體如下：

概念	說明	示例
Registry	儲存映像檔的服務	Docker Hub、ghcr.io
Repository (倉庫)	同一軟體的映像檔集合	nginx、mysql、mycompany/myapp
Tag (標籤)	倉庫內的版本標識	latest、1.28、alpine

映像檔的完整名稱

一個完整的 Docker 映像檔名稱由 Registry 地址、使用者名稱/組織名、倉庫名和標籤組成。瞭解其結構有助於我們更準確地定位映像檔。基本格式如下：

[registry 地址/][使用者名稱/]倉庫名[:標籤]

示例：

## 完整格式

registry.example.com/mycompany/myapp:v1.2.3
│                    │         │     │
│                    │         │     └── 標籤
│                    │         └── 倉庫名
│                    └── 使用者名稱/組織名
└── Registry 地址

## Docker Hub 官方映像檔（省略 registry 和使用者名稱）

nginx:1.28
ubuntu:24.04

## Docker Hub 使用者映像檔

jwilder/nginx-proxy:latest

## 其他 Registry

ghcr.io/username/myapp:v1.0
us-west1-docker.pkg.dev/my-project/my-repo/myapp:v1.0

💡 筆者提示：如果不指定 Registry 地址，預設使用 Docker Hub。如果不指定標籤，預設使用 latest。

2.3.3 公共 Registry 服務

公共 Registry 服務為開發者提供了便捷的映像檔獲取途徑。其中最著名的是 Docker Hub。

預設的 Docker Hub

Docker Hub 是最大的公共 Registry，也是 Docker 的預設 Registry。

特點：

• 擁有大量官方映像檔 (nginx、mysql、redis 等)
• 免費賬戶可以建立公開倉庫
• 免費個人賬戶可建立 1 個私有倉庫；更高套餐支援更多私有倉庫

## 從 Docker Hub 拉取映像檔

$ docker pull nginx              # 官方映像檔
$ docker pull bitnami/redis      # 第三方映像檔

## 推送映像檔到 Docker Hub

$ docker login
$ docker push username/myapp:v1.0

其他公共 Registry

除了 Docker Hub，還有以下幾個常見的公共 Registry：

Registry	地址	說明
GitHub Container Registry	ghcr.io	GitHub 提供，與 GitHub Actions 整合好
Google Artifact Registry	LOCATION-docker.pkg.dev	Google Cloud 當前推薦；也支援遷移後的 gcr.io 相容域名
Quay.io	quay.io	Red Hat 提供
阿里雲容器映像檔服務	registry.cn-*.aliyuncs.com	國內訪問快
騰訊雲容器映像檔服務	ccr.ccs.tencentyun.com	國內訪問快

Google 的 Container Registry 已廢棄並完成下線，當前應優先使用 Artifact Registry；如果已經完成遷移，部分 gcr.io 域名請求會被相容到 Artifact Registry。

2.3.4 映像檔加速器

由於網路原因，在國內直接訪問 Docker Hub 可能會很慢。可以配置 映像檔加速器 (Registry Mirror) 來加速下載。配置示例如下：

// /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://your-accelerator-url"
  ]
}

詳細配置方法請參考映像檔加速器章節。

⚠️ 筆者提醒：映像檔加速器的可用性經常變化，使用前建議先測試是否可用。

2.3.5 私有 Registry

出於安全和隱私的考慮，企業往往需要搭建自己的私有 Registry。以下是幾種常見的搭建方案。

官方 Registry 映像檔

Docker 官方提供了 registry 映像檔，可以快速搭建私有 Registry：

## 啟動一個本地 Registry

$ docker run -d -p 5000:5000 --name registry registry:2

## 推送映像檔到本地 Registry

$ docker tag myapp:v1.0 localhost:5000/myapp:v1.0
$ docker push localhost:5000/myapp:v1.0

## 從本地 Registry 拉取

$ docker pull localhost:5000/myapp:v1.0

企業級解決方案

官方 Registry 功能較為基礎，企業環境常用以下方案：

方案	特點
Harbor	CNCF 專案，功能全面 (使用者管理、漏洞掃描、映像檔簽名)
Nexus Repository	支援多種製品型別 (Docker、Maven、npm 等)
雲廠商服務	阿里雲 ACR、騰訊雲 TCR、AWS ECR 等

筆者建議：

• 小團隊：可以先用官方 Registry，夠用即可
• 中大型團隊：推薦 Harbor，功能完善且開源免費
• 已使用雲服務：直接用雲廠商的 Registry 服務更省心

2.3.6 映像檔的推送和拉取

掌握映像檔的推送 (Push) 和拉取 (Pull) 是使用 Docker Registry 的基本功。

完整工作流程

如圖 2-3 所示，映像檔從開發環境構建後推送到 Registry，再由生產環境拉取並執行。

開發者機器                    Registry                    生產伺服器
     │                           │                             │
     │  docker build             │                             │
     │  構建映像檔                  │                             │
     │                           │                             │
     │  docker push ─────────────▶                             │
     │  推送映像檔                  │  儲存映像檔                   │
     │                           │                             │
     │                           │  ◀───────────── docker pull │
     │                           │                  拉取映像檔    │
     │                           │                             │
     │                           │                  docker run │
     │                           │                  執行容器    │

圖 2-3：映像檔構建、推送與拉取流程

常用命令

## 登入 Registry

$ docker login                      # 登入 Docker Hub
$ docker login registry.example.com # 登入其他 Registry

## 拉取映像檔

$ docker pull nginx:1.28

## 標記映像檔（準備推送）

$ docker tag myapp:latest registry.example.com/myteam/myapp:v1.0

## 推送映像檔

$ docker push registry.example.com/myteam/myapp:v1.0

## 登出

$ docker logout

2.3.7 映像檔的安全性

在使用公共映像檔或維護私有映像檔時，安全性是不容忽視的重要環節。

使用官方映像檔

Docker Hub 的官方映像檔 (標有 “Official Image” 標識) 經過 Docker 團隊稽核，相對更安全。示例如下：

## 官方映像檔示例

nginx          # ✅ 官方
mysql          # ✅ 官方
redis          # ✅ 官方

## 第三方映像檔（需要自行評估可信度）

bitnami/redis  # ⚠️ 需要評估
someuser/myapp # ⚠️ 需要評估

映像檔簽名

當前更推薦使用 Sigstore / Notation 體系進行映像檔簽名與驗證。Docker Content Trust (DCT) 已進入棄用階段：2025 年 8 月 8 日起最早的 DCT 簽名證書開始過期，2025 年 9 月 30 日起不能在新 Registry 啟用 DCT，2028 年 3 月 31 日將完全刪除此功能。不建議作為新專案方案。

注意：Cosign 預設會把簽名推送回映像檔所在倉庫，請使用你有推送許可權的映像檔地址。

## 準備一個你有寫許可權的映像檔地址
$ export IMAGE=<你的倉庫名>/nginx:1.28
$ docker pull nginx:1.28
$ docker tag nginx:1.28 $IMAGE
$ docker push $IMAGE

## 生成簽名金鑰（會生成 cosign.key / cosign.pub）
$ cosign generate-key-pair

## 使用 Cosign 簽名與驗證
$ cosign sign --key cosign.key $IMAGE
$ cosign verify --key cosign.pub $IMAGE

漏洞掃描

## 使用 Docker Scout 掃描映像檔漏洞

$ docker scout cves nginx:latest

## 使用 Trivy（開源工具）

$ trivy image nginx:latest

本章小結

本章介紹了 Docker 的三個核心概念：映像檔、容器和倉庫。

概念	要點
映像檔是什麼	只讀的應用模板，包含執行所需的一切
分層儲存	多層疊加，共享基礎層，節省空間
只讀特性	構建後不可修改，保證一致性
層的陷阱	刪除操作只是標記，不減小體積
容器是什麼	映像檔的執行例項，本質是隔離的程序
容器 vs 虛擬機器	共享核心，更輕量，但隔離性較弱
儲存層	可寫層隨容器刪除而消失
資料持久化	使用 Volume 或 Bind Mount
生命週期	與主程序 (PID 1) 繫結
Registry	儲存和分發映像檔的服務
倉庫 (Repository)	同一軟體的映像檔集合
標籤 (Tag)	版本標識，預設為 latest
Docker Hub	預設的公共 Registry
私有 Registry	企業內部使用，推薦 Harbor

現在你已經瞭解了 Docker 的三個核心概念：映像檔、容器 和倉庫。接下來，讓我們開始 安裝 Docker，動手實踐！

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

3.1 Ubuntu

Ubuntu 是 Docker 最常用的執行環境之一。本節將介紹如何在 Ubuntu 系統上安裝 Docker，並配置國內映像檔加速。

為什麼推薦 APT 源安裝而不是指令碼？

雖然 Docker 官方提供了便捷的安裝指令碼（get.docker.com），但筆者在生產環境中強烈推薦透過 Docker 官方 APT 倉庫安裝，原因如下：

• 版本管理：透過 APT 倉庫安裝後，可以像管理其他系統軟體包一樣升級、回滾和鎖定版本
• 安全更新：Docker 官方倉庫會持續釋出新版本和安全修復，適合長期維護
• 一致性：團隊更容易鎖定同一版本，避免“在我的機器上可以執行”的問題
• 解除安裝乾淨：APT 包管理系統會負責清理所有相關檔案，指令碼安裝的清理往往不夠徹底

如果你只是想快速嘗試 Docker，指令碼安裝沒有問題；但一旦涉及持久運維，APT 源是更成熟的選擇。

警告：切勿在沒有配置 Docker APT 源的情況下直接使用 apt 命令安裝 Docker。

3.1.1 準備工作

在開始安裝之前，我們需要確認系統版本是否滿足要求，並清理可能存在的舊版本。

系統要求

根據 Docker 官方安裝文件，當前受支援的 Ubuntu 64 位版本包括（具體以官方 安裝文件 為準）：

• Ubuntu Resolute Raccoon 26.04 (LTS)
• Ubuntu Questing Quokka 25.10
• Ubuntu Noble 24.04 (LTS)
• Ubuntu Jammy 22.04 (LTS)

警告：Ubuntu 20.04 LTS 已不在 Docker 當前支援列表中，不建議用於新部署。對於仍在執行 20.04 的生產系統，應儘快升級到 22.04 LTS 或 24.04 LTS；若短期內無法遷移，可透過 Ubuntu Pro 獲取作業系統層面的擴充套件安全維護（ESM），但這並不改變 Docker 官方支援矩陣。

在 Ubuntu LTS 版本上，目前 Docker 支援 amd64、arm64、armhf、ppc64el、s390x 等 5 個平臺；而非 LTS 版本支援的平臺通常較少。同時，LTS 版本會獲得 5 年的升級維護支援，這樣的系統會獲得更長期的安全保障，因此在生產環境中推薦使用 LTS 版本。

解除安裝舊版本

Docker 官方建議先解除安裝可能衝突的非官方軟體包：

$ for pkg in docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc;
do
    sudo apt remove $pkg;
done

3.1.2 使用 APT 安裝

先安裝基礎依賴，並準備 Docker 官方金鑰目錄：

$ sudo apt update

$ sudo apt install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings

如果企業內網已經維護了受信任的軟體包映像檔，可在後續步驟中替換 URIs 的域名；預設建議優先以 Docker 官方倉庫為準。

為了確認所下載軟體包的合法性，需要新增倉庫簽名金鑰：

$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

然後向 apt 新增 Docker 倉庫：

$ sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

如果需要測試頻道，可將 Components: stable 改為 test，或改用 test.docker.com 指令碼在測試環境驗證。

更新 APT 快取，並安裝 Docker Engine 及常用 CLI 外掛：

$ sudo apt update

$ sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.1.3 使用指令碼自動安裝

在測試或開發環境中，Docker 官方提供了便捷安裝指令碼，但官方明確不建議把它作為生產環境的標準安裝方式。

在真正執行前，建議先用 --dry-run 預覽指令碼動作：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

# 若需要測試頻道：
# curl -fsSL https://test.docker.com -o test-docker.sh
# sudo sh ./test-docker.sh

確認無誤後，再執行 sudo sh ./get-docker.sh 安裝穩定版。

3.1.4 啟動 Docker

$ sudo systemctl enable --now docker

3.1.5 建立 docker 使用者組

預設情況下，docker 命令會使用 Unix socket 與 Docker 引擎通訊。而只有 root 使用者和 docker 組的使用者才可以訪問 Docker 引擎的 Unix socket。出於安全考慮，一般 Linux 系統上不會直接使用 root 使用者。因此，更好的做法是將需要使用 docker 的使用者加入 docker 使用者組。

⚠️ 安全警告：docker 使用者組等同於 root 許可權

將使用者加入 docker 組免去了每次執行 docker 命令時輸入 sudo 的繁瑣，但這也意味著該使用者可以輕易獲取主機的最高 root 許可權（例如透過掛載根目錄執行容器）。 如果你在一個多使用者共享的生產系統上配置，切勿隨意將普通使用者加入此組。此時，更安全的替代方案是使用官方提供的 Rootless 模式 (Rootless mode)，它允許在沒有任何 root 許可權的情況下執行 Docker 守護程序和容器。

建立 docker 組：

$ sudo groupadd docker

將當前使用者加入 docker 組：

$ sudo usermod -aG docker $USER

退出當前終端並重新登入，進行如下測試。

3.1.6 測試 Docker 是否安裝正確

$ docker run --rm hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b8dfde127a29: Pull complete
Digest: sha256:308866a43596e83578c7dfa15e27a73011bdd402185a84c5cd7f32a88b501a24
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

若能正常輸出以上資訊，則說明安裝成功。

3.1.7 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.2 Debian

Debian 以其穩定性著稱，是 Docker 的理想宿主系統。本節將指導你在 Debian 上完成 Docker 的安裝。

APT 源安裝的必要性

與 Ubuntu 類似，Debian 使用者在安裝 Docker 時同樣應該優先選擇 Docker 官方 APT 倉庫。對於伺服器環境，這種方式更利於版本控制、升級和長期維護。

警告：切勿在沒有配置 Docker APT 源的情況下直接使用 apt 命令安裝 Docker。

3.2.1 準備工作

安裝前請仔細檢查 Debian 版本支援情況，並解除安裝舊版本以避免衝突。

系統要求

Docker 支援以下版本的 Debian 作業系統（具體以官方 安裝文件 為準）：

• Debian Trixie 13 (stable)
• Debian Bookworm 12 (oldstable，全面支援至 2026 年 6 月 10 日，LTS 至 2028 年 6 月 30 日)
• Debian Bullseye 11 (oldoldstable，LTS 支援至 2026 年 8 月 31 日)

注意：Debian Bullseye 11 將於 2026 年 8 月底結束長期支援。建議新部署使用 Bookworm 12 或 Trixie 13。

解除安裝舊版本

Docker 官方建議先解除安裝可能衝突的非官方軟體包：

$ for pkg in docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc; do
    sudo apt remove $pkg
done

3.2.2 使用 APT 安裝

先安裝基礎依賴，並準備金鑰目錄：

$ sudo apt update

$ sudo apt install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings

如果公司內網維護了受信任映像檔站，可在後續倉庫地址中替換域名；預設建議優先使用 Docker 官方倉庫。

為了確認所下載軟體包的合法性，需要新增軟體源的 GPG 金鑰。

$ sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

然後，我們需要向 sources.list 中新增 Docker 軟體源：

在一些基於 Debian 的 Linux 發行版中，$(. /etc/os-release && echo "$VERSION_CODENAME") 可能不會返回 Debian 官方倉庫使用的代號，例如 Kali Linux 等衍生發行版。此時請手動替換為對應的 Debian 代號，例如 bookworm。

$ sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

如果使用 Kali 等衍生發行版，請把 Suites 對應的版本代號替換為對映到的 Debian 代號，例如 bookworm。如果需要測試頻道，可將 Components: stable 改為 test。

更新 APT 快取，並安裝 Docker Engine 及常用 CLI 外掛。

$ sudo apt update

$ sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.2.3 使用指令碼自動安裝

在測試或開發環境中，Docker 官方提供了便捷安裝指令碼，但官方明確不建議把它作為生產環境的標準安裝方式。

在真正執行前，建議先用 --dry-run 預覽指令碼動作：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

# 若需要測試頻道：
# curl -fsSL https://test.docker.com -o test-docker.sh
# sudo sh ./test-docker.sh

確認無誤後，再執行 sudo sh ./get-docker.sh 安裝穩定版。

3.2.4 啟動 Docker

$ sudo systemctl enable --now docker

3.2.5 建立 docker 使用者組

預設情況下，docker 命令會使用 Unix socket 與 Docker 引擎通訊。而只有 root 使用者和 docker 組的使用者才可以訪問 Docker 引擎的 Unix socket。出於安全考慮，一般 Linux 系統上不會直接使用 root 使用者。因此，更好的做法是將需要使用 docker 的使用者加入 docker 使用者組。

⚠️ 安全警告：docker 使用者組等同於 root 許可權

將使用者加入 docker 組免去了每次執行 docker 命令時輸入 sudo 的繁瑣，但這也意味著該使用者可以輕易獲取主機的最高 root 許可權（例如透過掛載根目錄執行容器）。 如果你在一個多使用者共享的生產系統上配置，切勿隨意將普通使用者加入此組。此時，更安全的替代方案是使用官方提供的 Rootless 模式 (Rootless mode)，它允許在沒有任何 root 許可權的情況下執行 Docker 守護程序和容器。

建立 docker 組：

$ sudo groupadd docker

將當前使用者加入 docker 組：

$ sudo usermod -aG docker $USER

退出當前終端並重新登入，進行如下測試。

3.2.6 測試 Docker 是否安裝正確

$ docker run --rm hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b8dfde127a29: Pull complete
Digest: sha256:308866a43596e83578c7dfa15e27a73011bdd402185a84c5cd7f32a88b501a24
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

若能正常輸出以上資訊，則說明安裝成功。

3.2.7 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.3 Fedora

Fedora 作為技術前瞻的 Linux 發行版，對 Docker 有著良好的支援。本節介紹在 Fedora 上的安裝步驟。

YUM/DNF 源安裝的策略建議

Fedora 的快速釋出週期（每 6 個月釋出新版本）決定了它的使用者群體多為開發者和技術愛好者。雖然透過 DNF 可以直接安裝 Docker，但筆者建議仍然透過 Docker 官方 YUM 源進行安裝，原因是：Fedora 官方倉庫的 Docker 版本往往滯後，而官方源能確保你獲得最新的 Docker 功能和安全補丁。特別是在開發環境需要用到最新 Docker 特性時，這一點顯得尤為重要。

警告：切勿在沒有配置 Docker dnf 源的情況下直接使用 dnf 命令安裝 Docker。

3.3.1 準備工作

確保你的 Fedora 版本在支援列表中，並清理舊版本。

系統要求

根據 Docker 官方安裝文件，當前受支援的 Fedora 版本包括（具體以官方 安裝文件 為準）：

• Fedora 44
• Fedora 43
• Fedora 42

解除安裝舊版本

舊版本的 Docker 稱為 docker 或者 docker-engine，使用以下命令解除安裝舊版本：

$ sudo dnf remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine

3.3.2 使用 dnf 安裝

使用 dnf 包管理器安裝是推薦的方式，便於後續的更新和管理。

執行以下命令安裝依賴包：

$ sudo dnf -y install dnf-plugins-core

預設建議優先使用 Docker 官方倉庫；如果企業內網維護了受信任映像檔站，可自行替換倉庫 URL。

執行下面的命令新增 dnf 軟體源：

$ sudo dnf config-manager \
    --add-repo \
    https://download.docker.com/linux/fedora/docker-ce.repo

如果需要測試版本的 Docker 請使用以下命令：

$ sudo dnf config-manager --set-enabled docker-ce-test

你也可以禁用測試版本的 Docker

$ sudo dnf config-manager --set-disabled docker-ce-test

安裝 Docker

更新 dnf 軟體源快取，並安裝 Docker Engine 及常用 CLI 外掛。

$ sudo dnf update
$ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

你也可以使用以下命令安裝指定版本的 Docker

$ dnf list docker-ce  --showduplicates | sort -r

docker-ce.x86_64          3:29.4.0-1.fc42                       docker-ce-stable

$ sudo dnf -y install docker-ce-<VERSION_STRING> docker-ce-cli-<VERSION_STRING>

3.3.3 使用指令碼自動安裝

在測試或開發環境中，Docker 官方提供了便捷安裝指令碼，但官方明確不建議把它作為生產環境的標準安裝方式。

在真正執行前，建議先用 --dry-run 預覽指令碼動作：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

# 若需要測試頻道：
# curl -fsSL https://test.docker.com -o test-docker.sh
# sudo sh ./test-docker.sh

確認無誤後，再執行 sudo sh ./get-docker.sh 安裝穩定版。

3.3.4 啟動 Docker

$ sudo systemctl enable --now docker

3.3.5 建立 docker 使用者組

預設情況下，docker 命令會使用 Unix socket 與 Docker 引擎通訊。而只有 root 使用者和 docker 組的使用者才可以訪問 Docker 引擎的 Unix socket。出於安全考慮，一般 Linux 系統上不會直接使用 root 使用者。因此，更好的做法是將需要使用 docker 的使用者加入 docker 使用者組。

⚠️ 安全警告：docker 使用者組等同於 root 許可權

將使用者加入 docker 組免去了每次執行 docker 命令時輸入 sudo 的繁瑣，但這也意味著該使用者可以輕易獲取主機的最高 root 許可權（例如透過掛載根目錄執行容器）。 如果你在一個多使用者共享的生產系統上配置，切勿隨意將普通使用者加入此組。此時，更安全的替代方案是使用官方提供的 Rootless 模式 (Rootless mode)，它允許在沒有任何 root 許可權的情況下執行 Docker 守護程序和容器。

建立 docker 組：

$ sudo groupadd docker

將當前使用者加入 docker 組：

$ sudo usermod -aG docker $USER

退出當前終端並重新登入，進行如下測試。

3.3.6 測試 Docker 是否安裝正確

$ docker run --rm hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b8dfde127a29: Pull complete
Digest: sha256:308866a43596e83578c7dfa15e27a73011bdd402185a84c5cd7f32a88b501a24
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

若能正常輸出以上資訊，則說明安裝成功。

3.3.7 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.4 CentOS

CentOS (及其替代品 Rocky Linux、AlmaLinux) 是企業級伺服器常用的作業系統。本節介紹在這些系統上安裝 Docker 的步驟。

企業級部署的版本選擇

值得注意的是，CentOS 8 已停止維護，CentOS 7 已停止支援。如果你正在規劃新的生產部署，強烈建議選擇 Rocky Linux 或 AlmaLinux——這兩個專案是由社群維護的 CentOS 替代品，延續了 CentOS 的企業級特性，同時提供了更長的生命週期承諾。選擇穩定的基礎系統，才能為 Docker 的長期運維奠定堅實基礎。

警告：切勿在沒有配置 Docker YUM 源的情況下直接使用 yum 命令安裝 Docker。

3.4.1 準備工作

安裝前請確認系統版本和核心版本滿足 Docker 的執行要求。

系統要求

嚴重警告：CentOS 7 已於 2024 年 6 月 30 日結束所有支援，不再接收任何安全更新。CentOS 8 已於 2021 年 12 月 31 日停止維護。強烈建議新專案使用 Rocky Linux 或 AlmaLinux 替代，這兩個專案由社群維護，提供長期支援承諾。

Docker 官方當前安裝文件覆蓋的 CentOS 平臺為 CentOS Stream 9 和 CentOS Stream 10（具體以官方 安裝文件 為準）。Rocky Linux、AlmaLinux 等 RHEL 相容發行版通常可以沿用相近步驟，但建議先在測試環境驗證倉庫與依賴是否匹配。

對於 Rocky Linux、AlmaLinux 或 CentOS Stream，推薦使用 dnf 包管理器。

解除安裝舊版本

舊版本的 Docker 稱為 docker 或者 docker-engine，使用以下命令解除安裝舊版本：

$ sudo yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine \
                  docker-ce-cli \
                  containerd.io

3.4.2 使用 yum 安裝

使用 yum/dnf 安裝是管理 Docker 生命週期的標準方式。

執行以下命令安裝依賴包：

$ sudo dnf install -y dnf-plugins-core

預設建議優先使用 Docker 官方倉庫；如果企業內網維護了受信任映像檔站，可自行替換倉庫 URL。

執行下面的命令新增 yum 軟體源：

$ sudo dnf config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

如果需要測試版本的 Docker 請執行以下命令：

$ sudo dnf config-manager --set-enabled docker-ce-test

安裝 Docker

更新 dnf 軟體源快取，並安裝 Docker Engine 及常用 CLI 外掛。

$ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.4.3 防火牆注意事項

Docker 官方提醒：如果主機使用 ufw 或 firewalld 管理防火牆，容器暴露出的埠可能繞過現有規則；同時 Docker 僅相容 iptables-nft 和 iptables-legacy，不支援直接由 nft 建立的規則集。

因此，生產環境中更穩妥的做法是：

• 明確使用 iptables-nft 或 iptables-legacy 維護規則；
• 需要限制容器流量時，優先把自定義規則寫入 DOCKER-USER 鏈；
• 在變更防火牆策略前，先用測試容器驗證埠暴露和東西向流量是否符合預期。

3.4.4 使用指令碼自動安裝

在測試或開發環境中，Docker 官方提供了便捷安裝指令碼，但官方明確不建議把它作為生產環境的標準安裝方式。

在真正執行前，建議先用 --dry-run 預覽指令碼動作：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

# 若需要測試頻道：
# curl -fsSL https://test.docker.com -o test-docker.sh
# sudo sh ./test-docker.sh

確認無誤後，再執行 sudo sh ./get-docker.sh 安裝穩定版。

3.4.5 啟動 Docker

$ sudo systemctl enable --now docker

3.4.6 建立 docker 使用者組

預設情況下，docker 命令會使用 Unix socket 與 Docker 引擎通訊。而只有 root 使用者和 docker 組的使用者才可以訪問 Docker 引擎的 Unix socket。出於安全考慮，一般 Linux 系統上不會直接使用 root 使用者。因此，更好的做法是將需要使用 docker 的使用者加入 docker 使用者組。

⚠️ 安全警告：docker 使用者組等同於 root 許可權

將使用者加入 docker 組免去了每次執行 docker 命令時輸入 sudo 的繁瑣，但這也意味著該使用者可以輕易獲取主機的最高 root 許可權（例如透過掛載根目錄執行容器）。 如果你在一個多使用者共享的生產系統上配置，切勿隨意將普通使用者加入此組。此時，更安全的替代方案是使用官方提供的 Rootless 模式 (Rootless mode)，它允許在沒有任何 root 許可權的情況下執行 Docker 守護程序和容器。

建立 docker 組：

$ sudo groupadd docker

將當前使用者加入 docker 組：

$ sudo usermod -aG docker $USER

退出當前終端並重新登入，進行如下測試。

3.4.7 測試 Docker 是否安裝正確

$ docker run --rm hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b8dfde127a29: Pull complete
Digest: sha256:308866a43596e83578c7dfa15e27a73011bdd402185a84c5cd7f32a88b501a24
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

若能正常輸出以上資訊，則說明安裝成功。

3.4.8 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.4.9 新增核心引數

如果在 CentOS 使用 Docker 看到下面的這些警告資訊：

WARNING: bridge-nf-call-iptables is disabled
WARNING: bridge-nf-call-ip6tables is disabled

請新增核心配置引數以啟用這些功能。

$ sudo tee -a /etc/sysctl.conf <<-EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF

然後重新載入 sysctl.conf 即可

$ sudo sysctl -p

3.5 Raspberry Pi

樹莓派等 ARM 架構裝置在物聯網和邊緣計算領域應用廣泛。本節介紹如何在樹莓派上安裝 Docker。

樹莓派執行 Docker 的現實考慮

樹莓派是 Docker 在邊緣計算的一個優秀用例。但在安裝前，筆者建議你瞭解幾個實際情況：

效能特性：

• Raspberry Pi 4 及以上才能流暢執行 Docker 和基本容器
• Raspberry Pi Zero 2 可以執行，但效能受限
• 磁碟 I/O 是主要瓶頸（特別是使用 microSD 卡時）

映像檔可用性：

• 並非所有 Docker 映像檔都有 ARM 版本（arm64 或 armv7）
• 官方映像檔通常提供多架構支援，但第三方映像檔可能沒有
• 某些依賴 Intel 特定指令的應用無法在 ARM 上執行

儲存和記憶體：

• 容器映像檔會佔用較多儲存空間，128GB microSD 卡建議最多執行 3-4 箇中等大小的容器
• 512MB 或 1GB 記憶體的樹莓派執行多個容器會非常吃力

實踐建議：樹莓派 Docker 部署最適合輕量級應用——單個微服務、監控代理、Web 伺服器等。複雜多容器應用還是應該部署在效能更強的硬體上。

警告：切勿在沒有配置 Docker APT 源的情況下直接使用 apt 命令安裝 Docker。

3.5.1 系統要求

Docker 對 ARM 架構有著良好的支援。

Docker 可以執行在多種 CPU 架構上，但本小節只聚焦 Raspberry Pi OS 32-bit (armhf) 的官方安裝流程；如果你使用的是 64 位 Raspberry Pi OS，請直接參考 Debian arm64 安裝說明。

Docker 官方目前單獨提供的是 Raspberry Pi OS 32-bit (armhf) 安裝頁（具體以官方 安裝文件 為準），支援情況如下：

• Raspberry Pi OS Bookworm
• Raspberry Pi OS Bullseye

重要提醒：Docker Engine v28 是官方最後一個支援 Raspberry Pi OS 32-bit (armhf) 的大版本。從 v29 開始，32 位 Raspberry Pi OS 不再提供新主版本軟體包。若你使用的是 64 位 Raspberry Pi OS，請直接參考 Debian arm64 安裝方式。

注：Raspberry Pi OS 由樹莓派的開發與維護機構樹莓派基金會官方支援，並推薦用作樹莓派的首選系統，其基於 Debian。

3.5.2 使用 APT 安裝

推薦使用 APT 包管理器進行安裝，以確保版本的穩定性和安全性。

先安裝基礎依賴，並準備金鑰目錄：

$ sudo apt-get update

$ sudo apt-get install \
     ca-certificates \
     curl \
     gnupg

預設建議優先使用 Docker 官方倉庫；如果企業內網維護了受信任映像檔站，可自行替換倉庫 URL。

為了確認所下載軟體包的合法性，需要新增軟體源的 GPG 金鑰。

$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/raspbian/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

然後，我們需要向 sources.list 中新增 Docker 軟體源：

$ sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/raspbian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

以上命令會新增穩定版本的 Docker APT 源，如果需要測試版本的 Docker 請將 stable 改為 test。

報錯解決辦法

在 Raspberry Pi OS Bullseye/Bookworm 中，如果你使用 add-apt-repository 新增源，可能會出現如下報錯。官方當前更推薦的做法是不要繼續回退到舊式單行 deb 配置，而是直接使用上面的 docker.sources 檔案方式寫入倉庫：

Traceback (most recent call last):
 File "/usr/bin/add-apt-repository", line 95, in <module>
   sp = SoftwareProperties(options=options)
 File "/usr/lib/python3/dist-packages/softwareproperties/SoftwareProperties.py", line 109, in __init__
   self.reload_sourceslist()
 File "/usr/lib/python3/dist-packages/softwareproperties/SoftwareProperties.py", line 599, in reload_sourceslist
   self.distro.get_sources(self.sourceslist)
 File "/usr/lib/python3/dist-packages/aptsources/distro.py", line 91, in get_sources
   raise NoDistroTemplateException(
aptsources.distro.NoDistroTemplateException: Error: could not find a distribution template for Raspbian/bullseye

如果之前已經寫入了錯誤的源配置，建議先刪除舊條目，再重新執行本節前面的 docker.asc + docker.sources 兩步。

安裝 Docker

更新 apt 軟體包快取，並安裝 Docker Engine 及常用 CLI 外掛。

$ sudo apt-get update

$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.5.3 使用指令碼自動安裝

在測試或開發環境中，Docker 官方提供了便捷安裝指令碼，但官方明確不建議把它作為生產環境的標準安裝方式。

在真正執行前，建議先用 --dry-run 預覽指令碼動作：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

# 若需要測試頻道：
# curl -fsSL https://test.docker.com -o test-docker.sh
# sudo sh ./test-docker.sh

確認無誤後，再執行 sudo sh ./get-docker.sh 安裝穩定版。如果你執行的是 64 位 Raspberry Pi OS，更推薦直接遷移到 Debian arm64 安裝路徑，而不是繼續停留在 32 位 armhf 流程上。

3.5.4 啟動 Docker

$ sudo systemctl enable --now docker

3.5.5 建立 docker 使用者組

預設情況下，docker 命令會使用 Unix socket 與 Docker 引擎通訊。而只有 root 使用者和 docker 組的使用者才可以訪問 Docker 引擎的 Unix socket。出於安全考慮，一般 Linux 系統上不會直接使用 root 使用者。因此，更好的做法是將需要使用 docker 的使用者加入 docker 使用者組。

⚠️ 安全警告：docker 使用者組等同於 root 許可權

將使用者加入 docker 組免去了每次執行 docker 命令時輸入 sudo 的繁瑣，但這也意味著該使用者可以輕易獲取主機的最高 root 許可權（例如透過掛載根目錄執行容器）。 如果你在一個多使用者共享的生產系統上配置，切勿隨意將普通使用者加入此組。此時，更安全的替代方案是使用官方提供的 Rootless 模式 (Rootless mode)，它允許在沒有任何 root 許可權的情況下執行 Docker 守護程序和容器。

建立 docker 組：

$ sudo groupadd docker

將當前使用者加入 docker 組：

$ sudo usermod -aG docker $USER

退出當前終端並重新登入，進行如下測試。

3.5.6 測試 Docker 是否安裝正確

$ docker run --rm hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
4ee5c797bcd7: Pull complete
Digest: sha256:308866a43596e83578c7dfa15e27a73011bdd402185a84c5cd7f32a88b501a24
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm32v7)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

若能正常輸出以上資訊，則說明安裝成功。

注意：ARM 平臺不能使用 x86 映像檔，檢視 Raspberry Pi OS 可使用映像檔請訪問 arm32v7 或者 arm64v8。

3.5.7 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.6 Linux 離線安裝

生產環境中一般都是沒有公網資源的，本文介紹如何在生產伺服器上離線部署 Docker

括號內的字母表示該操作需要在哪些伺服器上執行

3.6.1 CentOS/Rocky/AlmaLinux 離線安裝 Docker

在無法連線外網的安全環境中，離線安裝是唯一的選擇。本節介紹如何在 RHEL 系發行版中進行離線安裝。

注意：Docker 官方當前支援的 RHEL 相容平臺基線已是 CentOS Stream 9/10（具體以官方 安裝文件 為準）。下面的離線示例建議統一按 el9 軟體包和 dnf 流程準備，Rocky Linux 9、AlmaLinux 9 也可先在測試環境按相同思路驗證。

3.6.1.1 本地 RPM 檔案安裝：推薦

推薦這種方式，是因為在生產環境中一般會選定某個指定的 Docker 軟體版本使用。

查詢可用的軟體版本

$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ sudo dnf list docker-ce --showduplicates | sort -r

docker-ce.x86_64            3:29.4.0-1.el9                      docker-ce-stable
docker-ce.x86_64            3:29.3.1-1.el9                      docker-ce-stable
docker-ce.x86_64            3:29.3.0-1.el9                      docker-ce-stable

下載到指定資料夾

sudo dnf install --downloadonly --downloaddir=/tmp/docker_offline_install/ \
  docker-ce-<VERSION_STRING> \
  docker-ce-cli-<VERSION_STRING> \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

下載完成後，把 /tmp/docker_offline_install/ 目錄中的全部 RPM 檔案複製到離線目標伺服器。

在目標伺服器進入資料夾後安裝

• 離線安裝時，不要使用 rpm --nodeps --force 跳過依賴檢查；應先把完整依賴包集複製到目標伺服器，再讓 dnf 從本地 RPM 安裝。

$ sudo dnf install ./*.rpm

鎖定軟體版本（可選）

下載鎖定版本軟體

可參考下文的網路源搭建

$ sudo dnf install 'dnf-command(versionlock)'

鎖定軟體版本

$ sudo dnf versionlock add docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

檢視鎖定列表

$ sudo dnf versionlock list

鎖定後無法再更新

$ sudo dnf upgrade docker-ce

解鎖指定軟體

$ sudo dnf versionlock delete docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

解鎖所有軟體

$ sudo dnf versionlock clear

3.6.1.2 本地倉庫伺服器搭建安裝 Docker

掛載 ISO 映像檔搭建本地 File 源

## 刪除其他網路源

$ sudo rm -f /etc/yum.repos.d/*

## 掛載光碟或者iso映像檔

$ sudo mount /dev/cdrom /mnt

## 新增本地源

$ sudo tee /etc/yum.repos.d/local-base.repo <<EOF
[local_base]
name=local_base
baseurl=file:///mnt
enabled=1
gpgcheck=0
EOF

## 測試剛才的本地源,安裝createrepo軟體

$ sudo dnf clean all
$ sudo dnf install -y createrepo_c httpd

根據本地檔案搭建 BaseOS/AppStream 網路源

## 安裝apache 伺服器

## 新建centos目錄

$ sudo mkdir -p /var/www/html/base

## 複製光碟內的檔案到剛才新建的目錄

$ sudo cp -R /mnt/* /var/www/html/base/
$ sudo createrepo_c /var/www/html/base/
$ sudo systemctl enable --now httpd

下載 Docker CE 倉庫內容

在有網路的伺服器上同步 Docker CE RPM 包：

$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ mkdir -p /tmp/docker-ce
$ sudo dnf reposync --repo=docker-ce-stable --download-path=/tmp/docker-ce

建立倉庫索引

把下載的 docker-ce 資料夾複製到離線的伺服器

## 把 docker-ce 資料夾複製到 /var/www/html/docker-ce

$ sudo createrepo_c /var/www/html/docker-ce/

DNF 用戶端設定

$ sudo rm -f /etc/yum.repos.d/*
$ sudo tee /etc/yum.repos.d/local-files.repo <<EOF
[local_base]
name=local_base

## 改成倉庫伺服器地址

baseurl=http://x.x.x.x/base
enabled=1
gpgcheck=0
proxy=_none_
[docker-ce-stable]
name=docker-ce-stable

## 改成倉庫伺服器地址

baseurl=http://x.x.x.x/docker-ce
enabled=1
gpgcheck=0
proxy=_none_
EOF

安裝 Docker

$ sudo dnf makecache
$ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable --now docker
$ sudo docker run hello-world

3.7 macOS

Mac 使用者的特殊考慮

macOS 上沒有原生 Linux 核心，Docker 需要執行在一個輕量級虛擬機器中。Docker Desktop 完全封裝了這個複雜性，讓 Mac 使用者可以像 Linux 使用者一樣使用 Docker。但有幾點需要特別瞭解：

效能特性：

• Apple Silicon（M 系列晶片）比 Intel Mac 的效能更好，且擁有原生支援
• 檔案 I/O 效能：macOS 與容器之間的卷掛載效能不如 Linux（這是虛擬化的代價）
• 記憶體使用：Docker Desktop 本身會消耗一定記憶體用於虛擬機器管理

許可考慮：

• 小型企業（少於 250 名員工且年收入低於 1000 萬美元）、個人使用、教育和非商業開源專案可免費使用
• 超出上述範圍的商業用途需要付費訂閱

3.7.1 系統要求

Docker Desktop for Mac 支援當前版本及前兩個主要版本的 macOS（具體以官方 安裝文件 為準），並且至少需要 4 GB 記憶體。對於 Apple Silicon 機型，若需要相容部分 Intel 命令列工具，官方建議安裝 Rosetta 2。

3.7.2 安裝

[!WARNING] 商業許可限制：Docker Desktop 對小型企業（少於 250 名員工且年收入低於 1000 萬美元）、個人使用、教育和非商業開源專案仍然免費。超出上述範圍的商業用途需要付費訂閱。企業使用者請注意合規風險。

Docker Desktop 為 Mac 使用者提供了標準的圖形化安裝體驗。官方當前主要提供 DMG 互動安裝和命令列/企業部署安裝；這裡先介紹最常見的 DMG 安裝方式。

手動下載安裝

如果需要手動下載，可直接使用 Docker Desktop for Mac Intel 版 安裝包。

如果你的電腦搭載的是 Apple Silicon 晶片（arm64 架構），請使用 Docker Desktop for Mac Apple Silicon 版。

如同 macOS 其它軟體一樣，安裝也非常簡單，雙擊下載的 .dmg 檔案，然後將那隻叫 Moby 的鯨魚圖示拖拽到 Application 資料夾即可 (其間需要輸入使用者密碼)。

3.7.3 執行

從應用中找到 Docker 圖示並點選執行。

執行之後，會在右上角選單欄看到多了一個鯨魚圖示，這個圖示表明瞭 Docker 的執行狀態。

每次點選鯨魚圖示會彈出操作選單。

之後，你可以在終端透過命令檢查安裝後的 Docker 版本。

$ docker version
$ docker info

如果 docker version 和 docker info 都能正常返回資訊，就可以嘗試執行一個 Nginx 伺服器：

$ docker run -d -p 80:80 --name webserver nginx

服務執行後，可以訪問 http://localhost。如果看到了 Welcome to nginx!，就說明 Docker Desktop for Mac 安裝成功了。

要停止並刪除 Nginx 容器，執行下面的命令：

$ docker stop webserver
$ docker rm webserver

3.7.4 替代容器執行時

Docker Desktop 並非 macOS 上執行容器的唯一選擇。以下兩個工具也廣泛使用，各有側重：

特性	Docker Desktop	OrbStack	Colima
啟動速度	較慢（約 10–30 秒）	極快（約 2 秒）	中等（約 5–10 秒）
空閒記憶體佔用	4–6 GB	200–300 MB	約 400 MB
圖形介面	完整 GUI	輕量 GUI	僅命令列
Apple Silicon	支援	原生最佳化	支援
商業許可	大型企業需付費	個人免費，商業付費	MIT 開源
Kubernetes	內建	內建	透過 k3s 支援

OrbStack：以極低的資源佔用和接近原生的 I/O 效能著稱。對於 Apple Silicon 機型上需要頻繁構建映像檔的開發者，體驗提升尤為明顯。個人和教育用途免費。

Colima：完全開源的命令列方案，底層基於 Lima 虛擬機器。適合偏好終端工作流、不需要 GUI 的開發者，或企業中希望避免商業許可限制的團隊。

上述三種工具均相容標準的 docker CLI 命令。從 Docker Desktop 切換到 OrbStack 或 Colima 時，已有的映像檔和容器配置通常可以平滑遷移。

3.7.5 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.8 Windows 10/11

在 Windows 平臺上，Docker Desktop 提供了完整的 Docker 開發環境。本節介紹在 Windows 10/11 上的安裝和配置。

Windows 上的 Docker：執行原理理解

與 macOS 類似，Windows 也沒有原生 Linux 容器支援。Docker Desktop for Windows 有兩種執行後端可選：

WSL 2（Windows Subsystem for Linux 2） - 推薦：

• 利用 Hyper-V 虛擬化執行真正的 Linux 核心
• 效能更好，檔案系統整合更深
• 現代 Windows 10/11 的標準選擇
• 支援在 Linux 和 Windows 之間的無縫檔案訪問

Hyper-V - 傳統方案：

• 純虛擬化方式
• 效能略低於 WSL 2
• 在某些企業網路環境下仍被使用

實踐建議：WSL 2 和 Hyper-V 在功能上都能滿足 Docker Desktop 的日常開發需求，選擇哪種後端應以機器能力、企業策略和你的工作流為準；如果系統只滿足其中一種後端的前置條件，安裝器才會自動選擇可用的那一種。

3.8.1 系統要求

Docker Desktop for Windows 支援 Docker 官方文件列出的受支援 Windows 10/11 64 位版本（具體以官方 安裝文件 為準）。若使用 WSL 2 後端，需要啟用 WSL 2，並滿足官方要求的 WSL 2.1.5 或更高版本；若使用 Hyper-V 後端，則需要啟用 Hyper-V 和 Containers 功能。Windows 10 64 位支援 Enterprise、Pro 和 Education 22H2（build 19045），Windows 11 64 位支援 Enterprise、Pro 和 Education 23H2（build 22631）或更高版本，且官方建議主機至少具備 8 GB 記憶體。

3.8.2 安裝

[!WARNING] 商業許可限制：Docker Desktop 對小型企業（少於 250 名員工且年收入少於 1000 萬美元）、個人使用、教育和非商業開源專案仍然免費。對於其他商業用途，以及政府機構使用，需要付費訂閱。企業使用者請注意合規風險。

手動下載安裝

官方當前提供三個主要入口：

• Docker Desktop for Windows x86_64 安裝包
• Docker Desktop for Windows Microsoft Store 版本
• Docker Desktop for Windows Arm 早期訪問版

下載好對應安裝包後，雙擊 Docker Desktop Installer.exe 開始安裝。

使用winget安裝

$ winget install Docker.DockerDesktop

3.8.3 在 WSL2 執行 Docker

若你的環境使用 WSL 2 後端，請先確認 wsl --version 滿足 Docker 官方的版本要求，並按 Docker Desktop 的 WSL 說明啟用對應功能。

3.8.4 執行

在 Windows 搜尋欄輸入 Docker 點選 Docker Desktop 開始執行。

Docker 啟動之後會在 Windows 工作列出現鯨魚圖示。

等待片刻，當鯨魚圖示靜止時，說明 Docker 啟動成功，之後你可以開啟 PowerShell 使用 Docker。

推薦使用 Windows Terminal 在終端使用 Docker。

3.8.5 映像檔加速

如果在使用過程中發現拉取 Docker 映像檔十分緩慢，可以配置 Docker 國內映像檔加速。

3.9 映像檔加速器

國內從 Docker Hub 拉取映像檔有時會遇到困難，此時可以配置映像檔加速器。

⚠️ 注意：映像檔加速器的可用性經常變化。配置前請先訪問 docker-practice/docker-registry-cn-mirror-test 檢視各映像檔站的實時狀態。

3.9.1 推薦配置方案

針對不同的使用情境，我們推薦以下幾種映像檔加速配置方案，以確保最佳的拉取速度。

⚠️ 重要提示：國內大多數 Docker Hub 加速服務已於 2024 年中旬關閉（包括阿里雲、騰訊雲、網易雲、百度雲等）。如下推薦的映像檔源可用性因人而異，建議先測試可用性再配置。

1. 雲伺服器使用者：優先使用所在雲平臺提供的內部加速器（見本頁末尾“雲服務商”部分）
2. 本地開發使用者：優先使用自建 pull-through cache；如果必須依賴社群映像檔，請先用上面的測試倉庫確認實時可用性
3. 代理方案：如有條件，可配置 HTTP 代理直接訪問 Docker Hub

更穩妥的長期方案是使用自己控制的 pull-through cache / registry mirror，或者優先使用雲廠商提供的內網映像檔。下文統一用 https://<your-registry-mirror> 作為佔位符；如果你選擇第三方公共站，請先確認可用性、服務條款和快取策略。

3.9.2 Ubuntu 22.04+、Debian 12+、Rocky/Alma/CentOS Stream 9+

目前主流 Linux 發行版均已使用 systemd 進行服務管理，這裡介紹如何在使用 systemd 的 Linux 發行版中配置映像檔加速器。

請首先執行以下命令，檢視是否在 docker.service 檔案中配置過映像檔地址。

$ systemctl cat docker | grep '\-\-registry\-mirror'

如果該命令有輸出，那麼請執行 $ systemctl cat docker 檢視 ExecStart= 出現的位置，修改對應的檔案內容去掉 --registry-mirror 引數及其值，並按接下來的步驟進行配置。

如果以上命令沒有任何輸出，那麼就可以在 /etc/docker/daemon.json 中寫入如下內容 (如果檔案不存在請新建該檔案)：

{
  "registry-mirrors": [
    "https://<your-registry-mirror>"
  ]
}

注意，一定要保證該檔案符合 json 規範，否則 Docker 將不能啟動。

之後重新啟動服務。

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker

3.9.3 Windows 10/11

對於使用 Windows 10/11 的使用者，在工作列托盤 Docker 圖示內開啟 Settings，在左側導航選單選擇 Docker Engine，在右側像下邊一樣編輯 JSON 檔案，之後點選 Apply & Restart 儲存後 Docker 就會重啟並應用配置的映像檔地址了。

{
  "registry-mirrors": [
    "https://<your-registry-mirror>"
  ]
}

3.9.4 macOS

對於使用 macOS 的使用者，在工作列點選 Docker Desktop 應用圖示 -> Settings...，在左側導航選單選擇 Docker Engine，在右側像下邊一樣編輯 json 檔案。修改完成之後，點選 Apply & restart 按鈕，Docker 就會重啟並應用配置的映像檔地址了。

{
  "registry-mirrors": [
    "https://<your-registry-mirror>"
  ]
}

3.9.5 檢查加速器是否生效

執行 $ docker info，如果從結果中看到了如下內容，說明配置成功。

Registry Mirrors:
 https://<your-registry-mirror>/

3.9.6 Kubernetes 官方映像檔地址遷移

可以登入 阿里雲容器映像檔服務，在 映像檔中心 -> 映像檔搜尋 中查詢。

Kubernetes 社群已將官方映像檔地址從 k8s.gcr.io 遷移到 registry.k8s.io。建議優先使用新地址。

一般情況下有如下對應關係：

$ docker pull registry.k8s.io/xxx

3.9.7 已停止服務的映像檔列表

以下映像檔源已停止服務，新增無用的映像檔加速器會拖慢拉取速度，請從配置中刪除：

• https://hub.atomgit.com （已於 2024 年底關閉）
• https://registry.cn-hangzhou.aliyuncs.com （阿里雲 Docker 加速已於 2024 年關閉）
• https://dockerhub.azk8s.cn （已轉為私有）
• https://reg-mirror.qiniu.com （已停止服務）
• https://registry.docker-cn.com （已停止服務）
• https://hub-mirror.c.163.com （網易雲映像檔已於 2024 年關閉）
• https://mirror.baidubce.com （百度雲映像檔已停止）

建議 watch（頁面右上角） 映像檔測試倉庫 這個 GitHub 倉庫，我們會持續更新各映像檔源的可用狀態。

3.9.8 雲服務商

某些雲服務商提供了 僅供內部 訪問的映像檔服務，當您的 Docker 執行在雲平臺時可以選擇它們。

• 騰訊雲 https://mirror.ccs.tencentyun.com

3.10 開啟實驗特性

一些 docker 命令或功能僅當 實驗特性 開啟時才能使用，請按照以下方法進行設定。

3.10.1 Docker CLI 的實驗特性

CLI 的實驗特性通常包含仍在開發中的新功能。幸運的是，在較新版本中這些特性已經更加易用。

從 v20.10 及更高版本開始，Docker CLI 所有實驗特性的命令均預設開啟，無需再進行配置或設定系統環境變數。

3.10.2 開啟 dockerd 的實驗特性

編輯 /etc/docker/daemon.json，新增如下條目

{
  "experimental": true
}

儲存後重啟 Docker daemon：

$ sudo systemctl restart docker

然後執行下面的命令驗證伺服器端實驗特性已經生效：

$ docker version

若輸出中的 Server / Engine 部分出現 Experimental: true，說明 daemon 端實驗特性已經啟用。

本章小結

Docker 支援在多種平臺上安裝和使用，選擇合適的安裝方式是順利使用 Docker 的第一步。

平臺	推薦方式	說明
Ubuntu/Debian	官方 APT 倉庫	最完善的支援，推薦首選
CentOS/Fedora	官方 DNF/YUM 倉庫	注意驗證防火牆與 iptables 相容性
macOS	Docker Desktop	圖形化安裝，預設整合 Compose
Windows 10/11	Docker Desktop（WSL 2 或 Hyper-V）	按機器能力與企業策略選擇後端
Raspberry Pi	官方 APT 倉庫或 Debian arm64 方案	32 位系統已停止接收 v29+ 新主版本
離線環境	二進位制包安裝	適用於無法聯網的伺服器

安裝後驗證

安裝完成後，執行以下命令驗證 Docker 是否正常工作：

$ docker version
$ docker run --rm hello-world

延伸閱讀

• 映像檔加速器：解決國內拉取映像檔慢的問題
• 開啟實驗特性：使用最新功能
• Docker Hub：官方映像檔倉庫

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

4.1 獲取映像檔

從 Docker 映像檔倉庫獲取映像檔可謂是 Docker 運作的第一步。本節將介紹如何使用 docker pull 命令下載映像檔，以及如何理解下載過程。

版本號最佳實務

• 永遠指定版本號：避免使用 latest 標籤，應指定具體的版本（如 ubuntu:24.04、nginx:1.28），以確保映像檔內容穩定一致。
• 在生產環境使用摘要：優先使用映像檔摘要（SHA256）而非標籤，如 nginx@sha256:abc123...，因為摘要不可變。
• 定期評估依賴：即使指定了版本號，仍應定期檢查依賴的基礎映像檔是否有安全更新。

4.1.1 docker pull 命令

從映像檔倉庫獲取映像檔的命令是 docker pull：

docker pull [選項] [Registry地址/]倉庫名[:標籤]

映像檔名稱格式

Docker 映像檔名稱由 Registry 地址、使用者名稱、倉庫名和標籤組成。其標準格式如下：

docker.io / library / ubuntu : 24.04
────┬────   ───┬───   ──┬───   ──┬──
    │         │        │        │
Registry地址  使用者名稱    倉庫名    標籤
 (可省略)    (可省略)

組成部分	說明	預設值
Registry 地址	映像檔倉庫地址	docker.io (Docker Hub)
使用者名稱	映像檔所屬使用者/組織	library (官方映像檔)
倉庫名	映像檔名稱	必須指定
標籤	版本標識	latest

示例

## 完整格式

$ docker pull docker.io/library/ubuntu:24.04

## 省略 Registry（預設 Docker Hub）

$ docker pull library/ubuntu:24.04

## 省略 library（官方映像檔）

$ docker pull ubuntu:24.04

## 省略標籤（預設 latest）

$ docker pull ubuntu

## 拉取第三方映像檔

$ docker pull bitnami/redis:latest

## 從其他 Registry 拉取

$ docker pull ghcr.io/username/myapp:v1.0

---

4.1.2 下載過程解析

當我們執行 docker pull 命令時，Docker 會輸出詳細的下載進度。讓我們以 ubuntu:24.04 為例來解析這些資訊。

$ docker pull ubuntu:24.04
24.04: Pulling from library/ubuntu
92dc2a97ff99: Pull complete
be13a9d27eb8: Pull complete
c8299583700a: Pull complete
Digest: sha256:4bc3ae6596938cb0d9e5ac51a1152ec9dcac2a1c50829c74abd9c4361e321b26
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04

輸出解讀

輸出內容	說明
Pulling from library/ubuntu	正在從官方 ubuntu 倉庫拉取
92dc2a97ff99: Pull complete	各層的下載狀態 (顯示層 ID 前 12 位)
Digest: sha256:...	映像檔內容的唯一摘要
docker.io/library/ubuntu:24.04	映像檔的完整名稱

分層下載

從輸出可以看到，映像檔是 分層下載 的：

flowchart TD
    subgraph Image ["ubuntu:24.04 映像檔"]
        direction TB
        L3["第3層 c8299583700a<br/>(已存在，跳過下載)"]
        L2["第2層 be13a9d27eb8<br/>(下載中... 完成)"]
        L1["第1層 92dc2a97ff99<br/>(下載中... 完成)"]
        L3 --- L2 --- L1
    end

如果本地已有相同的層，Docker 會跳過下載，節省頻寬和時間。

---

4.1.3 常用選項

docker pull 命令支援多種選項來滿足不同的下載需求，例如下載所有標籤、指定平臺架構等。

選項	說明	示例
--all-tags, -a	拉取所有標籤	docker pull -a ubuntu
--platform	指定平臺架構	docker pull --platform linux/arm64 nginx
--quiet, -q	靜默模式	docker pull -q nginx

指定平臺

在 Apple Silicon Mac 上拉取 x86 映像檔：

$ docker pull --platform linux/amd64 nginx

---

4.1.4 拉取後執行

拉取映像檔後，可以基於它啟動容器：

## 拉取映像檔

$ docker pull ubuntu:24.04

## 執行容器

$ docker run -it --rm ubuntu:24.04 bash
root@e7009c6ce357:/# cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
...
root@e7009c6ce357:/# exit

本例使用 ubuntu:24.04 這樣的具體版本標籤是最佳實務。若無特殊需求，避免使用 docker pull ubuntu 或 ubuntu:latest，因為映像檔內容可能在某個時刻發生變化。

引數說明：

引數	說明
-it	互動式終端模式
--rm	退出後自動刪除容器
bash	啟動命令

💡 docker run 在需要時會自動 pull 映像檔，因此通常不需要單獨執行 docker pull。

---

4.1.5 映像檔加速

從 Docker Hub 下載可能較慢。可以配置映像檔加速器：

// /etc/docker/daemon.json (Linux)
// ~/.docker/daemon.json (Docker Desktop)
{
  "registry-mirrors": [
    "https://your-accelerator-url"
  ]
}

配置後重啟 Docker：

$ sudo systemctl restart docker  # Linux

## 或在 Docker Desktop 中重啟

詳見映像檔加速器章節。

---

4.1.6 驗證映像檔完整性

為了確保下載的映像檔沒有被篡改且內容一致，我們可以校驗映像檔的摘要 (Digest)。

檢視映像檔摘要

$ docker images --digests ubuntu
REPOSITORY   TAG     DIGEST                                                                    IMAGE ID
ubuntu       24.04   sha256:4bc3ae6596938cb0d9e5ac51a1152ec9dcac2a1c50829c74abd9c4361e321b26   ca2b0f26964c

使用摘要拉取

用摘要拉取可確保獲取完全相同的映像檔：

$ docker pull ubuntu@sha256:4bc3ae6596938cb0d9e5ac51a1152ec9dcac2a1c50829c74abd9c4361e321b26

筆者建議：生產環境使用摘要而非標籤，因為標籤可能被覆蓋，摘要則是不可變的。

---

4.1.7 常見問題

在使用 docker pull 過程中，可能會遇到下載速度慢、映像檔不存在或磁碟空間不足等問題。以下是一些常見問題的排查思路。

Q：下載速度很慢

1. 配置映像檔加速器
2. 檢查網路連線
3. 嘗試拉取更小的映像檔版本 (如 alpine 變體)

Q：提示映像檔不存在

Error: pull access denied, repository does not exist

可能原因：

• 映像檔名拼寫錯誤
• 私有映像檔未登入 (需要 docker login)
• 映像檔確實不存在

Q：磁碟空間不足

## 清理未使用的映像檔

$ docker image prune

## 清理所有未使用資源

$ docker system prune

---

4.2 列出映像檔

在下載了映像檔後，我們可以使用 docker image ls 命令列出本地主機上的映像檔。

4.2.1 基本用法

檢視本地已下載的映像檔：

$ docker image ls
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
redis        latest    5f515359c7f8   5 days ago     183MB
nginx        latest    05a60462f8ba   5 days ago     181MB
ubuntu       24.04     329ed837d508   3 days ago     78MB
ubuntu       noble     329ed837d508   3 days ago     78MB

💡 docker images 是 docker image ls 的簡寫，兩者等效。

---

4.2.2 輸出欄位說明

docker image ls 命令預設輸出的列表包含倉庫名、標籤、映像檔 ID、建立時間和佔用空間等資訊。

欄位	說明
REPOSITORY	倉庫名
TAG	標籤 (版本)
IMAGE ID	映像檔唯一標識 (短 ID，前 12 位)
CREATED	建立時間
SIZE	本地佔用空間

同一映像檔多個標籤

注意上面的 ubuntu:24.04 和 ubuntu:noble 擁有相同的 IMAGE ID——它們是同一個映像檔的不同標籤，只佔用一份儲存空間。

版本說明：ubuntu:24.04 是具體版本號，ubuntu:noble 是釋出代號（Ubuntu 24.04 的代號）。在 Dockerfile 中應優先使用版本號（如 ubuntu:24.04）而非釋出代號，因為版本號在將來更易理解。

---

4.2.3 理解映像檔大小

Docker 映像檔的大小可能與我們通常理解的檔案大小有所不同，這涉及到分層儲存的概念。

本地大小 vs Hub 顯示大小

位置	顯示大小	說明
Docker Hub	29MB	壓縮後的網路傳輸大小
docker image ls	78MB	本地解壓後的實際大小

實際磁碟佔用

由於映像檔是分層儲存，不同映像檔可能共享相同的層：

ubuntu:24.04    nginx:latest    redis:latest
    │               │                │
    └───────┬───────┘                │
            ▼                        │
       共享基礎層 ◄───────────────────┘

因此，docker image ls 中各映像檔大小之和 > 實際磁碟佔用。

檢視實際空間佔用

$ docker system df
TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images          15      3        2.5GB     1.8GB (72%)
Containers      5       2        100MB     80MB (80%)
Local Volumes   8       2        500MB     400MB (80%)
Build Cache     0       0        0B        0B

---

4.2.4 過濾映像檔

隨著本地映像檔數量的增加，我們需要更有效的方式來查詢特定的映像檔。Docker 提供了多種過濾方式。

按倉庫名過濾

## 列出所有 ubuntu 映像檔

$ docker images ubuntu
REPOSITORY   TAG     IMAGE ID       SIZE
ubuntu       24.04   329ed837d508   78MB
ubuntu       noble   329ed837d508   78MB
ubuntu       22.04   a1b2c3d4e5f6   72MB

按倉庫名和標籤過濾

$ docker images ubuntu:24.04
REPOSITORY   TAG     IMAGE ID       SIZE
ubuntu       24.04   329ed837d508   78MB

使用過濾器 --filter

過濾條件	說明	示例
dangling=true	虛懸映像檔	-f dangling=true
before=映像檔	在某映像檔之前建立	-f before=nginx:latest
since=映像檔	在某映像檔之後建立	-f since=nginx:latest
label=key=value	按 LABEL 過濾	-f label=version=1.0
reference=pattern	按名稱模式	-f reference='*:latest'

## 列出 nginx 之後建立的映像檔

$ docker images -f since=nginx:latest

## 列出所有帶 latest 標籤的映像檔

$ docker images -f reference='*:latest'

## 列出帶特定 LABEL 的映像檔

$ docker images -f [email protected]

---

4.2.5 虛懸映像檔

在映像檔列表裡，你可能會看到一些倉庫名和標籤都為 <none> 的映像檔，這類映像檔被稱為虛懸映像檔。

什麼是虛懸映像檔

倉庫名和標籤都顯示為 <none> 的映像檔：

$ docker images
REPOSITORY   TAG       IMAGE ID       SIZE
<none>       <none>    00285df0df87   342MB

產生原因

1. 映像檔重新構建：新映像檔使用了舊映像檔的標籤，舊映像檔標籤被移除
2. docker pull 更新：拉取更新版本時，舊版本失去標籤

處理虛懸映像檔

## 列出虛懸映像檔

$ docker images -f dangling=true

## 刪除虛懸映像檔

$ docker image prune

---

4.2.6 中間層映像檔

除了虛懸映像檔，docker image ls 預設列出的只是頂層映像檔。還有一種映像檔是為了加速映像檔構建、重複利用資源而存在的中間層映像檔。

檢視所有映像檔：包含中間層

$ docker images -a

會顯示很多無標籤映像檔——這些是構建過程中產生的中間層，被其他映像檔依賴。

⚠️ 不要刪除中間層映像檔。它們是其他映像檔的依賴，刪除會導致上層映像檔無法使用。刪除頂層映像檔時會自動清理不再需要的中間層。

---

4.2.7 格式化輸出

為了配合指令碼使用或展示更關注的資訊，我們可以使用 --format 引數來自定義輸出格式。

只輸出 ID

$ docker images -q
5f515359c7f8
05a60462f8ba
329ed837d508

常用於配合其他命令：

## 刪除所有映像檔

$ docker rmi $(docker images -q)

## 刪除所有 redis 映像檔

$ docker rmi $(docker images -q redis)

顯示完整 ID

$ docker images --no-trunc

顯示摘要

$ docker images --digests
REPOSITORY   TAG     DIGEST                    IMAGE ID
nginx        latest  sha256:b4f0e0bdeb5...    e43d811ce2f4

自定義格式

使用 Go 模板語法自定義輸出：

## 只顯示 ID 和倉庫名

$ docker images --format "{{.ID}}: {{.Repository}}"
5f515359c7f8: redis
05a60462f8ba: nginx
329ed837d508: ubuntu

## 表格形式（帶標題）

$ docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
REPOSITORY   TAG       SIZE
redis        latest    183MB
nginx        latest    181MB
ubuntu       24.04     78MB

可用模板欄位

欄位	說明
.ID	映像檔 ID
.Repository	倉庫名
.Tag	標籤
.Digest	摘要
.CreatedSince	建立後經過的時間
.CreatedAt	建立時間
.Size	大小

---

4.2.8 常用命令組合

## 列出所有映像檔及其大小，按大小排序（需要系統 sort 命令）

$ docker images --format "{{.Size}}\t{{.Repository}}:{{.Tag}}" | sort -h

## 查詢大於 500MB 的映像檔

$ docker images --format "{{.Size}}\t{{.Repository}}:{{.Tag}}" | grep -E "^[0-9]+GB|^[5-9][0-9]{2}MB"

## 匯出映像檔列表

$ docker images --format "{{.Repository}}:{{.Tag}}" > images.txt

---

4.3 刪除本地映像檔

當不再需要某個映像檔時，我們可以將其刪除以釋放儲存空間。本節介紹刪除映像檔的常用方法。

4.3.1 基本用法

使用 docker image rm 刪除本地映像檔：

$ docker image rm [選項] <映像檔1> [<映像檔2> ...]

💡 docker rmi 是 docker image rm 的簡寫，兩者等效。

---

4.3.2 映像檔標識方式

刪除映像檔時，可以使用多種方式指定映像檔：

方式	說明	示例
短 ID	ID 的前幾位 (通常 3-4 位)	docker rmi 501
長 ID	完整的映像檔 ID	docker rmi 501ad78535f0...
映像檔名:標籤	倉庫名和標籤	docker rmi redis:7.0
映像檔摘要	精確的內容摘要	docker rmi nginx@sha256:...

版本提示：建議使用 映像檔名:標籤 的方式刪除，特別是當需要明確清理特定版本的映像檔時。例如 docker rmi redis:7.0 比 docker rmi redis:latest 更清晰且安全。

使用短 ID 刪除

$ docker image ls
REPOSITORY   TAG     IMAGE ID       SIZE
redis        alpine  501ad78535f0   30MB
nginx        latest  e43d811ce2f4   142MB

## 只需輸入足夠區分的前幾位

$ docker rmi 501
Untagged: redis:alpine
Deleted: sha256:501ad78535f0...

使用映像檔名刪除

$ docker rmi redis:alpine
Untagged: redis:alpine
Deleted: sha256:501ad78535f0...

使用摘要刪除

摘要刪除最精確，適用於 CI/CD 情境：

## 檢視映像檔摘要

$ docker images --digests
REPOSITORY   TAG    DIGEST                   IMAGE ID
nginx        latest sha256:b4f0e0bdeb5...    e43d811ce2f4

## 使用摘要刪除

$ docker rmi nginx@sha256:b4f0e0bdeb578043c1ea6862f0d40cc4afe32a4a582f3be235a3b164422be228

---

4.3.3 理解輸出資訊

執行刪除命令後，Docker 會輸出一系列的操作記錄，理解這些資訊有助於我們掌握映像檔刪除的機制。

刪除映像檔時會看到兩類資訊：Untagged 和 Deleted

$ docker rmi redis:alpine
Untagged: redis:alpine
Untagged: redis@sha256:f1ed3708f538b537eb9c2a7dd50dc90a706f7debd7e1196c9264edeea521a86d
Deleted: sha256:501ad78535f015d88872e13fa87a828425117e3d28075d0c117932b05bf189b7
Deleted: sha256:96167737e29ca8e9d74982ef2a0dda76ed7b430da55e321c071f0dbff8c2899b
Deleted: sha256:32770d1dcf835f192cafd6b9263b7b597a1778a403a109e2cc2ee866f74adf23

Untagged vs Deleted

操作	含義
Untagged	移除映像檔的標籤
Deleted	刪除映像檔的儲存層

刪除流程

Docker 會檢測映像檔是否有容器依賴或其他標籤指向，只有在確認為無用資源時才會真正刪除儲存層。

flowchart TD
    Start(["docker rmi redis:alpine"]) --> Step1

    subgraph Process ["刪除流程"]
        direction TB
        Step1["1. Untag：移除 redis:alpine 標籤"] --> Step2

        Step2{"2. 檢查是否還有其他標籤指向此映像檔"}
        Step2 -- "有" --> Keep1["只 Untag，不刪除"]
        Step2 -- "無" --> Step3

        Step3{"3. 檢查是否有容器依賴"}
        Step3 -- "有" --> Error["報錯，無法刪除"]
        Step3 -- "無" --> Step4

        Step4{"4. 從上到下逐層刪除，檢查每層是否被其他映像檔使用"}
        Step4 -- "被使用" --> Keep2["保留該層"]
        Step4 -- "未使用" --> Delete["Deleted (刪除該層)"]
    end

---

4.3.4 批次刪除

手動一個一個刪除映像檔非常繁瑣，Docker 提供了 image prune 命令和 shell 組合命令來實現批次清理。

刪除所有虛懸映像檔

虛懸映像檔 (dangling)：沒有標籤的映像檔，通常是舊版本被新版本覆蓋後產生的

## 檢視虛懸映像檔

$ docker images -f dangling=true

## 刪除虛懸映像檔

$ docker image prune

## 不提示確認

$ docker image prune -f

刪除所有未使用的映像檔

## 刪除所有沒有被容器使用的映像檔

$ docker image prune -a

## 保留最近 24 小時的

$ docker image prune -a --filter "until=24h"

按條件刪除

## 刪除所有 redis 映像檔

$ docker rmi $(docker images -q redis)

## 刪除 mongo:8.0 之前的所有映像檔

$ docker rmi $(docker images -q -f before=mongo:8.0)

## 刪除某個時間之前的映像檔

$ docker image prune -a --filter "until=168h"  # 7天前

---

4.3.5 刪除失敗的常見原因

在刪除映像檔時，Docker 可能會提示錯誤並拒絕執行。這通常是為了防止誤刪正在使用的資源。

原因一：有容器依賴

$ docker rmi nginx
Error: conflict: unable to remove repository reference "nginx"
(must force) - container abc123 is using its referenced image

解決方案：

## 方案1：先刪除依賴的容器

$ docker rm abc123
$ docker rmi nginx

## 方案2：強制刪除映像檔（容器仍可執行，但無法再建立新容器）

$ docker rmi -f nginx

原因二：多個標籤指向同一映像檔

$ docker images
REPOSITORY   TAG     IMAGE ID
ubuntu       24.04   ca2b0f26964c
ubuntu       latest  ca2b0f26964c   # 同一個映像檔

$ docker rmi ubuntu:24.04
Untagged: ubuntu:24.04

## 只是移除標籤，映像檔仍存在（因為還有 ubuntu:latest 指向它）

當同一個映像檔有多個標籤時，docker rmi 只是刪除指定的標籤，不會刪除映像檔本身。

原因三：被其他映像檔依賴：中間層

$ docker rmi some_base_image
Error: image has dependent child images

中間層映像檔被其他映像檔依賴，無法刪除。需要先刪除依賴它的映像檔。

---

4.3.6 常用過濾條件

過濾條件	說明	示例
dangling=true	虛懸映像檔	-f dangling=true
before=映像檔	在某映像檔之前	-f before=mongo:3.2
since=映像檔	在某映像檔之後	-f since=mongo:3.2
label=key=value	按標籤過濾	-f label=version=1.0
reference=pattern	按名稱模式	-f reference='*:latest'

---

4.3.7 清理策略

針對不同的環境 (開發環境 vs 生產環境)，我們應該採用不同的映像檔清理策略。

開發環境

## 定期清理虛懸映像檔

$ docker image prune -f

## 一鍵清理所有未使用資源

$ docker system prune -a

CI/CD 環境

## 只保留最近使用的映像檔

$ docker image prune -a --filter "until=72h" -f

檢視空間佔用

$ docker system df
TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images          15      3        2.5GB     1.8GB (72%)
Containers      5       2        100MB     80MB (80%)
Local Volumes   8       2        500MB     400MB (80%)
Build Cache     0       0        0B        0B

---

4.4 利用 commit 理解映像檔構成

注意：如果你是初學者，可以暫時跳過後面的內容，直接學習容器一節。

docker commit 除了幫助理解映像檔分層之外，在少數情境下也可用於留存現場，例如事後分析被入侵容器的狀態；但是，日常定製映像檔不應依賴 docker commit，而應使用下一節介紹的 Dockerfile。

映像檔是容器的基礎，每次執行 docker run 的時候都會指定哪個映像檔作為容器執行的基礎。在之前的例子中，我們所使用的都是來自於 Docker Hub 的映像檔。直接使用這些映像檔是可以滿足一定的需求，而當這些映像檔無法直接滿足需求時，我們就需要定製這些映像檔。接下來的幾節就將講解如何定製映像檔。

回顧一下之前我們學到的知識，映像檔是多層儲存，每一層是在前一層的基礎上進行的修改；而容器同樣也是多層儲存，它以映像檔層為只讀基礎，並在最上方增加一層供執行時寫入的容器層。

現在讓我們以定製一個 Web 伺服器為例子，來講解映像檔是如何構建的。

版本提示：以下示例中 nginx 映像檔使用預設 latest 標籤。生產環境建議指定具體版本號（如 nginx:1.28），以避免映像檔更新帶來的不相容性。

$ docker run --name webserver -d -p 8080:80 nginx

這條命令會用 nginx 映像檔啟動一個容器，命名為 webserver。其中，-p 8080:80 表示把宿主機的 8080 埠對映到容器內的 80 埠，這樣我們就可以用瀏覽器去訪問這個 nginx 伺服器。

如果是在本機執行的 Docker，那麼可以直接訪問：http://localhost:8080；如果是在虛擬機器、雲伺服器上安裝的 Docker，則需要將 localhost 換為虛擬機器地址或者實際雲伺服器地址，並保留 8080 埠。

直接用瀏覽器訪問的話，我們會看到預設的 Nginx 歡迎頁面。

現在，假設我們非常不喜歡這個歡迎頁面，我們希望改成歡迎 Docker 的文字，我們可以使用 docker exec 命令進入容器，修改其內容。

$ docker exec -it webserver bash
root@3729b97e8226:/# echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html
root@3729b97e8226:/# exit
exit

我們以互動式終端方式進入 webserver 容器，並執行了 bash 命令，也就是獲得一個可操作的 Shell。

然後，我們用 <h1>Hello, Docker!</h1> 覆蓋了 /usr/share/nginx/html/index.html 的內容。

現在我們再重新整理瀏覽器的話，會發現內容被改變了。

我們修改了容器的檔案，也就是改動了容器的儲存層。我們可以透過 docker diff 命令看到具體的改動。

$ docker diff webserver
C /root
A /root/.bash_history
C /run
C /usr
C /usr/share
C /usr/share/nginx
C /usr/share/nginx/html
C /usr/share/nginx/html/index.html
C /var
C /var/cache
C /var/cache/nginx
A /var/cache/nginx/client_temp
A /var/cache/nginx/fastcgi_temp
A /var/cache/nginx/proxy_temp
A /var/cache/nginx/scgi_temp
A /var/cache/nginx/uwsgi_temp

其中，A 表示新增（Added），C 表示變更（Changed），D 表示刪除（Deleted）。

現在我們定製好了變化，我們希望能將其儲存下來形成映像檔。

要知道，當我們執行一個容器的時候 (如果不使用卷的話)，我們做的任何檔案修改都會被記錄於容器儲存層裡。而 Docker 提供了一個 docker commit 命令，可以將容器的儲存層儲存下來成為映像檔。換句話說，就是在原有映像檔的基礎上，再疊加上容器的儲存層，並構成新的映像檔。以後我們執行這個新映像檔的時候，就會擁有原有容器最後的檔案變化。

docker commit 的語法格式為：

docker commit [選項] <容器ID或容器名> [<倉庫名>[:<標籤>]]

我們可以用下面的命令將容器儲存為映像檔。預設情況下，docker commit 會在提交時暫停容器程序，以降低資料損壞的風險；如果確實不希望暫停，可以顯式指定 --no-pause：

$ docker commit \
    --author "Tao Wang <[email protected]>" \
    --message "修改了預設網頁" \
    webserver \
    nginx:v2
sha256:07e33465974800ce65751acc279adc6ed2dc5ed4e0838f8b86f0c87aa1795214

其中 --author 是指定修改的作者，而 --message 則是記錄本次修改的內容。這點和 git 版本控制相似，不過這裡這些資訊可以省略留空。

我們可以在 docker image ls 中看到這個新定製的映像檔。下面的輸出僅為示例，標籤、建立時間和大小會隨著映像檔版本和本地環境不同而變化：

$ docker image ls nginx
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
nginx               v2                  07e334659748        9 seconds ago       181.5 MB
nginx               1.30                05a60462f8ba        12 days ago         181.5 MB
nginx               latest              e43d811ce2f4        4 weeks ago         181.5 MB

版本說明：上面示例中 nginx:1.30 代表 1.30 系列的最新 patch 版本。在實際應用中應根據需求選擇確切的版本號，而不是盲目使用 latest。

我們還可以用 docker history 具體檢視映像檔內的歷史記錄。例如先執行 docker history nginx:v2，再對比 docker history nginx:latest，就能看到我們剛剛提交出來的新層。

$ docker history nginx:v2
IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
07e334659748        54 seconds ago      nginx -g daemon off;                            95 B                修改了預設網頁
e43d811ce2f4        4 weeks ago         /bin/sh -c #(nop)  CMD ["nginx" "-g" "daemon    0 B
<missing>           4 weeks ago         /bin/sh -c #(nop)  EXPOSE 443/tcp 80/tcp        0 B
<missing>           4 weeks ago         /bin/sh -c ln -sf /dev/stdout /var/log/nginx/   22 B
<missing>           4 weeks ago         /bin/sh -c apt-key adv --keyserver hkp://pgp.   58.46 MB
<missing>           4 weeks ago         /bin/sh -c #(nop)  ENV NGINX_VERSION=1.27.0-1   0 B
<missing>           4 weeks ago         /bin/sh -c #(nop)  MAINTAINER NGINX Docker Ma   0 B
<missing>           4 weeks ago         /bin/sh -c #(nop)  CMD ["/bin/bash"]            0 B
<missing>           4 weeks ago         /bin/sh -c #(nop) ADD file:23aa4f893e3288698c   123 MB

新的映像檔定製好後，我們可以來執行這個映像檔。

$ docker run --name web2 -d -p 81:80 nginx:v2

這裡我們將新容器命名為 web2，並把宿主機的 81 埠對映到容器的 80 埠。訪問 http://localhost:81 後，看到的內容應該和之前修改後的 webserver 一樣。

至此，我們第一次完成了定製映像檔，使用的是 docker commit 命令，手動操作給舊的映像檔新增了新的一層，形成新的映像檔，對映像檔多層儲存應該有了更直觀的感覺。

4.4.1 慎用 docker commit

使用 docker commit 命令雖然可以比較直觀地幫助理解映像檔分層儲存的概念，但它不應作為常規定製映像檔的方式。

首先，如果仔細觀察之前的 docker diff webserver 的結果，你會發現除了真正想要修改的 /usr/share/nginx/html/index.html 檔案外，由於命令的執行，還有很多檔案被改動或新增了。這還僅僅是最簡單的操作，如果是安裝軟體包、編譯構建，那會有大量的無關內容被新增進來，將會導致映像檔極為臃腫。

此外，使用 docker commit 意味著所有對映像檔的操作都是黑箱操作，生成的映像檔也被稱為 黑箱映像檔，換句話說，就是除了製作映像檔的人知道執行過什麼命令、怎麼生成的映像檔，別人根本無從得知。而且，即使是這個製作映像檔的人，過一段時間後也無法記清具體的操作。這種黑箱映像檔的維護工作是非常痛苦的。

而且，回顧之前提及的映像檔所使用的分層儲存的概念，除當前層外，之前的每一層都不會發生改變。換句話說，任何修改的結果僅僅是在當前層進行標記、新增、修改，而不會改動上一層。如果使用 docker commit 製作映像檔，以及後期繼續修改，那麼每一次修改都會讓映像檔再膨脹一層；即使某些檔案在更高層裡被刪除了，它們仍然存在於更低層中，只是在最終檢視裡被隱藏而已。因此，日常定製映像檔應使用下一節介紹的 Dockerfile，把構建過程寫成可重複執行、便於審查的文字。

4.5 使用 Dockerfile 定製映像檔

從剛才的 docker commit 的學習中，我們可以瞭解到，映像檔的定製實際上就是定製每一層所新增的配置、檔案。如果我們可以把每一層修改、安裝、構建、操作的命令都寫入一個指令碼，用這個指令碼來構建、定製映像檔，那麼之前提及的無法重複、映像檔構建不透明、體積難以控制等問題就會更容易解決。這個指令碼就是 Dockerfile。

Dockerfile 是一個文字檔案，其內包含了一條條的 指令 (Instruction)。其中，會修改檔案系統的指令通常會建立新層；而 LABEL、CMD 這類只修改映像檔後設資料的指令，則不會新增檔案系統層。每一條指令的內容，都是在描述該映像檔應當如何構建。

4.5.1 使用 docker init 快速建立：推薦

Docker 提供了 docker init 命令，可以根據專案型別自動生成 Dockerfile、.dockerignore、compose.yaml 和 README.Docker.md 等檔案：

$ docker init

該命令會互動式地詢問專案型別（支援 Go、Node.js、Python、Rust、Java、ASP.NET Core、PHP with Apache 等），並生成可作為起點的配置檔案。對於新專案，這是一個很好的起步方式，但生成後的內容仍應結合專案實際情況繼續調整。

4.5.2 手動建立 Dockerfile

還以之前定製 nginx 映像檔為例，這次我們使用 Dockerfile 來定製。

在一個空白目錄中，建立一個文字檔案，並命名為 Dockerfile：

$ mkdir mynginx
$ cd mynginx
$ touch Dockerfile

其內容為：

版本提示：下面示例中 FROM nginx 使用的是 latest 標籤。在實際應用中應使用明確的版本號（如 FROM nginx:1.28），以確保 Dockerfile 的可重現性和穩定性。

FROM nginx
RUN echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html

這個 Dockerfile 很簡單，一共就兩行。涉及到了兩條指令，FROM 和 RUN。

4.5.3 FROM 指定基礎映像檔

所謂定製映像檔，那一定是以一個映像檔為基礎，在其上進行定製。就像我們之前執行了一個 nginx 映像檔的容器，再進行修改一樣，基礎映像檔是必須指定的。而 FROM 就是指定 基礎映像檔，因此一個 Dockerfile 中 FROM 是必備的指令，並且必須是第一條指令。

版本號最佳實務：在 FROM 指令中 務必指定具體版本號（如 FROM ubuntu:24.04 或 FROM python:3.12-slim）而非 FROM ubuntu 或 FROM python:latest。這樣可以確保 Dockerfile 在不同時間、不同環境下構建出的映像檔內容一致，避免因基礎映像檔更新導致的不可預期的變化。

在 Docker Hub 上有非常多的高質量的官方映像檔，有可以直接拿來使用的服務類的映像檔，如 nginx、redis、mongo、mysql、httpd、php、tomcat 等；也有一些方便開發、構建、執行各種語言應用的映像檔，如 node、openjdk、python、ruby、golang 等。可以在其中尋找一個最符合我們最終目標的映像檔為基礎映像檔進行定製。

如果沒有找到對應服務的映像檔，官方映像檔中還提供了一些更為基礎的作業系統映像檔，如 ubuntu、debian、centos、fedora、alpine 等，這些作業系統的軟體庫為我們提供了更廣闊的擴充套件空間。

除了選擇現有映像檔為基礎映像檔外，Docker 還存在一個特殊的映像檔，名為 scratch。這個映像檔是虛擬的概念，並不實際存在，它表示一個空白的映像檔。

FROM scratch
...

如果你以 scratch 為基礎映像檔的話，意味著你不以任何映像檔為基礎，接下來所寫的指令將作為映像檔第一層開始存在。

不以任何系統為基礎，直接將可執行檔案複製進映像檔的做法並不罕見，對於 Linux 下靜態編譯的程式來說，並不需要有作業系統提供執行時支援，所需的一切庫都已經在可執行檔案裡了，因此直接 FROM scratch 會讓映像檔體積更加小巧。使用 Go 語言開發的應用很多會使用這種方式來製作映像檔，這也是有人認為 Go 是特別適合容器微服務架構的語言的原因之一。

4.5.4 RUN 執行命令

RUN 指令是用來執行命令列命令的。由於命令列的強大能力，RUN 指令在定製映像檔時是最常用的指令之一。其格式有兩種：

• shell 格式：RUN <命令>，就像直接在命令列中輸入的命令一樣。剛才寫的 Dockerfile 中的 RUN 指令就是這種格式。

RUN echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html

• exec 格式：RUN ["可執行檔案", "引數1", "引數2"]，這更像是函式呼叫中的格式。

在會修改檔案系統的指令裡，RUN 是最典型的一類。每一個 RUN 的行為，都可以類比為我們剛才手工建立映像檔的過程：先基於當前結果啟動一個臨時構建環境，在其上執行這些命令，再把這一步產生的檔案系統變化儲存為新的結果層。

注意

每一個 RUN 指令都會產生一個新的映像檔層。為了減少映像檔體積和層數，我們通常會將多個命令合併到一個 RUN 指令中執行。

更多關於 RUN 指令的詳細用法、最佳實務 (如清理快取、使用 pipefail 等) 及 Union FS 的層數限制等內容，請參閱 第七章 Dockerfile 指令詳解 中的 RUN 指令 小節。

要想編寫優秀的 Dockerfile，必須瞭解每一條指令的作用和副作用。在 第七章 Dockerfile 指令詳解 中，我們將對 COPY，ADD，CMD，ENTRYPOINT 等指令進行詳細講解。

4.5.5 構建映像檔

好了，讓我們再回到之前定製的 nginx 映像檔的 Dockerfile 來。現在我們明白了這個 Dockerfile 的內容，那麼讓我們來構建這個映像檔吧。

在 Dockerfile 檔案所在目錄執行：

$ docker build -t nginx:v3 .

在當前版本的 Docker 中，docker build 預設會透過 Buildx 呼叫 BuildKit，因此你更常看到的是 [+] Building ... 這類輸出。為了幫助理解“每一步如何形成映像檔歷史”，下面仍展示一種較容易閱讀的經典輸出形式：

Sending build context to Docker daemon 2.048 kB
Step 1 : FROM nginx
 ---> e43d811ce2f4
Step 2 : RUN echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html
 ---> Running in 9cdc27646c7b
 ---> 44aa4490ce2c
Removing intermediate container 9cdc27646c7b
Successfully built 44aa4490ce2c

從命令的輸出結果中，我們可以清晰的看到映像檔的構建過程。在 Step 2 中，如同我們之前所說的那樣，RUN 指令啟動了一個容器 9cdc27646c7b，執行了所要求的命令，並最後提交了這一層 44aa4490ce2c，隨後刪除了所用到的這個容器 9cdc27646c7b。

這裡我們使用了 docker build 命令進行映像檔構建。其格式為：

docker build [選項] <上下文路徑/URL/->

在這裡我們指定了最終映像檔的名稱 -t nginx:v3，構建成功後，我們可以像之前執行 nginx:v2 那樣來執行這個映像檔，其結果會和 nginx:v2 一樣。

4.5.6 映像檔構建上下文

如果注意，會看到 docker build 命令最後有一個 .。. 表示當前目錄，而 Dockerfile 就在當前目錄，因此不少初學者以為這個路徑是在指定 Dockerfile 所在路徑，這麼理解其實是不準確的。如果對應上面的命令格式，你可能會發現，這是在指定 上下文路徑。那麼什麼是上下文呢？

首先要理解 docker build 的工作原理。今天的 docker build 預設會透過 Buildx 向 BuildKit 後端發起構建請求；無論後端執行在本機還是遠端，位置引數指定的都是 構建上下文，也就是構建器可以訪問到的檔案集合。

當我們進行映像檔構建的時候，並非所有定製都會透過 RUN 指令完成，經常還需要把本地檔案複製進映像檔，比如透過 COPY 指令、ADD 指令等。因此，構建器必須能夠訪問這些檔案，而它能訪問的範圍正是你傳給 docker build 的那個上下文。

如果上下文是本地目錄，那麼這個目錄中的檔案和子目錄就會成為可用輸入；如果上下文是遠端 Git 倉庫或 tar 包，那麼構建器會直接獲取對應內容。對於本地目錄，BuildKit 會按需讀取構建過程中真正需要的檔案，而不是讓 Dockerfile 任意訪問宿主機上的任意路徑。

如果在 Dockerfile 中這麼寫：

COPY ./package.json /app/

這並不是要複製執行 docker build 命令所在的目錄下的 package.json，也不是複製 Dockerfile 所在目錄下的 package.json，而是複製 上下文 (context) 目錄下的 package.json。

因此，COPY 這類指令中的原始檔路徑都應該以構建上下文為基準來理解。對於 legacy builder，像 COPY ../package.json /app 這樣的寫法會直接報錯；而在 BuildKit 下，前導的越界 ../ 會被剝離並重新解釋為上下文內路徑。無論是哪種情況，構建器都無法讀取上下文之外的宿主機檔案；如果真的需要那些檔案，應該先把它們放進上下文目錄，或重新選擇合適的上下文。

現在就可以理解剛才的命令 docker build -t nginx:v3 . 中的這個 .，實際上是在指定上下文目錄，而不是單純指定 Dockerfile 所在目錄。

如果觀察 docker build 的經典輸出，或 BuildKit 輸出中的 transferring context 提示，我們其實都能看到上下文傳輸的過程：

$ docker build -t nginx:v3 .
Sending build context to Docker daemon 2.048 kB
...

理解構建上下文對於映像檔構建是很重要的，避免犯一些不應該的錯誤。比如有些初學者在發現需要的檔案不在上下文裡後，乾脆把上下文切到硬碟根目錄去構建。這樣做即使在 BuildKit 下也會讓可見上下文變得過大，並且在使用 COPY . .、ADD . /app 之類寫法時，仍可能觸發大規模上下文傳輸，導致構建緩慢甚至失敗。這顯然是使用錯誤。

一般來說，應該會將 Dockerfile 置於一個空目錄下，或者專案根目錄下。如果該目錄下沒有所需檔案，那麼應該把所需檔案複製一份過來。如果目錄下有些東西確實不希望構建時傳給 Docker 引擎，那麼可以用 .gitignore 一樣的語法寫一個 .dockerignore，該檔案是用於剔除不需要作為上下文傳遞給 Docker 引擎的。

那麼為什麼會有人誤以為 . 是指定 Dockerfile 所在目錄呢？這是因為在預設情況下，如果不額外指定 Dockerfile 的話，會將上下文目錄下的名為 Dockerfile 的檔案作為 Dockerfile。

這只是預設行為，實際上 Dockerfile 的檔名並不要求必須為 Dockerfile，而且並不要求必須位於上下文目錄中，比如可以用 -f ../Dockerfile.php 引數指定某個檔案作為 Dockerfile。

當然，一般大家習慣性的會使用預設的檔名 Dockerfile，以及會將其置於映像檔構建上下文目錄中。

4.5.7 其它 docker build 的用法

直接用 Git repo 進行構建

或許你已經注意到了，docker build 還支援從 URL 構建，也就是直接把遠端 Git 倉庫作為上下文。傳統寫法可以使用 URL 片段 #ref:dir，例如：

$ docker build https://github.com/user/myrepo.git#mybranch:docker

這行命令表示：把 Git 倉庫作為構建上下文，使用 mybranch 分支中的 docker/ 子目錄來構建。在較新的 Buildx 中，也可以改用結構更清晰的查詢引數寫法，例如 ?branch=mybranch&subdir=docker。

用給定的 tar 壓縮包構建

$ docker build http://server/context.tar.gz

如果所給出的 URL 不是個 Git repo，而是個 tar 壓縮包，那麼 Docker 引擎會下載這個包，並自動解壓縮，以其作為上下文，開始構建。

從標準輸入中讀取 Dockerfile 進行構建

docker build - < Dockerfile

或

cat Dockerfile | docker build -

如果標準輸入傳入的是文字檔案，則將其視為 Dockerfile，並開始構建。這種形式由於直接從標準輸入中讀取 Dockerfile 的內容，它沒有上下文，因此不可以像其他方法那樣可以將本地檔案 COPY 進映像檔之類的事情。

從標準輸入中讀取上下文壓縮包進行構建

$ docker build - < context.tar.gz

如果發現標準輸入的檔案格式是 gzip、bzip2 以及 xz 的話，將會使其為上下文壓縮包，直接將其展開，將裡面視為上下文，並開始構建。

4.6 其它製作映像檔的方式

除了標準的使用 Dockerfile 生成映像檔的方法外，由於各種特殊需求和歷史原因，還提供了一些其它方法用以生成映像檔。

4.6.1 從 rootfs 壓縮包匯入

格式：docker import [選項] <檔案>|<URL>|- [<倉庫名>[:<標籤>]]

壓縮包可以是本地檔案、遠端 Web 檔案，甚至是從標準輸入中得到。壓縮包將會在映像檔 / 目錄展開，並直接作為映像檔第一層提交。

比如我們想要建立一個 OpenVZ 的 Ubuntu 16.04 模板的映像檔：

版本提示：noble 對應 Ubuntu 24.04 LTS。實際用於生產環境時，應選擇仍在安全維護期內的發行版，並按團隊的基礎映像檔更新策略定期重建。

$ docker import \
    http://download.openvz.org/template/precreated/ubuntu-16.04-x86_64.tar.gz \
    openvz/ubuntu:16.04

Downloading from http://download.openvz.org/template/precreated/ubuntu-16.04-x86_64.tar.gz
sha256:412b8fc3e3f786dca0197834a698932b9c51b69bd8cf49e100c35d38c9879213

這條命令自動下載了 ubuntu-16.04-x86_64.tar.gz 檔案，並且作為根檔案系統展開匯入，並儲存為映像檔 openvz/ubuntu:16.04。

匯入成功後，我們可以用 docker image ls 看到這個匯入的映像檔：

$ docker image ls openvz/ubuntu
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
openvz/ubuntu       16.04               412b8fc3e3f7        55 seconds ago      505MB

如果我們檢視其歷史的話，會看到描述中有匯入的檔案連結：

$ docker history openvz/ubuntu:16.04
IMAGE               CREATED              CREATED BY          SIZE                COMMENT
f477a6e18e98        About a minute ago                       214.9 MB            Imported from http://download.openvz.org/template/precreated/ubuntu-16.04-x86_64.tar.gz

4.6.2 Docker 映像檔的匯入和匯出 docker save 和 docker load

Docker 還提供了 docker save 和 docker load 命令，用以將映像檔儲存為一個檔案，然後傳輸到另一個位置上，再載入進來。這是在沒有 Docker Registry 時的做法，現在已經不推薦，映像檔遷移應該直接使用 Docker Registry，無論是直接使用 Docker Hub 還是使用內網私有 Registry 都可以。

儲存映像檔

使用 docker save 命令可以將映像檔儲存為歸檔檔案。

比如我們希望儲存這個 alpine 映像檔。

$ docker image ls alpine
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
alpine              latest              baa5d63471ea        5 weeks ago         4.803 MB

版本提示：alpine:latest 為最新版本的 Alpine Linux。如果需要特定版本號（如 alpine:3.20），可以明確指定以確保可重現性。 儲存映像檔的命令為：

$ docker save alpine -o filename
$ file filename
filename: POSIX tar archive

這裡的 filename 可以為任意名稱甚至任意字尾名，但檔案的本質都是歸檔檔案

注意：如果同名則會覆蓋 (沒有警告)

若使用 gzip 壓縮：

$ docker save alpine | gzip > alpine-latest.tar.gz

然後我們將 alpine-latest.tar.gz 檔案複製到了到了另一個機器上，可以用下面這個命令載入映像檔：

$ docker load -i alpine-latest.tar.gz
Loaded image: alpine:latest

如果我們結合這兩個命令以及 ssh 甚至 pv 的話，利用 Linux 強大的管道，我們可以寫一個命令完成從一個機器將映像檔遷移到另一個機器，並且帶進度條的功能：

docker save <映像檔名> | bzip2 | pv | ssh <使用者名稱>@<主機名> 'cat | docker load'

4.7 實現原理

Docker 映像檔是怎麼實現增量的修改和維護的？為什麼容器啟動如此之快？這一切都歸功於 Docker 的映像檔分層儲存設計。

4.7.1 映像檔與分層儲存

在之前的章節中，我們一直強調映像檔包含作業系統完整的 root 檔案系統，其體積往往是龐大的。因此在 Docker 設計時，就充分利用 Union FS 的技術，將其設計為分層儲存的架構。

Docker 映像檔並不是一個單純的檔案，而是由一組檔案系統疊加構成的。

最底層的映像檔稱為 基礎映像檔 (Base Image)，通常是各種 Linux 發行版的 root 檔案系統，如 Ubuntu、Debian、CentOS 等。

當我們在基礎映像檔之上構建新的映像檔時 (例如安裝了 Nginx)，Docker 並不是複製一份基礎映像檔，而是在基礎映像檔之上，新建一個層 (Layer)，並在該層中僅記錄為了安裝 Nginx 而發生的檔案變更 (新增、修改、刪除)。

這種分層儲存結構使得映像檔的複用、分發變得非常高效：

• 複用：如果多個映像檔都基於同一個基礎映像檔 (例如都基於 ubuntu:24.04)，那麼宿主機只需要下載一份 ubuntu:24.04，所有映像檔都可以共享它。
• 輕量分發：映像檔可以複用已有層，只傳輸和儲存新增差異層；不過映像檔是否足夠小，仍然取決於基礎映像檔和新增內容本身。

4.7.2 容器層與讀寫

我們要理解的一個關鍵概念是：映像檔的每一層都是隻讀的 (Read-only)。

那麼，既然映像檔只讀，容器為什麼能寫檔案呢？

當容器啟動時，Docker 會在映像檔的最上層，新增一個新的 可寫層 (Writable Layer)，通常被稱為 容器層。

flowchart TD
    subgraph Container ["執行中的容器"]
        direction TB
        L4["容器層 (可寫, Writable Container Layer)"]
        L3["映像檔層 (只讀, Read-only Image Layer)"]
        L2["映像檔層 (只讀, Read-only Image Layer)"]
        L1["基礎映像檔層 (只讀, Base Image Layer)"]

        L4 --- L3 --- L2 --- L1
    end
    Note["所有的寫操作都在容器層這裡"] -.-> L4

• 讀取檔案：當容器需要讀取檔案時，Docker 會從最上層 (容器層) 開始向下層 (映像檔層) 尋找，直到找到該檔案為止。
• 修改檔案：當容器需要修改某個檔案時，Docker 會從下層映像檔中將該檔案複製到上層的容器層，然後對副本進行修改。這被稱為 寫時複製 (Copy-on-Write，CoW) 策略。
• 刪除檔案：當容器刪除某個檔案時，Docker 並不是真的去下層刪除它 (因為下層是隻讀的)，而是在容器層建立一個特殊的 “白障 (Whiteout)” 檔案，用來標記該檔案已被刪除，從而在容器檢視中隱藏它。

這就是為什麼：

1. 容器刪除後資料會丟失：因為所有的資料修改都儲存在最上層的容器層中，容器銷燬時，這個層也就隨之銷燬了。(除非使用了資料卷，詳見資料管理)。
2. 映像檔不可變：無論我們在容器裡刪除了多少檔案，基礎映像檔的體積並不會減小，因為它們依然存在於底層的只讀層中。

4.7.3 內容定址與映像檔 ID

Docker 映像檔的每一層都有一個唯一的 ID，這個 ID 是根據該層的內容計算出來的雜湊值 (SHA256)。這意味著：

• 內容即 ID：只要層的內容有一丁點變化，ID 就會變。
• 安全性：確保了映像檔內容的完整性，下載過程中如果資料損壞，ID 校驗就會失敗。
• 去重：如果兩個不同的映像檔 (甚至是不同來源的映像檔) 包含相同的層 (ID 相同)，Docker 引擎在本地只會儲存一份，絕不重複下載。

4.7.4 聯合檔案系統

Docker 使用聯合檔案系統 (Union FS) 與寫時複製思路來實現這種分層掛載。傳統的實現方式常見於 overlay2、aufs、btrfs、zfs 等儲存驅動；而在 Docker Engine 29.0 及之後的全新安裝中，預設映像檔後端已經變為 containerd image store，它使用 snapshotter 來管理這些層。

版本背景：Docker Engine 29.0.0 釋出於 2025 年 11 月 10 日，是一個重要版本分界點。Docker Engine 29.0 及之後的全新安裝預設使用 containerd image store；從更早版本升級的 daemon 會繼續使用 legacy graph driver，直到顯式啟用 containerd image store。Docker Desktop 4.34 及之後也預設啟用 containerd image store，實際環境仍應以當前配置為準。

雖然底層實現細節不同，但它們都遵循上述的 分層 + CoW 模型；因此，無論你看到的是 overlay2 還是 containerd snapshotter，理解映像檔層、容器層和寫時複製的方式都是一樣重要的。

想要深入瞭解 Overlay2 等檔案系統的具體實現原理，包括 WorkDir、UpperDir、LowerDir 等底層細節，請閱讀 第十二章 底層實現 中的 聯合檔案系統 章節。

本章小結

本章介紹了 Docker 映像檔的獲取、列出、刪除以及構建方式。

操作	命令
拉取映像檔	docker pull 映像檔名:標籤
拉取所有標籤	docker pull -a 映像檔名
指定平臺	docker pull --platform linux/amd64 映像檔名
用摘要拉取	docker pull 映像檔名@sha256:...
列出所有映像檔	docker images
按倉庫名過濾	docker images nginx
列出虛懸映像檔	docker images -f dangling=true
只輸出 ID	docker images -q
顯示摘要	docker images --digests
自定義格式	docker images --format "..."
檢視空間佔用	docker system df
刪除指定映像檔	docker rmi 映像檔名:標籤
強制刪除	docker rmi -f 映像檔名
刪除虛懸映像檔	docker image prune
刪除未使用映像檔	docker image prune -a
批次刪除	docker rmi $(docker images -q -f ...)

延伸閱讀

• 獲取映像檔：從 Registry 拉取映像檔
• 列出映像檔：檢視和過濾映像檔
• 刪除映像檔：清理本地映像檔
• 映像檔加速器：加速映像檔下載
• Docker Hub：官方映像檔倉庫
• 映像檔：理解映像檔概念
• 刪除容器：清理容器
• 資料卷：清理資料卷

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

5.1 啟動

本節將詳細介紹 Docker 容器的啟動方式，包括新建啟動和重新啟動已停止的容器。

5.1.1 啟動方式概述

啟動容器有兩種方式：

• 新建並啟動：基於映像檔建立新容器
• 重新啟動：將已終止的容器重新執行

由於 Docker 容器非常輕量，實際使用中常常是隨時刪除和新建容器，而不是反覆重啟同一個容器。

5.1.2 新建並啟動

基本語法

docker run [選項] 映像檔 [命令] [引數...]

最簡單的例子

輸出 “Hello World” 後容器自動終止：

$ docker run ubuntu:24.04 /bin/echo 'Hello world'
Hello world

這與直接執行 /bin/echo 'Hello world' 幾乎沒有區別，但實際上已經啟動了一個完整的 Ubuntu 容器來執行這條命令。

版本說明：示例使用 ubuntu:24.04，這是最新 LTS 版本。如需其他版本，可替換為 ubuntu:22.04、ubuntu:20.04 等。

互動式容器

啟動一個可以互動的 bash 終端：

$ docker run -it ubuntu:24.04 /bin/bash
root@af8bae53bdd3:/#

引數說明：

引數	作用
-i	保持標準輸入 (stdin) 開啟，允許輸入
-t	分配偽終端 (pseudo-TTY)，提供終端介面
-it	兩者組合使用，獲得互動式終端

在互動模式下可以執行命令：

root@af8bae53bdd3:/# pwd
/
root@af8bae53bdd3:/# ls
bin boot dev etc home lib lib64 media mnt opt proc root run sbin srv sys tmp usr var
root@af8bae53bdd3:/# exit  # 退出容器

5.1.3 docker run 的完整流程

執行 docker run 時，Docker 在後臺完成以下操作：

flowchart TD
    Cmd["docker run ubuntu:24.04 /bin/echo 'Hello'"] --> Step1

    Step1{"1. 檢查本地是否有 ubuntu:24.04 映像檔"}
    Step1 -- 有 --> Step1_Yes["使用本地映像檔"]
    Step1 -- 無 --> Step1_No["從 Registry 下載"]

    Step1_Yes --> Step2
    Step1_No --> Step2

    Step2["2. 建立容器<br/>• 基於映像檔的只讀層<br/>• 新增一層可讀寫層（容器儲存層）"] --> Step3
    Step3["3. 配置網路<br/>• 建立虛擬網絡卡<br/>• 分配 IP 地址<br/>• 連線到 Docker 網橋"] --> Step4
    Step4["4. 啟動容器，執行指定命令"] --> Step5
    Step5["5. 命令執行完畢，容器停止"]

5.1.4 常用啟動選項

基礎選項

選項	說明	示例
-d	後臺執行 (detach)	docker run -d nginx:latest
-it	互動式終端	docker run -it ubuntu:24.04 bash
--name	指定容器名稱	docker run --name myapp nginx:latest
--rm	退出後自動刪除容器	docker run --rm ubuntu:24.04 echo hi

埠對映

## 將容器的 80 埠對映到宿主機的 8080 埠

$ docker run -d -p 8080:80 nginx:latest

## 隨機對映埠

$ docker run -d -P nginx:latest

## 只繫結到 localhost

$ docker run -d -p 127.0.0.1:8080:80 nginx:latest

資料卷掛載

## 掛載命名卷

$ docker run -v mydata:/data nginx:latest

## 掛載宿主機目錄

$ docker run -v /host/path:/container/path nginx:latest

## 只讀掛載

$ docker run -v /host/path:/container/path:ro nginx:latest

環境變數

## 設定單個環境變數

$ docker run -e MYSQL_ROOT_PASSWORD=secret mysql

## 從檔案載入環境變數

$ docker run --env-file .env myapp

資源限制

## 限制記憶體

$ docker run -m 512m nginx:latest

## 限制 CPU

$ docker run --cpus=1.5 nginx:latest

5.1.5 啟動已終止容器

使用 docker start 重新啟動已停止的容器：

## 檢視所有容器（包括已停止的）

$ docker ps -a
CONTAINER ID  IMAGE   STATUS                     NAMES
af8bae53bdd3  ubuntu  Exited (0) 2 minutes ago   myubuntu

## 重新啟動

$ docker start myubuntu

## 啟動並附加終端

$ docker start -ai myubuntu

5.1.6 容器內程序的特點

容器內只執行指定的應用程式及其必需資源：

root@ba267838cc1b:/# ps
  PID TTY          TIME CMD
    1 ?        00:00:00 bash
   11 ?        00:00:00 ps

可見容器中僅執行了 bash 程序。這種特點使得 Docker 對資源的利用率極高。

💡 筆者提示：容器內的 PID 1 程序很重要——它是容器的主程序，該程序退出則容器停止。詳見後臺執行章節。

5.1.7 常見問題

Q：容器啟動後立即退出

原因：主程序執行完畢或無法保持執行

## 這個容器會立即退出（echo 執行完就結束了）

$ docker run ubuntu:24.04 echo "hello"

## 解決：使用能持續執行的命令

$ docker run -d nginx:latest  # nginx 是持續執行的服務

詳細解釋見後臺執行。

Q：無法連線容器內的服務

原因：未正確對映埠

## 錯誤：沒有 -p 引數，外部無法訪問

$ docker run -d nginx:latest

## 正確：對映埠

$ docker run -d -p 80:80 nginx:latest

Q：容器內修改的檔案丟失

原因：未使用資料卷，資料儲存在容器儲存層

## 使用資料卷持久化

$ docker run -v mydata:/app/data myapp

詳見資料管理。

5.2 守護態執行

在生產環境中，我們通常需要容器持續執行，不受終端關閉的影響。本節將深入講解如何讓容器在後臺執行，以及理解容器生命週期的核心概念。

5.2.1 核心概念：前臺 vs 後臺

當你在終端執行一個程式時，有兩種模式：

• 前臺執行：程式佔用當前終端，輸出直接顯示，關閉終端程式就停止
• 後臺執行：程式在後臺執行，不佔用終端，終端關閉也不影響程式

Docker 容器預設是 前臺執行 的。使用 -d (detach) 引數可以讓容器在後臺執行。

5.2.2 基本使用

前臺執行：預設

$ docker run ubuntu:24.04 /bin/sh -c "while true; do echo hello world; sleep 1; done"
hello world
hello world
hello world
hello world

容器會把輸出的結果 (STDOUT) 列印到宿主機上面。此時：

• 終端被佔用，無法執行其他命令
• 按 Ctrl+C 會終止容器
• 關閉終端視窗，容器也會停止

後臺執行：使用 -d 引數

$ docker run -d ubuntu:24.04 /bin/sh -c "while true; do echo hello world; sleep 1; done"
77b2dc01fe0f3f1265df143181e7b9af5e05279a884f4776ee75350ea9d8017a

使用 -d 引數後：

• 容器在後臺執行
• 返回容器的完整 ID
• 終端立即釋放，可以繼續執行其他命令
• 輸出不會直接顯示 (需要用 docker logs 檢視)

5.2.3 深入理解：容器為什麼會 “立即退出”？

這是初學者最常遇到的困惑。 理解這個問題，你就理解了 Docker 的核心設計理念。

很多人嘗試這樣啟動容器：

$ docker run -d ubuntu:24.04

然後用 docker ps 檢視，發現容器根本不在執行！這是為什麼？

核心原理：容器的生命週期與主程序繫結

flowchart TD
    subgraph Lifecycle ["Docker 容器的生命週期 = 容器內 PID 1 程序的生命週期"]
        direction LR
        Start["主程序啟動"] --> Run["容器執行"]
        Exit["主程序退出"] --> Stop["容器停止"]
    end

當你執行 docker run -d ubuntu:24.04 時：

1. 容器啟動
2. 沒有指定命令，預設執行 /bin/bash
3. 但沒有互動式終端 (沒有 -it 引數)，bash 發現沒有輸入源
4. bash 立即退出
5. 主程序退出，容器停止

關鍵理解：

• ❌ -d 引數 不是 讓容器 “一直執行”
• ✅ -d 引數是讓容器 “在後臺執行”，能執行多久取決於主程序

常見的 “立即退出” 情境

情境	原因	解決方案
docker run -d ubuntu	預設 bash 無輸入立即退出	指定長期執行的命令
docker run -d nginx 後改了配置	配置錯誤導致 nginx 啟動失敗	檢視 docker logs
自定義映像檔容器啟動即退	Dockerfile 的 CMD 執行完畢	確保 CMD 是前臺程序

5.2.4 檢視後臺容器

檢視執行中的容器

$ docker container ls
CONTAINER ID  IMAGE         COMMAND               CREATED        STATUS       PORTS NAMES
77b2dc01fe0f  ubuntu:24.04  /bin/sh -c 'while tr  2 minutes ago  Up 1 minute        agitated_wright

檢視容器輸出日誌

$ docker container logs 77b2dc01fe0f
hello world
hello world
hello world
...

實時檢視日誌 (類似 tail -f)：

$ docker container logs -f 77b2dc01fe0f

檢視已停止的容器

$ docker container ls -a

加上 -a 引數可以看到所有容器，包括已停止的。這對於除錯 “容器啟動即退出” 的問題非常有用。

5.2.5 最佳實務

1. 長期執行的服務使用 -d

## Web 伺服器

$ docker run -d -p 80:80 nginx:latest

## 資料庫

$ docker run -d -p 3306:3306 mysql:8.4

## 快取服務

$ docker run -d -p 6379:6379 redis:latest

版本說明：示例使用常見的標籤如 latest 或穩定大版本號如 mysql:8.4。具體版本可根據需求調整，生產環境建議明確指定版本號（如 mysql:8.4.4）而非使用 latest。

2. 除錯時先用前臺模式

當容器啟動有問題時，去掉 -d 引數 可以直接看到輸出和錯誤：

## 有問題的容器，先前臺執行看看發生了什麼

$ docker run myimage:v1.0.0

3. 使用 --rm 自動清理

對於一次性任務，使用 --rm 引數讓容器退出後自動刪除：

$ docker run --rm ubuntu:24.04 echo "Hello, World!"
Hello, World!

## 容器執行完後自動刪除

...

4. 配合日誌檢視

## 後臺啟動

$ docker run -d --name myapp myimage:v1.0.0

## 檢視最近 100 行日誌

$ docker logs --tail 100 myapp

## 實時跟蹤日誌

$ docker logs -f myapp

## 檢視帶時間戳的日誌

$ docker logs -t myapp

5.2.6 常見問題排查

Q：容器啟動後立即退出

1. 檢視退出狀態碼： ```bash $ docker ps -a --filter "name=mycontainer" # 檢視 STATUS 列，如 “Exited (1)” 表示異常退出

```

2. 檢視容器日誌： bash $ docker logs mycontainer

3. 以互動模式除錯： bash # /bin/sh 覆蓋映像檔原本的啟動命令，避免容器再次崩潰退出 # 進入 shell 後可手動執行原啟動命令，定位具體報錯原因 $ docker run -it myimage:v1.0.0 /bin/sh

Q：容器在後臺執行但無法訪問服務

1. 檢查埠對映： bash $ docker port mycontainer

2. 檢查容器內服務狀態： bash $ docker exec mycontainer ps aux

Q：如何讓已經在後臺執行的容器回到前臺？

使用 docker attach：

$ docker attach mycontainer

注意：attach 會連線到容器的主程序。如果主程序不是互動式的，你可能只能看到輸出。使用 Ctrl+P Ctrl+Q 可以安全退出而不停止容器。

5.2.7 延伸閱讀

• 進入容器：如何進入正在執行的容器執行命令
• 容器日誌：生產環境的日誌管理最佳實務
• HEALTHCHECK 健康檢查：自動檢測容器內服務是否正常
• Docker Compose：管理多個後臺容器的更好方式

5.3 終止

本節將介紹如何終止一個執行中的容器，以及幾種不同的終止方式及其區別。

5.3.1 終止方式概述

終止容器有三種方式：

方式	命令	說明
優雅停止	docker stop	先發 SIGTERM，超時後發 SIGKILL
強制停止	docker kill	直接發 SIGKILL
自動終止	-	容器主程序退出時自動停止

---

5.3.2 docker stop：推薦

docker stop 基本用法

$ docker stop 容器名或ID

工作原理

flowchart TD
    cmd["docker stop mycontainer"] --> A["1. 傳送 SIGTERM 訊號給容器主程序 (PID 1)"]
    A --> B["2. 等待容器優雅退出 (預設 10 秒)"]
    B --> C["3. 如果超時仍未退出，傳送 SIGKILL 強制終止"]

自定義超時時間

## 等待 30 秒後強制終止

$ docker stop -t 30 mycontainer

## 立即傳送 SIGKILL（相當於 docker kill）

$ docker stop -t 0 mycontainer

停止多個容器

## 停止多個指定容器

$ docker stop container1 container2 container3

## 停止所有執行中的容器

$ docker stop $(docker ps -q)

---

5.3.3 docker kill

基本用法

$ docker kill 容器名或ID

與 stop 的區別

命令	訊號	使用情境
docker stop	SIGTERM → SIGKILL	正常停止，讓應用優雅退出
docker kill	SIGKILL	應用無響應，強制終止

傳送自定義訊號

## 傳送 SIGHUP（讓程序重新載入配置）

$ docker kill -s HUP mycontainer

## 傳送 SIGTERM

$ docker kill -s TERM mycontainer

---

5.3.4 容器自動終止

容器的生命週期與主程序繫結。主程序退出時，容器自動停止：

## 主程序是互動式 bash

$ docker run -it ubuntu bash
root@abc123:/# exit    # 退出 bash → 容器停止

## 主程序執行完畢

$ docker run ubuntu echo "Hello"    # echo 執行完 → 容器停止

---

5.3.5 檢視已停止的容器

$ docker ps -a
CONTAINER ID   IMAGE    COMMAND       STATUS                      NAMES
ba267838cc1b   ubuntu   "/bin/bash"   Exited (0) 2 minutes ago    myubuntu
c5d3a5e8f7b2   nginx    "nginx"       Up 5 minutes                mynginx

STATUS 欄位說明：

狀態	說明
Up X minutes	執行中
Exited (0)	正常退出 (退出碼 0)
Exited (1)	異常退出 (非零退出碼)
Exited (137)	被 SIGKILL 終止 (128 + 9)
Exited (143)	被 SIGTERM 終止 (128 + 15)

---

5.3.6 重新啟動容器

啟動已停止的容器

$ docker start 容器名或ID

## 啟動並附加終端

$ docker start -ai 容器名

重啟執行中的容器

## 先停止再啟動

$ docker restart 容器名

## 自定義停止超時

$ docker restart -t 30 容器名

---

5.3.7 生命週期狀態圖

stateDiagram-v2
    direction TB
    [*] --> Created : docker create
    Created --> Running : docker start
    Running --> Stopped : docker stop
    Running --> Paused : docker pause
    Paused --> Running : docker unpause

    Created --> Deleted : docker rm
    Stopped --> Deleted : docker rm
    Paused --> Deleted : docker rm

    Deleted --> [*]

---

5.3.8 批次操作

停止所有容器

$ docker stop $(docker ps -q)

刪除所有已停止的容器

$ docker container prune

停止並刪除所有容器

$ docker stop $(docker ps -q) && docker container prune -f

---

5.3.9 常見問題

Q：容器停止很慢

原因：應用沒有正確處理 SIGTERM 訊號，需要等待超時後強制終止。

解決方案：

1. 在應用中正確處理 SIGTERM
2. 使用 docker stop -t 0 立即終止
3. 檢查 Dockerfile 中的 STOPSIGNAL 配置

Q：如何讓容器優雅退出

確保容器主程序正確處理訊號：

## Dockerfile 示例

FROM node:22-alpine
...

## 使用 exec 形式確保訊號能傳遞給 node 程序

CMD ["node", "server.js"]

版本說明：示例使用 node:22-alpine，這是一個精簡的 Node.js 22 版本映像檔。可根據需求替換為其他版本（如 node:24-alpine、node:latest）。

Q：容器無法停止

## 強制終止

$ docker kill 容器名

## 如果仍無法停止，檢查系統資源

$ docker inspect 容器名

---

5.4 進入容器

5.4.1 為什麼需要進入容器

使用 -d 引數啟動容器後，容器在後臺執行。以下情境需要進入容器內部操作：

情境	示例
除錯問題	檢視日誌、檢查配置、排查錯誤
臨時操作	執行資料庫遷移、清理快取
檢查狀態	檢視程序、網路連線、檔案系統
開發測試	互動式測試命令、驗證環境

5.4.2 兩種進入方式

Docker 提供兩種進入容器的命令：

命令	推薦程度	特點
docker exec	✅ 推薦	啟動新程序，退出不影響容器
docker attach	⚠️ 謹慎使用	附加到主程序，退出可能停止容器

---

5.4.3 docker exec：推薦

docker exec 基本用法

## 進入容器並啟動互動式 shell

$ docker exec -it 容器名 /bin/bash

## 或使用 sh（適用於 Alpine 等精簡映像檔）

$ docker exec -it 容器名 /bin/sh

引數說明

引數	作用
-i	保持標準輸入開啟 (interactive)
-t	分配偽終端 (TTY)
-it	兩者組合，獲得完整互動體驗
-u	指定使用者 (如 -u root)
-w	指定工作目錄
-e	設定環境變數

docker exec 示例

## 啟動一個後臺容器

$ docker run -dit --name myubuntu ubuntu
69d137adef7a...

## 進入容器（互動式 shell）

$ docker exec -it myubuntu bash
root@69d137adef7a:/# ls
bin  boot  dev  etc  home  lib  ...
root@69d137adef7a:/# exit

## 容器仍在執行！

$ docker ps
CONTAINER ID   IMAGE    STATUS         NAMES
69d137adef7a   ubuntu   Up 2 minutes   myubuntu

執行單條命令

不進入互動模式，直接執行命令：

## 檢視容器內程序

$ docker exec myubuntu ps aux

## 檢視配置檔案

$ docker exec myubuntu cat /etc/nginx/nginx.conf

## 以 root 使用者執行

$ docker exec -u root myubuntu apt update

只用 -i 不用 -t 的區別

## 只用 -i：可以執行命令，但沒有提示符

$ docker exec -i myubuntu bash
ls           # 輸入命令
bin          # 輸出結果
boot
dev
...

## 用 -it：有完整的終端體驗

$ docker exec -it myubuntu bash
root@69d137adef7a:/#    # 有提示符

💡 通常使用 -it 組合。只有在指令碼中需要透過管道傳入命令時才只用 -i。

---

5.4.4 docker attach：謹慎使用

docker attach 基本用法

$ docker attach 容器名

工作原理

attach 會附加到容器的 主程序 (PID 1) 的標準輸入輸出：

flowchart LR
    subgraph Container ["容器"]
        direction TB
        subgraph Process ["主程序"]
            P1["PID 1: /bin/bash<br>(你的輸入直接傳送到主程序)"]
        end
    end
    Attach["docker attach"] -->|"附加到這裡"| P1

docker attach 示例

## 啟動容器

$ docker run -dit --name myubuntu ubuntu
243c32535da7...

## 附加到容器

$ docker attach myubuntu
root@243c32535da7:/#

⚠️ 重要警告

從 attach 會話中輸入 exit 或按 Ctrl+D 會導致容器停止！

$ docker attach myubuntu
root@243c32535da7:/# exit    # 這會停止容器！

$ docker ps
CONTAINER ID   IMAGE    STATUS                     NAMES
243c32535da7   ubuntu   Exited (0) 2 seconds ago   myubuntu

原因：attach 附加到主程序，退出主程序就等於退出容器。

安全退出 attach

使用 Ctrl+P 然後 Ctrl+Q 可以從 attach 會話中 分離，而不停止容器：

$ docker attach myubuntu
root@243c32535da7:/#

## 按 Ctrl+P 然後 Ctrl+Q

read escape sequence

$ docker ps    # 容器仍在執行
CONTAINER ID   IMAGE    STATUS         NAMES
243c32535da7   ubuntu   Up 5 minutes   myubuntu

---

5.4.5 exec vs attach 對比

特性	docker exec	docker attach
工作方式	在容器內啟動新程序	附加到主程序
退出影響	不影響容器	可能停止容器
多終端	可以開多個	共享同一個會話
適用情境	除錯、臨時操作	檢視主程序輸出
推薦程度	✅ 推薦	⚠️ 特殊情境使用

flowchart LR
    subgraph Exec ["docker exec"]
        direction TB
        subgraph Container1 ["容器"]
            E_PID1["PID 1: nginx"]
            E_PID50["PID 50: bash"]
        end
        NewProc["新程序"] -- 附加到 --> E_PID50
    end

    subgraph Attach ["docker attach"]
        direction TB
        subgraph Container2 ["容器"]
            A_PID1["PID 1: bash"]
        end
        MainProc["附加到主程序"] --> A_PID1
    end

    note1["退出 bash 不影響 nginx"]
    note2["退出 bash 容器停止"]
    Container1 -.-> note1
    Container2 -.-> note2

---

5.4.6 最佳實務

1. 首選 docker exec

## 進入容器除錯

$ docker exec -it myapp bash

## 檢視日誌

$ docker exec myapp tail -f /var/log/app.log

## 執行資料庫遷移

$ docker exec myapp python manage.py migrate

2. 生產環境避免進入容器

筆者建議：生產環境應儘量避免進入容器直接操作，而是透過：

• 日誌系統檢視日誌 (如 docker logs 或集中式日誌)
• 監控系統檢視狀態
• 重新部署而非手動修改

3. 無 shell 映像檔的處理

某些精簡映像檔 (如基於 scratch 或 distroless) 沒有 shell：

## 這會失敗

$ docker exec -it myapp bash
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found

## 解決方案：使用除錯容器（需要 Docker Desktop Pro/Team/Business 訂閱）

$ docker debug myapp

> 注意：docker debug 是 Docker Desktop 4.33+ 提供的功能，需要 Pro、Team 或 Business 訂閱。它會附加一個包含常用除錯工具（vim、curl、htop 等）的工具箱到目標容器，即使目標映像檔基於 scratch 也能使用。

5.4.7 常見問題

Q：exec 進入後看不到其他終端的操作

這是正常的。exec 啟動的是獨立程序，多個 exec 會話互不影響。

Q：容器沒有 bash

嘗試使用 sh：

$ docker exec -it myapp /bin/sh

Q：需要 root 許可權

$ docker exec -u root -it myapp bash

---

5.5 匯出和匯入

當我們需要遷移容器或者備份容器時，可以使用 Docker 的匯入和匯出功能。本節將介紹這兩個命令的使用方法。

5.5.1 匯出容器

如果要匯出本地某個容器，可以使用 docker export 命令。

$ docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                    PORTS               NAMES
7691a814370e        ubuntu:24.04        "/bin/bash"         36 hours ago        Exited (0) 21 hours ago                       test
$ docker export 7691a814370e > ubuntu.tar

這樣將匯出容器快照到本地檔案。

版本說明：匯出的容器快照不包含映像檔版本歷史，匯入時可以自定義標籤和版本號。

5.5.2 匯入容器快照

可以使用 docker import 從容器快照檔案中再匯入為映像檔，例如

$ cat ubuntu.tar | docker import - test/ubuntu:v1.0
$ docker image ls
REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
test/ubuntu         v1.0                9d37a6082e97        About a minute ago   171.3 MB

此外，也可以透過指定 URL 或者某個目錄來匯入，例如

$ docker import http://example.com/exampleimage.tgz example/imagerepo

注：使用者既可以使用 docker load 來匯入映像檔儲存檔案到本地映像檔庫，也可以使用 docker import 來匯入一個容器快照到本地映像檔庫。這兩者的區別在於容器快照檔案將丟棄所有的歷史記錄和後設資料資訊 (即僅儲存容器當時的快照狀態)，而映像檔儲存檔案將儲存完整記錄，體積也要大。此外，從容器快照檔案匯入時可以重新指定標籤等後設資料資訊。

5.6 刪除

隨著容器的建立和停止，系統中會積累大量的容器。本節將介紹如何刪除不再需要的容器，以及如何清理所有停止的容器。

5.6.1 基本用法

使用 docker rm 刪除已停止的容器：

$ docker rm 容器名或ID

💡 docker rm 是 docker container rm 的簡寫，兩者等效。

---

5.6.2 刪除選項

選項	說明	示例
無引數	刪除已停止的容器	docker rm mycontainer
-f	強制刪除執行中的容器	docker rm -f mycontainer
-v	同時刪除關聯的匿名卷	docker rm -v mycontainer

刪除已停止的容器

$ docker rm mycontainer
mycontainer

強制刪除執行中的容器

## 不加 -f 會報錯

$ docker rm running_container
Error: cannot remove running container

## 加 -f 強制刪除

$ docker rm -f running_container
running_container

⚠️ 強制刪除會向容器傳送 SIGKILL 訊號，可能導致資料丟失。建議先 docker stop 優雅停止。

刪除容器及其資料卷

## 刪除容器時同時刪除其匿名卷

$ docker rm -v mycontainer

注意：只刪除匿名卷，命名卷不會被刪除。

---

5.6.3 批次刪除

刪除所有已停止的容器

## 方式一：使用 prune 命令（推薦）

$ docker container prune

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
abc123...
def456...
Total reclaimed space: 150MB

## 方式二：不提示確認

$ docker container prune -f

刪除所有容器：包括執行中的

## 先停止所有容器，再刪除

$ docker stop $(docker ps -q)
$ docker rm $(docker ps -aq)

## 或者直接強制刪除

$ docker rm -f $(docker ps -aq)

按條件刪除

## 刪除所有已退出的容器

$ docker rm $(docker ps -aq -f status=exited)

## 刪除名稱包含 "test" 的容器

$ docker rm $(docker ps -aq -f name=test)

## 刪除 24 小時前建立的容器

$ docker container prune --filter "until=24h"

---

5.6.4 常用過濾條件

docker ps 的過濾條件可以配合 rm 使用：

過濾條件	說明	示例
status=exited	已退出的容器	-f status=exited
status=created	已建立未啟動	-f status=created
name=xxx	名稱匹配	-f name=myapp
ancestor=xxx	基於某映像檔建立	-f ancestor=nginx
before=xxx	在某容器之前建立	-f before=mycontainer
since=xxx	在某容器之後建立	-f since=mycontainer

示例

## 刪除所有基於 nginx 映像檔的容器

$ docker rm $(docker ps -aq -f ancestor=nginx)

## 刪除所有建立後未啟動的容器

$ docker rm $(docker ps -aq -f status=created)

---

5.6.5 容器與映像檔的依賴關係

有容器依賴的映像檔無法刪除。

## 嘗試刪除有容器依賴的映像檔

$ docker image rm nginx
Error: image is being used by stopped container abc123

## 需要先刪除依賴該映像檔的容器

$ docker rm abc123
$ docker image rm nginx

---

5.6.6 清理策略建議

開發環境

## 定期清理已停止的容器

$ docker container prune -f

## 一鍵清理所有未使用資源

$ docker system prune -f

生產環境

## 使用 --rm 引數執行臨時容器

$ docker run --rm ubuntu echo "Hello"

## 容器退出後自動刪除

## 定期清理（設定保留時間）

$ docker container prune --filter "until=168h"  # 保留 7 天內的

完整清理指令碼

#!/bin/bash

## cleanup.sh - Docker 資源清理指令碼

echo "清理已停止的容器..."
docker container prune -f

echo "清理未使用的映像檔..."
docker image prune -f

echo "清理未使用的資料卷..."
docker volume prune -f

echo "清理未使用的網路..."
docker network prune -f

echo "清理完成！"
docker system df

---

5.6.7 常見問題

Q：容器無法刪除

Error: container is running

解決：先停止容器，或使用 -f 強制刪除

$ docker stop mycontainer
$ docker rm mycontainer

## 或

$ docker rm -f mycontainer

Q：刪除後磁碟空間沒釋放

可能原因：

1. 容器的資料卷未刪除 (使用 -v 引數)
2. 映像檔未刪除
3. 構建快取未清理

解決：

## 檢視空間佔用

$ docker system df

## 完整清理

$ docker system prune -a --volumes

---

本章小結

本章介紹了 Docker 容器的啟動、停止、進入和刪除等核心操作。

操作	命令	說明
新建並執行	docker run	最常用的啟動方式
互動式啟動	docker run -it	用於除錯或臨時操作
後臺執行	docker run -d	用於服務類應用
啟動已停止的容器	docker start	重用已有容器
優雅停止	docker stop	先 SIGTERM，超時後 SIGKILL
強制停止	docker kill	直接 SIGKILL
重啟	docker restart	停止後立即啟動
停止全部	docker stop $(docker ps -q)	停止所有執行中容器
進入容器除錯	docker exec -it 容器名 bash	推薦方式
執行單條命令	docker exec 容器名 命令	不進入互動模式
檢視主程序輸出	docker attach 容器名	慎用，退出可能停止容器
刪除已停止容器	docker rm 容器名	需先停止
強制刪除執行中容器	docker rm -f 容器名	直接刪除
刪除容器及匿名卷	docker rm -v 容器名	同時清理匿名卷
清理所有已停止容器	docker container prune	批次清理

延伸閱讀

• 後臺執行：理解 -d 引數和容器生命週期
• 進入容器：操作執行中的容器
• 網路配置：理解埠對映的原理
• 資料管理：資料持久化方案
• 刪除映像檔：清理映像檔
• 資料卷：資料卷管理

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

6.1 Docker Hub

6.1.1 什麼是 Docker Hub

Docker Hub 是 Docker 的中央映像檔倉庫，透過它您可以輕鬆地分享和獲取 Docker 映像檔。

Docker Hub 是 Docker 官方維護的公共映像檔倉庫，也是全球最大的容器映像檔庫。

它提供了：

• 官方映像檔：由 Docker 官方和軟體廠商 (如 Nginx，MySQL，Node.js) 維護的高質量映像檔。
• 個人/組織倉庫：使用者可以上傳自己的映像檔。
• 自動構建：與 GitHub/Bitbucket 整合 (需付費)。
• Webhooks：映像檔更新時觸發回撥。

---

6.1.2 核心功能

1. 搜尋映像檔

我們可以透過 docker search 命令來查詢官方倉庫中的映像檔，並利用 docker pull 命令來將它下載到本地。

除了網頁搜尋，也可以使用命令列：

$ docker search centos
NAME      DESCRIPTION                      STARS     OFFICIAL
centos    The official build of CentOS.    7000+     [OK]

技巧：始終優先使用 OFFICIAL 標記為 [OK] 的映像檔，安全性更有保障。

2. 拉取映像檔

$ docker pull nginx:alpine

3. 推送映像檔

需要先登入：

$ docker login

## 預設情況下，不帶其它引數進行 docker login 會自動走 Device Code Web Flow (瀏覽器認證)
## 若在非互動 CI 環境中，推薦結合 --username 與 --password-stdin 引數使用

...

打標籤並推送：

## 1. 標記映像檔

$ docker tag myapp:v1 username/myapp:v1

## 2. 推送

$ docker push username/myapp:v1

---

6.1.3 限制與配額

映像檔拉取限制

Docker Hub 對不同型別使用者實施拉取速率限制（基於 6 小時週期）：

使用者型別	限制
匿名使用者 (未登入)	每 6 小時 100 次請求
免費賬戶 (已登入)	每 6 小時 200 次請求
Pro/Team/Business 賬戶	無限制（公平使用政策）

注意：Docker 曾計劃於 2025 年 4 月調整拉取限制策略，但在 2025 年 2 月宣佈取消該計劃。目前付費訂閱使用者享有無限制拉取額度，匿名使用者和免費賬戶的限制保持不變。建議在 CI/CD 環境中始終配置 docker login 以獲得更高的拉取額度。

濫用限流

除了上述針對特定賬號拉取映像檔數量的 Pull Rate Limit 之外，Docker Hub 對所有使用者（包含已認證及付費使用者）還實施了 濫用保護限流 (Abuse Rate Limiting)。它是根據網路出口 IP (IPv4 或 IPv6 /64 子網) 計算整體請求頻率，門檻值動態觸發（通常為每分鐘數千級別請求）。

兩類的差異與排查方法：

• Pull Rate Limit：針對拉取量達到上限。報錯返回 429 Too Many Requests，並且 HTTP 返回體/CLI 錯誤提示中會帶有明確的 toomanyrequests: You have reached your pull rate limit 提示，常附有賬戶升級連結。
• Abuse Rate Limit：防範介面頻率打擊。報錯僅返回簡化的 429 Too Many Requests。這一限流不分付費與否，常發生在“多終端共享出口 IP”的企業區域網或者第三方雲 CI 服務（如 GitHub Actions 等）中，即使你已正常配置 docker login 也依舊可能觸發。

提示：如果在 CI/CD 等環境遇到 429 錯誤，建議： 1. 先甄別具體是哪類限流：普通的 pull rate limit 只要在 CI 中配置 docker login (並使用有效賬號) 就能解除匿名限制。 2. 如果是 Abuse 頻控導致，應考慮搭建私有倉庫作為拉取快取代理 (Registry pull-through cache)，避免頻繁直接請求官方 Hub。 3. 使用國內映像檔加速器。

---

6.1.4 安全最佳實務

1. 啟用 2FA：雙因素認證

為了保護您的 Docker Hub 賬號安全，我們建議採取以下措施。

在 Account Settings -> Security 中啟用 2FA，保護賬號安全。啟用後，CLI 登入需要使用 Access Token 而非密碼。

2. 使用 Access Token

⚠️ 警告：絕不要在指令碼或 CI/CD 系統中，直接使用 -p 引數傳遞密碼或 Token (類似 docker login -p xxx)！這會導致憑證直接暴露在系統的命令歷史、程序列表和終端輸出中。

1. 在 Docker Hub -> Account Settings -> Security -> Access Tokens 建立 Token (PAT)。
2. 將 Token 透過標準輸入 (stdin) 安全傳遞給 Docker:

$ echo "dckr_pat_xxxxxxx" | docker login --username username --password-stdin

3. 關注映像檔漏洞

Docker Hub 提供 Docker Scout 安全掃描功能。官方映像檔的漏洞掃描結果對所有使用者免費可見。Docker Scout 的持續掃描功能在免費層可以覆蓋 1 個私有倉庫，付費使用者可以掃描更多倉庫。在映像檔標籤頁可以看到漏洞掃描結果。

---

6.1.5 Webhooks

當映像檔被推送時，可以自動觸發 HTTP 回撥 (例如通知 CI 系統部署)。

配置方法： 倉庫頁面 -> Webhooks -> Create Webhook。

---

6.1.6 自動構建

⚠️ 目前僅限付費使用者 (Pro/Team) 使用。

連結 GitHub/Bitbucket 倉庫後，當程式碼有提交或打標籤時，Docker Hub 會自動執行構建。這保證了映像檔總是與程式碼同步，且由可信的官方環境構建。

---

6.2 私有倉庫

有時候使用 Docker Hub 這樣的公共倉庫可能不方便，使用者可以建立一個本地倉庫供私人使用。

本節介紹如何使用本地倉庫。

Docker Registry 是官方提供的工具，可以用於構建私有的映像檔倉庫。本文內容基於 distribution/distribution v2.x 版本。

6.2.1 安裝執行 docker-registry

容器執行

如果您需要搭建私有倉庫，可以透過官方提供的 registry 映像檔快速部署。

你可以使用官方 registry 映像檔來執行。

$ docker run -d -p 5000:5000 --restart=always --name registry registry:2

版本說明：使用 registry:2 表示 Docker Registry 2.x 版本，這是當前推薦的版本。舊版本 Registry 1.x 已停止維護，不建議使用。 這將使用官方的 registry 映像檔來啟動私有倉庫。預設情況下，倉庫會被建立在容器的 /var/lib/registry 目錄下。你可以透過 -v 引數來將映像檔檔案存放在本地的指定路徑。例如下面的例子將上傳的映像檔放到本地的 /opt/data/registry 目錄。

$ docker run -d \
    -p 5000:5000 \
    -v /opt/data/registry:/var/lib/registry \
    registry:2

6.2.2 在私有倉庫上傳、搜尋、下載映像檔

建立好私有倉庫之後，就可以使用 docker tag 來標記一個映像檔，然後推送它到倉庫。例如私有倉庫地址為 127.0.0.1:5000。

先在本機檢視已有的映像檔。

$ docker image ls
REPOSITORY                        TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
ubuntu                            latest              ba5877dc9bec        6 weeks ago         192.7 MB

使用 docker tag 將 ubuntu:latest 這個映像檔標記為 127.0.0.1:5000/ubuntu:latest。

格式為 docker tag IMAGE[:TAG] [REGISTRY_HOST[:REGISTRY_PORT]/]REPOSITORY[:TAG]。

$ docker tag ubuntu:latest 127.0.0.1:5000/ubuntu:latest
$ docker image ls
REPOSITORY                        TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
ubuntu                            latest              ba5877dc9bec        6 weeks ago         192.7 MB
127.0.0.1:5000/ubuntu:latest      latest              ba5877dc9bec        6 weeks ago         192.7 MB

使用 docker push 上傳標記的映像檔。

$ docker push 127.0.0.1:5000/ubuntu:latest
The push refers to repository [127.0.0.1:5000/ubuntu]
373a30c24545: Pushed
a9148f5200b0: Pushed
cdd3de0940ab: Pushed
fc56279bbb33: Pushed
b38367233d37: Pushed
2aebd096e0e2: Pushed
latest: digest: sha256:fe4277621f10b5026266932ddf760f5a756d2facd505a94d2da12f4f52f71f5a size: 1568

用 curl 檢視倉庫中的映像檔。

$ curl 127.0.0.1:5000/v2/_catalog
{"repositories":["ubuntu"]}

這裡可以看到 {"repositories":["ubuntu"]}，表明映像檔已經被成功上傳了。

先刪除已有映像檔，再嘗試從私有倉庫中下載這個映像檔。

$ docker image rm 127.0.0.1:5000/ubuntu:latest

$ docker pull 127.0.0.1:5000/ubuntu:latest
Pulling repository 127.0.0.1:5000/ubuntu:latest
ba5877dc9bec: Download complete
511136ea3c5a: Download complete
9bad880da3d2: Download complete
25f11f5fb0cb: Download complete
ebc34468f71d: Download complete
2318d26665ef: Download complete

$ docker image ls
REPOSITORY                         TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
127.0.0.1:5000/ubuntu:latest       latest              ba5877dc9bec        6 weeks ago         192.7 MB

6.2.3 配置非 https 倉庫地址

如果你不想使用 127.0.0.1:5000 作為倉庫地址，比如想讓本網段的其他主機也能把映像檔推送到私有倉庫。你就得把例如 192.168.199.100:5000 這樣的內網地址作為私有倉庫地址，這時你會發現無法成功推送映像檔。

這是因為 Docker 預設不允許非 HTTPS 方式推送映像檔。我們可以透過 Docker 的配置選項來取消這個限制，或者檢視下一節配置能夠透過 HTTPS 訪問的私有倉庫。

Linux

預設情況下，Docker 強制使用 HTTPS 協議推送映像檔。如果您搭建的私有倉庫是 HTTP 協議，需要進行如下配置。

對於使用 systemd 的系統，請在 /etc/docker/daemon.json 中寫入如下內容 (如果檔案不存在請新建該檔案)

{
  "registry-mirrors": [
    "https://docker.your-mirror.example.com"
  ],
  "insecure-registries": [
    "192.168.199.100:5000"
  ]
}

注意：該檔案必須符合 json 規範，否則 Docker 將不能啟動。映像檔加速器地址請替換為實際可用的源，具體配置參見 3.9 映像檔加速器。

6.2.4 其他

對於 Docker Desktop for Windows、Docker Desktop for Mac 在設定中的 Docker Engine 中進行編輯，增加和上邊一樣的字串即可。

6.3 私有倉庫高階配置

上一節我們搭建了一個具有基礎功能的私有倉庫，本小節我們來使用 Docker Compose 搭建一個擁有許可權認證、TLS 的私有倉庫。

新建一個資料夾，以下步驟均在該資料夾中進行。

6.3.1 準備站點證書

如果你擁有一個域名，國內各大雲服務商均提供免費的站點證書。你也可以使用 openssl 自行簽發證書。

這裡假設我們將要搭建的私有倉庫地址為 docker.domain.com，下面我們介紹使用 openssl 自行簽發 docker.domain.com 的站點 SSL 證書。

第一步建立 CA 私鑰。

$ openssl genrsa -out "root-ca.key" 4096

第二步利用私鑰建立 CA 根證書請求檔案。

$ openssl req \
          -new -key "root-ca.key" \
          -out "root-ca.csr" -sha256 \
          -subj '/C=CN/ST=Shanxi/L=Datong/O=Your Company Name/CN=Your Company Name Docker Registry CA'

以上命令中 -subj 引數裡的 /C 表示國家，如 CN；/ST 表示省；/L 表示城市或者地區；/O 表示組織名；/CN 通用名稱。

第三步配置 CA 根證書，新建 root-ca.cnf。

[root_ca]
basicConstraints = critical,CA:TRUE,pathlen:1
keyUsage = critical, nonRepudiation, cRLSign, keyCertSign
subjectKeyIdentifier=hash

第四步簽發根證書。

$ openssl x509 -req  -days 3650  -in "root-ca.csr" \
               -signkey "root-ca.key" -sha256 -out "root-ca.crt" \
               -extfile "root-ca.cnf" -extensions \
               root_ca

第五步生成站點 SSL 私鑰。

$ openssl genrsa -out "docker.domain.com.key" 4096

第六步使用私鑰生成證書請求檔案。

$ openssl req -new -key "docker.domain.com.key" -out "site.csr" -sha256 \
          -subj '/C=CN/ST=Shanxi/L=Datong/O=Your Company Name/CN=docker.domain.com'

第七步配置證書，新建 site.cnf 檔案。

[server]
authorityKeyIdentifier=keyid,issuer
basicConstraints = critical,CA:FALSE
extendedKeyUsage=serverAuth
keyUsage = critical, digitalSignature, keyEncipherment
subjectAltName = DNS:docker.domain.com, IP:127.0.0.1
subjectKeyIdentifier=hash

第八步簽署站點 SSL 證書。

$ openssl x509 -req -days 750 -in "site.csr" -sha256 \
    -CA "root-ca.crt" -CAkey "root-ca.key"  -CAcreateserial \
    -out "docker.domain.com.crt" -extfile "site.cnf" -extensions server

這樣已經擁有了 docker.domain.com 的網站 SSL 私鑰 docker.domain.com.key 和 SSL 證書 docker.domain.com.crt 及 CA 根證書 root-ca.crt。

新建 ssl 資料夾並將 docker.domain.com.key docker.domain.com.crt root-ca.crt 這三個檔案移入，刪除其他檔案。

安全提示：這些私鑰和證書應在本地或受控部署環境中生成，不要提交進 Git 倉庫。示例目錄只保留佔位說明，執行前請按上面的步驟重新生成。

6.3.2 配置私有倉庫

私有倉庫預設的配置檔案位於 /etc/docker/registry/config.yml，我們先在本地編輯 config.yml，之後掛載到容器中。

log:
  accesslog:
    disabled: true
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging
storage:
  delete:
    enabled: true
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
auth:
  htpasswd:
    realm: basic-realm
    path: /etc/docker/registry/auth/nginx.htpasswd
http:
  addr: :443
  host: https://docker.domain.com
  headers:
    X-Content-Type-Options: [nosniff]
  http2:
    disabled: false
  tls:
    certificate: /etc/docker/registry/ssl/docker.domain.com.crt
    key: /etc/docker/registry/ssl/docker.domain.com.key
health:
  storagedriver:
    enabled: true
    interval: 10s
threshold: 3

6.3.3 生成 http 認證檔案

$ mkdir auth

$ docker run --rm \
    --entrypoint htpasswd \
    httpd:2.4-alpine \
    -Bbn username password > auth/nginx.htpasswd

將上面的 username password 替換為你自己的使用者名稱和密碼。

安全提示：上述命令會將密碼明文暴露在 shell 歷史記錄和程序列表中。生產環境建議使用互動式方式輸入密碼（不帶 -b 引數），或透過環境變數/檔案傳入。

版本說明：使用 httpd:2.4-alpine 基於 Apache 2.4 的精簡映像檔。如需其他版本，可替換為 httpd:latest 或指定具體版本號如 httpd:2.4.58-alpine。

6.3.4 編輯 Docker Compose 配置

編輯 compose.yaml (或 docker-compose.yml) 配置如下：

services:
  registry:
    image: registry:2
    ports:
      - "443:443"
    volumes:
      - ./:/etc/docker/registry
      - registry-data:/var/lib/registry

volumes:
  registry-data:

版本說明：Compose 配置中明確指定 registry:2 版本。生產環境建議固定版本號（如 registry:2.8.3）而非使用 latest，以保證部署的可重複性。

6.3.5 修改 Hosts 檔案

編輯 /etc/hosts

127.0.0.1 docker.domain.com

6.3.6 啟動

$ docker compose up -d

這樣我們就搭建好了一個具有許可權認證、TLS 的私有倉庫，接下來我們測試其功能是否正常。

6.3.7 測試私有倉庫功能

由於自行簽發的 CA 根證書不被系統信任，所以我們需要將 CA 根證書 ssl/root-ca.crt 移入 /etc/docker/certs.d/docker.domain.com 資料夾中。

$ sudo mkdir -p /etc/docker/certs.d/docker.domain.com

$ sudo cp ssl/root-ca.crt /etc/docker/certs.d/docker.domain.com/ca.crt

登入到私有倉庫。

$ docker login docker.domain.com

嘗試推送、拉取映像檔。

$ docker pull ubuntu:24.04

$ docker tag ubuntu:24.04 docker.domain.com/username/ubuntu:24.04

$ docker push docker.domain.com/username/ubuntu:24.04

$ docker image rm docker.domain.com/username/ubuntu:24.04

$ docker pull docker.domain.com/username/ubuntu:24.04

版本說明：示例使用 ubuntu:24.04，這是最新 LTS 版本。推送到私有倉庫時保持了原有的版本標籤，建議生產環境明確指定映像檔版本號。 如果我們退出登入，嘗試推送映像檔。

$ docker logout docker.domain.com

$ docker push docker.domain.com/username/ubuntu:24.04

no basic auth credentials

發現會提示沒有登入，不能將映像檔推送到私有倉庫中。

6.3.8 注意事項

如果你本機佔用了 443 埠，你可以配置 Nginx 代理，這裡不再贅述。

6.4 Nexus 3

使用 Docker 官方的 Registry 建立的倉庫面臨一些維護問題。比如某些映像檔刪除以後空間預設是不會回收的，需要一些命令去回收空間然後重啟 Registry。在企業中把內部的一些工具包放入 Nexus 中是比較常見的做法，最新版本 Nexus3.x 全面支援 Docker 的私有映像檔。所以使用 Nexus 3 一個軟體來管理 Docker，Maven，Yum，PyPI 等是一個明智的選擇。

6.4.1 啟動 Nexus 容器

$ docker run -d --name nexus3 --restart=always \
    -p 8081:8081 \
    --mount src=nexus-data,target=/nexus-data \
    sonatype/nexus3:3.69

版本說明：使用 sonatype/nexus3:3.69 指定穩定的 Nexus 版本。使用具體版本號而非 latest 可以避免意外升級帶來的不相容問題。 首次執行需等待 3-5 分鐘，你可以使用 docker logs nexus3 -f 檢視日誌：

$ docker logs nexus3 -f

2021-03-11 15:31:21,990+0000 INFO  [jetty-main-1] *SYSTEM org.sonatype.nexus.bootstrap.jetty.JettyServer -
-------------------------------------------------

Started Sonatype Nexus OSS 3.69.0

-------------------------------------------------

版本說明：上述日誌中顯示的是 Nexus 3.69 版本的啟動日誌。具體版本號會隨著容器映像檔版本而不同。 如果你看到以上內容，說明 Nexus 已經啟動成功，你可以使用瀏覽器開啟 http://YourIP:8081 訪問 Nexus 了。

首次執行請透過以下命令獲取初始密碼：

$ docker exec nexus3 cat /nexus-data/admin.password

9266139e-41a2-4abb-92ec-e4142a3532cb

首次啟動 Nexus 的預設賬號是 admin，密碼則是上邊命令獲取到的，點選右上角登入，首次登入需更改初始密碼。

登入之後可以點選頁面上方的齒輪按鈕按照下面的方法進行設定。

6.4.2 建立倉庫

建立一個私有倉庫的方法：Repository->Repositories 點選右邊選單 Create repository 選擇 docker (hosted)

• Name：倉庫的名稱
• HTTP：倉庫單獨的訪問埠 (例如：5001)
• Hosted -> Deployment policy：請選擇 Allow redeploy 否則無法上傳 Docker 映像檔。

其它的倉庫建立方法請各位自己摸索，還可以建立一個 docker (proxy) 型別的倉庫連結到 DockerHub 上。再建立一個 docker (group) 型別的倉庫把剛才的 hosted 與 proxy 新增在一起。主機在訪問的時候預設下載私有倉庫中的映像檔，如果沒有將連結到 DockerHub 中下載並快取到 Nexus 中。

6.4.3 新增訪問許可權

選單 Security->Realms 把 Docker Bearer Token Realm 移到右邊的框中儲存。

新增使用者規則：選單 Security->Roles->Create role 在 Privileges 選項搜尋 docker 把相應的規則移動到右邊的框中然後儲存。

新增使用者：選單 Security->Users->Create local user 在 Roles 選項中選中剛才建立的規則移動到右邊的視窗儲存。

6.4.4 NGINX 反向代理配置

證書的生成請參見 私有倉庫認證 裡面證書生成一節。

NGINX 示例配置如下

upstream register
{
    server "YourHostName OR IP":5001; #埠為上面新增私有映像檔倉庫時設定的 HTTP 選項的埠號
    check interval=3000 rise=2 fall=10 timeout=1000 type=http;
    check_http_send "HEAD / HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_4xx;
}

server {
    server_name YourDomainName;#如果沒有 DNS 伺服器做解析，請刪除此選項使用本機 IP 地址訪問
    listen       443 ssl;

    ssl_certificate key/example.crt;
    ssl_certificate_key key/example.key;

    ssl_session_timeout  5m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers  HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers   on;
    large_client_header_buffers 4 32k;
    client_max_body_size 300m;
    client_body_buffer_size 512k;
    proxy_connect_timeout 600;
    proxy_read_timeout   600;
    proxy_send_timeout   600;
    proxy_buffer_size    128k;
    proxy_buffers       4 64k;
    proxy_busy_buffers_size 128k;
    proxy_temp_file_write_size 512k;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_redirect off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://register;
        proxy_read_timeout 900s;

    }
    error_page   500 502 503 504  /50x.html;
}

6.4.5 Docker 主機訪問映像檔倉庫

如果不啟用 SSL 加密可以透過前面章節的方法新增非 https 倉庫地址到 Docker 的配置檔案中然後重啟 Docker。

使用 SSL 加密以後程式需要訪問就不能採用修改配置的方式了。具體方法如下：

$ openssl s_client -showcerts -connect YourDomainName OR HostIP:443 </dev/null 2>/dev/null|openssl x509 -outform PEM >ca.crt
$ cat ca.crt | sudo tee -a /etc/ssl/certs/ca-certificates.crt
$ systemctl restart docker

使用 docker login YourDomainName OR HostIP 進行測試，使用者名稱密碼填寫上面 Nexus 中設定的。

本章小結

本章介紹了 Docker Hub 的使用、私有倉庫的搭建以及 Nexus 3 等企業級方案。

功能	說明
官方映像檔	優先使用的基礎映像檔
拉取限制	匿名 100 次/6h，登入 200 次/6h
安全	推薦開啟 2FA 並使用 Access Token
自動化	支援 Webhooks 和自動構建

延伸閱讀

• 私有倉庫：搭建自己的 Registry
• 映像檔加速器：加速下載

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

docker build [選項] <上下文路徑/URL/->

docker build -t my-image:1.0 .

7.1 RUN 執行命令

何時使用 RUN

RUN 是 Dockerfile 中最常用的指令，主要用於在映像檔構建階段執行命令來修改映像檔。具體來說：

• 安裝依賴：RUN apt-get install nginx
• 編譯程式：RUN gcc -o app main.c
• 下載檔案：RUN curl -O https://example.com/file.tar.gz
• 配置系統：RUN mkdir -p /app/data

理解 RUN 的核心是理解映像檔分層：每一個 RUN 都會在當前層之上建立新的一層，這會影響映像檔大小。因此，合理使用 RUN（特別是合併多個 RUN）是構建輕量級映像檔的關鍵。

7.1.1 基本語法

RUN <command>
RUN ["executable", "param1", "param2"]

RUN 指令是 Dockerfile 中最常用的指令之一。它在 當前映像檔層 之上建立一個新層，執行指定的命令，並提交結果。

---

7.1.2 兩種格式對比

1. Shell 格式

RUN apt-get update

• 特點：預設透過 /bin/sh -c 執行。
• 優勢：可以使用環境變數、管道、重定向等 Shell 特性。
• 示例： docker RUN echo "Hello" > /test.txt

2. Exec 格式

RUN ["apt-get", "update"]

• 特點：直接呼叫可執行檔案，不經過 Shell。
• 優勢：避免 Shell 字串解析問題，適用於引數中包含特殊字元的情況。
• 注意：無法使用 $VAR 環境變數替換 (除非顯式呼叫 shell)。

---

7.1.3 常見最佳實務

1. 組合命令：減少層數

每一個 RUN 指令都會新建一層映像檔。為了減少映像檔體積和層數，應使用 && 連線命令。

❌ 糟糕的寫法 (建立 3 層)：

RUN apt-get update
RUN apt-get install -y nginx
RUN rm -rf /var/lib/apt/lists/*

✅ 推薦寫法 (建立 1 層)：

RUN apt-get update && \
    apt-get install -y nginx && \
    rm -rf /var/lib/apt/lists/*

2. 清理快取

在安裝完軟體後，立即清除快取，可以顯著減小映像檔體積。

• Debian/Ubuntu: docker RUN apt-get update && apt-get install -y package-bar \ && rm -rf /var/lib/apt/lists/*

• Alpine: docker RUN apk add --no-cache package-bar

3. 使用 set -e 和 pipefail

預設情況下，管道命令 cmd1 | cmd2 的返回值由最後一個命令 (cmd2) 決定，即使前面的命令失敗了，整個 RUN 仍可能視為成功。

❌ 隱蔽的錯誤：

## 如果下載失敗，gzip 可能會報錯，但如果不影響後續，構建可能繼續

RUN wget http://error-url | gzip -d > file

✅ 推薦寫法：

SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN wget http://url | gzip -d > file

---

7.1.4 常見問題

Q：為什麼 RUN cd /app 不生效？

RUN cd /app
RUN touch hello.txt

結果：hello.txt 會出現在根目錄 /，而不是 /app。原因：每個 RUN 都在一個新的 Shell/容器環境中執行。cd 隻影響當前 RUN 的環境。解決：使用 WORKDIR 指令。

WORKDIR /app
RUN touch hello.txt

Q：環境變數不生效？

RUN export MY_VAR=hello
RUN echo $MY_VAR

結果：輸出為空。原因：同上，環境變數只在當前 RUN 有效。解決：使用 ENV 指令，或在同一行 RUN 中匯出。

ENV MY_VAR=hello
RUN echo $MY_VAR

---

7.1.5 高階技巧

1. 使用 BuildKit 的掛載快取

BuildKit 支援在 RUN 指令中使用 --mount 掛載快取，加速構建。

## 快取 apt 包

RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y gcc

## 快取 Go 模組

RUN --mount=type=cache,target=/go/pkg/mod \
    go build -o app

2. 掛載金鑰

安全地使用 SSH 金鑰或 Token，而不將其記錄在映像檔中。

RUN --mount=type=secret,id=mysecret \
    cat /run/secrets/mysecret

3. Heredoc 語法

BuildKit 支援使用 heredoc 語法編寫多行指令碼，無需行末反斜槓 \ 連線：

RUN <<EOF
apt-get update
apt-get install -y \
  build-essential \
  curl \
  git
rm -rf /var/lib/apt/lists/*
EOF

優勢：

• 可讀性更強，不需要在每行末尾新增 \
• 避免在指令碼中轉義引號
• 支援多個 heredoc 塊，可指定不同的 Shell

RUN <<EOF
echo "使用預設 /bin/sh"
EOF

RUN <<'EOF'
#!/bin/bash
set -euo pipefail
echo "使用 bash"
wget http://example.com/file.tar.gz
EOF

使用 heredoc 需要在 Dockerfile 首行宣告 BuildKit 語法版本：# syntax=docker/dockerfile:1

---

7.2 COPY 複製檔案

何時使用 COPY

COPY 是在構建映像檔時，將構建上下文（Dockerfile 所在目錄及其子目錄）中的檔案或目錄複製到容器內的指令。它是處理應用程式碼、配置檔案最常用的方式。

典型情境：

• 複製應用原始碼：COPY . /app
• 複製配置檔案：COPY nginx.conf /etc/nginx/nginx.conf
• 複製靜態資源：COPY public /app/public

為什麼 COPY 比 ADD 更值得推薦？ 筆者建議在 90% 的情況下使用 COPY。原因是 COPY 的語義更清晰——它就是簡單地複製檔案。而 ADD 有額外的功能（自動解壓、支援 URL），這些功能往往會帶來意外的行為。除非你明確需要 ADD 的自動解壓功能，否則用 COPY。詳見 7.3 ADD 指令 中的詳細對比。

7.2.1 基本語法

COPY [選項] <源路徑>... <目標路徑>
COPY [選項] ["<源路徑1>", "<源路徑2>", ... "<目標路徑>"]

COPY 指令將構建上下文中的檔案或目錄複製到映像檔內。

---

7.2.2 基本用法

複製單個檔案

## 複製檔案到指定目錄

COPY package.json /app/

## 複製檔案並重新命名

COPY config.json /app/settings.json

複製多個檔案

## 複製多個指定檔案

COPY package.json package-lock.json /app/

## 使用萬用字元

COPY *.json /app/
COPY src/*.js /app/src/

複製目錄

## 複製整個目錄的內容（不是目錄本身）

COPY src/ /app/src/

⚠️ 注意：複製目錄時，複製的是目錄的 內容，不包含目錄本身。

構建上下文：              映像檔內：
src/                     /app/src/
├── index.js      →      ├── index.js
└── utils.js             └── utils.js

---

7.2.3 萬用字元規則

COPY 支援 Go 的 filepath.Match 萬用字元規則：

萬用字元	說明	示例
*	匹配任意字元序列	*.json
?	匹配單個字元	config?.json
[abc]	匹配括號內任一字元	[abc].txt
[a-z]	匹配範圍內字元	file[0-9].txt

COPY hom* /mydir/       # home.txt, homework.md 等
COPY hom?.txt /mydir/   # home.txt, homy.txt 等
COPY app[0-9].js /app/  # app0.js ~ app9.js

---

7.2.4 目標路徑

絕對路徑

COPY app.js /usr/src/app/

相對路徑：基於 WORKDIR

WORKDIR /app
COPY package.json ./        # 複製到 /app/package.json
COPY src/ ./src/            # 複製到 /app/src/

自動建立目錄

如果目標目錄不存在，Docker 會自動建立：

## /app/config/ 不存在也會自動建立

COPY settings.json /app/config/

---

7.2.5 修改檔案所有者

使用 --chown 選項設定檔案的使用者和組：

## 使用使用者名稱和組名

COPY --chown=node:node package.json /app/

## 使用 UID 和 GID

COPY --chown=1000:1000 . /app/

## 只指定使用者

COPY --chown=node . /app/

💡 結合 USER 指令使用，確保應用以非 root 使用者執行。

---

7.2.6 保留檔案後設資料

COPY 會保留原始檔的後設資料：

• 讀、寫、執行許可權
• 修改時間

這對於指令碼檔案特別重要：

## start.sh 的可執行許可權會被保留

COPY start.sh /app/

---

7.2.7 COPY vs ADD

特性	COPY	ADD
複製本地檔案	✅	✅
自動解壓 tar	❌	✅
支援 URL	❌	✅ (不推薦)
推薦程度	✅ 推薦	⚠️ 特殊情境使用

## 推薦：使用 COPY

COPY app.tar.gz /app/
RUN tar -xzf /app/app.tar.gz

## ADD 會自動解壓（行為不明顯，不推薦）

ADD app.tar.gz /app/

筆者建議：除非需要自動解壓 tar 檔案，否則始終使用 COPY。明確的行為比隱式的魔法更好。

---

7.2.8 多階段構建中的 COPY

從其他構建階段複製

## 構建階段

FROM node:22 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

## 生產階段

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

使用 --link 最佳化快取

## 使用 --link 後，檔案以獨立層新增，不依賴前序指令

COPY --link --from=builder /app/dist /usr/share/nginx/html

--link 的優勢：

• 更高效利用構建快取
• 並行化構建過程
• 加速多階段構建

⚠️ 注意：使用 --link 需要滿足以下條件： - 啟用 BuildKit（Docker Engine 23.0+ 預設啟用） - Dockerfile 語法版本 1.4 或更高（在首行宣告 # syntax=docker/dockerfile:1） - 目標路徑在前序指令中應不存在或為空目錄

---

7.2.9 dockerignore

使用 .dockerignore 排除不需要複製的檔案：

## .dockerignore

node_modules
.git
.env
*.log
Dockerfile
.dockerignore

這可以：

• 減小構建上下文大小
• 加速構建
• 避免複製敏感檔案

---

7.2.10 最佳實務

1. 利用快取，先複製依賴檔案

## ✅ 好：先複製依賴定義，再安裝，最後複製程式碼

COPY package.json package-lock.json ./
RUN npm install
COPY . .

## ❌ 差：一次性複製所有檔案，程式碼變更會導致重新 npm install

COPY . .
RUN npm install

2. 使用 .dockerignore

## 確保 node_modules 不被複制

COPY . .

## .dockerignore 中應包含 node_modules

...

3. 明確複製路徑

## ✅ 好：明確的路徑

COPY src/ /app/src/
COPY package.json /app/

## ❌ 差：過於寬泛

COPY . .

---

🔥 踩坑實錄

某公司在最佳化 Node.js 應用的 Docker 映像檔時，發現構建出來的映像檔體積超過了 2GB，遠遠超過生產部署的需求。排查發現，Dockerfile 中使用了 COPY . . 把整個構建上下文複製進映像檔，導致 node_modules/、.git/ 目錄和大量測試資料全部被打包進映像檔。最初他們沒有建立 .dockerignore 檔案，預設會複製所有檔案。解決方案是新增一個 .dockerignore 檔案，排除這些不必要的目錄，使映像檔縮小到了 200MB。這個教訓深刻地說明了：.dockerignore 和 .gitignore 一樣重要，應該在專案初始化時就建立，而不是等到出現問題時才想起來。建議的標準做法是先複製 package.json 和 package-lock.json 安裝依賴，再複製應用程式碼，同時在 .dockerignore 中明確列出 node_modules、.git、test 目錄等。

7.3 ADD 更高階的複製檔案

何時使用 ADD？何時用 COPY？

在開始前，讓我們直言不諱：在大多數情況下，你應該使用 COPY，而不是 ADD。

ADD 在 COPY 基礎上增加了兩個額外功能，但這些功能往往引入複雜性而非便利：

1. 自動解壓 tar 壓縮包（有時你想複製一個 .tar.gz 本身，而 ADD 會意外地解壓它）
2. 支援從 URL 下載檔案（這個功能由於網路不穩定已被廣泛認為是反模式）

實踐中的建議：除非你明確需要自動解壓功能（比如官方基礎映像檔構建根檔案系統），否則始終使用 COPY。原因很簡單——顯式優於隱式。你的 Dockerfile 在 6 個月後被接手維護時，清晰的意圖會讓團隊少走很多彎路。

7.3.1 基本語法

ADD [選項] <源路徑>... <目標路徑>
ADD [選項] ["<源路徑>", ... "<目標路徑>"]

ADD 在 COPY 基礎上增加了兩個功能：

1. 自動解壓 tar 壓縮包
2. 支援從 URL 下載檔案 (不推薦)

---

7.3.2 ADD vs COPY 詳細對比

特性	COPY	ADD
複製本地檔案	✅	✅
自動解壓 tar	❌	✅
支援 URL	❌	✅ (不推薦)
行為可預測性	✅ 高	⚠️ 低
推薦程度	✅ 優先使用	僅解壓情境

筆者建議：除非需要自動解壓 tar 檔案，否則始終使用 COPY。明確的行為比隱式的魔法更好。

---

7.3.3 自動解壓功能

基本用法：自動解壓本地 tar

## 自動解壓 tar.gz 到目標目錄

ADD app.tar.gz /app/

ADD 會識別並解壓以下格式：

• .tar
• .tar.gz / .tgz
• .tar.bz2 / .tbz2
• .tar.xz / .txz

實際應用

官方基礎映像檔通常使用 ADD 解壓根檔案系統：

FROM scratch
ADD ubuntu-noble-core-cloudimg-amd64-root.tar.gz /

解壓過程

ADD app.tar.gz /app/
        │
        ├─ 識別 .tar.gz 格式
        ├─ 自動解壓
        └─ 內容放入 /app/

app.tar.gz 包含：        /app/ 目錄結果：
├── src/                 ├── src/
│   └── main.py          │   └── main.py
└── config.json          └── config.json

---

7.3.4 URL 下載功能：不推薦

基本用法

## 從 URL 下載檔案

ADD https://example.com/app.zip /app/app.zip

為什麼不推薦

問題	說明
許可權固定	下載的檔案許可權為 600，通常需要額外 RUN 修改
不會解壓	URL 下載的壓縮包不會自動解壓
快取問題	URL 內容變化時不會重新下載
層數增加	需要額外 RUN 清理

推薦替代方案

## ❌ 不推薦：使用 ADD 下載

ADD https://example.com/app.tar.gz /tmp/
RUN tar -xzf /tmp/app.tar.gz -C /app && rm /tmp/app.tar.gz

## ✅ 推薦：使用 RUN + curl

RUN curl -fsSL https://example.com/app.tar.gz | tar -xz -C /app

優勢：

• 一條 RUN 完成下載、解壓、清理
• 減少映像檔層數
• 更清晰的構建意圖

---

7.3.5 修改檔案所有者

ADD --chown=node:node app.tar.gz /app/
ADD --chown=1000:1000 files/ /app/

---

7.3.6 何時使用 ADD

✅ 適合使用 ADD

## 解壓本地 tar 檔案

FROM scratch
ADD rootfs.tar.gz /

## 解壓應用包

ADD dist.tar.gz /app/

❌ 不適合使用 ADD

## 複製普通檔案（用 COPY）

ADD package.json /app/          # ❌
COPY package.json /app/         # ✅

## 下載檔案（用 RUN + curl）

ADD https://example.com/file /  # ❌
RUN curl -fsSL ... -o /file     # ✅

## 需要保留 tar 不解壓（用 COPY）

ADD archive.tar.gz /archives/   # ❌ 會解壓
COPY archive.tar.gz /archives/  # ✅ 保持原樣

---

7.3.7 快取行為

ADD 可能導致構建快取失效：

## 如果 app.tar.gz 內容變化，此層及後續層都需重建

ADD app.tar.gz /app/
RUN npm install

最佳化建議：

## 先複製依賴檔案

COPY package*.json /app/
RUN npm install

## 再新增應用程式碼

ADD app.tar.gz /app/

---

7.3.8 最佳實務

1. 預設使用 COPY

## ✅ 大多數情境使用 COPY

COPY . /app/

2. 僅在需要解壓時使用 ADD

## ✅ 自動解壓情境

ADD app.tar.gz /app/

3. 不要用 ADD 下載檔案

## ❌ 避免

ADD https://example.com/file.tar.gz /tmp/

## ✅ 推薦

RUN curl -fsSL https://example.com/file.tar.gz | tar -xz -C /app

4. 解壓後清理

## 如果需要控制解壓過程

COPY app.tar.gz /tmp/
RUN tar -xzf /tmp/app.tar.gz -C /app && \
    rm /tmp/app.tar.gz

---

7.4 CMD 容器啟動命令

何時使用 CMD，何時使用 ENTRYPOINT？

在深入 CMD 的細節之前，我們需要理解一個關鍵問題：CMD 和 ENTRYPOINT 應該在什麼時候使用？

這是 Dockerfile 使用中最常見的困惑之一。簡單的答案是：

• CMD：定義容器的“預設命令”。如果使用者在 docker run 時提供命令，CMD 會被覆蓋
• ENTRYPOINT：定義容器的“入口指令碼”。通常用於啟動應用的某個特定部分

決策樹：

1. 你的容器是否有不可變的啟動邏輯？ 比如需要先做一些初始化工作，然後才執行應用 → 使用 ENTRYPOINT
2. 使用者經常會在 docker run 時傳入不同的命令嗎？ → 使用 CMD（讓使用者靈活覆蓋）
3. 大多數情況下，你希望容器始終以相同的方式啟動？ → 使用 ENTRYPOINT

更多細節見 7.5 ENTRYPOINT 指令。

7.4.1 什麼是 CMD

CMD 指令用於指定容器啟動時預設執行的命令。它定義了容器的 “主程序”。

核心概念：容器的生命週期 = 主程序的生命週期。CMD 指定的命令就是這個主程序。

---

7.4.2 語法格式

CMD 有三種格式：

格式	語法	推薦程度
exec 格式	CMD ["可執行檔案", "引數1", "引數2"]	✅推薦
shell 格式	CMD 命令 引數1 引數2	⚠️ 簡單情境
引數格式	CMD ["引數1", "引數2"]	配合 ENTRYPOINT

exec 格式：推薦

CMD ["nginx", "-g", "daemon off;"]
CMD ["python", "app.py"]
CMD ["node", "server.js"]

優點：

• 直接執行指定程式，是容器的 PID 1
• 正確接收訊號 (如 SIGTERM)
• 無需 shell 解析

shell 格式

CMD echo "Hello World"
CMD nginx -g "daemon off;"

實際執行：會被包裝為 sh -c

## 你寫的

CMD echo $HOME

## 實際執行的

CMD ["sh", "-c", "echo $HOME"]

優點：可以使用環境變數、管道等 shell 特性

缺點：主程序是 sh，訊號無法正確傳遞給應用

---

7.4.3 exec 格式 vs shell 格式

特性	exec 格式	shell 格式
主程序	指定的程式	/bin/sh
訊號傳遞	✅ 正確	❌ 無法傳遞
環境變數	❌ 需要 shell 包裝	✅ 自動解析
推薦使用	✅ 大多數情境	需要 shell 特性時

訊號傳遞問題示例

## ❌ shell 格式：docker stop 會超時

CMD node server.js

## 實際是 sh -c "node server.js"

## SIGTERM 發給 sh，不會傳遞給 node

## ✅ exec 格式：docker stop 正常工作

CMD ["node", "server.js"]

## SIGTERM 直接發給 node

...

---

7.4.4 執行時覆蓋 CMD

docker run 後的命令會覆蓋 Dockerfile 中的 CMD：

## ubuntu 預設 CMD 是 /bin/bash

$ docker run -it ubuntu        # 進入 bash
$ docker run ubuntu cat /etc/os-release  # 覆蓋為 cat 命令

Dockerfile:              docker run 命令:
CMD ["/bin/bash"]   +    cat /etc/os-release
        │                        │
        └───────► 被覆蓋 ◄───────┘
                    ↓
           執行: cat /etc/os-release

---

7.4.5 經典錯誤：容器立即退出

錯誤示例

## ❌ 容器啟動後立即退出

CMD service nginx start

原因分析

1. CMD service nginx start
   ↓ 被轉換為
2. CMD ["sh", "-c", "service nginx start"]
   ↓
3. sh 啟動，執行 service 命令
   ↓
4. service 命令將 nginx 放到後臺
   ↓
5. service 命令結束，sh 退出
   ↓
6. 容器主程序（sh）退出 → 容器停止

正確做法

## ✅ 讓 nginx 在前臺執行

CMD ["nginx", "-g", "daemon off;"]

---

7.4.6 CMD vs ENTRYPOINT

指令	用途	執行時行為
CMD	預設命令	docker run 引數會 覆蓋 它
ENTRYPOINT	入口點	docker run 引數會 追加 到它後面

單獨使用 CMD

## Dockerfile

CMD ["curl", "-s", "http://example.com"]

$ docker run myimage              # 執行預設命令
$ docker run myimage curl -v ...  # 完全覆蓋

搭配 ENTRYPOINT

## Dockerfile

ENTRYPOINT ["curl", "-s"]
CMD ["http://example.com"]

$ docker run myimage              # curl -s http://example.com
$ docker run myimage http://other.com  # curl -s http://other.com（引數覆蓋）

詳見 ENTRYPOINT 入口點章節。

---

7.4.7 最佳實務

1. 優先使用 exec 格式

## ✅ 推薦

CMD ["python", "app.py"]

## ⚠️ 僅在需要 shell 特性時使用

CMD ["sh", "-c", "echo $PATH && python app.py"]

2. 確保應用在前臺執行

## ✅ 前臺執行

CMD ["nginx", "-g", "daemon off;"]
CMD ["apache2ctl", "-D", "FOREGROUND"]
CMD ["java", "-jar", "app.jar"]

## ❌ 不要使用後臺服務命令

CMD service nginx start
CMD systemctl start nginx

3. 使用雙引號

## ✅ 正確：雙引號

CMD ["node", "server.js"]

## ❌ 錯誤：單引號（JSON 不支援）

CMD ['node', 'server.js']

4. 配合 ENTRYPOINT 使用

## 用於可配置引數的情境

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8080"]

## 執行時可以覆蓋埠

$ docker run myapp --port 9000

...

---

7.4.8 常見問題

Q：CMD 可以寫多個嗎？

不可以。多個 CMD 只有最後一個生效：

CMD ["echo", "first"]
CMD ["echo", "second"]  # 只有這個生效

Q：如何在 CMD 中使用環境變數？

## 方法1：使用 shell 格式

CMD echo "Port is $PORT"

## 方法2：顯式使用 sh -c

CMD ["sh", "-c", "echo Port is $PORT"]

Q：為什麼我的容器不響應 Ctrl+C？

可能是使用了 shell 格式，訊號被 sh 吃掉了：

## ❌ 訊號無法傳遞

CMD python app.py

## ✅ 訊號正確傳遞

CMD ["python", "app.py"]

---

7.5 ENTRYPOINT 入口點

何時使用 ENTRYPOINT：從“容器”到“命令”

如果說 CMD 是“容器中的預設程式”，那麼 ENTRYPOINT 就是“把容器變成一個命令”。這個思維轉變決定了你何時使用 ENTRYPOINT。

使用 ENTRYPOINT 的典型情境：

1. 命令列工具：你想讓映像檔像 curl 或 wget 一樣使用 dockerfile ENTRYPOINT ["curl"] # docker run myimage http://example.com → curl http://example.com

2. 應用啟動指令碼：你有一個初始化指令碼，需要接收命令列引數 dockerfile ENTRYPOINT ["/app/entrypoint.sh"] # docker run myimage --debug → /app/entrypoint.sh --debug

3. 與 CMD 結合：ENTRYPOINT 定義入口，CMD 定義預設引數 dockerfile ENTRYPOINT ["python", "app.py"] CMD ["--port", "8000"] # docker run myimage → python app.py --port 8000 # docker run myimage --port 9000 → python app.py --port 9000

對比 CMD：如果沒有這些“把容器當命令用”的需求，通常使用 CMD 就足夠了。

7.5.1 什麼是 ENTRYPOINT

ENTRYPOINT 指定容器啟動時執行的入口程式。與 CMD 不同，ENTRYPOINT 定義的命令不會被 docker run 的引數覆蓋，而是 接收這些引數。

核心作用：讓映像檔像一個可執行程式一樣使用，docker run 的引數作為這個程式的引數。

---

7.5.2 語法格式

格式	語法	推薦程度
exec 格式	ENTRYPOINT ["可執行檔案", "引數1"]	✅推薦
shell 格式	ENTRYPOINT 命令 引數	⚠️ 不推薦

## exec 格式（推薦）

ENTRYPOINT ["nginx", "-g", "daemon off;"]

## shell 格式（不推薦）

ENTRYPOINT nginx -g "daemon off;"

---

7.5.3 ENTRYPOINT vs CMD

核心區別

特性	ENTRYPOINT	CMD
定位	固定的入口程式	預設引數
docker run 引數	追加為引數	完全覆蓋
覆蓋方式	--entrypoint	直接指定命令
適用情境	把映像檔當命令用	提供預設行為

行為對比

## 只用 CMD

CMD ["curl", "-s", "http://example.com"]

$ docker run myimage              # curl -s http://example.com
$ docker run myimage -v           # 執行 -v（錯誤！）
$ docker run myimage curl -v ...  # curl -v ...（完全替換）

## 只用 ENTRYPOINT

ENTRYPOINT ["curl", "-s"]

$ docker run myimage                      # curl -s（缺引數）
$ docker run myimage http://example.com   # curl -s http://example.com ✓

## ENTRYPOINT + CMD 組合（推薦）

ENTRYPOINT ["curl", "-s"]
CMD ["http://example.com"]

$ docker run myimage                      # curl -s http://example.com（預設）
$ docker run myimage http://other.com     # curl -s http://other.com ✓
$ docker run myimage -v http://other.com  # curl -s -v http://other.com ✓

---

7.5.4 情境一：讓映像檔像命令一樣使用

需求：啟動前準備

建立一個查詢公網 IP 的 “命令” 映像檔。

使用 CMD 的問題

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
CMD ["curl", "-s", "http://myip.ipip.net"]

$ docker run myip           # ✓ 正常工作
當前 IP：61.148.226.66

$ docker run myip -i        # ✗ 錯誤！
exec: "-i": executable file not found

## -i 替換了整個 CMD，被當作可執行檔案

...

使用 ENTRYPOINT 解決

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["curl", "-s", "http://myip.ipip.net"]

$ docker run myip           # ✓ 正常工作
當前 IP：61.148.226.66

$ docker run myip -i        # ✓ 新增 -i 引數
HTTP/1.1 200 OK
...
當前 IP：61.148.226.66

互動圖示

ENTRYPOINT ["curl", "-s", "http://myip.ipip.net"]
            │
docker run myip -i
            │
            ▼
curl -s http://myip.ipip.net -i
└─────────────────────────────┘
     ENTRYPOINT + docker run 引數

---

7.5.5 情境二：啟動前的準備工作

需求

在啟動主服務前執行初始化指令碼 (如資料庫遷移、許可權設定)。

實現方式

# 建議使用 redis:7 或 redis:latest，具體版本號根據生產需求選擇
FROM redis:7-alpine
COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["redis-server"]

docker-entrypoint.sh：

#!/bin/sh
set -e

## 準備工作

echo "Initializing..."

## 如果第一個引數是 redis-server，以 redis 使用者執行

if [ "$1" = 'redis-server' ]; then
    chown -R redis:redis /data
    exec gosu redis "$@"
fi

## 其他命令直接執行

exec "$@"

工作流程

docker run redis                    docker run redis bash
        │                                    │
        ▼                                    ▼
docker-entrypoint.sh redis-server   docker-entrypoint.sh bash
        │                                    │
        ├─ 初始化                            ├─ 初始化
        ├─ chown -R redis:redis /data        │
        └─ exec gosu redis redis-server      └─ exec bash
           (以 redis 使用者執行)                  (以 root 使用者執行)

關鍵點

1. exec “$@”：用傳入的引數替換當前程序，確保訊號正確傳遞
2. 條件判斷：根據 CMD 不同執行不同邏輯
3. 使用者切換：使用 gosu 切換使用者 (比 su 更適合容器)

---

7.5.6 情境三：帶引數的應用

# 建議使用 python:3.12 或 python:3，具體版本號根據應用相容性需求選擇
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

ENTRYPOINT ["python", "app.py"]
CMD ["--host", "0.0.0.0", "--port", "8080"]

## 使用預設引數

$ docker run myapp

## 執行: python app.py --host 0.0.0.0 --port 8080

## 覆蓋引數

$ docker run myapp --host 0.0.0.0 --port 9000

## 執行: python app.py --host 0.0.0.0 --port 9000

## 完全不同的引數

$ docker run myapp --help

## 執行: python app.py --help

...

---

7.5.7 覆蓋 ENTRYPOINT

使用 --entrypoint 引數覆蓋：

## 正常執行

$ docker run myimage

## 覆蓋 ENTRYPOINT 進入 shell 除錯

$ docker run --entrypoint /bin/sh myimage

## 覆蓋 ENTRYPOINT 並傳入引數

$ docker run --entrypoint /bin/cat myimage /etc/os-release

---

7.5.8 ENTRYPOINT 與 CMD 組合表

ENTRYPOINT	CMD	最終執行命令
無	無	無 (容器無法啟動)
無	["cmd", "p1"]	cmd p1
["ep", "p1"]	無	ep p1
["ep", "p1"]	["cmd", "p2"]	ep p1 cmd p2
ep p1 (shell)	["cmd", "p2"]	/bin/sh -c "ep p1" (CMD 被忽略)

⚠️ 注意：shell 格式的 ENTRYPOINT 會忽略 CMD！

---

7.5.9 最佳實務

1. 使用 exec 格式

## ✅ 推薦

ENTRYPOINT ["python", "app.py"]

## ❌ 避免 shell 格式

ENTRYPOINT python app.py

2. 提供有意義的預設引數

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

3. 入口指令碼使用 exec

#!/bin/sh

## 準備工作...

## 使用 exec 替換當前程序

exec "$@"

4. 處理訊號

確保 ENTRYPOINT 指令碼能正確傳遞訊號：

#!/bin/bash
trap 'kill -TERM $PID' TERM INT

## 啟動應用

app "$@" &
PID=$!

## 等待應用退出

wait $PID

---

7.6 ENV 設定環境變數

7.6.1 基本語法

## 格式一：單個變數

ENV <key> <value>

## 格式二：多個變數（推薦）

ENV <key1>=<value1> <key2>=<value2> ...

---

7.6.2 基本用法

設定單個變數

ENV NODE_VERSION 20
ENV APP_ENV production

設定多個變數

ENV NODE_VERSION=20 \
    APP_ENV=production \
    APP_NAME="My Application"

💡 包含空格的值用雙引號括起來。

---

7.6.3 環境變數的作用

1. 後續指令中使用

ENV NODE_VERSION=20.10.0

## 在 RUN 中使用

RUN curl -fsSL https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz \
    | tar -xJ -C /usr/local --strip-components=1

## 在 WORKDIR 中使用

ENV APP_HOME=/app
WORKDIR $APP_HOME

## 在 COPY 中使用

COPY . $APP_HOME

2. 容器執行時使用

ENV DATABASE_URL=postgres://localhost/mydb

應用程式碼中可以讀取：

import os
db_url = os.environ.get('DATABASE_URL')

const dbUrl = process.env.DATABASE_URL;

---

7.6.4 支援環境變數的指令

以下指令可以使用 $變數名 或 ${變數名} 格式：

指令	示例
RUN	RUN echo $VERSION
CMD	CMD ["sh", "-c", "echo $HOME"]
ENTRYPOINT	同上
COPY	COPY . $APP_HOME
ADD	ADD app.tar.gz $APP_HOME
WORKDIR	WORKDIR $APP_HOME
EXPOSE	EXPOSE $PORT
VOLUME	VOLUME $DATA_DIR
USER	USER $USERNAME
LABEL	LABEL version=$VERSION
FROM	FROM node:$NODE_VERSION

---

7.6.5 執行時覆蓋

使用 -e 或 --env 覆蓋 Dockerfile 中定義的環境變數：

## 覆蓋單個變數

$ docker run -e APP_ENV=development myimage

## 覆蓋多個變數

$ docker run -e APP_ENV=development -e DEBUG=true myimage

## 從環境變數檔案讀取

$ docker run --env-file .env myimage

.env 檔案格式

## .env

APP_ENV=development
DEBUG=true
DATABASE_URL=postgres://localhost/mydb

---

7.6.6 ENV vs ARG

特性	ENV	ARG
生效時間	構建時 + 執行時	僅構建時
永續性	寫入映像檔，執行時可用	構建後消失
覆蓋方式	docker run -e	docker build --build-arg
適用情境	應用配置	構建引數 (如版本號)

組合使用

## ARG 接收構建時引數

ARG NODE_VERSION=20

## ENV 儲存到執行時

ENV NODE_VERSION=$NODE_VERSION

## 後續指令使用

RUN curl -fsSL https://nodejs.org/dist/v${NODE_VERSION}/...

## 構建時指定版本

$ docker build --build-arg NODE_VERSION=18 -t myapp .

---

7.6.7 最佳實務

1. 統一管理版本號

## ✅ 好：版本集中管理

ENV NGINX_VERSION=1.30 \
    NODE_VERSION=22 \
    PYTHON_VERSION=3.12

RUN apt-get install nginx=${NGINX_VERSION}

## ❌ 差：版本分散在各處

RUN apt-get install nginx=1.30

2. 不要儲存敏感資訊

## ❌ 錯誤：密碼寫入映像檔

ENV DB_PASSWORD=secret123

## ✅ 正確：執行時傳入

## docker run -e DB_PASSWORD=xxx myimage

...

3. 為應用提供合理預設值

ENV APP_ENV=production \
    APP_PORT=8080 \
    LOG_LEVEL=info

4. 使用有意義的變數名

## ✅ 好：清晰的命名

ENV REDIS_HOST=localhost \
    REDIS_PORT=6379

## ❌ 差：模糊的命名

ENV HOST=localhost \
    PORT=6379

---

7.6.8 常見問題

Q：環境變數在 CMD 中不展開

exec 格式不會自動展開環境變數：

## ❌ 不會展開 $PORT

CMD ["python", "app.py", "--port", "$PORT"]

## ✅ 使用 shell 格式或顯式呼叫 sh

CMD ["sh", "-c", "python app.py --port $PORT"]

Q：如何檢視容器的環境變數

$ docker inspect mycontainer --format '{{json .Config.Env}}'
$ docker exec mycontainer env

Q：多行 ENV 還是多個 ENV

## ✅ 推薦：減少層數

ENV VAR1=value1 \
    VAR2=value2 \
    VAR3=value3

## ⚠️ 多個 ENV 會建立多層

ENV VAR1=value1
ENV VAR2=value2
ENV VAR3=value3

---

7.7 ARG 構建引數

7.7.1 基本語法

ARG <引數名>[=<預設值>]

ARG 指令定義構建時的變數，可以在 docker build 時透過 --build-arg 傳入。

---

7.7.2 ARG vs ENV

特性	ARG	ENV
生效時間	僅構建時	構建時 + 執行時
永續性	構建後消失	寫入映像檔
覆蓋方式	docker build --build-arg	docker run -e
適用情境	構建引數 (版本號等)	應用配置
可見性	docker history 可見	docker inspect 可見

構建時                         執行時
├─ ARG VERSION=1.0             │ （ARG 已消失）
├─ ENV APP_ENV=prod            │ APP_ENV=prod（仍存在）
└─ RUN echo $VERSION           │

⚠️ 安全提示：不要用 ARG 傳遞密碼等敏感資訊，docker history 可以檢視所有 ARG 值。

---

7.7.3 基本用法

定義和使用

## 定義有預設值的 ARG
## 建議使用主版本號，如 20 而非 20.10.0，這樣可以自動獲取最新的補丁版本

ARG NODE_VERSION=20

## 使用 ARG

FROM node:${NODE_VERSION}-alpine
RUN echo "Using Node.js $NODE_VERSION"

構建時覆蓋

## 使用預設值

$ docker build -t myapp .

## 覆蓋預設值

$ docker build --build-arg NODE_VERSION=18 -t myapp .

---

7.7.4 ARG 的作用域

FROM 之前的 ARG

## FROM 之前的 ARG 只能用於 FROM 指令

ARG REGISTRY=docker.io
ARG IMAGE_NAME=node

FROM ${REGISTRY}/${IMAGE_NAME}:20

## ❌ 這裡無法使用上面的 ARG

RUN echo $REGISTRY  # 輸出空

FROM 之後重新宣告

ARG NODE_VERSION=20

FROM node:${NODE_VERSION}-alpine

## 需要再次宣告才能使用

ARG NODE_VERSION
RUN echo "Node version: $NODE_VERSION"

多階段構建中的 ARG

ARG BASE_VERSION=alpine

FROM node:22-${BASE_VERSION} AS builder

## 需要重新宣告

ARG NODE_VERSION=20
RUN echo "Building with Node $NODE_VERSION"

FROM node:22-${BASE_VERSION}

## 每個階段都需要重新宣告

ARG NODE_VERSION=20
RUN echo "Running with Node $NODE_VERSION"

---

7.7.5 常見使用情境

1. 控制基礎映像檔版本

# 推薦使用主版本號（如 3），或指定次版本號（如 3.19），避免指定完整補丁版本
ARG ALPINE_VERSION=3
FROM alpine:${ALPINE_VERSION}

$ docker build --build-arg ALPINE_VERSION=3.19 .

2. 設定軟體版本

# 使用次版本號 (1.30) 而非完整版本號 (1.30.0)，以便自動更新到最新補丁版本
ARG NGINX_VERSION=1.30

RUN curl -fsSL https://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz | tar -xz

3. 配置構建環境

ARG BUILD_ENV=production
ARG ENABLE_DEBUG=false

RUN if [ "$ENABLE_DEBUG" = "true" ]; then \
        npm install --include=dev; \
    else \
        npm install --production; \
    fi

4. 配置私有倉庫

ARG NPM_TOKEN

RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc && \
    npm install && \
    rm ~/.npmrc

## 構建時傳入 token

$ docker build --build-arg NPM_TOKEN=xxx .

---

7.7.6 將 ARG 傳遞給 ENV

如果需要在執行時使用 ARG 的值：

ARG VERSION=1.0.0

## 將 ARG 傳遞給 ENV

ENV APP_VERSION=$VERSION

## 執行時可用

CMD echo "App version: $APP_VERSION"

---

7.7.7 預定義 ARG

Docker 提供了一些預定義的 ARG，無需宣告即可使用：

ARG	說明
HTTP_PROXY	HTTP 代理
HTTPS_PROXY	HTTPS 代理
NO_PROXY	不使用代理的地址
FTP_PROXY	FTP 代理

## 構建時使用代理

$ docker build --build-arg HTTP_PROXY=http://proxy:8080 .

---

7.7.8 最佳實務

1. 為 ARG 提供合理預設值

## ✅ 好：有預設值，建議使用主或次版本號而非完整版本號

ARG NODE_VERSION=20

## ⚠️ 需要每次傳入

ARG NODE_VERSION

2. 不要用 ARG 儲存敏感資訊

## ❌ 錯誤：密碼會被記錄在映像檔歷史中

ARG DB_PASSWORD
RUN echo "password=$DB_PASSWORD" > /app/.env

## ✅ 正確：使用 secrets 或執行時環境變數

...

3. 使用 ARG 提高構建靈活性

# 推薦使用次版本號標籤，允許Docker自動拉取最新的補丁版本
ARG BASE_IMAGE=python:3.12-slim
FROM ${BASE_IMAGE}

## 可以構建不同基礎映像檔的版本

## docker build --build-arg BASE_IMAGE=python:3-slim .

...

---

7.8 VOLUME 定義匿名卷

7.8.1 基本語法

VOLUME ["/路徑1", "/路徑2"]
VOLUME /路徑

VOLUME 指令建立掛載點，並標記為外部掛載的卷。

---

7.8.2 為什麼使用 VOLUME

核心原則：容器儲存層應該保持無狀態，任何執行時資料都應該儲存在卷中。

flowchart LR
    subgraph NoVolume ["沒有 VOLUME："]
        direction TB
        subgraph Container1 ["容器儲存層"]
            direction TB
            Files["資料庫檔案 (問題)<br/>日誌檔案<br/>上傳檔案"]
        end
        Result1["容器刪除 = 資料丟失"]
        Container1 ~~~ Result1
    end

    subgraph UseVolume ["使用 VOLUME："]
        direction TB
        Container2["容器儲存層<br/>（只讀/無狀態）"]
        subgraph Volume ["資料卷"]
            Data["持久化資料 (安全)"]
        end
        Container2 --> Volume
        Result2["容器刪除，資料保留"]
        Volume ~~~ Result2
    end

---

7.8.3 基本用法

定義單個卷

FROM mysql:8.4
VOLUME /var/lib/mysql

定義多個卷

FROM myapp
VOLUME ["/data", "/logs", "/config"]

---

7.8.4 VOLUME 的行為

1. 自動建立匿名卷

如果執行時未指定掛載，Docker 會自動建立匿名卷：

$ docker run mysql:8.4
$ docker volume ls
DRIVER    VOLUME NAME
local     a1b2c3d4e5f6...  # 自動建立的匿名卷

2. 可被命名卷覆蓋

## 使用命名卷替代匿名卷

$ docker run -v mysql_data:/var/lib/mysql mysql:8.4

3. 可被 Bind Mount 覆蓋

## 使用宿主機目錄替代

$ docker run -v /my/data:/var/lib/mysql mysql:8.4

---

7.8.5 VOLUME 在構建時的特殊行為

⚠️ 重要：VOLUME 之後對該目錄的修改會被丟棄！

FROM ubuntu
VOLUME /data

## ❌ 這個檔案不會出現在映像檔中！

RUN echo "hello" > /data/test.txt

原因：在構建過程中，VOLUME 指令會為該目錄建立一個臨時的匿名卷。後續 RUN 指令對該目錄的寫入實際發生在這個臨時卷中，而非映像檔層。當該 RUN 指令結束後，臨時卷被丟棄，因此寫入的內容不會儲存到最終映像檔中。注意：這與容器執行時建立的匿名卷是不同的——執行時建立的卷會在容器生命週期內持續存在。

正確做法

FROM ubuntu

## ✅ 先寫入檔案

RUN mkdir -p /data && echo "hello" > /data/test.txt

## 再宣告 VOLUME

VOLUME /data

---

7.8.6 常見使用情境

資料庫持久化

# 建議使用 postgres:16 或 postgres:latest，具體版本號根據資料庫相容性需求選擇
FROM postgres:16
VOLUME /var/lib/postgresql/data

日誌目錄

FROM nginx
VOLUME /var/log/nginx

上傳檔案目錄

FROM myapp
VOLUME /app/uploads

---

7.8.7 檢視 VOLUME 定義

## 檢視映像檔定義的 VOLUME

$ docker inspect mysql:8.4 --format '{{json .Config.Volumes}}' | jq
{
  "/var/lib/mysql": {}
}

## 檢視容器掛載的卷

$ docker inspect mycontainer --format '{{json .Mounts}}' | jq

---

7.8.8 VOLUME vs docker run -v

特性	Dockerfile VOLUME	docker run -v
定義時機	映像檔構建時	容器執行時
預設行為	建立匿名卷	可指定命名卷或路徑
靈活性	低 (固定路徑)	高 (可任意指定)
適用情境	定義必須持久化的路徑	靈活的資料管理

---

7.8.9 在 Compose 中

在 Compose 中配置如下：

services:
  db:
    # 建議使用 postgres:16 或其他具體版本，避免 latest
    image: postgres:16
    volumes:
      # 命名卷（推薦）

      - postgres_data:/var/lib/postgresql/data
      # Bind Mount

      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  postgres_data:  # 宣告命名卷

---

7.8.10 安全注意事項

匿名卷可能導致資料丟失

## 使用 --rm 執行的容器，匿名卷會在容器刪除時一起刪除

$ docker run --rm mysql:8.4

## 容器停止後，資料丟失！

...

解決：始終使用命名卷

$ docker run -v mysql_data:/var/lib/mysql mysql:8.4

---

7.8.11 最佳實務

1. 定義必須持久化的路徑

## 資料庫必須使用卷

FROM postgres:16
VOLUME /var/lib/postgresql/data

2. 不要在 VOLUME 後修改目錄

## ❌ 避免

VOLUME /app/data
RUN cp init-data.json /app/data/

## ✅ 正確

RUN mkdir -p /app/data && cp init-data.json /app/data/
VOLUME /app/data

3. 文件中說明 VOLUME 用途

## 持久化使用者上傳的檔案

VOLUME /app/uploads

## 持久化資料庫資料

VOLUME /var/lib/mysql

---

7.9 EXPOSE 暴露埠

7.9.1 基本語法

EXPOSE <埠> [<埠>/<協議>...]

EXPOSE 宣告容器執行時提供服務的埠。這是一個 文件性質的宣告，告訴使用者容器會監聽哪些埠。

---

7.9.2 基本用法

## 宣告單個埠

EXPOSE 80

## 宣告多個埠

EXPOSE 80 443

## 宣告 TCP 和 UDP 埠

EXPOSE 80/tcp
EXPOSE 53/udp

---

7.9.3 EXPOSE 的作用

1. 文件說明

告訴映像檔使用者，容器將在哪些埠提供服務：

## 使用者一看就知道這是 web 應用

EXPOSE 80 443

## 檢視映像檔暴露的埠

$ docker inspect nginx --format '{{.Config.ExposedPorts}}'
map[80/tcp:{}]

2. 配合 -P 使用

使用 docker run -P 時，Docker 會自動對映 EXPOSE 的埠到宿主機隨機埠：

## Dockerfile

EXPOSE 80

$ docker run -P nginx
$ docker port $(docker ps -q)
80/tcp -> 0.0.0.0:32768

---

7.9.4 EXPOSE vs -p

特性	EXPOSE	-p
位置	Dockerfile	docker run 命令
作用	宣告/文件	實際埠對映
是否必需	否	是 (外部訪問時)
對映發生時	不發生	執行時發生

flowchart TD
    Expose["EXPOSE 80<br/>僅宣告意圖"]
    Run["docker run -p<br/>實際埠對映<br/>宿主機 ←→ 容器"]
    Expose ~~~ Run

沒有 EXPOSE 也能 -p

## 即使沒有 EXPOSE，也可以使用 -p

FROM nginx

## 沒有 EXPOSE

...

## 仍然可以對映埠

$ docker run -p 8080:80 mynginx

---

7.9.5 常見誤解

誤解：EXPOSE 會開啟埠

## ❌ 錯誤理解：這不會讓容器可從外部訪問

EXPOSE 80

EXPOSE 不會：

• 自動進行埠對映
• 讓服務可從外部訪問
• 在容器啟動時開啟埠監聽

EXPOSE 只是後設資料宣告。容器是否實際監聽該埠，取決於容器內的應用。

正確理解

## Dockerfile

FROM nginx
EXPOSE 80    # 1. 宣告：這個容器會在 80 埠提供服務

## 執行：需要 -p 才能從外部訪問

$ docker run -p 8080:80 nginx    # 2. 對映：宿主機 8080 → 容器 80

---

7.9.6 最佳實務

1. 總是宣告應用使用的埠

## Web 服務

FROM nginx
EXPOSE 80 443

## 資料庫

FROM postgres
EXPOSE 5432

## Redis

FROM redis
EXPOSE 6379

2. 使用明確的協議

## 預設是 TCP

EXPOSE 80

## 明確指定 UDP

EXPOSE 53/udp

## 同時支援 TCP 和 UDP

EXPOSE 53/tcp 53/udp

3. 與應用實際埠保持一致

## ✅ 好：EXPOSE 與應用埠一致

ENV PORT=3000
EXPOSE 3000
CMD ["node", "server.js"]

## ❌ 差：EXPOSE 與應用埠不一致（誤導）

EXPOSE 80
CMD ["node", "server.js"]  # 實際監聽 3000

---

7.9.7 使用環境變數

ARG PORT=80
EXPOSE $PORT

---

7.9.8 在 Compose 中

在 Compose 中配置如下：

services:
  web:
    build: .
    ports:
      - "8080:80"    # 對映埠（類似 -p）
    expose:
      - "80"         # 僅宣告（類似 EXPOSE）

expose 在 Compose 中僅用於容器間通訊的文件說明，不進行埠對映。

---

7.10 WORKDIR 指定工作目錄

7.10.1 基本語法

WORKDIR <工作目錄路徑>

WORKDIR 指定後續指令的工作目錄。如果目錄不存在，Docker 會自動建立。

---

7.10.2 基本用法

WORKDIR /app

RUN pwd          # 輸出 /app
RUN echo "hello" > world.txt    # 建立 /app/world.txt
COPY . .         # 複製到 /app/

---

7.10.3 為什麼需要 WORKDIR

常見錯誤

## ❌ 錯誤：cd 在下一個 RUN 中無效

RUN cd /app
RUN echo "hello" > world.txt    # 檔案在根目錄！

原因分析

RUN cd /app
    ↓
啟動容器 → cd /app（僅記憶體變化）→ 提交映像檔層 → 容器銷燬
                                   │
                                   ↓ 工作目錄未改變！
RUN echo "hello" > world.txt
    ↓
啟動新容器（工作目錄在 /）→ 建立 /world.txt

每個 RUN 都在新容器中執行，前一個 RUN 的記憶體狀態 (包括工作目錄) 不會保留。

正確做法

## ✅ 正確：使用 WORKDIR

WORKDIR /app
RUN echo "hello" > world.txt    # 建立 /app/world.txt

---

7.10.4 相對路徑

WORKDIR 支援相對路徑，基於上一個 WORKDIR：

WORKDIR /a
WORKDIR b
WORKDIR c

RUN pwd    # 輸出 /a/b/c

---

7.10.5 使用環境變數

ENV APP_HOME=/app
WORKDIR $APP_HOME

RUN pwd    # 輸出 /app

---

7.10.6 多階段構建中的 WORKDIR

## 構建階段
## 建議使用 node:22 或 node: 等具體版本標籤，避免使用 latest

FROM node:22 AS builder
WORKDIR /build
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

## 生產階段
## 建議使用 nginx:alpine 或其他具體版本

FROM nginx:alpine
WORKDIR /usr/share/nginx/html
COPY --from=builder /build/dist .

---

7.10.7 最佳實務

1. 儘早設定 WORKDIR

# 建議使用 node:22 等主/次版本號標籤
FROM node:22
WORKDIR /app    # 儘早設定

COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

2. 使用絕對路徑

## ✅ 推薦：絕對路徑，意圖明確

WORKDIR /app

## ⚠️ 避免：相對路徑可能造成混淆

WORKDIR app

3. 不要用 RUN cd

## ❌ 避免

RUN cd /app && echo "hello" > world.txt

## ✅ 推薦

WORKDIR /app
RUN echo "hello" > world.txt

4. 適時重置 WORKDIR

WORKDIR /app

## ... 應用相關操作 ...

WORKDIR /data

## ... 資料相關操作 ...

...

---

7.10.8 與其他指令的關係

指令	WORKDIR 的影響
RUN	在 WORKDIR 中執行命令
CMD	在 WORKDIR 中啟動
ENTRYPOINT	在 WORKDIR 中啟動
COPY	相對目標路徑基於 WORKDIR
ADD	相對目標路徑基於 WORKDIR

WORKDIR /app

RUN pwd                    # /app
COPY . .                   # 複製到 /app
CMD ["./start.sh"]         # /app/start.sh

---

7.10.9 執行時覆蓋

使用 -w 引數覆蓋工作目錄：

$ docker run -w /tmp myimage pwd
/tmp

---

7.11 USER 指定當前使用者

7.11.1 基本語法

USER <使用者名稱>[:<使用者組>]
USER <UID>[:<GID>]

USER 指令切換後續指令 (RUN、CMD、ENTRYPOINT) 的執行使用者。

---

7.11.2 為什麼要使用 USER

筆者強調：以非 root 使用者執行容器是最重要的安全實踐之一。

flowchart LR
    subgraph Root ["root 使用者執行的風險："]
        direction TB
        R_C["容器內 root"] -- 可能逃逸 --> R_H["宿主機 root"]
        R_C -- 漏洞利用 --> R_Control["完全控制宿主機"]
    end

    subgraph NonRoot ["非 root 使用者執行："]
        direction TB
        NR_C["容器內普通使用者"] -- 逃逸後 --> NR_H["宿主機普通使用者"]
        NR_C -- 許可權受限，危害降低 --> NR_Safe["無法控制系統"]
    end

---

7.11.3 基本用法

建立並切換使用者

FROM node:22-alpine

## 1. 建立使用者和組

RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -D appuser

## 2. 設定目錄許可權

WORKDIR /app
COPY --chown=appuser:appgroup . .

## 3. 切換使用者

USER appuser

## 4. 後續命令以 appuser 身份執行

CMD ["node", "server.js"]

使用 UID/GID

## 也可以使用數字

USER 1001:1001

---

7.11.4 使用者必須已存在

USER 指令只能切換到 已存在 的使用者：

## ❌ 錯誤：使用者不存在

USER nonexistent

## Error: unable to find user nonexistent

## ✅ 正確：先建立使用者

RUN useradd -r -s /bin/false appuser
USER appuser

建立使用者的方式

Debian/Ubuntu：

RUN groupadd -r appgroup && \
    useradd -r -g appgroup appuser

Alpine：

RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S -G appgroup appuser

選項	說明
-r (useradd) / -S (adduser)	建立系統使用者
-g	指定主組
-G	指定附加組
-u	指定 UID
-s /bin/false	禁用登入 shell

---

7.11.5 執行時切換使用者

使用 gosu：推薦

在 ENTRYPOINT 指令碼中切換使用者時，不要使用 su 或 sudo，應使用 gosu：

FROM debian:bookworm

## 建立使用者

RUN groupadd -r redis && useradd -r -g redis redis

## 安裝 gosu

RUN apt-get update && apt-get install -y gosu && rm -rf /var/lib/apt/lists/*

COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["redis-server"]

docker-entrypoint.sh：

#!/bin/bash
set -e

## 以 root 執行初始化

chown -R redis:redis /data

## 用 gosu 切換到 redis 使用者執行服務

exec gosu redis "$@"

為什麼不用 su/sudo

問題	su/sudo	gosu
TTY 要求	需要	不需要
訊號傳遞	不正確	正確
子程序	是	exec 替換
容器中使用	❌	✅

---

7.11.6 執行時覆蓋使用者

使用 -u 或 --user 引數：

## 以指定使用者執行

$ docker run -u 1001:1001 myimage

## 以 root 執行（除錯時）

$ docker run -u root myimage

---

7.11.7 檔案許可權處理

切換使用者後，確保應用有權訪問檔案：

FROM node:22-alpine

## 建立使用者

RUN adduser -D -u 1001 appuser

WORKDIR /app

## 方式1：使用 --chown

COPY --chown=appuser:appuser . .

## 方式2：手動 chown（減少層數）

## COPY . .

## RUN chown -R appuser:appuser /app

USER appuser
CMD ["node", "server.js"]

---

7.11.8 最佳實務

1. 始終使用非 root 使用者

## ✅ 推薦

RUN adduser -D appuser
USER appuser
CMD ["myapp"]

## ❌ 避免

CMD ["myapp"]  # 以 root 執行

2. 使用固定 UID/GID

便於在宿主機和容器間共享檔案：

## 使用常見的非 root UID

RUN addgroup -g 1000 -S appgroup && \
    adduser -u 1000 -S -G appgroup appuser
USER 1000:1000

3. 多階段構建中的 USER

## 構建階段可以用 root

FROM node:22 AS builder
WORKDIR /app
COPY . .
RUN npm install && npm run build

## 生產階段用非 root

FROM node:22-alpine
RUN adduser -D appuser
WORKDIR /app
COPY --from=builder --chown=appuser:appuser /app/dist .
USER appuser
CMD ["node", "server.js"]

---

7.11.9 常見問題

Q：許可權被拒絕

permission denied: '/app/data.log'

解決：確保目錄許可權正確

RUN mkdir -p /app/data && chown appuser:appuser /app/data

Q：無法繫結低於 1024 的埠

非 root 使用者無法繫結 80、443 等埠。

解決：

1. 使用高階口 (如 8080)
2. 在執行時對映埠：docker run -p 80:8080

---

7.12 HEALTHCHECK 健康檢查

7.12.1 基本語法

HEALTHCHECK [選項] CMD <命令>
HEALTHCHECK NONE

HEALTHCHECK 指令告訴 Docker 如何判斷容器狀態是否正常。這是保障服務高可用的重要機制。

---

7.12.2 為什麼需要 HEALTHCHECK

在沒有 HEALTHCHECK 之前，Docker 只能透過 程序退出碼 來判斷容器狀態。問題情境：

• Web 服務死鎖，無法響應請求，但程序仍在執行
• 資料庫正在啟動中，尚未準備好接受連線
• 應用陷入死迴圈，CPU 爆滿但程序存活

引入 HEALTHCHECK 後： Docker 定期執行指定的檢查命令，根據返回值判斷容器是否 “健康”。

容器狀態轉換：
Starting ──成功──> Healthy ──失敗N次──> Unhealthy
                    ▲                │
                    └──────成功──────┘

---

7.12.3 基本用法

Web 服務檢查

# 注：nginx 映像檔推薦使用具體的版本標籤（如 nginx:1.28-alpine）
FROM nginx
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -fs http://localhost/ || exit 1

命令返回值

• 0：成功 (healthy)
• 1：失敗 (unhealthy)
• 2：保留值 (不使用)

常用選項

選項	說明	預設值
--interval	兩次檢查的間隔	30s
--timeout	檢查命令的超時時間	30s
--start-period	啟動緩衝期 (期間失敗不計入次數)	0s
--retries	連續失敗多少次標記為 unhealthy	3

---

7.12.4 遮蔽健康檢查

如果基礎映像檔定義了 HEALTHCHECK，但你不想使用它：

FROM my-base-image
HEALTHCHECK NONE

---

7.12.5 常見檢查指令碼

HTTP 服務

使用 curl 或 wget：

## 使用 curl

HEALTHCHECK CMD curl -f http://localhost/ || exit 1

## 使用 wget（Alpine 預設包含）

HEALTHCHECK CMD wget -q --spider http://localhost/ || exit 1

資料庫

## MySQL

HEALTHCHECK CMD mysqladmin ping -h localhost || exit 1

## Redis

HEALTHCHECK CMD redis-cli ping || exit 1

自定義指令碼

COPY healthcheck.sh /usr/local/bin/
HEALTHCHECK CMD ["healthcheck.sh"]

---

7.12.6 在 Compose 中使用

可以在 compose.yaml (或 docker-compose.yml) 中覆蓋或定義健康檢查：

services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s

帶健康檢查的依賴啟動：

services:
  web:
    depends_on:
      db:
        condition: service_healthy  # 等待 db 變健康才啟動 web
  db:
    image: mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]

---

7.12.7 檢視健康狀態

## 檢視容器狀態（包含健康資訊）

$ docker ps
CONTAINER ID   STATUS
abc123         Up 1 minute (healthy)
def456         Up 2 minutes (unhealthy)

## 檢視詳細健康日誌

$ docker inspect --format '{{json .State.Health}}' mycontainer | jq
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "...",
      "End": "...",
      "ExitCode": 0,
      "Output": "..."
    }
  ]
}

---

7.12.8 最佳實務

1. 避免副作用

健康檢查會被頻繁執行，不要在檢查指令碼中進行寫操作或消耗大量資源的操作。

2. 使用輕量級工具

優先使用映像檔中已有的工具 (如 wget)，避免為了健康檢查安裝龐大的依賴 (如 curl)。

3. 設定合理的 Start Period

應用啟動可能需要時間 (如 Java 應用)。設定 --start-period 可以防止在啟動階段因檢查失敗而誤判。

## 給應用 1 分鐘啟動時間

HEALTHCHECK --start-period=60s CMD curl -f http://localhost/ || exit 1

4. 只檢查核心依賴

健康檢查應主要關注 當前服務 是否可用，而不是檢查其下游依賴 (資料庫等)。下游依賴的檢查應由應用邏輯處理。

5. 與容器編排平臺的關係

不同平臺對 HEALTHCHECK 的支援有所不同：

• Docker Compose：直接使用 Dockerfile 中定義的 HEALTHCHECK，也可在 compose.yaml 中覆蓋
• Docker Swarm：使用 HEALTHCHECK 進行服務健康判斷和滾動更新決策
• Kubernetes：忽略 Dockerfile 中的 HEALTHCHECK，使用自己的 livenessProbe 和 readinessProbe 機制

如果應用同時部署在 Docker Compose 和 Kubernetes 環境中，建議在 Dockerfile 中保留 HEALTHCHECK（供 Compose 使用），同時在 Kubernetes 的 Pod 配置中定義對應的探針。

---

7.13 ONBUILD 為他人作嫁衣裳

7.13.1 基本語法

ONBUILD <其它指令>

ONBUILD 是一個特殊的指令，它後面跟的是其它指令 (如 RUN，COPY 等)，這些指令 在當前映像檔構建時不會執行，只有當以當前映像檔為基礎映像檔去構建下一級映像檔時才會被執行。

---

7.13.2 為什麼需要 ONBUILD

ONBUILD 主要用於製作 語言棧基礎映像檔 或 框架基礎映像檔。

情境：維護 Node.js 專案

假設你有多個 Node.js 專案，它們的構建流程都一樣：

1. 建立目錄
2. 複製 package.json
3. 執行 npm install
4. 複製原始碼
5. 啟動應用

如果不使用 ONBUILD，每個專案的 Dockerfile 都要重複這些步驟，且透過 COPY 複製檔案時，基礎映像檔無法預知子專案的檔名。

使用 ONBUILD 的解決方案

基礎映像檔 (my-node-base)：

FROM node:22-alpine
WORKDIR /app

## 這些指令將在子映像檔構建時執行

ONBUILD COPY package*.json ./
ONBUILD RUN npm install
ONBUILD COPY . .

CMD ["npm", "start"]

子專案 Dockerfile：

FROM my-node-base

## 只需要一行！

## 構建時會自動執行 COPY 和 RUN

...

---

7.13.3 執行機制

基礎映像檔構建：
Dockerfile (含 ONBUILD) ──build──> 基礎映像檔 (記錄了 ONBUILD 觸發器)
                                    (指令未執行)

子映像檔構建：
FROM 基礎映像檔 ──build──> 讀取基礎映像檔觸發器 ──> 執行觸發器指令 ──> 繼續執行子 Dockerfile

---

7.13.4 常見使用情境

1. 自動處理依賴安裝

## Python 基礎映像檔

ONBUILD COPY requirements.txt ./
ONBUILD RUN pip install -r requirements.txt

2. 自動編譯程式碼

## Go 基礎映像檔

ONBUILD COPY . .
ONBUILD RUN go build -o app main.go

3. 處理靜態資源

## Nginx 靜態網站基礎映像檔

ONBUILD COPY dist/ /usr/share/nginx/html/

---

7.13.5 注意事項

1. 繼承性限制

ONBUILD 指令 只會繼承一次。

• 映像檔 A (含 ONBUILD)
• 映像檔 B (FROM A) -> 觸發 ONBUILD
• 映像檔 C (FROM B) -> 不會 再次觸發 ONBUILD

2. 構建上下文

子映像檔構建時，ONBUILD COPY . . 中的 . 指的是 子專案 的構建上下文，而不是基礎映像檔的上下文。

3. 不允許級聯

ONBUILD ONBUILD 是非法的。你不能寫 ONBUILD ONBUILD COPY ...。

4. 可能會導致構建失敗

由於 ONBUILD 實際上是在子映像檔中執行指令，如果子專案的上下文不滿足要求 (例如缺少 package.json)，會導致子映像檔構建失敗，且錯誤資訊可能比較隱晦。

---

7.13.6 最佳實務

1. 命名規範

建議在映像檔標籤中新增 -onbuild 字尾，明確告知使用者該映像檔包含觸發器。

node:22-onbuild
python:3.12-onbuild

2. 避免執行耗時操作

儘量不要在 ONBUILD 中執行過於耗時或不確定的操作 (如更新系統軟體)，這會讓子映像檔構建變得緩慢且不可控。

3. 清理工作

如果 ONBUILD 指令產生了臨時檔案，最好在同一個指令鏈中清理，或者提供機制讓子映像檔清理。

---

7.14 LABEL 為映像檔新增後設資料

7.14.1 基本語法

LABEL <key>=<value> <key>=<value> ...

LABEL 指令以鍵值對的形式給映像檔新增後設資料。這些資料不會影響映像檔的功能，但可以幫助使用者理解映像檔，或被自動化工具使用。

---

7.14.2 為什麼需要 LABEL

1. 版本管理：記錄版本號、構建時間、Git Commit ID
2. 聯絡資訊：維護者郵箱、文件地址、支援渠道
3. 自動化工具：CI/CD 工具可以讀取標籤觸發操作
4. 許可證資訊：宣告開源協議

---

7.14.3 基本用法

定義單個標籤

LABEL version="1.0"
LABEL description="這是一個 Web 應用伺服器"

定義多個標籤：推薦

LABEL maintainer="[email protected]" \
      version="1.2.0" \
      description="My App Description" \
      org.opencontainers.image.authors="Yeasy"

💡 包含空格的值需要用引號括起來。

---

7.14.4 常用標籤規範

為了標準和互操作性，推薦使用 OCI Image Format Specification 定義的標準標籤：

標籤 Key	說明	示例
org.opencontainers.image.created	構建時間(RFC 3339)	2024-01-01T00:00:00Z
org.opencontainers.image.authors	作者/維護者	[email protected]
org.opencontainers.image.url	專案主頁	https://example.com
org.opencontainers.image.documentation	文件地址	https://example.com/docs
org.opencontainers.image.source	原始碼倉庫	https://github.com/user/repo
org.opencontainers.image.version	版本號	1.0.0
org.opencontainers.image.licenses	許可證	MIT
org.opencontainers.image.title	映像檔標題	My App
org.opencontainers.image.description	描述	Production ready web server

示例

LABEL org.opencontainers.image.authors="yeasy" \
      org.opencontainers.image.documentation="https://yeasy.gitbooks.io" \
      org.opencontainers.image.source="https://github.com/yeasy/docker_practice" \
      org.opencontainers.image.licenses="MIT"

---

7.14.5 MAINTAINER 指令：已廢棄

舊版本的 Dockerfile 中常看到 MAINTAINER 指令：

## ❌ 已棄用

MAINTAINER [email protected]

現在推薦使用 LABEL：

## ✅ 推薦

LABEL maintainer="[email protected]"

## 或

LABEL org.opencontainers.image.authors="[email protected]"

---

7.14.6 動態標籤

配合 ARG 使用，可以在構建時動態注入標籤：

ARG BUILD_DATE
ARG VCS_REF

LABEL org.opencontainers.image.created=$BUILD_DATE \
      org.opencontainers.image.revision=$VCS_REF

構建命令：

$ docker build \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  .

---

7.14.7 檢視標籤

docker inspect

檢視映像檔的標籤資訊：

$ docker inspect nginx --format '{{json .Config.Labels}}' | jq
{
  "maintainer": "NGINX Docker Maintainers <[email protected]>"
}

過濾器

可以使用標籤過濾映像檔：

## 列出作者是 yeasy 的所有映像檔

$ docker images --filter "label=org.opencontainers.image.authors=yeasy"

## 刪除所有帶有特定標籤的映像檔

$ docker rmi $(docker images -q --filter "label=stage=builder")

---

7.15 SHELL 指令

7.15.1 基本語法

SHELL ["executable", "parameters"]

SHELL 指令允許覆蓋 Docker 預設的 shell。

• Linux 預設：["/bin/sh", "-c"]
• Windows 預設：["cmd", "/S", "/C"]

該指令會影響後續的 RUN，CMD，ENTRYPOINT 指令 (當它們使用 shell 格式時)。

---

7.15.2 為什麼要用 SHELL 指令

1. 使用 bash 特性

預設的 /bin/sh (通常是 dash 或 alpine 的 ash) 功能有限。如果你需要使用 bash 的特有功能 (如陣列、{} 擴充套件、pipefail 等)，可以切換 shell。

FROM ubuntu:24.04

## 切換到 bash

SHELL ["/bin/bash", "-c"]

## 現在可以使用 bash 特性了

RUN echo {a..z}

2. 增強錯誤處理

預設情況下，管道命令 cmd1 | cmd2 只要 cmd2 成功，整個指令就視為成功。這可能掩蓋構建錯誤。

## ❌ 這裡的 wget 失敗了，但構建繼續（因為 tar 成功了）

RUN wget -O - https://invalid-url | tar xz

使用 SHELL 啟用 pipefail：

## ✅ 啟用 pipefail

SHELL ["/bin/bash", "-o", "pipefail", "-c"]

## 如果 wget 失敗，整個 RUN 就會失敗

RUN wget -O - https://invalid-url | tar xz

3. Windows 環境

在 Windows 容器中，經常需要在 cmd 和 powershell 之間切換。

FROM mcr.microsoft.com/windows/servercore:ltsc2022

## 預設是 cmd

RUN echo Default shell is cmd

## 切換到 powershell

SHELL ["powershell", "-command"]
RUN Write-Host "Hello from PowerShell"

## 切回 cmd

SHELL ["cmd", "/S", "/C"]

---

7.15.3 作用範圍

SHELL 指令可以出現多次，每次隻影響其後的指令：

FROM ubuntu:24.04

## 使用預設 sh

RUN echo "Using sh"

SHELL ["/bin/bash", "-c"]

## 使用 bash

RUN echo "Using bash"

SHELL ["/bin/sh", "-c"]

## 回到 sh

RUN echo "Using sh again"

---

7.15.4 對其他指令的影響

SHELL 影響的是所有使用 shell 格式 的指令：

指令格式	是否受 SHELL 影響
RUN command	✅ 是
RUN ["exec", "param"]	❌ 否
CMD command	✅ 是
CMD ["exec", "param"]	❌ 否
ENTRYPOINT command	✅ 是
ENTRYPOINT ["exec", "param"]	❌ 否

---

7.15.5 最佳實務

1. 推薦開啟 pipefail

對於使用 bash 的映像檔，強烈建議開啟 pipefail，以確保構建過程中的錯誤能被及時捕獲。

SHELL ["/bin/bash", "-o", "pipefail", "-c"]

2. 明確意圖

如果由於指令碼需求必須更改 shell，最好在 Dockerfile 中顯式宣告，而不是依賴預設行為。

3. 儘量保持一致

避免在 Dockerfile 中頻繁切換 SHELL，這會使構建過程難以理解和除錯。儘量在頭部定義一次即可。

---

7.16 參考文件

官方文件

• Dockerfile 官方參考手冊：https://docs.docker.com/engine/reference/builder/

• Dockerfile 最佳實務指南：https://docs.docker.com/develop/develop-images/dockerfile_best-practices/

• Docker 官方映像檔 Dockerfile 庫：https://github.com/docker-library/docs

常用指令總結

Dockerfile 中的常用指令包括：

• FROM: 指定基礎映像檔，必須是第一條指令
• RUN: 在映像檔中執行命令，用於安裝軟體包等
• COPY: 複製檔案到映像檔中
• ADD: 更高階的複製檔案（支援 URL 和自動解壓）
• CMD: 容器預設執行的命令
• ENTRYPOINT: 容器啟動時的入口點
• ENV: 設定環境變數
• ARG: 構建時的引數變數
• VOLUME: 定義匿名卷掛載點
• EXPOSE: 宣告容器監聽的埠
• WORKDIR: 設定工作目錄
• USER: 指定執行容器時的使用者
• HEALTHCHECK: 配置容器健康檢查
• ONBUILD: 設定觸發器指令，在子映像檔構建時執行
• LABEL: 為映像檔新增後設資料標籤
• SHELL: 指定 RUN 等指令使用的 shell

最佳實務建議

1. 使用具體的基礎映像檔版本標籤而非 latest
2. 最小化映像檔層數，合併 RUN 指令
3. 使用 .dockerignore 檔案排除不必要的檔案
4. 安裝必要的軟體包後清理快取
5. 使用多階段構建減小最終映像檔體積
6. 避免以 root 身份執行容器應用

相關資源

• Docker 官方映像檔庫：https://hub.docker.com/
• Docker 映像檔構建最佳實務：https://docs.docker.com/build/building/best-practices/

7.17 多階段構建

在 Docker 17.05 版本之前，我們構建 Docker 映像檔時，通常會採用兩種方式：

7.17.1 全部放入一個 Dockerfile

一種方式是將所有的構建過程包含在一個 Dockerfile 中，包括專案及其依賴庫的編譯、測試、打包等流程，這裡可能會帶來的一些問題：

• 映像檔層次多，映像檔體積較大，部署時間變長

• 原始碼存在洩露的風險

例如，編寫 app.go 檔案，該程式輸出 Hello World!

package main

import "fmt"

func main(){
    fmt.Printf("Hello World!");
}

編寫 Dockerfile.one 檔案

FROM golang:alpine

RUN apk --no-cache add git ca-certificates

WORKDIR /go/src/github.com/go/helloworld/

COPY app.go .

RUN go mod init helloworld \
  && go get github.com/go-sql-driver/mysql \
  && CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . \
  && cp /go/src/github.com/go/helloworld/app /root

WORKDIR /root/

CMD ["./app"]

構建映像檔

$ docker build -t go/helloworld:1 -f Dockerfile.one .

7.17.2 分散到多個 Dockerfile

另一種方式，就是我們事先在一個 Dockerfile 將專案及其依賴庫編譯測試打包好後，再將其複製到執行環境中，這種方式需要我們編寫兩個 Dockerfile 和一些編譯指令碼才能將其兩個階段自動整合起來，這種方式雖然可以很好地規避第一種方式存在的風險，但明顯部署過程較複雜。

例如，編寫 Dockerfile.build 檔案

FROM golang:alpine

RUN apk --no-cache add git

WORKDIR /go/src/github.com/go/helloworld

COPY app.go .

RUN go mod init helloworld \
  && go get github.com/go-sql-driver/mysql \
  && CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

編寫 Dockerfile.copy 檔案

FROM alpine:3

RUN apk --no-cache add ca-certificates

WORKDIR /root/

COPY app .

CMD ["./app"]

新建 build.sh

#!/bin/sh
echo Building go/helloworld:build

docker build -t go/helloworld:build . -f Dockerfile.build

docker create --name extract go/helloworld:build
docker cp extract:/go/src/github.com/go/helloworld/app ./app
docker rm -f extract

echo Building go/helloworld:2

docker build --no-cache -t go/helloworld:2 . -f Dockerfile.copy
rm ./app

現在執行指令碼即可構建映像檔

$ chmod +x build.sh

$ ./build.sh

對比兩種方式生成的映像檔大小

$ docker image ls

REPOSITORY      TAG    IMAGE ID        CREATED         SIZE
go/helloworld   2      f7cf3465432c    22 seconds ago  6.47MB
go/helloworld   1      f55d3e16affc    2 minutes ago   295MB

7.17.3 使用多階段構建

為解決以上問題，Docker v17.05 開始支援多階段構建 (multistage builds)。使用多階段構建我們就可以很容易解決前面提到的問題，並且只需要編寫一個 Dockerfile：

例如，編寫 Dockerfile 檔案

FROM golang:alpine as builder

RUN apk --no-cache add git

WORKDIR /go/src/github.com/go/helloworld/

RUN go mod init helloworld \
  && go get github.com/go-sql-driver/mysql

COPY app.go .

RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

FROM alpine:3 as prod

RUN apk --no-cache add ca-certificates

WORKDIR /root/

COPY --from=builder /go/src/github.com/go/helloworld/app .

CMD ["./app"]

構建映像檔

$ docker build -t go/helloworld:3 .

對比三個映像檔大小

$ docker image ls

REPOSITORY        TAG   IMAGE ID         CREATED            SIZE
go/helloworld     3     d6911ed9c846     7 seconds ago      6.47MB
go/helloworld     2     f7cf3465432c     22 seconds ago     6.47MB
go/helloworld     1     f55d3e16affc     2 minutes ago      295MB

很明顯使用多階段構建的映像檔體積小，同時也完美解決了上邊提到的問題。

Go Modules 最佳實務：上述示例為簡化演示在 Dockerfile 中臨時執行 go mod init。在實際專案中，通常已在程式碼倉庫中維護好 go.mod 和 go.sum 檔案。推薦的 Dockerfile 寫法是先複製這兩個檔案並執行 go mod download 以利用 Docker 層快取，再複製原始碼並構建：

docker COPY go.mod go.sum ./ RUN go mod download COPY . . RUN go build -o app .

7.17.4 只構建某一階段的映像檔

我們可以使用 as 來為某一階段命名，例如

FROM golang:alpine as builder

例如當我們只想構建 builder 階段的映像檔時，增加 --target=builder 引數即可

$ docker build --target builder -t username/imagename:tag .

7.17.5 構建時從其他映像檔複製檔案

上面例子中我們使用 COPY --from=builder /go/src/github.com/go/helloworld/app . 透過已命名階段（as builder）從上一階段的映像檔中複製檔案（命名引用比 --from=0 這種位置索引更易讀，也是當前官方推薦的最佳實務）；我們也可以複製任意映像檔中的檔案。

COPY --from=nginx:1.28-alpine /etc/nginx/nginx.conf /nginx.conf

7.18 實戰多階段構建 Laravel 映像檔

本節適用於 PHP 開發者閱讀。Laravel 基於 8.x 版本，各個版本的檔案結構可能會有差異，請根據實際自行修改。

7.18.1 準備

新建一個 Laravel 專案或在已有的 Laravel 專案根目錄下新建 Dockerfile .dockerignore laravel.conf 檔案。

在 .dockerignore 檔案中寫入以下內容。

.idea/
.git/

vendor/

node_modules/

public/js/
public/css/
public/mix-manifest.json

yarn-error.log

bootstrap/cache/*
storage/

## 自行新增其他需要排除的檔案，例如 .env.* 檔案

...

在 laravel.conf 檔案中寫入 nginx 配置。

server {
  listen 80 default_server;
  root /app/laravel/public;
  index index.php index.html;

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }

  location ~ .*\.php(\/.*)*$ {
    fastcgi_pass   laravel:9000;
    include        fastcgi.conf;

    # fastcgi_connect_timeout 300;

    # fastcgi_send_timeout 300;

    # fastcgi_read_timeout 300;

  }
}

7.18.2 前端構建

第一階段進行前端構建。

# 注：node 映像檔推薦使用具體的版本標籤（如 node:22-alpine）
FROM node:22-alpine as frontend

COPY package.json /app/

RUN set -x ; cd /app \
      && npm install --registry=https://registry.npmmirror.com

COPY webpack.mix.js webpack.config.js tailwind.config.js /app/
COPY resources/ /app/resources/

RUN set -x ; cd /app \
      && touch artisan \
      && mkdir -p public \
      && npm run production

7.18.3 安裝 Composer 依賴

第二階段安裝 Composer 依賴。

# 注：composer 映像檔推薦使用具體的版本標籤（如 composer:2.x）
FROM composer:2 as composer

COPY database/ /app/database/
COPY composer.json composer.lock /app/

RUN set -x ; cd /app \
      && composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ \
      && composer install \
           --ignore-platform-reqs \
           --no-interaction \
           --no-plugins \
           --no-scripts \
           --prefer-dist

7.18.4 整合以上階段所生成的檔案

第三階段對以上階段生成的檔案進行整合。

# 注：php 映像檔版本號已包含 major.minor（8.3），生產環境可根據需要調整
FROM php:8.3-fpm-alpine as laravel

ARG LARAVEL_PATH=/app/laravel

COPY --from=composer /app/vendor/ ${LARAVEL_PATH}/vendor/
COPY . ${LARAVEL_PATH}
COPY --from=frontend /app/public/js/ ${LARAVEL_PATH}/public/js/
COPY --from=frontend /app/public/css/ ${LARAVEL_PATH}/public/css/
COPY --from=frontend /app/public/mix-manifest.json ${LARAVEL_PATH}/public/mix-manifest.json

RUN set -x ; cd ${LARAVEL_PATH} \
      && mkdir -p storage \
      && mkdir -p storage/framework/cache \
      && mkdir -p storage/framework/sessions \
      && mkdir -p storage/framework/testing \
      && mkdir -p storage/framework/views \
      && mkdir -p storage/logs \
      && chmod -R 777 storage \
      && php artisan package:discover

7.18.5 最後一個階段構建 NGINX 映像檔

# 注：nginx 映像檔推薦使用具體的版本標籤（如 nginx:1.28-alpine）
FROM nginx:1.28-alpine as nginx

ARG LARAVEL_PATH=/app/laravel

COPY laravel.conf /etc/nginx/conf.d/
COPY --from=laravel ${LARAVEL_PATH}/public ${LARAVEL_PATH}/public

7.18.6 構建 Laravel 及 Nginx 映像檔

使用 docker build 命令構建映像檔。

$ docker build -t my/laravel --target=laravel .

$ docker build -t my/nginx --target=nginx .

7.18.7 啟動容器並測試

新建 Docker 網路

$ docker network create laravel

啟動 laravel 容器，--name=laravel 引數設定的名字必須與 nginx 配置檔案中的 fastcgi_pass laravel:9000; 一致

$ docker run -dit --rm --name=laravel --network=laravel my/laravel

啟動 nginx 容器

$ docker run -dit --rm --network=laravel -p 8080:80 my/nginx

瀏覽器訪問 127.0.0.1:8080 可以看到 Laravel 專案首頁。

也許 Laravel 專案依賴其他外部服務，例如 redis、MySQL，請自行啟動這些服務之後再進行測試，本小節不再贅述。

7.18.8 生產環境最佳化

本小節內容為了方便測試，將配置檔案直接放到了映像檔中，實際在使用時 建議 將配置檔案作為 config 或 secret 掛載到容器中，請讀者自行學習 Kubernetes 的相關內容。

由於篇幅所限本小節只是簡單列出，更多內容可以參考 khs1994-docker/laravel-demo 專案。

7.18.9 附錄

完整的 Dockerfile 檔案如下。

# 注：生產環境推薦使用具體的版本標籤，如 node:22-alpine、composer:2.x、php:8.3-fpm-alpine、nginx:1.28-alpine
FROM node:22-alpine as frontend

COPY package.json /app/

RUN set -x ; cd /app \
      && npm install --registry=https://registry.npmmirror.com

COPY webpack.mix.js webpack.config.js tailwind.config.js /app/
COPY resources/ /app/resources/

RUN set -x ; cd /app \
      && touch artisan \
      && mkdir -p public \
      && npm run production

FROM composer:2 as composer

COPY database/ /app/database/
COPY composer.json composer.lock /app/

RUN set -x ; cd /app \
      && composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ \
      && composer install \
           --ignore-platform-reqs \
           --no-interaction \
           --no-plugins \
           --no-scripts \
           --prefer-dist

FROM php:8.3-fpm-alpine as laravel

ARG LARAVEL_PATH=/app/laravel

COPY --from=composer /app/vendor/ ${LARAVEL_PATH}/vendor/
COPY . ${LARAVEL_PATH}
COPY --from=frontend /app/public/js/ ${LARAVEL_PATH}/public/js/
COPY --from=frontend /app/public/css/ ${LARAVEL_PATH}/public/css/
COPY --from=frontend /app/public/mix-manifest.json ${LARAVEL_PATH}/public/mix-manifest.json

RUN set -x ; cd ${LARAVEL_PATH} \
      && mkdir -p storage \
      && mkdir -p storage/framework/cache \
      && mkdir -p storage/framework/sessions \
      && mkdir -p storage/framework/testing \
      && mkdir -p storage/framework/views \
      && mkdir -p storage/logs \
      && chmod -R 777 storage \
      && php artisan package:discover

FROM nginx:1.28-alpine as nginx

ARG LARAVEL_PATH=/app/laravel

COPY laravel.conf /etc/nginx/conf.d/
COPY --from=laravel ${LARAVEL_PATH}/public ${LARAVEL_PATH}/public

本章小結

本章詳細介紹了 Dockerfile 的所有核心指令，以下是各指令要點的速查表。

指令	作用	關鍵要點
FROM	指定基礎映像檔	必須是第一條指令
RUN	在新層執行命令	合併命令、清理快取以減小體積
COPY	複製檔案	優先使用，支援 --from
ADD	更高階的複製	自動解壓 tar，不推薦用於下載
CMD	容器啟動預設命令	可被 docker run 引數覆蓋
ENTRYPOINT	容器入口點	固定啟動命令，CMD 作為預設引數
ENV	設定環境變數	構建時 + 執行時均生效
ARG	構建引數	僅構建時生效，FROM 後需重新宣告
VOLUME	定義匿名卷	VOLUME 之後的修改會丟失
EXPOSE	宣告埠	僅文件作用，不自動對映
WORKDIR	指定工作目錄	替代 RUN cd，目錄不存在會自動建立
USER	指定執行使用者	使用者必須已存在，推薦 gosu
HEALTHCHECK	健康檢查	支援 starting/healthy/unhealthy 狀態
ONBUILD	延遲執行指令	只繼承一次，不可級聯
LABEL	新增後設資料	推薦 OCI 標準標籤，替代 MAINTAINER
SHELL	更改預設 shell	推薦 ["/bin/bash", "-o", "pipefail", "-c"]

生產映像檔快速檢查清單

在將映像檔推向生產之前，建議逐條過一遍以下清單：

• [ ] 基礎映像檔選擇了最小化版本（如 alpine、distroless）
• [ ] 使用了多階段構建，最終映像檔不含編譯工具鏈
• [ ] 以非 root 使用者執行（USER 指令）
• [ ] COPY 優先於 ADD，且僅複製必要檔案
• [ ] RUN 指令合併了 apt-get update && install && rm -rf /var/lib/apt/lists/*
• [ ] 設定了 HEALTHCHECK
• [ ] 使用了 .dockerignore 排除 .git、node_modules 等無關檔案
• [ ] 映像檔標籤使用了具體版本號或 commit hash，而非 latest

更完整的編寫指南見附錄：Dockerfile 最佳實務。

延伸閱讀

• 使用 Dockerfile 定製映像檔：Dockerfile 入門
• 多階段構建：最佳化映像檔大小
• Dockerfile 最佳實務：編寫指南
• 安全：容器安全實踐
• Compose 模板檔案：Compose 中的配置

---

📝 發現錯誤或有改進建議？ 歡迎提交 Issue 或 PR。

8.1 資料卷

8.1.1 為什麼需要資料卷

容器的儲存層有一個關鍵問題：容器刪除後，資料就沒了。

flowchart LR
    Run[容器執行] --> Write[寫入資料]
    Write --> Delete[容器刪除]
    Delete -->|資料都在容器 writable 層| Lost[DATA LOST! ❌]

資料卷 (Volume) 解決了這個問題，它的生命週期獨立於容器。

---

8.1.2 資料卷的特性

特性	說明
持久化	容器刪除後資料仍然保留
共享	多個容器可以掛載同一個資料卷
即時生效	對資料卷的修改立即可見
不影響映像檔	資料卷中的資料不會打包進映像檔
效能更好	繞過 UnionFS，直接讀寫

---

8.1.3 資料卷 vs 容器儲存層

容器儲存層：不推薦儲存重要資料

graph TD
    subgraph Container [容器]
        Writable[容器儲存層<br>Writable]
        Image[映像檔層<br>ReadOnly]
        Writable --- Image
    end

    Lifecycle[生命週期 = 容器生命週期] -.-> Container
    Delete[容器刪除] -->|導致| DataLost[資料丟失 ❌]

資料卷：推薦

graph TD
    subgraph Container [容器]
        AppDir["/app/data"]
    end

    subgraph Volume [資料卷 my-data]
        Data[持久化資料]
    end

    AppDir == 掛載 ==> Volume
    Delete[容器刪除] -.->|不會影響| Volume

---

8.1.4 資料卷基本操作

建立資料卷

$ docker volume create my-vol

列出所有資料卷

$ docker volume ls
DRIVER    VOLUME NAME
local     my-vol
local     postgres_data
local     redis_data

檢視資料卷詳情

$ docker volume inspect my-vol
[
    {
        "CreatedAt": "2026-01-15T10:00:00Z",
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
        "Name": "my-vol",
        "Options": {},
        "Scope": "local"
    }
]

關鍵欄位：

• Mountpoint：資料卷在宿主機上的實際儲存位置
• Driver：儲存驅動 (預設 local，也可以用第三方驅動)

---

8.1.5 掛載資料卷

方式一：--mount：推薦

$ docker run -d \
    --name web \
    --mount source=my-vol,target=/usr/share/nginx/html \
    nginx

引數說明：

引數	說明
source	資料卷名稱 (不存在會自動建立)
target	容器內掛載路徑
readonly	可選，只讀掛載

方式二：-v：簡寫

$ docker run -d \
    --name web \
    -v my-vol:/usr/share/nginx/html \
    nginx

格式：-v 資料卷名:容器路徑[:選項]

兩種方式對比

特性	--mount	-v
語法	鍵值對，更清晰	冒號分隔，更簡潔
資料卷 (Volume) 掛載行為	卷不存在會自動建立，與 -v 結果一致	卷不存在會自動建立
繫結掛載 (Bind Mount) 行為	⭐宿主機路徑不存在會報錯，不會自動建立	宿主機路徑不存在會 自動建立為目錄
推薦程度	✅ 推薦 (更明確安全，避免誤建立)	常用 (更簡潔)

提示：官方更推薦使用 --mount。除了語法格式可讀性更好之外，最重要的行為差異發生在 繫結掛載 (Bind Mount) 時：如果掛載的宿主機源路徑尚未存在，-v 會擅自將其自動建立為一個空目錄；而 --mount 則會嚴格檢查並直接報錯。這能有效避免因路徑拼寫錯誤而在宿主機上留下垃圾目錄（以及導致的容器訪問空目錄問題）。而對於本節的 資料卷 (Volume) 掛載而言，兩者在目標指定的卷不存在時皆會自動建立卷，產生的結果是 完全一致 的。

只讀掛載

## --mount 方式

$ docker run -d \
    --mount source=my-vol,target=/data,readonly \
    nginx

## -v 方式

$ docker run -d \
    -v my-vol:/data:ro \
    nginx

---

8.1.6 使用情境示例

情境一：資料庫持久化

## 建立資料卷

$ docker volume create postgres_data

## 啟動 PostgreSQL，資料儲存在資料卷中

$ docker run -d \
    --name postgres \
    -e POSTGRES_PASSWORD=secret \
    -v postgres_data:/var/lib/postgresql/data \
    postgres:16  # 確保與環境相容的 PostgreSQL 版本

## 即使刪除容器，資料仍然保留

$ docker rm -f postgres

## 重新啟動，資料還在

$ docker run -d \
    --name postgres \
    -e POSTGRES_PASSWORD=secret \
    -v postgres_data:/var/lib/postgresql/data \
    postgres:16  # 確保與環境相容的 PostgreSQL 版本

情境二：多容器共享資料

## 建立共享資料卷

$ docker volume create shared-data

## 容器 A 寫入資料

$ docker run -d --name writer \
    -v shared-data:/data \
    alpine sh -c "while true; do date >> /data/log.txt; sleep 5; done"

## 容器 B 讀取資料

$ docker run --rm \
    -v shared-data:/data \
    alpine cat /data/log.txt

情境三：配置檔案持久化

## 將 nginx 配置儲存在資料卷中

$ docker run -d \
    -v nginx-config:/etc/nginx/conf.d \
    -v nginx-logs:/var/log/nginx \
    -p 80:80 \
    nginx

---

8.1.7 資料卷管理

刪除資料卷

## 刪除指定資料卷

$ docker volume rm my-vol

## 刪除容器時同時刪除資料卷

$ docker rm -v container_name

清理未使用的資料卷

## 檢視未被任何容器使用的資料卷

$ docker volume ls -f dangling=true

## 刪除所有未使用的資料卷

$ docker volume prune

## 強制刪除（不提示確認）

$ docker volume prune -f

⚠️ 注意：資料卷不會自動垃圾回收。長期執行的系統應定期清理無用資料卷。

---

8.1.8 資料卷備份與恢復

備份資料卷

## 使用臨時容器掛載資料卷，打包備份

$ docker run --rm \
    -v my-vol:/source:ro \
    -v $(pwd):/backup \
    alpine tar czf /backup/my-vol-backup.tar.gz -C /source .

原理：

1. 建立臨時容器
2. 掛載要備份的資料捲到 /source
3. 掛載當前目錄到 /backup
4. 使用 tar 打包

恢復資料卷

## 建立新資料卷

$ docker volume create my-vol-restored

## 解壓備份到新資料卷

$ docker run --rm \
    -v my-vol-restored:/target \
    -v $(pwd):/backup:ro \
    alpine tar xzf /backup/my-vol-backup.tar.gz -C /target

備份指令碼示例

#!/bin/bash

## backup-volume.sh

VOLUME_NAME=$1
BACKUP_DIR=${2:-/backups}
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

docker run --rm \
    -v ${VOLUME_NAME}:/source:ro \
    -v ${BACKUP_DIR}:/backup \
    alpine tar czf /backup/${VOLUME_NAME}_${TIMESTAMP}.tar.gz -C /source .

echo "Backed up ${VOLUME_NAME} to ${BACKUP_DIR}/${VOLUME_NAME}_${TIMESTAMP}.tar.gz"

---

8.1.9 資料卷 vs 繫結掛載

Docker 有兩種主要的資料持久化方式：

特性	資料卷 (Volume)	繫結掛載 (Bind Mount)
管理方式	Docker 管理	使用者管理
儲存位置	/var/lib/docker/volumes/	任意宿主機路徑
可移植性	更好	依賴宿主機路徑
適用情境	生產資料持久化	開發時同步程式碼
備份	需要工具	直接訪問檔案

## 資料卷

$ docker run -v mydata:/app/data nginx

## 繫結掛載

$ docker run -v /host/path:/app/data nginx

詳見繫結掛載章節。

---

8.1.10 常見問題

Q：如何知道容器使用了哪些資料卷？

$ docker inspect container_name --format '{{json .Mounts}}' | jq

Q：資料卷的資料在哪裡？

## 檢視資料卷詳情

$ docker volume inspect my-vol

## Mountpoint 欄位顯示實際路徑

"Mountpoint": "/var/lib/docker/volumes/my-vol/_data"

⚠️ 注意：不建議直接修改 Mountpoint 中的檔案，應透過容器操作。

Q：如何在不同機器間遷移資料卷？

1. 在源機器備份：docker run --rm -v mydata:/data -v $(pwd):/backup alpine tar czf /backup/data.tar.gz -C /data .
2. 傳輸 tar.gz 檔案
3. 在目標機器恢復

---