Use a better structure

2026-03-10 11:54:37 +00:00 · 2026-02-09 09:32:05 -08:00
parent fdb879dcf2
commit e669ee0fe8
167 changed files with 2462 additions and 2462 deletions
--- a/09_compose/9.1_introduction.md
+++ b/09_compose/9.1_introduction.md
@@ -1,4 +1,4 @@
-# Compose 简介
+## Compose 简介

 `Compose` 项目是 Docker 官方的开源项目，负责实现对 Docker 容器集群的快速编排。从功能上看，跟 `OpenStack` 中的 `Heat` 十分类似。

@@ -10,7 +10,7 @@

 `Compose` 恰好满足了这样的需求。它允许用户通过一个单独的 `docker-compose.yml` 模板文件（YAML 格式）来定义一组相关联的应用容器为一个项目（project）。

-## 模板文件规范
+### 模板文件规范

 Compose 模板文件采用 YAML 格式，扩展名为 `.yml` 或 `.yaml`。

--- a/09_compose/9.2_install.md
+++ b/09_compose/9.2_install.md
@@ -1,4 +1,4 @@
-# 安装与卸载
+## 安装与卸载

 `Compose` 是 Docker 官方的开源项目，负责实现对 Docker 容器集群的快速编排。

@@ -10,7 +10,7 @@

 Linux 系统请使用以下介绍的方法安装。

-## Linux
+### Linux

 在 Linux 上，你可以通过下载 `docker-compose` 二进制包来安装。

@@ -32,20 +32,20 @@ $ curl -SL https://github.com/docker/compose/releases/download/v2.40.3/docker-co
 $ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
 ```

-## 测试安装
+### 测试安装

 ```bash
 $ docker compose version
 Docker Compose version v2.40.3
 ```

-## bash 补全命令
+### bash 补全命令

 ```bash
 $ curl -L https://raw.githubusercontent.com/docker/compose/v2.40.3/contrib/completion/bash/docker-compose > /etc/bash_completion.d/docker-compose
 ```

-## 卸载
+### 卸载

 如果是二进制包方式安装的，删除二进制文件即可。

--- a/09_compose/9.3_usage.md
+++ b/09_compose/9.3_usage.md
@@ -1,6 +1,6 @@
-# 使用
+## 使用

-## 术语
+### 术语

 首先介绍几个术语。

@@ -10,13 +10,13 @@

 可见，一个项目可以由多个服务（容器）关联而成，`Compose` 面向项目进行管理。

-## 场景
+### 场景

 最常见的项目是 web 网站，该项目应该包含 web 应用和缓存。

 下面我们用 `Python` 来建立一个能够记录页面访问次数的 web 网站。

-### web 应用
+#### web 应用

 新建文件夹，在该目录中编写 `app.py` 文件

@@ -36,7 +36,7 @@ if __name__ == "__main__":
    app.run(host="0.0.0.0", debug=True)
 ```

-### Dockerfile
+#### Dockerfile

 编写 `Dockerfile` 文件，内容为

@@ -48,7 +48,7 @@ RUN pip install redis flask
 CMD ["python", "app.py"]
 ```

-### docker-compose.yml
+#### docker-compose.yml

 编写 `docker-compose.yml` 文件，这个是 Compose 使用的主模板文件。

@@ -65,7 +65,7 @@ services:
    image: "redis:alpine"
 ```

-### 运行 compose 项目
+#### 运行 compose 项目

 ```bash
 $ docker compose up
@@ -76,19 +76,19 @@ $ docker compose up

 按下 `Ctrl-C` 停止项目。

-### 后台运行
+#### 后台运行

 ```bash
 $ docker compose up -d
 ```

-### 停止
+#### 停止

 ```bash
 $ docker compose stop
 ```

-### 进入服务
+#### 进入服务

 ```bash
 $ docker compose exec redis sh
@@ -97,37 +97,37 @@ $ docker compose exec redis sh
 "9"
 ```

-### 查看日志
+#### 查看日志

 ```bash
 $ docker compose logs -f
 ```

-### 构建镜像
+#### 构建镜像

 ```bash
 $ docker compose build
 ```

-### 启动服务
+#### 启动服务

 ```bash
 $ docker compose start
 ```

-### 运行一次性命令
+#### 运行一次性命令

 ```bash
 $ docker compose run web python app.py
 ```

-### 验证 `docker-compose.yml`
+#### 验证 `docker-compose.yml`

 ```bash
 $ docker compose config
 ```

-### 删除项目
+#### 删除项目

 ```bash
 $ docker compose down
