Use a better structure

08_buildx/8.1_buildkit.md

@@ -1,4 +1,4 @@
-# 使用 `BuildKit` 构建镜像
+## 使用 `BuildKit` 构建镜像
 
 **BuildKit** 是下一代的镜像构建组件，在 https://github.com/moby/buildkit 开源。
 
@@ -6,19 +6,19 @@
 
 目前，Docker Hub 自动构建已经支持 BuildKit，具体请参考 https://github.com/docker-practice/docker-hub-buildx
 
-## `Dockerfile` 新增指令详解
+### `Dockerfile` 新增指令详解
 
 使用 BuildKit 后，我们可以使用下面几个新的 `Dockerfile` 指令来加快镜像构建。
 
 要使用最新的 Dockerfile 语法特性，建议在 Dockerfile 开头添加语法指令：
 
 ```docker
-# syntax=docker/dockerfile:1
+## syntax=docker/dockerfile:1
 ```
 
 这将使用最新的稳定版语法解析器，确保你可以使用所有最新特性。
 
-### `RUN --mount=type=cache`
+#### `RUN --mount=type=cache`
 
 目前，几乎所有的程序都会使用依赖管理工具，例如 `Go` 中的 `go mod`、`Node.js` 中的 `npm` 等等，当我们构建一个镜像时，往往会重复的从互联网中获取依赖包，难以缓存，大大降低了镜像的构建效率。
 
@@ -50,7 +50,7 @@ COPY --from=builder /app/dist /app/dist
 `BuildKit` 提供了 `RUN --mount=type=cache` 指令，可以实现上边的设想。
 
 ```docker
-# syntax=docker/dockerfile:1
+## syntax=docker/dockerfile:1
 FROM node:alpine as builder
 
 WORKDIR /app
@@ -64,14 +64,14 @@ RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=loc
 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 \
+## --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
+## COPY --from=builder /app/dist /app/dist
 
-# 为了更直观的说明 from 和 source 指令，这里使用 RUN 指令
+## 为了更直观的说明 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
@@ -95,32 +95,32 @@ RUN --mount=type=cache,target=/tmp/dist,from=builder,source=/app/dist \
 |`from`               | 缓存来源（构建阶段），不填写时为空文件夹。|
 |`source`             | 来源的文件夹路径。|
 
-### `RUN --mount=type=bind`
+#### `RUN --mount=type=bind`
 
 该指令可以将一个镜像（或上一构建阶段）的文件挂载到指定位置。
 
 ```docker
-# syntax=docker/dockerfile:1
+## 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`
+#### `RUN --mount=type=tmpfs`
 
 该指令可以将一个 `tmpfs` 文件系统挂载到指定位置。
 
 ```docker
-# syntax=docker/dockerfile:1
+## syntax=docker/dockerfile:1
 RUN --mount=type=tmpfs,target=/temp \
         mount | grep /temp
 ```
 
-### `RUN --mount=type=secret`
+#### `RUN --mount=type=secret`
 
 该指令可以将一个文件(例如密钥)挂载到指定位置。
 
 ```docker
-# syntax=docker/dockerfile:1
+## syntax=docker/dockerfile:1
 RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
         cat /root/.aws/credentials
 ```
@@ -129,12 +129,12 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
 $ docker build -t test --secret id=aws,src=$HOME/.aws/credentials .
 ```
 
-### `RUN --mount=type=ssh`
+#### `RUN --mount=type=ssh`
 
 该指令可以挂载 `ssh` 密钥。
 
 ```docker
-# syntax=docker/dockerfile:1
+## 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
@@ -148,10 +148,10 @@ $ ssh-add ~/.ssh/id_rsa
 $ docker build -t test --ssh default=$SSH_AUTH_SOCK .
 ```
 
-## docker compose build 使用 BuildKit
+### docker compose build 使用 BuildKit
 
 自 Docker 23.0 起，BuildKit 已默认启用，无需额外配置。如果使用旧版本，可设置 `DOCKER_BUILDKIT=1` 环境变量启用。
 
-## 官方文档
+### 官方文档
 
 * https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md

08_buildx/8.2_buildx.md

@@ -1,6 +1,6 @@
-# 使用 Buildx 构建镜像
+## 使用 Buildx 构建镜像
 
-## 使用
+### 使用
 
 你可以直接使用 `docker buildx build` 命令构建镜像。
 
@@ -10,21 +10,21 @@ $ docker buildx build .
  => ...
 ```
 
-Buildx 使用 [BuildKit 引擎](buildkit.md) 进行构建，支持许多新的功能，具体参考 [Buildkit](buildkit.md) 一节。
+Buildx 使用 [BuildKit 引擎](8.1_buildkit.md) 进行构建，支持许多新的功能，具体参考 [Buildkit](8.1_buildkit.md) 一节。
 
