Release v1.5.0: Restructure chapters and update for Docker v30.x

2026-03-10 11:54:37 +00:00 · 2026-02-04 22:12:38 -08:00
parent b4b0d4160a
commit fdb879dcf2
304 changed files with 1314 additions and 364 deletions
--- a/08_buildx/README.md
+++ b/08_buildx/README.md
@@ -0,0 +1,5 @@
+# Docker Buildx
+
+Docker Buildx 是一个 docker CLI 插件，其扩展了 docker 命令，支持 [Moby BuildKit](buildkit.md) 提供的功能。提供了与 docker build 相同的用户体验，并增加了许多新功能。
+
+> 该功能仅适用于 Docker v19.03+ 版本
--- a/08_buildx/buildkit.md
+++ b/08_buildx/buildkit.md
@@ -0,0 +1,157 @@
+# 使用 `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
+
+## `Dockerfile` 新增指令详解
+
+使用 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 .
+```
+
+## docker compose build 使用 BuildKit
+
+自 Docker 23.0 起，BuildKit 已默认启用，无需额外配置。如果使用旧版本，可设置 `DOCKER_BUILDKIT=1` 环境变量启用。
+
+## 官方文档
+
+* https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md
--- a/08_buildx/buildx.md
+++ b/08_buildx/buildx.md
@@ -0,0 +1,39 @@
+# 使用 Buildx 构建镜像
+
+## 使用
+
+你可以直接使用 `docker buildx build` 命令构建镜像。
+
+```bash
+$ docker buildx build .
+[+] Building 8.4s (23/32)
+ => ...
+```
+
+Buildx 使用 [BuildKit 引擎](buildkit.md) 进行构建，支持许多新的功能，具体参考 [Buildkit](buildkit.md) 一节。
+
+### 使用 `bake`
+
+`docker buildx bake` 是一个高级构建命令，支持从 HCL、JSON 或 Compose 文件中定义构建目标，实现复杂的流水线构建。
+
+```bash
+# 从 docker-compose.yml 构建所有服务
+$ 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 数据。
+
+## 官方文档
+
+* https://docs.docker.com/engine/reference/commandline/buildx/
--- a/08_buildx/multi-arch-images.md
+++ b/08_buildx/multi-arch-images.md
@@ -0,0 +1,121 @@
+# 构建多种系统架构支持的 Docker 镜像
+
+Docker 镜像可以支持多种系统架构，这意味着你可以在 `x86_64`、`arm64` 等不同架构的机器上运行同一个镜像。这是通过一个名为 "manifest list"（或称为 "fat manifest"）的文件来实现的。
+
+## 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
+   ]
+}
+```
+
+## 使用 `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"]
+```
+
+## 使用 `docker manifest` (底层工具)
+
+`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 的详细信息，如上文所示。