--- a/09_compose/9.4_commands.md
+++ b/09_compose/9.4_commands.md
@@ -1,6 +1,6 @@
-# Compose 命令说明
+## Compose 命令说明

-## 命令对象与格式
+### 命令对象与格式

 对于 Compose 来说，大部分命令的对象既可以是项目本身，也可以指定为项目中的服务或者容器。如果没有特别的说明，命令对象将是项目，这意味着项目中所有的服务都会受到命令影响。

@@ -12,7 +12,7 @@
 docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
 ```

-## 命令选项
+### 命令选项

 * `-f, --file FILE` 指定使用的 Compose 模板文件，默认为 `docker-compose.yml`，可以多次指定。

@@ -22,9 +22,9 @@ docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]

 * `-v, --version` 打印版本并退出。

-## 命令使用说明
+### 命令使用说明

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

 格式为 `docker compose build [options] [SERVICE...]`。

@@ -42,27 +42,27 @@ docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]

 * `--pull` 始终尝试通过 pull 来获取更新版本的镜像。

-### `config`
+#### `config`

 验证 Compose 文件格式是否正确，若正确则显示配置，若格式错误显示错误原因。

-### `down`
+#### `down`

 此命令将会停止 `up` 命令所启动的容器，并移除网络

-### `exec`
+#### `exec`

 进入指定的容器。

-### `help`
+#### `help`

 获得一个命令的帮助。

-### `images`
+#### `images`

 列出 Compose 文件中包含的镜像。

-### `kill`
+#### `kill`

 格式为 `docker compose kill [options] [SERVICE...]`。

@@ -74,7 +74,7 @@ docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
 $ docker compose kill -s SIGINT
 ```

-### `logs`
+#### `logs`

 格式为 `docker compose logs [options] [SERVICE...]`。

@@ -82,13 +82,13 @@ $ docker compose kill -s SIGINT

 该命令在调试问题的时候十分有用。

-### `pause`
+#### `pause`

 格式为 `docker compose pause [SERVICE...]`。

 暂停一个服务容器。

-### `port`
+#### `port`

 格式为 `docker compose port [options] SERVICE PRIVATE_PORT`。

@@ -100,7 +100,7 @@ $ docker compose kill -s SIGINT

 * `--index=index` 如果同一服务存在多个容器，指定命令对象容器的序号（默认为 1）。

-### `ps`
+#### `ps`

 格式为 `docker compose ps [options] [SERVICE...]`。

@@ -110,7 +110,7 @@ $ docker compose kill -s SIGINT

 * `-q` 只打印容器的 ID 信息。

-### `pull`
+#### `pull`

 格式为 `docker compose pull [options] [SERVICE...]`。

@@ -120,11 +120,11 @@ $ docker compose kill -s SIGINT

 * `--ignore-pull-failures` 忽略拉取镜像过程中的错误。

-### `push`
+#### `push`

 推送服务依赖的镜像到 Docker 镜像仓库。

-### `restart`
+#### `restart`

 格式为 `docker compose restart [options] [SERVICE...]`。

@@ -134,7 +134,7 @@ $ docker compose kill -s SIGINT

 * `-t, --timeout TIMEOUT` 指定重启前停止容器的超时（默认为 10 秒）。

-### `rm`
+#### `rm`

 格式为 `docker compose rm [options] [SERVICE...]`。

@@ -146,7 +146,7 @@ $ docker compose kill -s SIGINT

 * `-v` 删除容器所挂载的数据卷。

-### `run`
+#### `run`
 格式为 `docker compose run [options] [-p PORT...] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]`。

 在指定服务上执行一个命令。
@@ -199,7 +199,7 @@ $ docker compose run --no-deps web python manage.py shell

 * `-T` 不分配伪 tty，意味着依赖 tty 的指令将无法运行。

-### `scale`
+#### `scale`

 格式为 `docker compose scale [options] [SERVICE=NUM...]`。

