docker-compose.yml 是 Docker Compose 的配置文件，用于定义和管理多容器应用的配置。它支持多种参数，用于指定服务的镜像、端口、环境变量、卷、网络、依赖关系等。以下是一个详细的 docker-compose.yml 参数说明，以及一个包含常用配置的完整示例。
1. docker-compose.yml 中的主要参数
以下是 docker-compose.yml 文件中常用的顶层字段和参数，按功能分类：
顶层字段
version:
- 指定 Docker Compose 文件格式的版本（例如
"3.8" 或 "3"）。版本决定了支持的语法和功能。
- 示例：
version: "3.8"
- 备注：最新版本建议使用
"3.8" 或更高（截至 2025 年），具体取决于 Docker Compose 版本。
services:
networks:
volumes:
configs 和 secrets:
服务级字段（services.<service_name> 下）
每个服务可以包含以下常用参数：
image:
- 指定容器使用的镜像（例如
nginx:latest）。可以是 Docker Hub 或私有仓库的镜像。
- 示例：
image: dokploy/dokploy:latest
build:
container_name:
- 自定义容器名称（默认是
项目名_服务名_编号）。
- 示例：
container_name: my-web
ports:
- 映射主机和容器的端口，支持
HOST:CONTAINER 格式或单独指定。
- 示例：
ports: ["80:80", "443:443"]
environment:
env_file:
- 指定外部文件加载环境变量（例如
.env）。
- 示例：
env_file: .env
volumes:
networks:
- 指定服务连接的网络，可以是默认或自定义网络。
- 示例：
networks: [my-network]
depends_on:
- 定义服务启动顺序，表示当前服务依赖其他服务。
- 示例：
depends_on: [db]
- 备注：仅控制启动顺序，不保证服务完全就绪。
restart:
- 定义容器重启策略（
no, always, on-failure, unless-stopped）。
- 示例：
restart: always
command:
- 覆盖容器启动时的默认命令。
- 示例：
command: ["nginx", "-g", "daemon off;"]
entrypoint:
- 覆盖容器默认的入口点。
- 示例：
entrypoint: /bin/bash
healthcheck:
labels:
- 为容器添加元数据标签。
- 示例：
labels: { com.example.description: "Web server" }
deploy (主要用于 Swarm 模式)：
logging:
secrets 和 configs:
- 引用顶层定义的
secrets 或 configs，将敏感数据挂载到容器。
- 示例：
secrets: [db-password]
网络级字段（networks.<network_name> 下）
driver:
- 指定网络驱动（如
bridge, overlay, host）。
- 示例：
driver: bridge
external:
- 指定使用外部创建的网络。
- 示例：
external: true
name:
- 自定义网络名称。
- 示例：
name: my-custom-network
卷级字段（volumes.<volume_name> 下）
driver:
- 指定卷驱动（如
local）。
- 示例：
driver: local
external:
- 指定使用外部创建的卷。
- 示例：
external: true
2. 完整的 docker-compose.yml 示例
以下是一个包含常见配置的完整 docker-compose.yml 示例，涵盖服务、环境变量、卷、网络等：
version: "3.8"
services:
web:
image: nginx:latest
container_name: web-server
ports:
- "80:80"
- "443:443"
environment:
- NGINX_PORT=80
- APP_ENV=${APP_ENV}
env_file:
- .env
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- web-data:/var/www/html
networks:
- app-network
depends_on:
- app
restart: always
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 10s
retries: 3
labels:
com.example.description: "Web server"
app:
build:
context: .
dockerfile: Dockerfile
container_name: app-server
environment:
- DB_HOST=db
- DB_USER=${DB_USER}
env_file:
- .env
volumes:
- app-data:/app/data
networks:
- app-network
depends_on:
db:
condition: service_healthy
restart: on-failure
deploy: # Swarm 模式下使用
replicas: 2
resources:
limits:
cpus: "0.5"
memory: 512M
db:
image: mysql:8.0
container_name: mysql-db
environment:
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
MYSQL_DATABASE: myapp
volumes:
- db-data:/var/lib/mysql
networks:
- app-network
restart: unless-stopped
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 5
secrets:
- db-password
networks:
app-network:
driver: bridge
name: my-app-network
volumes:
web-data:
driver: local
app-data:
driver: local
db-data:
driver: local
secrets:
db-password:
file: ./db-password.txt
对应的 .env 文件示例：
APP_ENV=production
DB_USER=myuser
DB_ROOT_PASSWORD=secretpassword
3. 说明与注意事项
- 版本选择：使用最新版本（如
"3.8"）以支持更多功能。检查 Docker Compose 版本兼容性（docker-compose --version）。
- 环境变量：
- 在
.env 中定义变量，通过 ${VARIABLE_NAME} 在 docker-compose.yml 中引用。
- 使用
env_file 指定额外的环境变量文件。
- 网络：
- 默认情况下，Compose 创建一个桥接网络，服务可相互通信。
- 自定义网络（如
app-network）可以更好地隔离服务。
- 卷：
- 使用命名卷（如
db-data）确保数据持久化。
- 外部卷（
external: true）需要事先用 docker volume create 创建。
- Swarm 模式：
deploy 字段仅在 Swarm 模式下生效，适合集群环境。- Compose 文件在单机和 Swarm 模式下大多兼容，但某些字段（如
deploy）仅限 Swarm。
- 验证配置：
- 使用
docker compose config 检查 docker-compose.yml 的语法和解析结果。
- 运行
docker compose up -d 后，用 docker compose ps 查看服务状态。
4. 与问题背景的关联
- 如果你修改了
.env 文件中的变量（如 APP_ENV 或 DB_ROOT_PASSWORD），运行 docker compose up -d 即可应用变化，Compose 会重启受影响的容器（如 web 或 db），无需 docker compose down。
- 如果修改了
docker-compose.yml 中的其他参数（如 ports、volumes），行为类似，up -d 通常足够。
- 如果需要清理资源或强制重置（如网络或卷变化），可先运行
docker compose down。
5. 总结
docker-compose.yml 支持丰富的配置参数，涵盖镜像、端口、环境变量、卷、网络等，适合定义复杂的多容器应用。上述示例展示了常见参数的用法，适用于大多数场景。根据你的需求（如更新 .env 或其他配置），通常直接运行 docker compose up -d 即可，无需 down，除非需要完全重置状态。
如果需要更具体的配置建议或针对某参数的解释，请提供更多细节！