docker-compose-layout

命令

Docker Compose 编排说明

docker-compose-layout

Docker Compose 编排说明

补充说明

Docker Compose 是 Docker 官方推出的多容器应用编排工具，专为单机多服务场景设计，通过标准化 YAML 文件统一定义应用的服务、网络、存储、环境变量等全部资源，解决多容器部署繁琐、环境不一致、服务依赖混乱等问题，是个人运维、小型生产服务、本地开发测试的核心工具。

核心优势

极简批量部署：单文件定义整套应用栈，一条命令即可完成多容器创建、启动、配置，无需逐个手动 docker run
环境完全一致：配置文件可跨设备、跨系统复用，杜绝环境差异问题
声明式配置管理：所有服务配置固化在文件中，无需记忆复杂的 Docker 启动参数
高效启停运维：支持批量启动、停止、重启、更新服务
自动依赖调度：可定义服务启动依赖关系，自动控制启动顺序
自动化网络管理：自动创建专属隔离网桥，实现容器间内网互通
支持版本管控：YAML 文件可纳入 Git 版本管理，方便回溯与协作
精细化资源管控：支持 CPU、内存配额限制，防止容器占用过多服务器资源

docker-compose.yml 完整基础结构

# Compose 文件版本，3.8 为通用稳定版本
version: "3.8"

# 核心：所有容器服务均定义在 services 下
services:
  # 自定义服务名称（全局唯一）
  toolbox:
    container_name: toolbox          # 固定容器名称
    image: cleverest/toolbox:latest  # 镜像地址:标签
    restart: unless-stopped          # 生产最优重启策略
    network_mode: bridge             # 网络模式，默认桥接
    ports:                           # 端口映射
      - "8383:80"
    volumes:                         # 数据持久化卷映射
      - /var/run/docker.sock:/var/run/docker.sock
      - ./app/data:/app/data
      - /mnt:/mnt
    environment:                     # 环境变量
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=1000
    extra_hosts:                     # 域名 IP 映射
      - "api.telegram.org:149.154.167.220"
    hostname: toolbox                # 容器内部主机名
    depends_on:                      # 服务依赖
      - database
      - redis

  database:
    image: postgres:13
    restart: unless-stopped
    environment:
      - POSTGRES_DB=mydb
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    volumes:
      - db_data:/var/lib/postgresql/data

# 顶层：自定义命名数据卷
volumes:
  db_data:

# 顶层：自定义网络
networks:
  default:
    driver: bridge

重启策略

策略	说明	适用场景
`"no"`	容器退出后绝不重启	一次性测试容器
`always`	无论正常退出还是异常崩溃，始终重启	常驻服务
`on-failure`	仅非 0 错误码退出时重启	程序异常自愈
`unless-stopped`	手动停止则不重启，其余情况自动重启	生产首选

端口映射

ports:
  - "8383:80"                  # 基础映射
  - "8443:443"                 # HTTPS 端口
  - "9000:9000/tcp"            # 指定 TCP 协议
  - "9000:9000/udp"            # 指定 UDP 协议
  - "49100-49200:3000-3100"    # 批量端口范围映射

卷映射

volumes:
  # 绝对路径绑定挂载（生产常用）
  - /host/path:/container/path
  # 相对路径绑定挂载
  - ./relative/path:/container/path
  # 命名卷挂载（数据库、核心数据首选）
  - named_volume:/container/path
  # 匿名卷（不推荐）
  - /container/path
  # 只读挂载
  - /host/path:/container/path:ro

环境变量

# 列表格式（通用、兼容性好）
environment:
  - TZ=Asia/Shanghai
  - PUID=1000
  - PGID=1000

# 字典格式（简洁）
environment:
  TZ: Asia/Shanghai
  PUID: 1000
  PGID: 1000

网络模式

# 默认桥接网络（推荐）
network_mode: bridge

# 主机网络（复用宿主机网卡）
network_mode: host

# 共享其他容器网络
network_mode: service:service_name

# 自定义独立网络
networks:
  - frontend
  - backend

主机映射

extra_hosts:
  - "api.telegram.org:149.154.167.220"
  - "api.tmdb.org:18.66.102.107"

容器主机名

hostname: my-container
domainname: example.com

高级配置

资源限制

deploy:
  resources:
    limits:
      memory: 2G        # 最大可用内存
      cpus: '2.0'       # 最大占用 CPU 核数
    reservations:
      memory: 512M      # 预留内存
      cpus: '1.0'       # 预留 CPU

健康检查

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

日志轮转

logging:
  driver: "json-file"
  options:
    max-size: "200k"
    max-file: "10"

实用技巧

统一环境变量文件

# .env
TZ=Asia/Shanghai
PUID=1000
PGID=1000
DB_PASSWORD=123456

# docker-compose.yml
env_file:
  - .env

多环境配置

# 开发环境
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# 生产环境
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

配置复用（YAML 锚点）

x-common: &common
  TZ: Asia/Shanghai
  PUID: 1000
  PGID: 1000

services:
  app1:
    environment:
      <<: *common
      SPECIFIC_VAR: value1

  app2:
    environment:
      <<: *common
      SPECIFIC_VAR: value2

生产规范

禁止使用 latest 标签，固定具体版本号
所有持久化数据必须挂载卷
核心服务配置资源限制 + 日志轮转
敏感信息放入 .env，禁止明文写入 compose
配置文件纳入 Git 版本管控

常用命令

启动服务

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

# 启动指定服务
docker-compose up -d 服务名

# 强制重建容器
docker-compose up -d --force-recreate

停止与销毁

# 停止服务（保留数据）
docker-compose down

# 停止并删除卷数据
docker-compose down --volumes

# 彻底清空所有资源
docker-compose down --rmi all --volumes --remove-orphans

状态与日志

# 查看服务状态
docker-compose ps

# 查看全部日志
docker-compose logs

# 实时滚动查看日志
docker-compose logs -f

# 查看指定服务日志
docker-compose logs 服务名

# 查看资源占用
docker-compose top

运维管理

# 重启全部服务
docker-compose restart

# 重启指定服务
docker-compose restart 服务名

# 扩展服务实例
docker-compose up -d --scale 服务名=3

# 进入容器
docker-compose exec 服务名 sh

故障排除

配置语法校验

docker-compose config

启动失败排查

# 查看最后 100 行日志
docker-compose logs --tail=100 -f

# 进入容器调试
docker-compose exec 服务名 sh

冗余资源清理

# 清理孤立资源
docker-compose down --remove-orphans

# 清理停止的容器
docker container prune -f

# 清理未使用的镜像
docker image prune -f

常见报错

端口冲突：修改宿主机映射端口，或关闭占用端口的程序
权限拒绝：添加 PUID/PGID 环境变量，或修改挂载目录权限
镜像拉取失败：更换镜像源、检查网络，手动拉取镜像
容器反复重启：查看日志，排查配置错误、依赖未就绪、资源不足