@@ -219,13 +219,13 @@ $ docker compose scale web=3 db=2

 * `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

-### `start`
+#### `start`

 格式为 `docker compose start [SERVICE...]`。

 启动已经存在的服务容器。

-### `stop`
+#### `stop`

 格式为 `docker compose stop [options] [SERVICE...]`。

@@ -235,17 +235,17 @@ $ docker compose scale web=3 db=2

 * `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

-### `top`
+#### `top`

 查看各个服务容器内运行的进程。

-### `unpause`
+#### `unpause`

 格式为 `docker compose unpause [SERVICE...]`。

 恢复处于暂停状态中的服务。

-### `up`
+#### `up`

 格式为 `docker compose up [options] [SERVICE...]`。

@@ -279,13 +279,13 @@ $ docker compose scale web=3 db=2

 * `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

-### `version`
+#### `version`

 格式为 `docker compose version`。

 打印版本信息。

-### `watch`
+#### `watch`

 格式为 `docker compose watch [options] [SERVICE...]`。

@@ -314,6 +314,6 @@ services:

 * `--quiet` 静默模式。

-## 参考资料
+### 参考资料

 * [官方文档](https://docs.docker.com/compose/reference/overview/)
--- a/09_compose/9.5_compose_file.md
+++ b/09_compose/9.5_compose_file.md
@@ -1,4 +1,4 @@
-# Compose 模板文件
+## Compose 模板文件

 模板文件是使用 `Compose` 的核心，涉及到的指令关键字也比较多。但大家不用担心，这里面大部分指令跟 `docker run` 相关参数的含义都是类似的。

@@ -22,7 +22,7 @@ services:

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

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

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

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

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

 指定容器的内核能力（capacity）分配。

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

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

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

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

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

 仅用于 `Swarm mode`（已弃用，推荐使用 Kubernetes）。

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

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

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

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

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

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

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

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

 仅用于 `Swarm mode`（已弃用，推荐使用 Kubernetes）。

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

 指定设备映射关系。

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

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

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

@@ -148,7 +148,7 @@ services:

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

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

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

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

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

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

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

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

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

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

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

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

@@ -203,11 +203,11 @@ env_file:
 环境变量文件中每一行必须符合格式，支持 `#` 开头的注释行。

 ```bash
-# common.env: Set development environment
+## common.env: Set development environment
 PROG_ENV=development
 ```

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

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

@@ -229,7 +229,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`
+### `expose`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 配置日志选项。

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

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

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

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

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

 配置容器连接的网络。

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

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

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

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

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

 暴露端口信息。

@@ -389,7 +389,7 @@ ports:

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

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

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

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

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

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

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

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

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

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

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

 配置容器内核参数。

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

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

 指定容器的 ulimits 限制值。

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

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

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

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

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

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

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

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

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

@@ -567,13 +567,13 @@ db:
 在当前目录新建 `.env` 文件并写入以下内容。

 ```bash
-# 支持 # 号注释
+## 支持 # 号注释
 MONGO_VERSION=3.6
 ```

 执行 `docker-compose up` 则会启动一个 `mongo:3.6` 镜像的容器。

-## 参考资料
+### 参考资料

 * [官方文档](https://docs.docker.com/compose/compose-file/)
 * [awesome-compose](https://github.com/docker/awesome-compose)
--- a/09_compose/9.6_django.md
+++ b/09_compose/9.6_django.md
@@ -1,10 +1,10 @@
-# 使用 Django
+## 使用 Django

 > 本小节内容适合 `Python` 开发人员阅读。

 本节将使用 Docker Compose 配置并运行一个 **Django + PostgreSQL** 应用。笔者不仅会介绍具体步骤，还会解释每个配置项的作用，以及开发环境和生产环境的差异。

-## 架构概览
+### 架构概览

 在开始之前，让我们先理解我们要构建的架构：

@@ -34,7 +34,7 @@
 - 两个服务通过 Docker Compose 自动创建的网络相互通信
 - `web` 服务可以通过服务名 `db` 访问数据库（Docker 内置 DNS）

-## 准备工作
+### 准备工作

 创建一个项目目录并进入：

@@ -44,24 +44,24 @@ $ mkdir django-docker && cd django-docker

 我们需要创建三个文件：`Dockerfile`、`requirements.txt` 和 `docker-compose.yml`。

-## Step 1: 创建 Dockerfile
+### Step 1: 创建 Dockerfile

 ```docker
 FROM python:3.12-slim

