多容器编排 / 网络 / Volume / 环境分离

# compose.yml -- 全部描述在这个文件里
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: xxx
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

  api:
    build: ./api             # 也可以用 Dockerfile 构建
    environment:
      DB_HOST: db            # 服务名直接当域名用
      REDIS_HOST: redis

  web:
    build: ./web
    ports:
      - "80:80"

volumes:                     # 声明命名卷
  pgdata:
  redisdata:

# 启动:docker compose up -d
# 停止:docker compose down
# 重建:docker compose up -d --build

# compose.yml 的顶层三大块
services:          # ← 容器 = 服务.一个 service = 一组相同的容器(可以扩缩容)
  web:             #   这个服务叫 "web"
    image: nginx   #   用什么镜像
    ports:         #   端口映射
      - "8080:80"

  api:             #   这个服务叫 "api"
    build: .       #   从当前目录的 Dockerfile 构建
    environment:   #   环境变量
      - PORT=3000

networks:          # ← 网络.不声明的话 Compose 自动创建一个 default 网络
  backend:

volumes:           # ← 数据卷.不声明的话 Compose 自动创建命名卷
  db-data:

services:
  api:
    depends_on:
      - db          # db 先启,api 后启
      - redis       # redis 先启,api 后启

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:                          # ← 定义健康检查
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      #     │             │
      #     │             └── 执行这条命令,返回 0 = 健康,非 0 = 不健康
      #     └── 执行方式:CMD(直接执行)或 CMD-SHELL(通过 shell 执行)
      interval: 5s       # 每 5 秒检查一次
      timeout: 3s        # 单次检查超过 3 秒视为失败
      retries: 5         # 连续失败 5 次后标记为 unhealthy
      start_period: 10s  # 容器启动后 10 秒内不检查(给初始化留时间)

  api:
    depends_on:
      db:
        condition: service_healthy   # ← 等 db 的 healthcheck 通过后才启动 api
        #          │
        #          └── 可选值:
        #              service_started  (默认)容器启动就算
        #              service_healthy  容器的 healthcheck 通过才算
        #              service_completed_successfully (一次性任务成功退出才算)

services:
  api:
    build: ./api
    environment:
      DB_HOST: db           # ← 直接写服务名!
      DB_PORT: "5432"       # ← 不需要查 IP
      REDIS_HOST: redis     # ← redis 的 IP 也不需要

  db:
    image: postgres:16

  redis:
    image: redis:7

# api 容器内的进程访问 db:直接连接 db:5432
# DNS 解析过程:
#   api → 发起连接 "db:5432"
#   → 内置 DNS 查 "db" → 解析为 db 容器的内网 IP(如 172.18.0.3)
#   → 连接成功
#
# db 容器重启后 IP 变了(变成 172.18.0.4)?
#   → DNS 自动更新 → api 仍然连 "db:5432",无感知!

# 对比不用 Compose:
#   docker run --name db ...  → IP 可能每次不同
#   docker run --name api -e DB_HOST=172.17.0.3 ...  → IP 写死了,重启就挂

services:
  api:
    networks:
      - backend          # ← api 只连接 backend 网
      - frontend         # ← 和 frontend 网

  db:
    networks:
      - backend          # ← db 只连 backend 网
                         #   前端流量永远到不了 db

  web:
    networks:
      - frontend         # ← web 只连 frontend 网

  # 用 docker compose exec api ping db     → 通(同 backend 网)
  # 用 docker compose exec api ping web    → 通(api 也接了 frontend)
  # 用 docker compose exec db ping web     → 不通(db 不在 frontend)

networks:
  frontend:
  backend:

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data   # ← 命名卷
      # │      │
      # └── 卷名 └── 容器内路径

volumes:                     # ← 这是顶层声明
  pgdata:
  redisdata:

# 场景一:引用宿主机上已有的外部卷
volumes:
  shared-data:
    external: true    # ← 告诉 Compose:"别新建!用已经存在的那个!"
                      #    不加这句,Compose 会新建一个名为 项目名_shared-data 的卷
                      #    那就不是你手动建的 shared-data 了

