style(docs): standardize heading formats and numbering

- Enforce Level 1-3 structural numbering based on SUMMARY.md hierarchy - Remove structural numbering from Level 4+ headings - Eliminate single child headings by converting to bold text - Auto-inject summary text for headings with multiple children missing intro text - Exclude Appendix chapters from structural numbering - Avoid modifying code block contents - Add script to detect non-standard English usage in headers
2026-03-11 04:14:38 +00:00 · 2026-02-21 22:40:33 -08:00
parent 33af380be1
commit 175aaae48a
136 changed files with 1015 additions and 766 deletions
--- a/10_compose/10.5_compose_file.md
+++ b/10_compose/10.5_compose_file.md
@@ -20,7 +20,7 @@ services:

 下面分别介绍各个指令的用法。

-### `build`
+### 10.5.1 `build`

 指定 `Dockerfile` 所在文件夹的路径 (可以是绝对路径，或者相对 Compose 文件的路径)。`Compose` 将会利用它自动构建这个镜像，然后使用这个镜像。

@@ -56,7 +56,7 @@ build:
    - corp/web_app:3.14
 ```

-### `cap_add, cap_drop`
+### 10.5.2 `cap_add, cap_drop`

 指定容器的内核能力 (capacity) 分配。

@@ -74,7 +74,7 @@ cap_drop:
  - NET_ADMIN
 ```

-### `command`
+### 10.5.3 `command`

 覆盖容器启动后默认执行的命令。

@@ -82,11 +82,11 @@ cap_drop:
 command: echo "hello world"
 ```

-### `configs`
+### 10.5.4 `configs`

 `configs` 来自 Compose Specification。它在 Swarm 中是原生对象；在本地 `docker compose` 模式下通常以文件挂载的形式实现，具体能力取决于 Compose 版本与运行平台。

-### `cgroup_parent`
+### 10.5.5 `cgroup_parent`

 指定父 `cgroup` 组，意味着将继承该组的资源限制。

@@ -96,7 +96,7 @@ command: echo "hello world"
 cgroup_parent: cgroups_1
 ```

-### `container_name`
+### 10.5.6 `container_name`

 指定容器名称。默认将会使用 `项目名称_服务名称_序号` 这样的格式。

@@ -106,11 +106,11 @@ container_name: docker-web-container

 >注意：指定容器名称后，该服务将无法进行扩展 (scale)，因为 Docker 不允许多个容器具有相同的名称。

-### `deploy`
+### 10.5.7 `deploy`

 `deploy` 用于描述副本数、更新策略、资源限制等部署参数。该字段在 Swarm 中支持最完整；在本地 `docker compose up` 场景下通常只有部分字段生效。

-### `devices`
+### 10.5.8 `devices`

 指定设备映射关系。

@@ -119,7 +119,7 @@ devices:
  - "/dev/ttyUSB1:/dev/ttyUSB0"
 ```

-### `depends_on`
+### 10.5.9 `depends_on`

 解决容器的依赖、启动先后的问题。以下例子中会先启动 `redis` `db` 再启动 `web`

@@ -140,7 +140,7 @@ services:

 >注意：`web` 服务不会等待 `redis` `db` “完全启动” 之后才启动。

-### `dns`
+### 10.5.10 `dns`

 自定义 `DNS` 服务器。可以是一个值，也可以是一个列表。

@@ -152,7 +152,7 @@ dns:
  - 114.114.114.114
 ```

-### `dns_search`
+### 10.5.11 `dns_search`

 配置 `DNS` 搜索域。可以是一个值，也可以是一个列表。

@@ -164,7 +164,7 @@ dns_search:
  - domain2.example.com
 ```

-### `tmpfs`
+### 10.5.12 `tmpfs`

 挂载一个 tmpfs 文件系统到容器。

@@ -175,7 +175,7 @@ tmpfs:
  - /tmp
 ```

-### `env_file`
+### 10.5.13 `env_file`

 从文件中获取环境变量，可以为单独的文件路径或列表。

@@ -200,7 +200,7 @@ env_file:
 PROG_ENV=development
 ```

-### `environment`
+### 10.5.14 `environment`

 设置环境变量。你可以使用数组或字典两种格式。

@@ -222,7 +222,7 @@ environment:
 y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF
 ```

-### `expose`
+### 10.5.15 `expose`

 暴露端口，但不映射到宿主机，只被连接的服务访问。

@@ -234,7 +234,7 @@ expose:
 - "8000"
 ```

-### `external_links`
+### 10.5.16 `external_links`

 >注意：不建议使用该指令。

@@ -247,7 +247,7 @@ external_links:
 - project_db_1:postgresql
 ```