-# 防止 Python 缓冲 stdout/stderr，让日志实时输出
+## 防止 Python 缓冲 stdout/stderr，让日志实时输出
 ENV PYTHONUNBUFFERED=1

-# 设置工作目录
+## 设置工作目录
 WORKDIR /code

-# 先复制依赖文件，利用 Docker 缓存加速构建
+## 先复制依赖文件，利用 Docker 缓存加速构建
 COPY requirements.txt /code/

-# 安装依赖
+## 安装依赖
 RUN pip install --no-cache-dir -r requirements.txt

-# 复制项目代码
+## 复制项目代码
 COPY . /code/
 ```

@@ -77,7 +77,7 @@ COPY . /code/

 > 💡 **笔者建议**：总是将变化频率低的文件先复制，变化频率高的后复制。这样可以最大化利用 Docker 的构建缓存。

-## Step 2: 创建 requirements.txt
+### Step 2: 创建 requirements.txt

 ```txt
 Django>=5.0,<6.0
@@ -93,7 +93,7 @@ gunicorn>=21.0,<22.0
 | `psycopg[binary]` | PostgreSQL 数据库驱动（推荐使用 psycopg 3） |
 | `gunicorn` | 生产环境 WSGI 服务器（可选，开发时可不用） |

-## Step 3: 创建 docker-compose.yml
+### Step 3: 创建 docker-compose.yml

 ```yaml
 services:
@@ -130,7 +130,7 @@ volumes:

 **配置详解**：

-### db 服务
+#### db 服务

 ```yaml
 db:
@@ -148,7 +148,7 @@ db:

 > ⚠️ **笔者提醒**：`volumes` 配置很重要！没有它，每次容器重启数据都会丢失。笔者见过不少新手因为忘记这一步，导致开发数据全部丢失。

-### web 服务
+#### web 服务

 ```yaml
 web:
@@ -171,7 +171,7 @@ web:
 | `depends_on` + `healthcheck` | 启动顺序 | 确保数据库就绪后 Django 才启动，避免连接错误 |
 | `environment` | 环境变量 | 推荐用环境变量管理配置，避免硬编码 |

-## Step 4: 创建 Django 项目
+### Step 4: 创建 Django 项目

 运行以下命令创建新的 Django 项目：

@@ -203,7 +203,7 @@ django-docker/

 > 💡 **Linux 用户注意**：如果遇到权限问题，执行 `sudo chown -R $USER:$USER .`

-## Step 5: 配置数据库连接
+### Step 5: 配置数据库连接

 修改 `mysite/settings.py`，配置数据库连接：

@@ -221,7 +221,7 @@ DATABASES = {
    }
 }

-# 允许的主机（开发环境）
+## 允许的主机（开发环境）
 ALLOWED_HOSTS = ['*']
 ```

@@ -229,7 +229,7 @@ ALLOWED_HOSTS = ['*']

 在 Docker Compose 中，各服务通过服务名相互访问。Docker 内置的 DNS 会将 `db` 解析为 db 服务容器的 IP 地址。这是 Docker Compose 的核心功能之一。

-## Step 6: 启动应用
+### Step 6: 启动应用

 ```bash
 $ docker compose up
@@ -249,29 +249,29 @@ web-1  | Starting development server at http://0.0.0.0:8000/

 打开浏览器访问 http://localhost:8000，可以看到 Django 欢迎页面！

-## 常用开发命令
+### 常用开发命令

 在另一个终端窗口执行：

 ```bash
-# 执行数据库迁移
+## 执行数据库迁移
 $ docker compose exec web python manage.py migrate

-# 创建超级用户
+## 创建超级用户
 $ docker compose exec web python manage.py createsuperuser

-# 进入 Django shell
+## 进入 Django shell
 $ docker compose exec web python manage.py shell

-# 进入 PostgreSQL 命令行
+## 进入 PostgreSQL 命令行
 $ docker compose exec db psql -U django_user -d django_db
 ```

 > 💡 笔者建议使用 `exec` 而不是 `run`。`exec` 在已运行的容器中执行命令，`run` 会创建新容器。

-## 常见问题排查
+### 常见问题排查

-### Q1: 数据库连接失败
+#### Q1: 数据库连接失败

 **错误信息**：`django.db.utils.OperationalError: could not connect to server`

@@ -284,12 +284,12 @@ $ docker compose exec db psql -U django_user -d django_db
 | 网络未创建 | 运行 `docker compose down` 后重新 `up` |

 ```bash
