第 3 章 · 基础语法：services、image、ports、volumes

第 3 章 · 基础语法

3.1 Compose 文件的基本结构

一个最小的 Compose 文件只需要一个 services 顶级键：

# compose.yaml（推荐文件名）
# 也可以是 docker-compose.yml 或 docker-compose.yaml

services:
  my-service:
    image: nginx:alpine

顶级键一览

顶级键	必填	说明
`services`	✅	定义应用的服务（容器）列表
`networks`	❌	自定义网络配置
`volumes`	❌	命名数据卷声明
`configs`	❌	配置对象（Swarm/独立）
`secrets`	❌	敏感信息声明

文件命名优先级

Compose 按以下顺序查找配置文件（找到第一个即停止）：

compose.yaml
compose.yml
docker-compose.yaml
docker-compose.yml

💡 建议：新项目统一使用 compose.yaml，更简洁且是官方推荐。

多文件指定

# 指定自定义文件名
docker compose -f my-services.yaml up

# 多文件合并（后面的覆盖前面的）
docker compose -f compose.yaml -f compose.prod.yaml up

3.2 services 详解

services 是 Compose 的核心，每个键代表一个服务，对应一个或多个容器。

最小示例

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

服务名规则

规则	示例
只能包含 `a-z`、`A-Z`、`0-9`、`_`、`.`、`-`	✅ `my-app`、`web_server`
不能以数字开头	❌ `1web`
服务名即为容器的主机名	容器内通过 `web` 访问同网络的其他服务

3.3 image 指令

指定服务使用的 Docker 镜像。

格式

services:
  app:
    image: <repository>[:<tag>][@<digest>]

示例

services:
  # 标准格式 - 仓库:标签
  web:
    image: nginx:1.27-alpine

  # 使用摘要锁定版本（不可变）
  db:
    image: postgres:16-alpine@sha256:abc123def456...

  # Docker Hub 官方镜像（省略仓库地址）
  cache:
    image: redis:7

  # 第三方镜像（完整路径）
  monitoring:
    image: grafana/grafana:11.0.0

  # 私有仓库镜像
  private-app:
    image: registry.example.com/myapp:latest

  # 本地构建的镜像（与 build 指令配合）
  backend:
    build: ./backend
    # 构建后镜像名自动为 <project>-backend

镜像标签最佳实践

做法	推荐	原因
`image: nginx:latest`	❌	每次拉取可能不同，不可复现
`image: nginx:1.27`	⚠️	次版本更新可能破坏兼容
`image: nginx:1.27.0-alpine`	✅	精确版本 + 轻量基础
`image: nginx@sha256:...`	✅✅	最安全，完全不可变

3.4 ports 端口映射

将容器内部端口暴露到宿主机。

格式

services:
  web:
    ports:
      - "HOST_PORT:CONTAINER_PORT"        # 短语法
      - target: 80                        # 长语法
        published: "8080"
        protocol: tcp
        host_ip: 127.0.0.1

短语法详解

services:
  web:
    ports:
      # 宿主机 8080 → 容器 80
      - "8080:80"

      # 仅暴露端口，宿主机随机分配
      - "80"

      # 指定协议
      - "53:53/udp"
      - "53:53/tcp"

      # 指定绑定地址（仅本地访问）
      - "127.0.0.1:8080:80"

      # 端口范围
      - "9090-9091:8080-8081"

      # 混合使用
      - "3000"
      - "8080:80"
      - "127.0.0.1:5432:5432"

长语法详解

services:
  web:
    ports:
      - target: 80           # 容器端口
        published: "8080"    # 宿主机端口（引号可选）
        protocol: tcp        # tcp 或 udp
        host_ip: 127.0.0.1   # 绑定地址，默认 0.0.0.0
        app_protocol: http   # 应用协议（Compose V2.20+）

      # 仅容器端口，不发布到宿主机
      - target: 9090
        published: false

端口映射对照表

