本模板完全适配 Docker Compose V2 最新标准，
废弃无用字段、规避所有前文提到的语法/格式/逻辑坑，
统一2空格缩进、规范数组格式、标注必填/可选项，
直接填空即可正常启动，无任何隐性报错。


一、极简基础版（小型项目/本地开发首选）
无多余配置，覆盖核心功能，100%规避语法坑，适合前端、单服务、简易后端项目

# Docker Compose V2 标准配置（无需version字段，无兼容问题）
# 文件名固定：compose.yml （首选） 或 docker-compose.yml

services:
  # 自定义服务名（容器间通信直接用这个名字当域名，禁止中文、特殊字符）
  app:
    # 镜像地址（必填！必须指定版本，禁止只用latest）
    image: 镜像名:版本号
    # 容器名称（可选！填了就无法scale扩容，本地开发可填，生产不建议填）
    # container_name: custom-container-name

    # -------------------------- 核心数组配置（规范格式，绝对不报错） --------------------------
    # 端口映射：格式 "宿主机端口:容器端口" 必须加双引号，禁止写反
    ports:
      - "8080:80"
      - "443:443"

    # 环境变量（推荐键值对格式，清晰不踩坑，禁止和横线数组混用）
    environment:
      TZ: Asia/Shanghai
      # 自定义环境变量
      APP_ENV: development
      # 变量引用格式：${变量名} 从同级.env文件读取，禁止简写$变量名
      APP_SECRET: ${APP_SECRET}

    # 数据卷挂载：格式 "宿主机路径:容器路径:权限(可选ro/rw)" 相对路径必须加./
    volumes:
      # 宿主机当前目录映射到容器工作目录
      - ./:/app
      # 命名卷（持久化数据，删除容器不丢失）
      - app-data:/data

    # 重启策略（本地开发用no，生产推荐unless-stopped）
    restart: unless-stopped

    # 网络配置（自动加入默认网络，容器间互通无需额外配置）
    networks:
      - app-default

# 命名卷声明（上面volumes用到的命名卷，必须在这里声明，否则创建匿名卷）
volumes:
  app-data:

# 网络声明（自定义默认网络，自动DNS解析，服务名直接互通）
networks:
  app-default:
    driver: bridge





二、生产完整版（全场景合规·规避所有生产级坑点）
包含健康检查、资源限制、日志限制、权限管控、依赖配置、多服务规范，
直接适配线上环境，无任何安全/稳定性隐患

# Docker Compose V2 生产标准模板
# 文件名：compose.yml
# 写完必执行校验：docker compose config

services:
  # 业务应用服务示例
  backend:
    image: 业务镜像名:稳定版本号
    restart: unless-stopped
    depends_on:
      mysql:
        # 严格等待依赖服务健康检查通过再启动（彻底解决启动顺序坑）
        condition: service_healthy
      redis:
        condition: service_healthy

    # 端口映射（仅对外暴露的端口填写，内部通信不用写ports）
    ports:
      - "8080:8080"

    # 环境变量
    environment:
      TZ: Asia/Shanghai
      SPRING_PROFILES_ACTIVE: prod
      DB_HOST: mysql
      DB_PORT: 3306
      REDIS_HOST: redis
      # 敏感配置从.env文件读取，不硬编码
      DB_PASSWORD: ${DB_PASSWORD}
      REDIS_PASSWORD: ${REDIS_PASSWORD}

    # 挂载配置
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - backend-data:/app/data

    # 容器资源限制（防止服务拖垮宿主机，生产必填）
    deploy:
      resources:
        limits:
          cpus: "1"
          memory: 1G
        reservations:
          cpus: "0.2"
          memory: 256M

    # 健康检查（判断服务真正就绪，不是仅容器启动）
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      # 启动缓冲期，慢启动服务不会被误判不健康
      start_period: 60s

    # 安全权限配置（非必要不开privileged，最小权限原则）
    read_only: false
    user: "1000:1000"
    cap_drop:
      - ALL

    # 日志限制（防止日志占满磁盘，生产必填）
    logging:
      driver: json-file
      options:
        max-size: 100m
        max-file: 5
        compress: "true"

    networks:
      - app-prod-net

  # MySQL数据库服务示例
  mysql:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: app_db
      MYSQL_CHARSET: utf8mb4
    volumes:
      - mysql-data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-uroot", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s
    networks:
      - app-prod-net

  # Redis缓存服务示例
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3
    networks:
      - app-prod-net

# 持久化命名卷声明
volumes:
  backend-data:
  mysql-data:
  redis-data:

# 生产自定义网络（隔离环境，自动DNS解析）
networks:
  app-prod-net:
    driver: bridge
    # 禁止外部访问，仅容器内部互通，提升安全
    internal: false




三、配套标准 .env 空白模板

# 环境变量配置文件，compose自动读取同级.env文件
# 带特殊字符、空格、冒号的值必须加引号
# 禁止在compose.yml内硬编码敏感信息

# 应用配置
APP_SECRET=自定义密钥
APP_ENV=prod

# 数据库配置
DB_PASSWORD=数据库密码
MYSQL_ROOT_PASSWORD=root管理员密码

# Redis配置
REDIS_PASSWORD=Redis密码


四、模板内置强制避坑规则

1. 全程2空格缩进，禁用Tab，所有冒号、短横线后强制加空格，彻底解决YAML语法报错
2. 所有数组统一规范格式，禁止键值对和横线数组混用，100%规避格式坑
3. 端口、健康检查、命令全部用数组格式，杜绝Shell解析异常、YAML语法歧义
4. 强制配置时区、健康检查、重启策略、日志限制、资源限制，覆盖所有生产级隐性坑
5. 依赖配置严格等待服务就绪，彻底解决「容器启动了但服务没就绪，应用连库失败」的经典坑
6. 命名卷、网络统一规范声明，杜绝匿名卷残留、容器网络不通问题
7. 敏感信息全部剥离到.env文件，符合安全规范，无硬编码风险