version: '3.8' # 指定 Docker Compose 文件格式的版本

services: # 定义应用程序中的所有服务（容器）
  web_app: # 服务名称，可以是任意有意义的字符串
    image: my-custom-web-app:latest # 使用自定义镜像
    # 或者使用公共镜像：image: nginx:stable-alpine
    build:
      context: ./web_app_source # Dockerfile 所在的目录路径
      dockerfile: Dockerfile.prod # 指定 Dockerfile 的名称，默认为 Dockerfile
    ports: # 端口映射
      - "25565:25565" # 将主机 25565 端口映射到容器 25565 端口
    environment: # 设置环境变量
      EULA: "TRUE" # 同意 Minecraft 的 EULA
    volumes: # 数据卷挂载
      - minecraft_data:/data # 挂载命名卷 'minecraft_data' 到容器的 /data 目录


  web_app: # 服务名称，可以是任意有意义的字符串
    # image: 指定用于创建容器的 Docker 镜像。
    # 如果本地不存在，Compose 会尝试从 Docker Hub 拉取。
    image: my-custom-web-app:latest # 使用自定义镜像
    # 或者使用公共镜像：
    # image: nginx:stable-alpine

    # build: 如果需要从 Dockerfile 构建镜像，而不是直接使用现有镜像。
    # 可以是一个字符串（Dockerfile 所在目录的路径）或一个映射。
    build:
      context: ./web_app_source # Dockerfile 所在的目录路径
      dockerfile: Dockerfile.prod # 指定 Dockerfile 的名称，默认为 Dockerfile
      args: # 构建时传递给 Dockerfile 的构建参数
        NODE_ENV: production
        APP_VERSION: 1.0.0
      cache_from: # 指定构建缓存的来源镜像
        - my-custom-web-app:build-cache
      labels: # 为构建的镜像添加标签
        com.example.build-date: "2025-07-31"
      network: host # 构建时使用的网络模式
      shm_size: 2g # /dev/shm 的大小，用于构建过程
      target: production-stage # 指定 Dockerfile 中的构建阶段 (multi-stage build)
      no_cache: false # 构建时不使用缓存
      pull: true # 始终尝试拉取最新的基础镜像

    # command: 覆盖镜像中定义的默认命令 (CMD)。
    # 可以是字符串或列表形式。
    command: ["nginx", "-g", "daemon off;"]
    # 或者：command: nginx -g "daemon off;"

    # entrypoint: 覆盖镜像中定义的默认入口点 (ENTRYPOINT)。
    # 可以是字符串或列表形式。
    entrypoint: ["/usr/local/bin/docker-entrypoint.sh"]

    # ports: 端口映射，将主机端口映射到容器端口。
    # 可以是 "HOST_PORT:CONTAINER_PORT" 或 "HOST_PORT:CONTAINER_PORT/PROTOCOL" 格式。
    ports:
      - "80:80" # 将主机 80 端口映射到容器 80 端口
      - "443:443/tcp" # 明确指定 TCP 协议
      - target: 8080 # 容器内部端口
        published: 8081 # 主机端口
        protocol: tcp
        mode: host # 端口发布模式 (host 或 ingress，ingress 仅用于 Swarm)

    # expose: 暴露端口给链接的服务，但不发布到主机。
    # 这些端口只能在 Compose 网络内部访问。
    expose:
      - "9000" # 暴露容器内部的 9000 端口

    # volumes: 数据卷挂载，用于持久化数据或共享文件。
    # 格式： "HOST_PATH:CONTAINER_PATH" 或 "VOLUME_NAME:CONTAINER_PATH"
    # 也可以使用长语法。
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro # 挂载主机目录到容器，只读
      - app_data:/var/www/html # 挂载命名卷 'app_data' 到容器
      - type: bind # 绑定挂载
        source: ./logs # 主机路径
        target: /var/log/nginx # 容器路径
        read_only: false # 可读写
      - type: volume # 命名卷挂载
        source: cache_volume # 命名卷名称
        target: /var/cache/nginx
      - type: tmpfs # 临时文件系统挂载 (仅限 Linux)
        target: /tmp/cache
        tmpfs:
          size: 100m # 临时文件系统大小

    # environment: 设置容器内的环境变量。
    # 可以是映射或列表形式。
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://user:password@db:5432/mydb
      # 或者列表形式：
      # - API_KEY=your_api_key
      # - DEBUG=false

    # env_file: 从文件中加载环境变量。
    # 可以是一个字符串（文件路径）或一个列表。
    env_file:
      - .env.production # 加载 .env.production 文件中的环境变量
      - common.env # 加载 common.env 文件中的环境变量

    # depends_on: 定义服务之间的启动依赖关系。
    # 列表形式：只表示启动顺序，不检查服务健康状态。
    # 映射形式：可以指定条件，如服务健康或成功完成。
    depends_on:
      - db_service # web_app 在 db_service 启动后才启动
      - redis_cache
      # 映射形式 (Compose V3.2+):
      # db_service:
      #   condition: service_healthy # 只有当 db_service 报告健康时才启动 web_app
      # redis_cache:
      #   condition: service_started # 只要 redis_cache 启动就启动 web_app

    # networks: 指定服务连接到哪些网络。
    # 可以是列表或映射形式。
    networks:
      - app_backend_network # 连接到名为 'app_backend_network' 的网络
      - app_frontend_network: # 连接到 'app_frontend_network' 并设置别名和 IP
          aliases:
            - webapp.local
            - myapp.internal
          ipv4_address: 172.20.0.10 # 为服务在这个网络中指定静态 IP (不推荐在生产环境广泛使用)

    # external_links: 链接到 Compose 文件外部的容器。
    # 格式： "CONTAINER_NAME:ALIAS"
    external_links:
      - existing_legacy_db:legacy_db_alias

    # container_name: 指定容器的名称，而不是由 Docker Compose 自动生成。
    # 建议在生产环境中使用，方便管理。
    container_name: my_web_app_container

    # hostname: 设置容器内部的主机名。
    hostname: webapp-host

    # domainname: 设置容器内部的域名。
    domainname: example.com

    # user: 指定运行容器的用户或 UID。
    user: "1000:1000" # UID:GID

    # working_dir: 设置容器的工作目录。
    working_dir: /app

    # restart: 定义容器的重启策略。
    # no: 不自动重启。
    # on-failure: 只有当容器以非零退出码退出时才重启。
    # always: 无论退出码如何，总是重启。
    # unless-stopped: 除非手动停止，否则总是重启
    restart: unless-stopped # 除非手动停止，否则总是重启
    # restart: no # 不自动重启
    # restart: on-failure # 只有当容器以非零退出码退出时才重启
    # restart: always # 无论退出码如何，总是重启

    # healthcheck: 定义容器的健康检查方式。
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost/health || exit 1"] # 执行的命令
      interval: 30s # 检查间隔
      timeout: 10s # 每次检查的超时时间
      retries: 3 # 失败重试次数
      start_period: 5s # 容器启动后，在开始健康检查前的等待时间
      disable: false # 禁用健康检查

    # logging: 配置容器的日志驱动和选项。
    logging:
      driver: "json-file" # 日志驱动，如 json-file, syslog, fluentd, journald 等
      options:
        max-size: "10m" # 单个日志文件最大大小
        max-file: "3" # 保留的日志文件数量

    # labels: 为服务和容器添加元数据标签。
    # 可以是映射或列表形式。
    labels:
      com.example.service: "web_app"
      com.example.tier: "frontend"
      # 或者列表形式：
      # - "com.example.project=my_app"

    # privileged: 授予容器扩展的权限，慎用。
    privileged: false

    # read_only: 将容器的根文件系统设置为只读。
    read_only: false

    # stdin_open: 保持 STDIN 打开，即使没有连接到终端。
    stdin_open: true # 等同于 docker run -i

    # tty: 分配一个伪 TTY。
    tty: true # 等同于 docker run -t

    # cap_add: 添加 Linux 能力。
    cap_add:
      - NET_ADMIN # 允许网络管理操作
      - SYS_PTRACE # 允许进程跟踪

    # cap_drop: 移除 Linux 能力。
    cap_drop:
      - ALL # 移除所有能力 (然后按需添加)

    # devices: 将主机设备添加到容器。
    devices:
      - "/dev/ttyUSB0:/dev/ttyUSB0" # 映射串口设备

    # dns: 设置容器的 DNS 服务器。
    dns:
      - 8.8.8.8
      - 8.8.4.4

    # dns_search: 设置容器的 DNS 搜索域。
    dns_search:
      - example.com
      - mycompany.local

    # tmpfs: 挂载一个 tmpfs 文件系统到容器。
    tmpfs:
      - /run/my_app:size=64m # 挂载一个 64MB 的 tmpfs 到 /run/my_app

    # ulimits: 设置容器的 ulimits。
    ulimits:
      nproc: 65535 # 最大进程数
      nofile:
        soft: 20000 # 软限制
        hard: 40000 # 硬限制

    # sysctls: 配置容器的内核参数。
    sysctls:
      net.core.somaxconn: 1024 # TCP 连接队列最大长度
      net.ipv4.ip_unprivileged_port_start: 0 # 允许非特权用户绑定低端口

    # security_opt: 配置容器的安全选项。
    security_opt:
      - no-new-privileges # 禁用新的特权

    # stop_grace_period: 容器停止前的优雅关闭等待时间。
    stop_grace_period: 30s

    # stop_signal: 发送给容器的停止信号。
    stop_signal: SIGTERM

    # cgroup_parent: 指定容器的 cgroup 父级。
    cgroup_parent: my_cgroup_group

    # cpu_shares: CPU 份额（相对权重）。
    cpu_shares: 512 # 默认 1024

    # cpu_quota: CPU 配额（微秒）。
    cpu_quota: 50000 # 容器每 100ms 最多使用 50ms CPU

    # cpu_period: CPU 周期（微秒）。
    cpu_period: 100000 # 默认 100ms

    # cpuset: 限制容器使用的 CPU 核心。
    cpuset: "0,1" # 限制容器只能使用 CPU 0 和 CPU 1

    # mem_limit: 内存限制。
    mem_limit: 2g # 限制容器最大使用 2GB 内存

    # mem_reservation: 内存预留。
    mem_reservation: 1g # 预留 1GB 内存

    # memswap_limit: 内存 + 交换空间限制。
    memswap_limit: 3g # 限制容器最大使用 3GB 内存和交换空间

    # oom_kill_disable: 禁用 OOM Killer。
    oom_kill_disable: false

    # pids_limit: 限制容器可以创建的进程数。
    pids_limit: 200

    # group_add: 添加额外的组 ID 到容器。
    group_add:
      - "100" # 添加 gid 100

    # init: 在容器中运行一个 init 进程。
    init: true

    # ipc: 设置容器的 IPC 模式。
    ipc: host # 共享主机 IPC 命名空间

    # pid: 设置容器的 PID 模式。
    pid: host # 共享主机 PID 命名空间

    # uts: 设置容器的 UTS 模式。
    uts: host # 共享主机 UTS 命名空间

    # userns_mode: 设置用户命名空间模式。
    userns_mode: host

    # runtime: 指定容器运行时。
    runtime: nvidia # 使用 nvidia 运行时 (如果安装了)

    # shm_size: /dev/shm 的大小。
    shm_size: 1g

    # storage_opt: 存储驱动选项。
    storage_opt:
      size: "10G" # 限制容器的存储大小 (仅限某些存储驱动)

    # volume_driver: 指定卷驱动。
    volume_driver: local

    # configs: 引用在顶级 'configs' 部分定义的配置数据。
    # 格式： source: config_name 或长语法。
    configs:
      - source: my_app_config # 引用名为 'my_app_config' 的配置
        target: /etc/app/config.conf # 挂载到容器内的路径
        uid: "1000" # 容器内文件的用户 ID
        gid: "1000" # 容器内文件的组 ID
        mode: 0444 # 容器内文件的权限 (八进制)

    # secrets: 引用在顶级 'secrets' 部分定义的敏感数据。
    # 格式： source: secret_name 或长语法。
    secrets:
      - source: db_password_secret # 引用名为 'db_password_secret' 的秘密
        target: /run/secrets/db_password # 挂载到容器内的路径
        uid: "1000"
        gid: "1000"
        mode: 0400

    # extends: 从另一个 Compose 文件或当前文件中的服务扩展配置。
    # 允许重用和继承配置。
    # extends:
    #   file: common-services.yml # 扩展自另一个文件
    #   service: base-web-service # 扩展自另一个文件中的服务名称
    # 或者：
    # extends:
    #   service: base-service # 扩展自当前文件中的服务名称

    # external: 标记服务为外部服务，Compose 不会尝试创建它。
    # 通常用于引用已经运行的容器。
    # external: true

    # profiles: (Compose V3.4+) 定义服务所属的配置文件。
    # 只有当激活了相应的 profile 时，服务才会被启动。
    profiles:
      - development
      - debug

    # platform: (Compose V3.8+) 指定容器运行的平台 (OS/ARCH)。
    platform: linux/amd64

    # deploy: (仅限 Compose V3.x，主要用于 Docker Swarm 模式，但部分资源限制在非 Swarm 模式也有效)
    # 定义服务的部署和运行时配置，如副本数量、资源限制、更新策略等。
    deploy:
      mode: replicated # 部署模式：replicated (副本) 或 global (每个节点一个实例)
      replicas: 3 # 副本数量 (仅限 replicated 模式)
      placement: # 放置约束
        constraints:
          - node.role == worker # 只能部署在 worker 节点
          - node.labels.env == production # 只能部署在带有 env=production 标签的节点
        preferences: # 放置偏好
          - spread: node.labels.zone # 尽量分散到不同 zone 的节点
      resources: # 资源限制和预留
        limits: # 资源上限
          cpus: '0.5' # 限制 CPU 使用为 0.5 个核心
          memory: 512M # 限制内存使用为 512MB
        reservations: # 资源预留 (保证的最低资源)
          cpus: '0.25'
          memory: 256M
      restart_policy: # 容器重启策略 (Swarm 模式下)
        condition: on-failure # 只有当容器失败时才重启
        delay: 5s # 重启前的延迟
        max_attempts: 3 # 最大重启尝试次数
        window: 120s # 检查重启尝试的窗口期
      update_config: # 服务更新策略
        parallelism: 1 # 并行更新的容器数量
        delay: 10s # 每次更新之间的延迟
        failure_action: rollback # 更新失败时的操作 (rollback, pause, continue)
        monitor: 60s # 监控更新状态的时间
        max_failure_ratio: 0.1 # 允许的最大失败率
        order: start-first # 更新顺序 (start-first 或 stop-first)
      rollback_config: # 服务回滚策略
        parallelism: 1
        delay: 10s
        failure_action: pause
        monitor: 60s
        max_failure_ratio: 0.1
        order: stop-first
      labels: # 为 Swarm 服务添加标签
        com.example.swarm-service: "true"
      endpoint_mode: vip # 服务发现模式 (vip 或 dnsrr)

  # -------------------------------------------------------------------------
  # 3. 网络定义 (Network Definition)
  # -------------------------------------------------------------------------