-# 调试：检查数据库是否正常运行
+## 调试：检查数据库是否正常运行
 $ docker compose ps
 $ docker compose logs db
 ```

-### Q2: 代码修改没有生效
+#### Q2: 代码修改没有生效

 **可能原因**：

@@ -297,14 +297,14 @@ $ docker compose logs db
 2. **Volume 挂载问题**：检查 `docker-compose.yml` 中的 volumes 配置
 3. **缓存问题**：尝试 `docker compose restart web`

-### Q3: 权限问题（Linux）
+#### Q3: 权限问题（Linux）

 ```bash
-# 如果容器内创建的文件 root 用户所有
+## 如果容器内创建的文件 root 用户所有
 $ sudo chown -R $USER:$USER .
 ```

-## 开发 vs 生产：关键差异
+### 开发 vs 生产：关键差异

 笔者特别提醒，本节的配置是**开发环境**配置。生产环境需要以下调整：

@@ -319,7 +319,7 @@ $ sudo chown -R $USER:$USER .
 **生产环境 docker-compose.yml 示例**：

 ```yaml
-# docker-compose.prod.yml
+## docker-compose.prod.yml
 services:
  web:
    build: .
@@ -331,9 +331,9 @@ services:
    # ...
 ```

-## 延伸阅读
+### 延伸阅读

- [Compose 模板文件详解](compose_file.md)：深入理解 docker-compose.yml 的所有配置项
- [使用 WordPress](wordpress.md)：另一个 Compose 实战案例
- [Dockerfile 最佳实践](../15_appendix/best_practices.md)：构建更小、更安全的镜像
+- [Compose 模板文件详解](9.5_compose_file.md)：深入理解 docker-compose.yml 的所有配置项
+- [使用 WordPress](9.8_wordpress.md)：另一个 Compose 实战案例
+- [Dockerfile 最佳实践](../15_appendix/15.1_best_practices.md)：构建更小、更安全的镜像
 - [数据管理](../07_data_network/README.md)：Volume 和数据持久化详解
--- a/09_compose/9.7_rails.md
+++ b/09_compose/9.7_rails.md
@@ -1,10 +1,10 @@
-# 使用 Rails
+## 使用 Rails

 > 本小节内容适合 Ruby 开发人员阅读。

 本节使用 Docker Compose 配置并运行一个 **Rails + PostgreSQL** 应用。

-## 架构概览
+### 架构概览

 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -25,7 +25,7 @@
         localhost:3000
 ```

-## 准备工作
+### 准备工作

 创建项目目录：

@@ -35,25 +35,25 @@ $ mkdir rails-docker && cd rails-docker

 需要创建三个文件：`Dockerfile`、`Gemfile` 和 `docker-compose.yml`。

-## Step 1: 创建 Dockerfile
+### Step 1: 创建 Dockerfile

 ```docker
 FROM ruby:3.2

-# 安装系统依赖
+## 安装系统依赖
 RUN apt-get update -qq && \
    apt-get install -y build-essential libpq-dev nodejs && \
    rm -rf /var/lib/apt/lists/*

-# 设置工作目录
+## 设置工作目录
 WORKDIR /myapp

-# 先复制 Gemfile，利用缓存加速构建
+## 先复制 Gemfile，利用缓存加速构建
 COPY Gemfile /myapp/Gemfile
 COPY Gemfile.lock /myapp/Gemfile.lock
 RUN bundle install

-# 复制应用代码
+## 复制应用代码
 COPY . /myapp
 ```

@@ -66,7 +66,7 @@ COPY . /myapp
 | `nodejs` | Rails Asset Pipeline 需要 |
 | 先复制 Gemfile | 只有依赖变化时才重新 `bundle install` |

-## Step 2: 创建 Gemfile
+### Step 2: 创建 Gemfile

 创建一个初始的 `Gemfile`，稍后会被 `rails new` 覆盖：

@@ -81,7 +81,7 @@ gem 'rails', '~> 7.1'
 $ touch Gemfile.lock
 ```

-## Step 3: 创建 docker-compose.yml
+### Step 3: 创建 docker-compose.yml

 ```yaml
 services:
