Docker Compose 使用指南#

Docker Compose 是 Docker 官方的容器编排工具，用于定义和运行多容器 Docker 应用。

特点#

特性	说明
声明式配置	使用 YAML 文件定义服务、网络、卷等
多容器管理	一键启动/停止多个关联容器
环境隔离	项目级别的容器分组管理
版本控制	配置文件可版本化管理
易于迁移	配置文件可轻松迁移到其他环境

安装#

Docker Desktop（推荐）#

Docker Desktop 已内置 Docker Compose，无需单独安装。

基本语法#

文件结构#

docker-compose.yml 基本结构：

services:
  服务名称:
    image: 镜像名
    ports:
      - "端口映射"
    volumes:
      - "卷映射"

networks:
  网络名称:
    driver: bridge

常用字段#

字段	说明	示例
`services`	定义服务（容器）	见下方详解
`networks`	定义网络	`networks: mynet:`
`volumes`	定义存储卷	`volumes: myvol:`

常用命令#

项目管理#

# 启动项目（前台运行）
docker compose up

# 启动项目（后台运行）
docker compose up -d

# 停止项目
docker compose down

# 停止并删除卷
docker compose down -v

# 重启项目
docker compose restart

服务管理#

# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs

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

# 进入服务容器
docker compose exec 服务名 bash

# 启动单个服务
docker compose start 服务名

# 停止单个服务
docker compose stop 服务名

# 重启单个服务
docker compose restart 服务名

构建和更新#

# 构建镜像
docker compose build

# 拉取镜像
docker compose pull

# 重新创建服务（更新配置）
docker compose up -d --force-recreate

# 仅重建变化的服务
docker compose up -d --build

其他命令#

# 验证配置文件语法
docker compose config

# 查看服务镜像
docker compose images

# 查看服务进程
docker compose top

# 指定配置文件
docker compose -f 文件名.yml up

# 指定项目名称
docker compose -p 项目名 up

配置详解#

服务配置 (services)#

基础配置#

services:
  myservice:
    image: nginx:latest       # 镜像名称
    container_name: nginx     # 容器名称
    restart: always           # 重启策略 (no/always/on-failure/unless-stopped)
    hostname: myhost          # 主机名

端口映射#

ports:
  - "8080:80"                 # 单端口映射
  - "192.168.1.1:8080:80"     # 指定IP映射
  - "9090:9090/tcp"           # 指定协议

卷映射#

volumes:
  - ./data:/app/data          # 相对路径映射
  - /var/log:/var/log         # 绝对路径映射
  - myvolume:/app/data        # 使用命名卷

环境变量#

environment:
  - TZ=Asia/Shanghai
  - MYSQL_ROOT_PASSWORD=123456

# 或使用 env_file
env_file:
  - .env
  - config.env

网络配置#

networks:
  - mynetwork
  - another-network

# 或指定别名
networks:
  mynetwork:
    aliases:
      - alias1

资源限制#

deploy:
  resources:
    limits:
      cpus: '0.5'             # CPU限制
      memory: 512M            # 内存限制
    reservations:
      cpus: '0.25'
      memory: 256M

其他配置#

privileged: true              # 特权模式
shm_size: 2g                  # 共享内存大小
working_dir: /app             # 工作目录
user: root                    # 用户
stdin_open: true              # 保持标准输入打开
tty: true                     # 分配伪终端

启动命令#

command: python app.py        # 启动命令

# 或使用 bash
command: >
  /bin/bash -c "
    service ssh start;
    tail -f /dev/null
  "

entrypoint: /entrypoint.sh    # 入口点

健康检查#

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

依赖关系#

depends_on:
  - db                         # 依赖的服务
  - redis

网络配置 (networks)#

networks:
  mynetwork:                   # 自定义网络
    driver: bridge             # 网络驱动
    ipam:
      config:
        - subnet: 172.20.0.0/16

  external_network:            # 外部网络
    external: true

卷配置 (volumes)#

volumes:
  myvolume:                    # 命名卷
    driver: local
    driver_opts:
      type: none
      device: /path/to/data
      o: bind

实战示例#

示例1：开发环境容器#

路径：assets/tong-ws/docker-compose.yml

networks:
  1panel-network:
    external: true             # 使用外部网络

services:
  tong-ws:
    image: tong/ws:2026-4-20
    container_name: tong-ws
    privileged: true           # 特权模式
    shm_size: 2g               # 共享内存大小
    networks:
      - 1panel-network
    ports:
      - "2202:22"              # SSH端口映射
    volumes:
      - /home/tong/ws:/opt/tong/ws  # 工作目录映射
    command: >
      /bin/bash -c "
        service ssh start;
        tail -f /dev/null
      "