写法	宿主机绑定	宿主机端口	容器端口
`"8080:80"`	0.0.0.0	8080	80
`"127.0.0.1:8080:80"`	127.0.0.1	8080	80
`"80"`	0.0.0.0	随机	80
`"80/tcp"`	0.0.0.0	80	80 (TCP)
`published: false`	—	不发布	80

⚠️ 安全提示：端口映射到 0.0.0.0 意味着所有网络接口都可访问。生产环境建议绑定到 127.0.0.1 或使用防火墙。

3.5 volumes 数据卷

数据卷用于持久化数据和共享文件。

三种挂载方式

services:
  db:
    volumes:
      # 1. Named Volume（命名卷）— 推荐用于持久数据
      - pgdata:/var/lib/postgresql/data

      # 2. Bind Mount（绑定挂载）— 用于开发时同步代码
      - ./src:/app/src

      # 3. tmpfs Mount（内存挂载）— 用于临时数据
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 100000000    # 100MB

短语法详解

services:
  app:
    volumes:
      # 命名卷
      - mydata:/data

      # 绑定挂载 — 只读
      - ./config/app.conf:/etc/app/app.conf:ro

      # 绑定挂载 — 读写（默认）
      - ./logs:/var/log/app

      # 命名卷 + 指定容器内路径
      - uploads:/var/www/uploads

长语法详解

services:
  app:
    volumes:
      - type: volume           # 命名卷
        source: mydata
        target: /data

      - type: bind             # 绑定挂载
        source: ./config
        target: /etc/app
        read_only: true

      - type: tmpfs            # 内存挂载
        target: /tmp
        tmpfs:
          size: 104857600      # 100MB

顶级 volumes 声明

使用命名卷时，必须在顶级 volumes 中声明：

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:    # 声明命名卷
    # 可选配置
    name: my_project_pgdata   # 自定义卷名（覆盖默认命名）
    external: false           # 是否为外部卷

卷命名规则

如果不指定 name 属性，命名卷的全名格式为 <项目名>_<卷名>：

# 项目目录名为 myapp
# 卷名 pgdata → 实际卷名 myapp_pgdata

# 查看卷
docker volume ls

# 查看卷详情
docker volume inspect myapp_pgdata

💡 建议：生产环境显式指定卷名（name 属性），避免因项目目录名变化导致卷名不一致。

3.6 完整示例：LAMP 环境

将以上概念组合，搭建一个经典的 LAMP（Linux + Apache + MySQL + PHP）环境：

# compose.yaml
services:
  # Apache + PHP
  web:
    image: php:8.3-apache
    ports:
      - "8080:80"
    volumes:
      - ./www:/var/www/html:ro    # 挂载网站代码
    depends_on:
      - db

  # MySQL 数据库
  db:
    image: mysql:8.0
    ports:
      - "127.0.0.1:3306:3306"    # 仅本地访问
    volumes:
      - mysql_data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: myapp
      MYSQL_USER: appuser
      MYSQL_PASSWORD: apppass

  # phpMyAdmin
  adminer:
    image: adminer:latest
    ports:
      - "8081:8080"
    depends_on:
      - db

volumes:
  mysql_data:

使用流程

# 创建项目结构
mkdir lamp-demo && cd lamp-demo
mkdir www

# 创建测试页面
cat > www/index.php << 'EOF'
<?php
echo "<h1>Docker Compose LAMP Demo</h1>";
echo "<p>PHP Version: " . phpversion() . "</p>";

try {
    $pdo = new PDO('mysql:host=db;dbname=myapp', 'apppass', 'apppass');
    echo "<p>✅ MySQL 连接成功</p>";
} catch (PDOException $e) {
    echo "<p>❌ MySQL 连接失败: " . $e->getMessage() . "</p>";
}
?>
EOF

# 启动
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f web

# 浏览器访问 http://localhost:8080

3.7 常用管理命令

生命周期命令

# 启动所有服务（前台，Ctrl+C 停止）
docker compose up

# 启动所有服务（后台）
docker compose up -d

# 停止并删除容器、网络
docker compose down

# 停止并删除容器、网络 + 数据卷
docker compose down -v

# 停止并删除容器、网络 + 本地镜像
docker compose down --rmi local