@@ -117,7 +117,7 @@ volumes:
 | `depends_on: db` | 确保数据库先启动 |
 | `DATABASE_URL` | Rails 12-factor 风格的数据库配置 |

-## Step 4: 生成 Rails 项目
+### Step 4: 生成 Rails 项目

 使用 `docker compose run` 生成项目骨架：

@@ -142,7 +142,7 @@ docker-compose.yml                bin              db               public

 > ⚠️ **Linux 用户**：如遇权限问题，执行 `sudo chown -R $USER:$USER .`

-## Step 5: 重新构建镜像
+### Step 5: 重新构建镜像

 由于生成了新的 Gemfile，需要重新构建镜像以安装完整依赖：

@@ -150,7 +150,7 @@ docker-compose.yml                bin              db               public
 $ docker compose build
 ```

-## Step 6: 配置数据库连接
+### Step 6: 配置数据库连接

 修改 `config/database.yml`：

@@ -174,7 +174,7 @@ production:

 > 💡 使用 `DATABASE_URL` 环境变量配置数据库，符合 12-factor 应用原则，便于在不同环境间切换。

-## Step 7: 启动应用
+### Step 7: 启动应用

 ```bash
 $ docker compose up
@@ -192,7 +192,7 @@ web-1  | Puma starting in single mode...
 web-1  | * Listening on http://0.0.0.0:3000
 ```

-## Step 8: 创建数据库
+### Step 8: 创建数据库

 在另一个终端执行：

@@ -204,28 +204,28 @@ Created database 'myapp_test'

 访问 http://localhost:3000 查看 Rails 欢迎页面。

-## 常用开发命令
+### 常用开发命令

 ```bash
-# 数据库迁移
+## 数据库迁移
 $ docker compose exec web rails db:migrate

-# Rails 控制台
+## Rails 控制台
 $ docker compose exec web rails console

-# 运行测试
+## 运行测试
 $ docker compose exec web rails test

-# 生成脚手架
+## 生成脚手架
 $ docker compose exec web rails generate scaffold Post title:string body:text

-# 进入容器 Shell
+## 进入容器 Shell
 $ docker compose exec web bash
 ```

-## 常见问题
+### 常见问题

-### Q: 数据库连接失败
+#### Q: 数据库连接失败

 检查 `DATABASE_URL` 环境变量格式是否正确，确保 db 服务已启动：

@@ -234,7 +234,7 @@ $ docker compose ps
 $ docker compose logs db
 ```

-### Q: server.pid 文件导致启动失败
+#### Q: server.pid 文件导致启动失败

 错误信息：`A server is already running`

@@ -244,7 +244,7 @@ $ docker compose logs db
 $ docker compose exec web rm -f tmp/pids/server.pid
 ```

-### Q: Gem 安装失败
+#### Q: Gem 安装失败

 可能需要更新 bundler 或清理缓存：

@@ -252,7 +252,7 @@ $ docker compose exec web rm -f tmp/pids/server.pid
 $ docker compose run --rm web bundle update
 ```

-## 开发 vs 生产
+### 开发 vs 生产

 | 配置项 | 开发环境 | 生产环境 |
 |--------|---------|---------|
@@ -261,8 +261,8 @@ $ docker compose run --rm web bundle update
 | 静态资源 | 动态编译 | 预编译 (`rails assets:precompile`) |
 | 数据库密码 | 明文配置 | 使用 Secrets 管理 |

-## 延伸阅读
+### 延伸阅读

- [使用 Django](django.md)：Python Web 框架实战
- [Compose 模板文件](compose_file.md)：配置详解
+- [使用 Django](9.6_django.md)：Python Web 框架实战
+- [Compose 模板文件](9.5_compose_file.md)：配置详解
 - [数据管理](../07_data_network/README.md)：数据持久化
--- a/09_compose/9.8_wordpress.md
+++ b/09_compose/9.8_wordpress.md
@@ -1,12 +1,12 @@
-# 实战 WordPress
+## 实战 WordPress

-## 简介
+### 简介

 WordPress 是全球最流行的内容管理系统（CMS）。使用 Docker Compose 可以在几分钟内搭建一个包含数据库、Web 服务和持久化存储的生产级 WordPress 环境。

 ---