-### `extra_hosts`
+### 10.5.17 `extra_hosts`

 类似 Docker 中的 `--add-host` 参数，指定额外的 host 名称映射信息。

@@ -264,7 +264,7 @@ extra_hosts:
 52.1.157.61 dockerhub
 ```

-### `healthcheck`
+### 10.5.18 `healthcheck`

 通过命令检查容器是否健康运行。

@@ -276,7 +276,7 @@ healthcheck:
  retries: 3
 ```

-### `image`
+### 10.5.19 `image`

 指定为镜像名称或镜像 ID。如果镜像在本地不存在，`Compose` 将会尝试拉取这个镜像。

@@ -286,7 +286,7 @@ image: orchardup/postgresql
 image: a4bc65fd
 ```

-### `labels`
+### 10.5.20 `labels`

 为容器添加 Docker 元数据 (metadata) 信息。例如可以为容器添加辅助说明信息。

@@ -297,11 +297,11 @@ labels:
  com.startupteam.release: "rc3 for v1.0"
 ```

-### `links`
+### 10.5.21 `links`

 >注意：不推荐使用该指令。容器之间应通过 Docker 网络 (networks) 进行互联。

-### `logging`
+### 10.5.22 `logging`

 配置日志选项。

@@ -328,7 +328,7 @@ options:
  max-file: "10"
 ```

-### `network_mode`
+### 10.5.23 `network_mode`

 设置网络模式。使用和 `docker run` 的 `--network` 参数一样的值。

@@ -340,7 +340,7 @@ network_mode: "service:[service name]"
 network_mode: "container:[container name/id]"
 ```

-### `networks`
+### 10.5.24 `networks`

 配置容器连接的网络。

@@ -358,7 +358,7 @@ networks:
  other-network:
 ```

-### `pid`
+### 10.5.25 `pid`

 跟主机系统共享进程命名空间。打开该选项的容器之间，以及容器和宿主机系统之间可以通过进程 ID 来相互访问和操作。

@@ -366,7 +366,7 @@ networks:
 pid: "host"
 ```

-### `ports`
+### 10.5.26 `ports`

 暴露端口信息。

@@ -382,7 +382,7 @@ ports:

 *注意：当使用 `HOST:CONTAINER` 格式来映射端口时，如果你使用的容器端口小于 60 并且没放到引号里，可能会得到错误结果，因为 `YAML` 会自动解析 `xx:yy` 这种数字格式为 60 进制。为避免出现这种问题，建议数字串都采用引号包括起来的字符串格式。*

-### `secrets`
+### 10.5.27 `secrets`

 存储敏感数据，例如 `mysql` 服务密码。

@@ -405,7 +405,7 @@ secrets:
    external: true
 ```

-### `security_opt`
+### 10.5.28 `security_opt`

 指定容器模板标签 (label) 机制的默认属性 (用户、角色、类型、级别等)。例如配置标签的用户名和角色名。

@@ -415,7 +415,7 @@ security_opt:
    - label:role:ROLE
 ```

-### `stop_signal`
+### 10.5.29 `stop_signal`

 设置另一个信号来停止容器。在默认情况下使用的是 SIGTERM 停止容器。

@@ -423,7 +423,7 @@ security_opt:
 stop_signal: SIGUSR1
 ```

-### `sysctls`
+### 10.5.30 `sysctls`

 配置容器内核参数。

@@ -437,7 +437,7 @@ sysctls:
  - net.ipv4.tcp_syncookies=0
 ```

-### `ulimits`
+### 10.5.31 `ulimits`

 指定容器的 ulimits 限制值。

@@ -451,7 +451,7 @@ sysctls:
      hard: 40000
 ```

-### `volumes`
+### 10.5.32 `volumes`

 数据卷所挂载路径设置。可以设置为宿主机路径 (`HOST:CONTAINER`) 或者数据卷名称 (`VOLUME:CONTAINER`)，并且可以设置访问模式 (`HOST:CONTAINER:ro`)。

@@ -477,7 +477,7 @@ volumes:
  mysql_data:  
 ```

-### 其它指令
+### 10.5.33 其它指令

 此外，还有包括 `domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir` 等指令，基本跟 `docker run` 中对应参数的功能一致。

@@ -537,7 +537,7 @@ stdin_open: true
 tty: true
 ```

-### 读取变量
+### 10.5.34 读取变量

 Compose 模板文件支持动态读取主机的系统环境变量和当前目录下的 `.env` 文件中的变量。