Compose模板文件主要命令 |
|---|
命令 | 功能 |
|---|
build | 指定Dockerfile所在文件夹的路径（可以是绝对路径，或者相对docker-compose.yml文件的路径）。Compose将会利用它自动构建应用镜像，然后使用这个镜像。 build指令还可以指定创建镜像的上下文（context）、Dockerfile路径、标签（labels）、Shm大小（shm_size）、参数（args）和缓存来源（cache_from）等。
version: '3'
services:
app:
build: /path/to/build/dir
####################################
version: '3'
services:
app:
build:
context: /path/to/build/dir
dockerfile: Dockerfile-app
labels:
version: "2.0"
released: "true"
shm_size: '2gb'
args:
key: value
name: myApp
cache_from:
- myApp:1.0
|
cap_add | cap_add:
- ALL
|
cap_drop | cap_drop:
- NET_ADMIN
|
cgroup_parent | cgroup_parent: cgroups_1
|
command | command: echo "hello world"
command: ["bash", "-c", "echo", "hello world"]
|
configs | version: "3.3"
services:
app:
image: myApp:1.0
deploy:
replicas: 1
configs: # 挂载配置文件到容器
- file_config # 本地文件配置
- external_config # 外部来源配置
configs:
file_config: # 本地文件配置定义
file: ./config_file.cfg # 配置文件的相对路径
external_config: # 外部来源配置定义
external: true # 使用预先在Swarm集群中创建的外部配置
|
container_name | 指定容器名称。默认格式：项目名称_服务名称_序号（如 myproject_web_1） 自定义名称：通过 container_name 字段指定 不支持 Swarm 模式：此配置仅在单机 Docker 环境生效 指定容器名称后，该服务无法横向扩展（scale），Docker 不允许同一主机上存在多个同名容器。
|
deploy | 指定部署和运行时的容器配置 仅Swarm模式生效 仅支持docker stack deploy
|
depends_on | services:
web:
image: my-web-app
depends_on:
- db # 声明依赖db服务
db:
image: postgres:14
|
devices | services:
my_service:
image: my_image
devices:
- "/dev/ttyUSB1:/dev/ttyUSB0" # 宿主机的USB1设备映射到容器USB0接口
|
dns | dns: 8.8.8.8 # 使用Google公共DNS
dns:
- 8.8.8.8 # 主DNS
- 9.9.9.9 # 备用DNS (Quad9)
|
dns_search | dns_search: example.com # 配置单个搜索域
dns_search:
- domain1.example.com # 主搜索域
- domain2.example.com # 备用搜索域
|
dockerfile | dockerfile: Dockerfile-alternate # 指定备用Dockerfile名称
|
entrypoint | entrypoint: python app.py # 直接覆盖为Python应用启动命令
|
env_file | 从指定文件加载环境变量到容器，支持两种配置形式：单文件路径（字符串格式）、多文件列表（数组格式）。 路径解析基准：若使用 -f 指定自定义模板文件（如 docker-compose -f file.yml），路径基于模板文件所在目录（非执行命令的当前目录）。 变量冲突处理：与 environment 指令冲突时，以 environment 定义的值为准。 文件格式规范：每行需符合 VAR=VALUE 格式，支持 # 开头的注释行。
env_file: .env # 加载当前目录下的.env文件
#############
env_file:
- ./common.env # 通用环境变量
- ./apps/web.env # 服务专用变量
- ./opt/secrets.env # 密钥文件
#########
环境变量文件
# common.env：设置开发环境
PROG_ENV=development # 程序环境变量
DB_HOST=db.example.com # 数据库地址
API_KEY=abc123xyz # 接口密钥（实际使用需加密）
|
environment | 字典格式
environment:
RACK_ENV: development # 直接赋值
SESSION_SECRET: # 继承宿主机同名变量值
数组格式
environment:
- "RACK_ENV=development"
- SESSION_SECRET # 继承宿主机变量（无需赋值）
|
expose | expose:
- '3000'
- '8000'
|
extends | 
|
external_links | external_links:
- redis_1 # 无别名链接
- project_db_1:mysql # 容器名:服务别名
- project_db_1:postgresql # 同一容器映射多别名
|
extra_hosts | 例如：
extra_hosts:
- "googledns:8.8.8.8"
- "dockerhub:52.1.157.61"
在启动后的服务容器中，/etc/hosts 文件会自动添加以下两条映射记录：
8.8.8.8 googledns
52.1.157.61 dockerhub
|
healthcheck | healthcheck:
# 健康检测命令：使用curl检测本地8080端口，-f参数确保服务不可用时返回非零状态码
test: ["CMD", "curl", "-f", "http://localhost:8080"]
# 检测频率：每30秒执行一次健康检查
interval: 30s
# 单次检测超时：每次检测最长等待15秒
timeout: 15s
# 失败重试：连续3次检测失败才标记为不健康
retries: 3
# 启动缓冲期：容器启动后等待30秒才开始健康检查（避免初始化期间误判）
start_period: 30s
|
image | # 1. 官方仓库镜像（简写形式）
image: ubuntu
# 2. Docker Hub用户仓库镜像（格式：用户名/镜像名）
image: orchardup/postgresql
# 3. 镜像ID（完整ID或缩写形式）
image: a4bc65fd
|
isolation | 配置容器隔离的机制，包括default、process和hyperv。 default：默认隔离机制（通常是命名空间隔离）
process：进程级隔离（轻量级隔离方案）
hyperv：基于Hyper-V的强隔离（Windows容器专用）
|
labels | labels:
com.startupteam.description: "webapp for a startup team"
com.startupteam.department: "devops department"
com.startupteam.release: "rc3 for v1.0"
|
links | 配置示例：
links:
- db
- db:database
- redis
使用的别名将会自动在服务容器中的/etc/hosts里创建。例如：
172.17.2.186 db
172.17.2.186 database
172.17.2.187 redis
被链接容器中相应的环境变量也将被创建。
|
logging | # 日志配置说明
# 包括一系列子配置
# 1. 日志驱动类型配置 (logging.driver)
# 类似于Docker中的--log-driver参数，指定日志驱动类型
# 目前支持三种日志驱动类型：
driver: "json-file" # 默认驱动，日志存储在JSON文件中
driver: "syslog" # 将日志发送到syslog服务器
driver: "none" # 禁用所有日志记录
# 2. 日志驱动参数配置 (logging.options)
# 日志驱动的相关参数设置
# 示例配置1：syslog驱动配置
logging:
driver: "syslog" # 指定syslog日志驱动类型
options:
syslog-address: "tcp://192.168.0.42:123" # syslog服务器的TCP地址
# 示例配置2：json-file驱动配置
logging:
driver: "json-file" # 指定json-file日志驱动类型
options:
max-size: "1000k" # 单个日志文件最大尺寸
max-file: "20" # 保留的日志文件最大数量
|
network_mode | network_mode: "none" # 无网络模式
network_mode: "bridge" # 默认桥接模式
network_mode: "host" # 宿主机网络模式
network_mode: "service:[service name]" # 共享服务网络栈
network_mode: "container:[name or id]" # 共享指定容器网络栈
|
networks | 首先在顶级networks中定义网络web_net的基本参数 在服务web中通过networks.web_net加入该网络（所加入的网络需要在顶级的networks字段中定义具体的网络信息）。 为服务添加别名web_app（其他容器可通过该别名访问） 指定服务的静态IPv4地址确保访问稳定性
顶级网络定义
networks:
web_net:
driver: bridge # 使用桥接网络驱动
enable_ipv6: true # 启用IPv6支持
ipam: # IP地址管理配置
driver: default # 使用默认IPAM驱动
config:
- subnet: 172.16.0.0/24 # 定义IP地址分配子网
服务网络配置
services:
web:
networks:
web_net:
aliases: web_app # 在网络中设置服务别名
ipv4_address: 172.16.0.10 # 指定服务的静态IPv4地址
|
pid | pid: "host"
|
ports | 暴露端口信息。使用宿主:容器(HOST:CONTAINER)格式，或者仅仅指定容器的端口(宿主将会随机选择端口)都可以。 当使用 HOST:CONTAINER 格式映射端口时，如果容器端口小于60且未加引号，可能会解析错误（YAML会将 xx:yy 格式解析为60进制数）。例如：30:30 会被解析为 30分30秒（即1830秒）而非端口映射。 强烈建议：所有端口配置都采用引号包裹的字符串格式。
ports:
- "3000" # 仅容器端口（宿主随机分配）
- "8000:8000" # 宿主端口:容器端口
- "49100:22" # 将宿主49100映射到容器22(SSH)
- "127.0.0.1:8001:8001" # 限定本地访问的映射
或者使用对象格式：
ports:
- target: 80 # 容器内部端口
published: 8080 # 宿主暴露端口
protocol: tcp # 协议类型（TCP/UDP）
mode: ingress # 模式（ingress/host）
|
restart | restart: unless-stopped # 严格保留原图短横线格式（无空格）
|
security_opt | security_opt:
- label:user:USER # 用户名标签配置
- label:role:ROLE # 角色名标签配置
|
secrets | version: "3.1" # Docker Compose版本
services:
web:
image: webapp:stable # 服务镜像
deploy: # 部署配置
replicas: 2 # 副本数量
secrets: # 密钥配置
- source: web_secret # 来源密钥名称
target: web_secret # 挂载后密钥名称
uid: '103' # 用户ID
gid: '103' # 组ID
mode: 0444 # 文件权限（只读）
secrets: # 密钥定义
web_secret: # 密钥名称
file: ./web_secret.txt # 密钥源文件路径
|
stop_grace_period | |
stop_signal | |
sysctls | # 示例：指定连接数和开启TCP防护
sysctls:
net.core.somaxconn: 4096 # 最大连接队列长度
net.ipv4.tcp_syncookies: 1 # 开启SYN洪水攻击防护
|
ulimits | # 示例配置：
ulimits:
nproc: 65535 # 最大进程数限制（硬限制）
nofile: # 文件句柄数限制
soft: 20000 # 软限制（应用可随时修改，不超过硬限制）
hard: 40000 # 硬限制（仅root用户可提高）
|
userns_mode | 例如，使用主机上的用户命名空间：
userns_mode: "host"
|
volumes | volumes:
- /var/lib/mysql # 匿名卷（仅指定容器路径）
- cache/:/tmp/cache # 相对路径（宿主机cache目录→容器/tmp/cache）
- ~/configs:/etc/configs/:ro # 用户家目录映射（ro=只读权限）
或者可以使用更详细的语法格式：
volumes:
- type: volume # 挂载类型（volume/bind/tmpfs）
source: mydata # 数据卷名称
target: /data # 容器内挂载点
volume:
nocopy: true # 禁止从容器复制初始数据
# 顶级数据卷定义
volumes:
mydata: # 自定义数据卷名称 # 实际使用时需在services和volumes中同时声明
|
deploy | |
其他指令 | 
|
读取环境变量 | 
|
扩展特性 | # 从3.4版本开始，Docker Compose支持用户自定义扩展字段
# 通过YAML的锚点引用功能实现配置复用
version: '3.4' # 要求最低3.4版本
# 定义自定义扩展字段 (x-前缀)
x-logging: &default-logging # 锚点命名为default-logging
options:
max-size: '10m' # 单个日志文件最大10MB
max-file: '10' # 最多保留10个历史日志文件
driver: json-file # 使用JSON格式日志驱动
services:
web:
image: webapp:stable # 服务镜像
logging: *default-logging # 引用自定义的日志配置
|