-### 使用 `bake`
+#### 使用 `bake`
 
 `docker buildx bake` 是一个高级构建命令，支持从 HCL、JSON 或 Compose 文件中定义构建目标，实现复杂的流水线构建。
 
 ```bash
-# 从 docker-compose.yml 构建所有服务
+## 从 docker-compose.yml 构建所有服务
 $ docker buildx bake
 
-# 仅构建指定目标
+## 仅构建指定目标
 $ docker buildx bake web
 ```
 
-### 生成 SBOM
+#### 生成 SBOM
 
 Buildx 支持在构建时直接生成 SBOM (Software Bill of Materials)，这对于软件供应链安全至关重要。
 
@@ -34,6 +34,6 @@ $ docker buildx build --sbom=true -t myimage .
 
 该命令会在构建结果中包含 SPDX 或 CycloneDX 格式的 SBOM 数据。
 
-## 官方文档
+### 官方文档
 
 * https://docs.docker.com/engine/reference/commandline/buildx/

08_buildx/8.3_multi-arch-images.md

@@ -1,8 +1,8 @@
-# 构建多种系统架构支持的 Docker 镜像
+## 构建多种系统架构支持的 Docker 镜像
 
 Docker 镜像可以支持多种系统架构，这意味着你可以在 `x86_64`、`arm64` 等不同架构的机器上运行同一个镜像。这是通过一个名为 "manifest list"（或称为 "fat manifest"）的文件来实现的。
 
-## Manifest List 是什么？
+### Manifest List 是什么？
 
 Manifest list 是一个包含了多个指向不同架构镜像的 manifest 的文件。当你拉取一个支持多架构的镜像时，Docker 会自动根据你当前的系统架构选择并拉取对应的镜像。
 
@@ -38,11 +38,11 @@ $ docker manifest inspect hello-world
 }
 ```
 
-## 使用 `docker buildx` 构建多架构镜像
+### 使用 `docker buildx` 构建多架构镜像
 
 在 Docker 19.03+ 版本中，`docker buildx` 是推荐的用于构建多架构镜像的工具。它使用 `BuildKit` 作为后端，可以大大简化构建过程。
 
-### 新建 `builder` 实例
+#### 新建 `builder` 实例
 
 首先，你需要创建一个新的 `builder` 实例，因为它支持同时为多个平台构建。
 
@@ -51,12 +51,12 @@ $ docker buildx create --name mybuilder --use
 $ docker buildx inspect --bootstrap
 ```
 
-### 构建和推送
+#### 构建和推送
 
 使用 `docker buildx build` 命令并指定 `--platform` 参数，可以同时构建支持多种架构的镜像。`--push` 参数会将构建好的镜像和 manifest list 推送到 Docker 仓库。
 
 ```dockerfile
-# Dockerfile
+## Dockerfile
 FROM --platform=$TARGETPLATFORM alpine
 
 RUN uname -a > /os.txt
@@ -70,7 +70,7 @@ $ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t your-us
 
 构建完成后，你就可以在不同架构的机器上拉取并运行 `your-username/multi-arch-image` 这个镜像了。
 
-### 架构相关的构建参数
+#### 架构相关的构建参数
 
 在 `Dockerfile` 中，你可以使用一些预定义的构建参数来根据目标平台定制构建过程：
 
@@ -96,26 +96,26 @@ COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist
 ENTRYPOINT ["/dist"]
 ```
 
-## 使用 `docker manifest` (底层工具)
+### 使用 `docker manifest` (底层工具)
 
 `docker manifest` 是一个更底层的命令，可以用来创建、检查和推送 manifest list。虽然 `docker buildx` 在大多数情况下更方便，但了解 `docker manifest` 仍然有助于理解其工作原理。
 
-### 创建 manifest list
+#### 创建 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，将它们组合在一起
+## 然后，创建一个 manifest list，将它们组合在一起
 $ docker manifest create your-username/my-app:latest \
     --amend your-username/my-app:amd64 \
     --amend your-username/my-app:arm64
 
-# 最后，推送 manifest list
+## 最后，推送 manifest list
 $ docker manifest push your-username/my-app:latest
 ```
 
-### 检查 manifest list
+#### 检查 manifest list
 
 你可以使用 `docker manifest inspect` 来查看一个 manifest list 的详细信息，如上文所示。

08_buildx/README.md

@@ -1,5 +1,5 @@
-# Docker Buildx
+# 第八章 Docker Buildx
 
-Docker Buildx 是一个 docker CLI 插件，其扩展了 docker 命令，支持 [Moby BuildKit](buildkit.md) 提供的功能。提供了与 docker build 相同的用户体验，并增加了许多新功能。
+Docker Buildx 是一个 docker CLI 插件，其扩展了 docker 命令，支持 [Moby BuildKit](8.1_buildkit.md) 提供的功能。提供了与 docker build 相同的用户体验，并增加了许多新功能。
 
 > 该功能仅适用于 Docker v19.03+ 版本