-## 项目结构
+### 项目结构

 ```
 wordpress/
@@ -18,7 +18,7 @@ wordpress/

 ---

-## 编写 `docker-compose.yml`
+### 编写 `docker-compose.yml`

 这是一个生产可用的最小化配置：

@@ -75,9 +75,9 @@ networks:

 ---

-## 配置文件详解
+### 配置文件详解

-### 1. 环境变量 (.env)
+#### 1. 环境变量 (.env)

 为了安全，不要在 `docker-compose.yml` 中直接写密码。创建 `.env` 文件：

@@ -88,13 +88,13 @@ DB_PASSWORD=somestronguserpassword

 Compose 会自动读取此同级目录下的文件。

-### 2. 数据持久化
+#### 2. 数据持久化

 我们定义了两个命名卷：
 - `db_data`: 确保 MySQL 容器重建后数据不丢失
 - `wp_data`: 保存 WordPress 的核心文件、插件、主题和上传的媒体文件

-### 3. PHP 配置优化
+#### 3. PHP 配置优化

 默认的 WordPress 镜像上传文件限制较小（通常 2MB）。创建 `uploads.ini`：

@@ -108,7 +108,7 @@ max_execution_time = 600

 ---

-## 启动与运行
+### 启动与运行

 1. 启动服务：

@@ -127,14 +127,14 @@ $ docker compose logs -f

 ---

-## 生产环境最佳实践
+### 生产环境最佳实践

-### 1. 数据库备份
+#### 1. 数据库备份

 不要只依赖 Volume。建议定期备份数据库：

 ```bash
-# 导出 SQL
+## 导出 SQL
 $ docker exec wordpress_db mysqldump -u wordpress -pwordpress wordpress > backup.sql
 ```

@@ -158,11 +158,11 @@ $ docker exec wordpress_db mysqldump -u wordpress -pwordpress wordpress > backup
      - wp_net
 ```

-### 2. 使用 Nginx 反向代理
+#### 2. 使用 Nginx 反向代理

 在生产环境中，不要直接暴露 WordPress 端口，而是通过 Nginx 进行反向代理并配置 SSL。

-### 3. 使用 Redis 缓存
+#### 3. 使用 Redis 缓存

 WordPress 支持 Redis 缓存以提高性能。

@@ -182,9 +182,9 @@ WordPress 支持 Redis 缓存以提高性能。

 ---

-## 常见问题
+### 常见问题

-### Q: 数据库连接错误
+#### Q: 数据库连接错误

 **现象**：访问页面显示 "Error establishing a database connection"。

@@ -194,7 +194,7 @@ WordPress 支持 Redis 缓存以提高性能。
 3. 确认 `WORDPRESS_DB_HOST` 也是 `db`（服务名）
 4. MySQL 8.0 可能需要几秒钟启动，WordPress 会自动重试，稍等片刻即可。

-### Q: 无法上传大文件
+#### Q: 无法上传大文件

 **解决**：确保挂载了 `uploads.ini` 配置，并且重启了容器：
 ```bash
@@ -203,8 +203,8 @@ $ docker compose restart wordpress

 ---

-## 延伸阅读
+### 延伸阅读

- [Compose 模板文件](compose_file.md)：深入了解配置项
+- [Compose 模板文件](9.5_compose_file.md)：深入了解配置项
 - [数据卷](../07_data_network/data/volume.md)：理解数据持久化
 - [Docker Hub WordPress](https://hub.docker.com/_/wordpress)：官方镜像文档
--- a/09_compose/9.9_lnmp.md
+++ b/09_compose/9.9_lnmp.md
@@ -1,3 +1,3 @@
-# 使用 compose 搭建 LNMP 环境
+## 使用 compose 搭建 LNMP 环境

 本项目的维护者 [khs1994](https://github.com/khs1994) 的开源项目 [khs1994-docker/lnmp](https://github.com/khs1994-docker/lnmp) 使用 Docker Compose 搭建了一套 LNMP 环境，各位开发者可以参考该项目在 Docker 或 Kubernetes 中运行 LNMP。
--- a/09_compose/README.md
+++ b/09_compose/README.md
@@ -1,4 +1,4 @@
-# Docker Compose 项目
+# 第九章 Docker Compose

 `Docker Compose` 是 Docker 官方编排（Orchestration）项目之一，负责快速的部署分布式应用。