# 重启服务
docker compose restart
docker compose restart web    # 重启指定服务

# 停止服务（不删除容器）
docker compose stop

# 启动已停止的服务
docker compose start

# 暂停/恢复服务
docker compose pause
docker compose unpause

查看状态

# 查看运行中的服务
docker compose ps

# 查看所有服务（含已停止的）
docker compose ps -a

# 查看资源使用情况
docker compose top

# 查看日志
docker compose logs
docker compose logs -f            # 实时跟踪
docker compose logs -f web        # 跟踪指定服务
docker compose logs --tail 50     # 最后 50 行
docker compose logs -f --since 5m # 最近 5 分钟

执行命令

# 在运行中的容器内执行命令
docker compose exec web bash
docker compose exec db mysql -uroot -prootpass

# 执行一次性命令（创建新容器）
docker compose run --rm web python manage.py migrate
docker compose run --rm web npm test

镜像管理

# 拉取所有服务的镜像
docker compose pull

# 构建所有服务的镜像
docker compose build

# 拉取 + 构建 + 启动
docker compose up -d --build

# 查看服务配置（解析后的 YAML）
docker compose config

# 查看镜像
docker compose images

3.8 服务的生命周期状态

              docker compose up
                    │
    ┌───────────────▼───────────────┐
    │          Creating             │
    │    (创建容器、网络、卷)         │
    └───────────────┬───────────────┘
                    │
    ┌───────────────▼───────────────┐
    │          Starting             │
    │      (启动容器进程)            │
    └───────────────┬───────────────┘
                    │
    ┌───────────────▼───────────────┐
    │          Running              │
    │       (正常运行中)             │
    └───────┬───────────────┬───────┘
            │               │
      docker compose    容器退出
        stop/down           │
            │         ┌─────▼──────┐
    ┌───────▼──────┐  │   Exited   │
    │   Stopped    │  │  (已退出)    │
    └───────┬──────┘  └─────┬──────┘
            │               │
      docker compose   docker compose
        down               up
            │               │
    ┌───────▼──────┐        │
    │   Removed    │        │
    │  (已删除)     │   (重新创建)
    └──────────────┘

3.9 实战：快速搭建 WordPress

# compose.yaml — 一键部署 WordPress
services:
  wordpress:
    image: wordpress:6-php8.3-apache
    ports:
      - "8080:80"
    volumes:
      - wp_data:/var/www/html
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress_pass
      WORDPRESS_DB_NAME: wordpress
    restart: unless-stopped

  db:
    image: mysql:8.0
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress_pass
      MYSQL_ROOT_PASSWORD: root_secret
    restart: unless-stopped

volumes:
  wp_data:
  db_data:

docker compose up -d
# 访问 http://localhost:8080 完成 WordPress 安装

3.10 小结

概念	要点
`services`	Compose 核心，每个服务对应一组容器
`image`	指定镜像，建议使用精确版本标签
`ports`	宿主机:容器端口映射，生产环境注意绑定地址
`volumes`	三种挂载方式，命名卷用于持久化，绑定挂载用于开发
管理命令	`up -d` / `down` / `logs -f` / `exec` / `ps`

扩展阅读

上一章：第 2 章 · 安装 ← ｜下一章：第 4 章 · 网络 →

强曰为道

第 3 章 · 基础语法：services、image、ports、volumes

第 3 章 · 基础语法

3.1 Compose 文件的基本结构

顶级键一览

文件命名优先级

多文件指定

3.2 services 详解

最小示例

服务名规则

3.3 image 指令

格式

示例

镜像标签最佳实践

3.4 ports 端口映射

格式

短语法详解

长语法详解

端口映射对照表

3.5 volumes 数据卷

三种挂载方式

短语法详解

长语法详解

顶级 volumes 声明

卷命名规则

3.6 完整示例：LAMP 环境

使用流程

3.7 常用管理命令

生命周期命令

查看状态

执行命令

镜像管理

3.8 服务的生命周期状态

3.9 实战：快速搭建 WordPress

3.10 小结

扩展阅读