说明： - 使用外部网络 1panel-network（由 1Panel 创建） - 启动 SSH 服务并保持容器运行 - 映射工作目录方便开发

示例2：AstrBot 应用#

路径：assets/astrbot/docker-compose.yml

networks:
  1panel-network:
    external: true

services:
  astrbot:
    container_name: astrbot
    deploy:
      resources:
        limits:
          cpus: ${CPUS}        # CPU限制（环境变量）
          memory: ${MEMORY_LIMIT}  # 内存限制（环境变量）
    environment:
      - TZ=${TIME_ZONE}        # 时区设置
    image: soulter/astrbot:v4.22.3
    labels:
      createdBy: Apps
    networks:
      - 1panel-network
    ports:
      - ${HOST_IP}:${PANEL_APP_PORT_HTTP}:6185
      - ${HOST_IP}:${ASTRBOT_WEIXIN_OFFICIAL_PORT}:6194
      - ${HOST_IP}:${ASTRBOT_WECOM_PORT}:6195
      - ${HOST_IP}:${ASTRBOT_QQ_OFFICIAL_PORT}:6196
      - ${HOST_IP}:${ASTRBOT_QQ_PERSONAL_PORT}:6199
      - ${HOST_IP}:${ASTRBOT_WECHAT_PERSONAL_PORT}:11451
    restart: always
    volumes:
      - ./data:/AstrBot/data   # 数据持久化

说明： - 使用环境变量配置端口和资源限制 - 多端口映射支持多种平台接入 - 数据目录持久化存储 - 需要 .env 文件定义环境变量

对应的 .env 文件示例：

HOST_IP=0.0.0.0
TIME_ZONE=Asia/Shanghai
CPUS=2
MEMORY_LIMIT=2G
PANEL_APP_PORT_HTTP=6185
ASTRBOT_WEIXIN_OFFICIAL_PORT=6194
ASTRBOT_WECOM_PORT=6195
ASTRBOT_QQ_OFFICIAL_PORT=6196
ASTRBOT_QQ_PERSONAL_PORT=6199
ASTRBOT_WECHAT_PERSONAL_PORT=11451

示例3：传统 docker run 转换为 compose#

原 docker run 命令（assets/start_docker_openclaw.sh）：

docker run -itd --privileged  --shm-size=1g  --ulimit memlock=-1  --ulimit stack=67108864 \
  --name openclaw \
  -p 2203:22 \
  -v /home/t/ws/openclaw/workspace:/root/.openclaw/workspace \
  openclaw-docker:latest \
  /bin/bash -c "service ssh start && /bin/bash"

转换为 docker-compose.yml：

services:
  openclaw:
    image: openclaw-docker:latest
    container_name: openclaw
    privileged: true
    shm_size: 1g
    ulimits:
      memlock: -1
      stack: 67108864
    ports:
      - "2203:22"
    volumes:
      - /home/t/ws/openclaw/workspace:/root/.openclaw/workspace
    command: >
      /bin/bash -c "
        service ssh start;
        /bin/bash
      "

常见问题#

Q1: 端口冲突#

错误：port is already allocated

解决： 1. 检查端口占用：netstat -tlnp | grep 端口 2. 修改 compose 文件中的端口映射 3. 停止冲突容器

Q2: 权限问题#

错误：permission denied

解决：

# 方式1：使用特权模式
privileged: true

# 方式2：指定用户
user: root

Q3: 网络连接问题#

问题：容器间无法通信

解决：

# 确保容器在同一网络
services:
  app:
    networks:
      - mynetwork
  db:
    networks:
      - mynetwork

networks:
  mynetwork:
    driver: bridge

Q4: 配置更新不生效#

问题：修改配置后容器未更新

解决：

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

# 或停止后重新启动
docker compose down
docker compose up -d

Q5: 环境变量未生效#

问题：.env 文件变量未加载

解决：

# 检查 .env 文件格式（无空格、无引号）
VAR=value

# 验证配置
docker compose config

# 明确指定 env_file
env_file:
  - .env

Q6: 卷挂载失败#

错误：mount destination must be a directory

解决：

# 确保宿主机目录存在
mkdir -p /path/to/data

# 或使用命名卷
volumes:
  myvolume:/app/data

最佳实践#

使用 .env 文件：环境变量分离，便于配置管理
命名卷管理数据：持久化数据使用命名卷
健康检查：配置健康检查确保服务稳定
资源限制：设置 CPU 和内存限制防止资源耗尽
网络隔离：不同项目使用不同网络
版本锁定：镜像使用具体版本号而非 latest
日志管理：配置日志驱动和大小限制