# ============================================================================
# Dockerfile - Flask 应用容器镜像构建文件
# ============================================================================
# 项目名称：flask_elevue
# 功能描述：构建 Flask 后端应用的生产级 Docker 镜像
# 维护团队：后端架构组
# 最后更新：2026-07-23
# 基础镜像：Python 3.9（官方镜像）
# ============================================================================

# ----------------------------------------------------------------------------
# 基础镜像选择
# ----------------------------------------------------------------------------
# 使用 Python 3.9 官方镜像
# 生产环境建议：使用 slim 或 alpine 版本以减小镜像体积
# 示例：python:3.9-slim（体积约 180MB）或 python:3.9-alpine（体积约 50MB）
FROM python:3.9-slim

# ----------------------------------------------------------------------------
# 镜像元数据（标签）
# ----------------------------------------------------------------------------
# 镜像作者信息
LABEL maintainer="djangoadmin@126.com"
# 添加更多标签便于管理和追溯
LABEL org.opencontainers.image.title="flask_elevue" \
      org.opencontainers.image.description="Flask Backend Service for Elevue Project" \
      org.opencontainers.image.version="1.0.0" \
      org.opencontainers.image.created="2026-07-23" \
      org.opencontainers.image.source="https://github.com/your-org/flask_elevue"

# 兼容旧版 MAINTAINER 指令（已废弃，但保留兼容性）
MAINTAINER admin@example.com  # 建议使用有效邮箱

# ----------------------------------------------------------------------------
# Python 环境变量配置
# ----------------------------------------------------------------------------
# PYTHONUNBUFFERED：禁用 Python 输出缓冲，日志实时输出（容器日志关键）
ENV PYTHONUNBUFFERED 1
# PYTHONDONTWRITEBYTECODE：禁止生成 .pyc 字节码文件，减小镜像体积
ENV PYTHONDONTWRITEBYTECODE 1
# PYTHONPATH：Python 模块搜索路径（可选）
# ENV PYTHONPATH /data/apps

# ----------------------------------------------------------------------------
# 系统级配置（时区/语言环境）
# ----------------------------------------------------------------------------
# 设置容器时区为中国时区（统一日志时间戳）
ENV TZ Asia/Shanghai
# 设置语言环境（避免中文乱码问题）
ENV LANG C.UTF-8
ENV LC_ALL C.UTF-8