networks:
  app_backend_network: # 定义一个名为 'app_backend_network' 的网络
    driver: bridge # 网络驱动，默认为 bridge
    driver_opts: # 驱动选项
      com.docker.network.bridge.host_binding_ipv4: "0.0.0.0"
    attachable: true # 允许独立容器连接到此网络
    enable_ipv6: true # 启用 IPv6
    internal: false # 是否为内部网络 (内部网络无法直接从外部访问)
    labels: # 为网络添加标签
      com.example.network_type: "backend"
    name: my_custom_backend_network # 指定网络在 Docker 中的实际名称 (如果与定义名称不同)
    ipam: # IP 地址管理配置
      driver: default # IPAM 驱动
      config: # IPAM 配置列表
        - subnet: 172.18.0.0/16 # 子网
          ip_range: 172.18.0.0/24 # IP 范围
          gateway: 172.18.0.1 # 网关
          aux_addresses: # 辅助地址
            host1: 172.18.0.2
            host2: 172.18.0.3
  app_frontend_network:
    external: true # 标记此网络为外部网络，Compose 不会创建它，而是使用已存在的同名网络
    # 如果外部网络名称与定义名称不同，可以使用 name 字段：
    # external:
    #   name: existing_frontend_network_on_docker

  # -------------------------------------------------------------------------
  # 4. 卷定义 (Volume Definition)
  # -------------------------------------------------------------------------

