version: '3.7'

# ============================================================================
# Docker Compose 配置文件 - Flask 后端服务
# ============================================================================
# 项目名称：flask_elevue
# 功能描述：Flask 应用服务容器化部署配置
# 维护团队：后端架构组
# 最后更新：2026-07-23
# 环境类型：开发/测试/生产（通过环境变量区分）
# ============================================================================

# 应用服务
services:
  # 后端服务
  flask_elevue:
    # ------------------------------------------------------------------------
    # 镜像与构建配置
    # ------------------------------------------------------------------------
    # 镜像名称（命名规范：项目名/服务名，建议使用私有仓库地址）
    image: flask_elevue
    # 容器实例名称（用于 docker ps 和日志过滤）
    container_name: flask_elevue
    # 镜像构建配置（当镜像不存在时自动构建）
    build:
      context: ./          # 构建上下文路径（项目根目录）
      dockerfile: Dockerfile  # Dockerfile 文件名
    #build: .              # 旧版构建语法（已注释，保留兼容）

    # ------------------------------------------------------------------------
    # 安全与权限配置
    # ------------------------------------------------------------------------
    # 【安全警告】privileged: true 授予容器所有宿主机权限
    # 风险等级：高危（容器逃逸风险）
    # 建议：生产环境必须改为 false，并使用 cap_add 精确授权
    # 当前设置为 true 的原因：如需访问宿主机设备或执行系统级操作
    privileged: true

    # 容器内运行的用户（安全最佳实践）
    # 当前使用 root（不推荐），建议在 Dockerfile 中创建专用用户
    # 示例：user: flask_user:flask_group (UID:GID)
    user: root

    # ------------------------------------------------------------------------
    # 服务高可用配置
    # ------------------------------------------------------------------------
    # 重启策略：always（始终重启，保证服务连续性）
    # 其他可选值：no | on-failure[:max-retries] | unless-stopped
    # 生产环境建议：unless-stopped（除非手动停止，否则自动重启）
    restart: always

    # ------------------------------------------------------------------------
    # 网络配置
    # ------------------------------------------------------------------------
    # 网络模式：host（容器直接使用宿主机网络栈）
    # 优点：网络性能高，无 NAT 开销
    # 缺点：网络隔离性差，端口冲突风险，不适用于多容器编排
    # 生产环境建议：使用 bridge 或自定义网络
    network_mode: host

    # 端口映射（仅在非 host 网络模式下生效）
    # 格式：宿主机端口:容器端口
    # 注意：host 模式下此配置无效，保留是为了模式切换时生效
    ports:
      - 8021:8021

    # ------------------------------------------------------------------------
    # 存储配置（数据持久化）
    # ------------------------------------------------------------------------
    # 文件挂载（宿主机路径:容器路径:权限）
    # 用途：持久化上传文件，避免容器重建时数据丢失
    # 权限：rw（读写），ro（只读）
    volumes:
      - ./uploads:/data/apps/uploads  # 上传文件目录（读写挂载）

    # ========================================================================
    # 资源限制配置（企业级标准）- 保障宿主机稳定性
    # ========================================================================
    # 说明：限制容器可使用的 CPU 和内存资源，防止资源耗尽导致系统崩溃
    # 适用范围：docker-compose up（单机）和 Docker Swarm（集群）均生效
    # 配置策略：根据应用实际负载和宿主机资源配置
    # ========================================================================
    deploy:
      resources:
        # --------------------------------------------------------------------
        # 硬限制（上限）- 容器绝对不能超过的资源量
        # --------------------------------------------------------------------
        limits:
          cpus: '2.0'      # CPU 上限：最多使用 2 个物理核心
                           # 说明：'2.0' 表示 2 个核心，'0.5' 表示半个核心
                           # 建议值：宿主机总核心数 * 0.7~0.8（预留系统资源）
          memory: 2G       # 内存上限：最多使用 2GB
                           # 说明：单位支持 b/k/m/g（小写）或 B/K/M/G（大写）
                           # 建议值：应用峰值内存 * 1.2~1.5（留出缓冲空间）
                           # 注意：内存超限时容器会被 OOM Killer 终止
        # --------------------------------------------------------------------
        # 软限制（预留）- 保证容器最少能获得的资源量
        # --------------------------------------------------------------------
        reservations:
          cpus: '0.5'      # CPU 保证下限：至少保留 0.5 个核心
                           # 说明：调度器会优先保证此资源量
                           # 建议值：限制值的 20%~30%
          memory: 512M     # 内存保证下限：至少保留 512MB
                           # 说明：确保容器在资源竞争时仍能获得最低内存
                           # 建议值：限制值的 25%~40%

    # 【备选方案】如果使用旧版 Compose 格式（v2），可用以下替代语法：
    # cpus: 2.0           # CPU 限制（已废弃，不推荐）
    # mem_limit: 2G       # 内存限制（已废弃，不推荐）
    # mem_reservation: 512M  # 内存预留（已废弃，不推荐）
    # ========================================================================

    # ------------------------------------------------------------------------
    # 启动命令配置
    # ------------------------------------------------------------------------
    # 执行命令（覆盖 Dockerfile 中的 CMD）
    # 生产环境启动：使用 Gunicorn + Gevent
    command: gunicorn -c gunicorn.conf.py app:app

    # ------------------------------------------------------------------------
    # 日志配置（集中式日志管理）
    # ------------------------------------------------------------------------
    logging:
      driver: "json-file"  # 日志驱动：JSON 文件格式（Docker 默认）
      # 其他驱动选项：fluentd（日志聚合）、syslog（系统日志）、none（禁用）
      options:
        max-size: "500m"   # 单个日志文件最大大小（达到后自动轮转）
                           # 说明：防止日志文件无限增长占满磁盘
                           # 建议值：根据日志量设置 100m~1g
        max-file: "10"     # 保留的日志文件数量（轮转保留数）
                           # 说明：保留最近 10 个轮转文件，旧文件自动删除
                           # 建议值：5~20 个，根据磁盘空间和保留周期决定

# ============================================================================
# 附录：运维操作指南
# ============================================================================
# 1. 启动服务（后台运行）：
#    docker-compose up -d
#
# 2. 查看服务日志：
#    docker-compose logs -f flask_elevue
#
# 3. 停止服务：
#    docker-compose down
#
# 4. 重新构建并启动（应用代码更新后）：
#    docker-compose up -d --build
#
# 5. 进入容器调试：
#    docker exec -it flask_elevue /bin/bash
#
# 6. 查看资源使用情况：
#    docker stats flask_elevue
#
# 7. 查看容器详细配置（含资源限制）：
#    docker inspect flask_elevue | grep -A 20 "Resources"
#
# ============================================================================
# 安全加固建议（企业级 Checklist）
# ============================================================================
# □ privileged: true → 改为 false，使用 cap_add 精确授权
# □ user: root → 改为非特权用户（如 flask_user）
# □ 敏感信息（密码/密钥）使用环境变量或 Docker Secrets，禁止硬编码
# □ 添加健康检查（healthcheck），配合负载均衡和自动恢复
# □ 日志驱动建议使用 fluentd 或 syslog 集中收集
# □ 定期更新基础镜像（python:3.x-slim 或 alpine）修复安全漏洞
# □ 使用镜像扫描工具（Trivy/Clair）检测漏洞
# □ 资源限制值根据实际压测结果动态调整
# ============================================================================