# ----------------------------------------------------------------------------
# 系统依赖安装（需在 Python 依赖之前安装）
# ----------------------------------------------------------------------------
# 安装系统级工具和依赖库（根据项目需要添加）
# 此处使用了 Debian 包管理器（官方镜像基于 Debian）
RUN apt-get update && apt-get install -y --no-install-recommends \
    # 常用网络工具（调试和健康检查需要）
    curl \
    wget \
    # 编译工具（部分 Python 包需要编译，如 uwsgi）
    build-essential \
    # 数据库客户端库（如使用 PostgreSQL/MySQL）
    # libpq-dev \
    # default-libmysqlclient-dev \
    # 图像处理库（如使用 Pillow 处理图片）
    # libjpeg-dev \
    # libpng-dev \
    # 系统清理（减小镜像体积）
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /tmp/* /var/tmp/*

# ----------------------------------------------------------------------------
# Python 包管理器配置
# ----------------------------------------------------------------------------
# 设置国内 PyPI 镜像源（加速依赖下载，网络环境不同可调整）
# 阿里云镜像：http://mirrors.aliyun.com/pypi/simple
# 清华大学镜像：https://pypi.tuna.tsinghua.edu.cn/simple
# 中科大镜像：https://pypi.mirrors.ustc.edu.cn/simple
RUN pip config set global.index-url http://mirrors.aliyun.com/pypi/simple \
    && pip config set install.trusted-host mirrors.aliyun.com

# 升级 pip 和 setuptools（确保最新版本，提升安装兼容性）
RUN python -m pip install --upgrade pip \
    && pip install --upgrade setuptools wheel

# ----------------------------------------------------------------------------
# 创建应用工作目录
# ----------------------------------------------------------------------------
# 创建容器内工作目录（标准应用目录结构）
RUN mkdir -p /data/apps \
    # 创建日志目录（便于日志挂载和收集）
    && mkdir -p /data/apps/logs \
    # 创建上传文件目录（数据持久化）
    && mkdir -p /data/apps/uploads \
    # 创建临时文件目录
    && mkdir -p /data/apps/tmp

# 设置工作目录（后续所有操作默认在此目录）
WORKDIR /data/apps

# ----------------------------------------------------------------------------
# Python 依赖安装优化（利用 Docker 层缓存）
# ----------------------------------------------------------------------------
# 策略说明：
# 1. 先复制 requirements.txt（依赖声明文件）
# 2. 安装依赖（此层会被缓存，只要 requirements.txt 不变则不会重新安装）
# 3. 最后复制应用代码（代码变更不影响依赖层，大幅提升构建速度）

# 复制依赖文件（利用 Docker 缓存，仅当 requirements.txt 变更时重新安装）
COPY requirements.txt .

# 安装 Python 依赖包（使用 --no-cache-dir 减小镜像体积）
# 生产环境建议固定版本号，避免依赖版本漂移
RUN pip install --no-cache-dir -r requirements.txt

# ----------------------------------------------------------------------------
# 安装 gunicorn（高性能 WSGI 服务器，生产环境推荐）
# 配合 gevent worker 支持高并发
RUN pip install --no-cache-dir gunicorn gevent

# 如果需要使用 gunicorn（替代方案）：
# RUN pip install --no-cache-dir gunicorn

# ----------------------------------------------------------------------------
# 复制应用代码（最后复制，利用 Docker 缓存）
# ----------------------------------------------------------------------------
# 将当前目录（项目根目录）所有文件复制到容器工作目录
# 注意：使用 .dockerignore 文件排除不需要的文件（如 .git、__pycache__）
COPY . /data/apps/

# 或者使用单个 COPY 命令（推荐方式）：
# COPY . .

# ----------------------------------------------------------------------------
# 创建非特权用户（安全最佳实践）
# ----------------------------------------------------------------------------
# 创建专用用户和用户组（避免容器使用 root 运行应用）
# 参数说明：-r（系统用户），-s（指定 shell），-m（创建家目录）
RUN groupadd -r flask_user && useradd -r -g flask_user flask_user

# 修改应用目录所有者为 flask_user（确保应用有写入权限）
RUN chown -R flask_user:flask_user /data/apps

# 切换到非特权用户（后续命令将以该用户身份执行）
USER flask_user

# ----------------------------------------------------------------------------
# 健康检查配置（容器健康状态监控）
# ----------------------------------------------------------------------------
# 定义健康检查命令（需应用提供 /health 端点）
# 生产环境建议使用 curl 或 wget 检查
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
    CMD curl -f http://localhost:8021/health || exit 1

# ----------------------------------------------------------------------------
# 容器暴露端口声明
# ----------------------------------------------------------------------------
# 声明应用监听端口（仅用于文档说明，实际映射在 docker-compose 中配置）
EXPOSE 8021

# ----------------------------------------------------------------------------
# 容器启动命令
# ----------------------------------------------------------------------------
# 生产环境启动命令（使用 gunicorn 启动应用）
# 配置文件：gunicorn.conf.py（在项目根目录）
CMD ["gunicorn", "-c", "gunicorn.conf.py", "src.wsgi:app"]

# ============================================================================
# 附录：构建和测试指南
# ============================================================================
# 1. 构建镜像：
#    docker build -t flask_elevue:latest .
#
# 2. 构建时指定版本号：
#    docker build -t flask_elevue:v1.0.0 .
#
# 3. 使用构建参数（多环境构建）：
#    docker build --build-arg ENV=production -t flask_elevue:prod .
#
# 4. 查看镜像层信息：
#    docker history flask_elevue:latest
#
# 5. 运行容器测试：
#    docker run -d -p 8021:8021 flask_elevue:latest
#
# 6. 进入容器调试：
#    docker run -it --entrypoint /bin/bash flask_elevue:latest