volumes:
  app_data: # 定义一个名为 'app_data' 的命名卷
    driver: local # 卷驱动，默认为 local
    driver_opts: # 驱动选项
      type: "nfs"
      o: "addr=192.168.1.1,rw"
      device: ":/mnt/nfs_share"
    labels: # 为卷添加标签
      com.example.data_type: "persistent"
    name: my_custom_app_data_volume # 指定卷在 Docker 中的实际名称
  cache_volume:
    external: true # 标记此卷为外部卷，Compose 不会创建它，而是使用已存在的同名卷
    # 如果外部卷名称与定义名称不同，可以使用 name 字段：
    # external:
    #   name: existing_cache_volume_on_docker

  # -------------------------------------------------------------------------
  # 5. 配置定义 (Config Definition) - Compose V3.3+
  # -------------------------------------------------------------------------

configs:
  my_app_config: # 定义一个名为 'my_app_config' 的配置
    file: ./configs/app_settings.conf # 从主机上的文件加载配置内容
    # external: true # 标记此配置为外部配置，Compose 不会创建它，而是使用已存在的同名配置
    # name: existing_app_config_on_docker # 如果外部配置名称不同

  # -------------------------------------------------------------------------
  # 6. 秘密定义 (Secret Definition) - Compose V3.1+
  # -------------------------------------------------------------------------