# 场景二:指定卷的物理存储位置
volumes:
  pgdata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/fast-ssd/pgdata    # ← 让这个卷存到指定磁盘路径
      #       └── 比如你有一块 SSD 专门放数据库

# 方式一:bind mount 用 ~(最简单,macOS 开发首选)
services:
  db:
    image: postgres:16
    volumes:
      - ~/docker_data/pgdata:/var/lib/postgresql/data
      # └── macOS 上 ~ 自动展开为 /Users/yutong
      #     docker compose up 后数据直接出现在 ~/docker_data/pgdata/

  redis:
    image: redis:7
    volumes:
      - ~/docker_data/redisdata:/data

# 优点:零额外配置,Finder 能直接看到文件
# 缺点:不是"命名卷",docker volume ls 看不到;路径写死了,换机器要改

# 方式二:命名卷 + .env 指定路径(推荐给想保留命名卷心智模型的人)
# compose.yml
services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ${DATA_DIR:-~/docker_data}/pgdata

# .env(和 compose.yml 同级,Compose 自动读取)
DATA_DIR=~/docker_data

# 优点:docker volume ls 可见;通过 .env 换机器只改一行
# 缺点:比纯 bind mount 多几行;底层还是 bind mount,性能没额外提升

services:
  api:
    build: ./api
    volumes:
      - ./api/src:/app/src          # ← bind mount
      #   │          │
      #   │          └── 容器内路径
      #   └── 宿主机相对路径(相对于 compose.yml 所在目录)
      #
      # 改了宿主机上的代码 → 容器里立刻生效(同一份文件)
      # 适合开发环境:改代码即刷新,不需要重新 build

      - /app/node_modules            # ← 匿名卷:保持容器内的 node_modules
      #   不映射到宿主机,防止被宿主机的空 node_modules 覆盖

# bind mount 风险:
#  • 容器进程以 root 运行 → 可以修改宿主机文件
#  • 路径硬编码 → 换机器可能路径不对
#  • 生产环境应避免--应用应通过 docker build 打包进镜像,不依赖外部目录

# compose.yml(基础配置,所有环境共享)
services:
  api:
    build: .
    environment:
      NODE_ENV: production

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# compose.dev.yml(开发环境覆盖)
services:
  api:
    build:
      target: dev              # 用 Dockerfile 的 dev stage
    environment:
      NODE_ENV: development
    volumes:
      - ./src:/app/src         # 代码热更新
    ports:
      - "3000:3000"

  db:
    ports:
      - "5432:5432"            # 开发时可以本地直连数据库

  # 开发环境额外加一个调试工具
  adminer:
    image: adminer
    ports:
      - "8080:8080

# compose.prod.yml(生产环境覆盖)
services:
  api:
    restart: always            # 崩溃自动重启
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 512M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  db:
    restart: always
    deploy:
      resources:
        limits:
          memory: 1G

services:
  api:
    build: .                     # ← 没写 profiles → 永远启动

  db:
    image: postgres:16           # ← 没写 profiles → 永远启动

  adminer:                       # 数据库 Web 管理界面(调试用)
    image: adminer
    ports: ["8080:8080"]
    profiles:
      - debug                    # ← 只在传了 --profile debug 时启动

  prometheus:                    # 监控(吃资源,平时不跑)
    image: prom/prometheus
    profiles:
      - monitoring               # ← 只在传了 --profile monitoring 时启动

services:
  adminer:
    image: adminer
    profiles:
      - debug          # ← 传 --profile debug 也启动
      - tools          # ← 传 --profile tools 也启动
      # 任意一个 match 就启动

services:
  api:
    build: .

  db:
    image: postgres:16

  redis:
    image: redis:7

  # -- 以下按需启动 --

  adminer:
    image: adminer
    profiles: [debug]

  mailhog:                        # 邮件调试
    image: mailhog/mailhog
    profiles: [debug]

  prometheus:
    image: prom/prometheus
    profiles: [monitoring]

  grafana:
    image: grafana/grafana
    profiles: [monitoring]

  elasticsearch:                  # 日志搜索(很吃内存)
    image: elasticsearch:8
    profiles: [heavy]

  kafka:                          # 消息队列(不常用)
    image: confluentinc/cp-kafka
    profiles: [heavy]