Fix naming of the chapter dir

2026-03-11 04:14:38 +00:00 · 2026-02-22 12:42:15 -08:00
parent b9ac198f19
commit 92ea9623b2
130 changed files with 1001 additions and 852 deletions
--- a/10_buildx/10.1_buildkit.md
+++ b/10_buildx/10.1_buildkit.md
@@ -0,0 +1,170 @@
+## 10.1 使用 `BuildKit` 构建镜像
+
+**BuildKit** 是下一代的镜像构建组件，在 https://github.com/moby/buildkit 开源。
+
+> **重要**：自 Docker 23.0 起，BuildKit 已成为 **默认稳定构建器**，无需手动启用。Docker Engine v29 进一步将 Containerd 镜像存储设为默认，提升与 Kubernetes 的互操作性。
+
+目前，Docker Hub 自动构建已经支持 BuildKit，具体请参考 https://github.com/docker-practice/docker-hub-buildx
+
+### 10.1.1 `Dockerfile` 新增指令详解
+
+BuildKit 引入了多项新指令，旨在优化构建缓存和安全性。以下将详细介绍这些指令的用法。
+
+使用 BuildKit 后，我们可以使用下面几个新的 `Dockerfile` 指令来加快镜像构建。
+
+要使用最新的 Dockerfile 语法特性，建议在 Dockerfile 开头添加语法指令：
+
+```docker
+## syntax=docker/dockerfile:1
+
+```
+
+这将使用最新的稳定版语法解析器，确保你可以使用所有最新特性。
+
+#### `RUN --mount=type=cache`
+
+目前，几乎所有的程序都会使用依赖管理工具，例如 `Go` 中的 `go mod`、`Node.js` 中的 `npm` 等等，当我们构建一个镜像时，往往会重复的从互联网中获取依赖包，难以缓存，大大降低了镜像的构建效率。
+
+例如一个前端工程需要用到 `npm`：
+
+```docker
+FROM node:alpine as builder
+
+WORKDIR /app
+
+COPY package.json /app/
+
+RUN npm i --registry=https://registry.npmmirror.com \
+        && rm -rf ~/.npm
+
+COPY src /app/src
+
+RUN npm run build
+
+FROM nginx:alpine
+
+COPY --from=builder /app/dist /app/dist
+```
+
+使用多阶段构建，构建的镜像中只包含了目标文件夹 `dist`，但仍然存在一些问题，当 `package.json` 文件变动时，`RUN npm i && rm -rf ~/.npm` 这一层会重新执行，变更多次后，生成了大量的中间层镜像。
+
+为解决这个问题，进一步的我们可以设想一个类似 **数据卷** 的功能，在镜像构建时把 `node_modules` 文件夹挂载上去，在构建完成后，这个 `node_modules` 文件夹会自动卸载，实际的镜像中并不包含 `node_modules` 这个文件夹，这样我们就省去了每次获取依赖的时间，大大增加了镜像构建效率，同时也避免了生成了大量的中间层镜像。
+
+`BuildKit` 提供了 `RUN --mount=type=cache` 指令，可以实现上边的设想。
+
+```docker
+## syntax=docker/dockerfile:1
+
+FROM node:alpine as builder
+
+WORKDIR /app
+
+COPY package.json /app/
+
+RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
+    --mount=type=cache,target=/root/.npm,id=npm_cache \
+        npm i --registry=https://registry.npmmirror.com
+
+COPY src /app/src
+
+RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
+## --mount=type=cache,target=/app/dist,id=my_app_dist,sharing=locked \
+
+        npm run build
+
+FROM nginx:alpine
+
+## COPY --from=builder /app/dist /app/dist
+
+## 为了更直观的说明 from 和 source 指令，这里使用 RUN 指令
+
+RUN --mount=type=cache,target=/tmp/dist,from=builder,source=/app/dist \
+    # --mount=type=cache,target/tmp/dist,from=my_app_dist,sharing=locked \
+
+    mkdir -p /app/dist && cp -r /tmp/dist/* /app/dist
+```
+
+
+第一个 `RUN` 指令执行后，`id` 为 `my_app_npm_module` 的缓存文件夹挂载到了 `/app/node_modules` 文件夹中。多次执行也不会产生多个中间层镜像。
+
+第二个 `RUN` 指令执行时需要用到 `node_modules` 文件夹，`node_modules` 已经挂载，命令也可以正确执行。
+
+第三个 `RUN` 指令将上一阶段产生的文件复制到指定位置，`from` 指明缓存的来源，这里 `builder` 表示缓存来源于构建的第一阶段，`source` 指明缓存来源的文件夹。
+
+上面的 `Dockerfile` 中 `--mount=type=cache,...` 中指令作用如下：
+
+|Option               |Description|
+|---------------------|-----------|
+|`id`                 | `id` 设置一个标志，以便区分缓存。|
+|`target` (必填项)     | 缓存的挂载目标文件夹。|
+|`ro`,`readonly`      | 只读，缓存文件夹不能被写入。 |
+|`sharing`            | 有 `shared` `private` `locked` 值可供选择。`sharing` 设置当一个缓存被多次使用时的表现，由于 `BuildKit` 支持并行构建，当多个步骤使用同一缓存时 (同一 `id`) 会发生冲突。`shared` 表示多个步骤可以同时读写，`private` 表示当多个步骤使用同一缓存时，每个步骤使用不同的缓存，`locked` 表示当一个步骤完成释放缓存后，后一个步骤才能继续使用该缓存。|
+|`from`               | 缓存来源 (构建阶段)，不填写时为空文件夹。|
+|`source`             | 来源的文件夹路径。|
+
+#### `RUN --mount=type=bind`
+
+该指令可以将一个镜像 (或上一构建阶段) 的文件挂载到指定位置。
+
+```docker
+## syntax=docker/dockerfile:1
+
+RUN --mount=type=bind,from=php:alpine,source=/usr/local/bin/docker-php-entrypoint,target=/docker-php-entrypoint \
+        cat /docker-php-entrypoint
+```
+
+#### `RUN --mount=type=tmpfs`
+
+该指令可以将一个 `tmpfs` 文件系统挂载到指定位置。
+
+```docker
+## syntax=docker/dockerfile:1
+
+RUN --mount=type=tmpfs,target=/temp \
+        mount | grep /temp
+```
+
+#### `RUN --mount=type=secret`
+
+该指令可以将一个文件 (例如密钥) 挂载到指定位置。
+
+```docker
+## syntax=docker/dockerfile:1
+
+RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
+        cat /root/.aws/credentials
+```
+
+```bash
+$ docker build -t test --secret id=aws,src=$HOME/.aws/credentials .
+```
+
+#### `RUN --mount=type=ssh`
+
+该指令可以挂载 `ssh` 密钥。
+
+```docker
+## syntax=docker/dockerfile:1
+
+FROM alpine
+RUN apk add --no-cache openssh-client
+RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
+RUN --mount=type=ssh ssh git@gitlab.com | tee /hello
+```
+
+```bash
+$ eval $(ssh-agent)
+$ ssh-add ~/.ssh/id_rsa
+(Input your passphrase here)
+$ docker build -t test --ssh default=$SSH_AUTH_SOCK .
+```
+
+### 10.1.2 使用 `docker compose build` 与 BuildKit
+
+Docker Compose 同样支持 BuildKit，这使得多服务应用的构建更加高效。
+
+自 Docker 23.0 起，BuildKit 已默认启用，无需额外配置。如果使用旧版本，可设置 `DOCKER_BUILDKIT=1` 环境变量启用。
+
+### 10.1.3 官方文档
+
+* https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md
--- a/10_buildx/10.2_buildx.md
+++ b/10_buildx/10.2_buildx.md
@@ -0,0 +1,45 @@
+## 10.2 使用 Buildx 构建镜像
+
+本节涵盖了相关内容与详细描述，主要探讨以下几个方面：
+
+### 10.2.1 使用
+
+Buildx 的使用非常直观，绝大多数情况下可以替代 `docker build` 命令。
+
+你可以直接使用 `docker buildx build` 命令构建镜像。
+
+```bash
+$ docker buildx build .
+[+] Building 8.4s (23/32)
+ => ...
+```
+
+Buildx 使用 [BuildKit 引擎](9.1_buildkit.md)进行构建，支持许多新的功能，具体参考 [Buildkit](9.1_buildkit.md) 一节。
+
+#### 使用 `bake`
+
+`docker buildx bake` 是一个高级构建命令，支持从 HCL、JSON 或 Compose 文件中定义构建目标，实现复杂的流水线构建。
+
+```bash
+## 从 Compose 文件构建所有服务
+
+$ docker buildx bake
+
+## 仅构建指定目标
+
+$ docker buildx bake web
+```
+
+#### 生成 SBOM
+
+Buildx 支持在构建时直接生成 SBOM (Software Bill of Materials)，这对于软件供应链安全至关重要。
+
+```bash
+$ docker buildx build --sbom=true -t myimage .
+```
+
+该命令会在构建结果中包含 SPDX 或 CycloneDX 格式的 SBOM 数据。
+
+### 10.2.2 官方文档
+
+* https://docs.docker.com/engine/reference/commandline/buildx/
--- a/10_buildx/10.3_multi-arch-images.md
+++ b/10_buildx/10.3_multi-arch-images.md
@@ -0,0 +1,133 @@
+## 10.3 构建多种系统架构支持的 Docker 镜像
+
+Docker 镜像可以支持多种系统架构，这意味着你可以在 `x86_64`、`arm64` 等不同架构的机器上运行同一个镜像。这是通过一个名为 “manifest list” (或称为 “fat manifest”) 的文件来实现的。
+
+### 10.3.1 Manifest List 是什么？
+
+为了理解多架构镜像的原理，我们需要先了解 Manifest List 的概念。
+
+Manifest list 是一个包含了多个指向不同架构镜像的 manifest 的文件。当你拉取一个支持多架构的镜像时，Docker 会自动根据你当前的系统架构选择并拉取对应的镜像。
+
+例如，官方的 `hello-world` 镜像就支持多种架构。你可以使用 `docker manifest inspect` 命令来查看它的 manifest list：
+
+```bash
+$ docker manifest inspect hello-world
+{
+   "schemaVersion": 2,
+   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
+   "manifests": [
+      {
+         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+         "size": 525,
+         "digest": "sha256:80852a401a974d9e923719a948cc5335a0a4435be8778b475844a7153a2382e5",
+         "platform": {
+            "architecture": "amd64",
+            "os": "linux"
+         }
+      },
+      {
+         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+         "size": 525,
+         "digest": "sha256:3adea81344be1724b383d501736c3852939b33b3903d02474373700b25e5d6e3",
+         "platform": {
+            "architecture": "arm",
+            "os": "linux",
+            "variant": "v5"
+         }
+      },
+      // ... more architectures
+   ]
+}
+```
+
+### 10.3.2 使用 `docker buildx` 构建多架构镜像
+
+`docker buildx` 是构建多架构镜像的最佳实践工具，它屏蔽了底层的复杂性，提供了一键构建多架构镜像的能力。
+
+在 Docker 19.03+ 版本中，`docker buildx` 是推荐的用于构建多架构镜像的工具。它使用 `BuildKit` 作为后端，可以大大简化构建过程。
+
+#### 新建 `builder` 实例
+
+首先，你需要创建一个新的 `builder` 实例，因为它支持同时为多个平台构建。
+
+```bash
+$ docker buildx create --name mybuilder --use
+$ docker buildx inspect --bootstrap
+```
+
+#### 构建和推送
+
+使用 `docker buildx build` 命令并指定 `--platform` 参数，可以同时构建支持多种架构的镜像。`--push` 参数会将构建好的镜像和 manifest list 推送到 Docker 仓库。
+
+```dockerfile
+## Dockerfile
+
+FROM --platform=$TARGETPLATFORM alpine
+
+RUN uname -a > /os.txt
+
+CMD cat /os.txt
+```
+
+```bash
+$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t your-username/multi-arch-image . --push
+```
+
+构建完成后，你就可以在不同架构的机器上拉取并运行 `your-username/multi-arch-image` 这个镜像了。
+
+#### 架构相关的构建参数
+
+在 `Dockerfile` 中，你可以使用一些预定义的构建参数来根据目标平台定制构建过程：
+
+*   `TARGETPLATFORM`：构建镜像的目标平台，例如 `linux/amd64`。
+*   `TARGETOS`：目标平台的操作系统，例如 `linux`。
+*   `TARGETARCH`：目标平台的架构，例如 `amd64`。
+*   `TARGETVARIANT`：目标平台的变种，例如 `v7`。
+*   `BUILDPLATFORM`：构建环境的平台。
+*   `BUILDOS`：构建环境的操作系统。
+*   `BUILDARCH`：构建环境的架构。
+*   `BUILDVARIANT`：构建环境的变种。
+
+例如，你可以这样编写 `Dockerfile` 来拷贝特定架构的二进制文件：
+
+```dockerfile
+FROM scratch
+
+ARG TARGETOS
+ARG TARGETARCH
+
+COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist
+
+ENTRYPOINT ["/dist"]
+```
+
+### 10.3.3 使用 `docker manifest` (底层工具)
+
+除了 `docker buildx`，我们也可以直接操作 Manifest List 来手动组合不同架构的镜像。
+
+`docker manifest` 是一个更底层的命令，可以用来创建、检查和推送 manifest list。虽然 `docker buildx` 在大多数情况下更方便，但了解 `docker manifest` 仍然有助于理解其工作原理。
+
+#### 创建 manifest list
+
+运行以下命令：
+
+```bash
+## 首先，为每个架构构建并推送镜像
+
+$ docker buildx build --platform linux/amd64 -t your-username/my-app:amd64 . --push
+$ docker buildx build --platform linux/arm64 -t your-username/my-app:arm64 . --push
+
+## 然后，创建一个 manifest list，将它们组合在一起
+
+$ docker manifest create your-username/my-app:latest \
+    --amend your-username/my-app:amd64 \
+    --amend your-username/my-app:arm64
+
+## 最后，推送 manifest list
+
+$ docker manifest push your-username/my-app:latest
+```
+
+#### 检查 manifest list
+
+你可以使用 `docker manifest inspect` 来查看一个 manifest list 的详细信息，如上文所示。
--- a/10_buildx/README.md
+++ b/10_buildx/README.md
@@ -0,0 +1,17 @@
+# 第十章 Docker Buildx
+
+Docker Buildx 是一个 docker CLI 插件，其扩展了 docker 命令，支持 [Moby BuildKit](9.1_buildkit.md) 提供的功能。提供了与 docker build 相同的用户体验，并增加了许多新功能。
+
+> Buildx 需要 Docker v19.03+。在较新版本中已更常用且功能更完整。
+
+## 概述
+
+总体概述了以下内容。
+
+## 本章内容
+
+本章将详细介绍 Docker Buildx 的使用，包括：
+
+* [使用 BuildKit 构建镜像](9.1_buildkit.md)
+* [使用 Buildx 构建镜像](9.2_buildx.md)
+* [构建多种系统架构支持的 Docker 镜像](9.3_multi-arch-images.md)
--- a/10_buildx/summary.md
+++ b/10_buildx/summary.md
@@ -0,0 +1,19 @@
+## 10.4 本章小结
+
+Docker Buildx 是 Docker 构建系统的重要进化，提供了高效、安全且支持多平台的镜像构建能力。
+
+| 概念 | 要点 |
+|------|------|
+| **BuildKit** | 下一代构建引擎，Docker 23.0+ 默认启用 |
+| **缓存挂载** | `RUN --mount=type=cache` 加速依赖安装 |
+| **Secret 挂载** | `RUN --mount=type=secret` 安全传递密钥 |
+| **buildx build** | 替代 `docker build`，支持更多构建功能 |
+| **多架构构建** | `--platform` 参数一键构建多种架构镜像 |
+| **Manifest List** | 多架构镜像的索引文件 |
+| **SBOM** | 通过 `--sbom=true` 生成软件物料清单 |
+
+### 10.4.1 延伸阅读
+
+- [Dockerfile 指令详解](../07_dockerfile/README.md)：Dockerfile 编写基础
+- [多阶段构建](../07_dockerfile/7.17_multistage_builds.md)：优化镜像体积
+- [Dockerfile 最佳实践](../appendix/20.1_best_practices.md)：编写高效 Dockerfile