secrets:
  db_password_secret: # 定义一个名为 'db_password_secret' 的秘密
    file: ./secrets/db_password.txt # 从主机上的文件加载秘密内容
    # external: true # 标记此秘密为外部秘密，Compose 不会创建它，而是使用已存在的同名秘密
    # name: existing_db_password_on_docker # 如果外部秘密名称不同
  api_key_secret:
    external: true # 引用一个已经存在的 Docker Secret
    name: my_global_api_key # 外部 Secret 的实际名称

version: "3.8"
services:
  minecraft:
    image: itzg/minecraft-server:latest
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      MEMORY: 4G
    volumes:
      - minecraft_data:/data

volumes:
  minecraft_data:

services:
  mc:
    image: itzg/minecraft-server:latest
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "FABRIC"
      VERSION: "1.21.1"
      MEMORY: "8192M"
      MAX_PLAYERS: "10"
      MOTD: "欢迎来到 ShiroRikka 的 PoopSky2 服务器！"
      ONLINE_MODE: "false"
      USE_MEOWICE_FLAGS: "true"
      TZ: "Asia/Shanghai"
      DIFFICULTY: "2"
      FORCE_GAMEMODE: "true"
      SIMULATION_DISTANCE: "8"
      VIEW_DISTANCE: "8"
      SPAWN_PROTECTION: "1"
      ENABLE_ROLLING_LOGS: "true"
      LOG_TIMESTAMP: "true"
      ALLOW_FLIGHT: "true"
      SERVER_NAME: "空中厕所2"
      GENERIC_PACK: "/data/s.zip"
    volumes:
      - "/vol3/1000/NVMe-SSD-Data/Minecraft/PoopSky2:/data"
      - "/vol1/1000/Docker/Minecraft/PoopSky2/modpacks/Fabric-PoopSky2-2.3.zip:/data/s.zip"