签入版本

2026-09-12 22:24:53 +08:00
commit 05cb22302c
863 changed files with 118186 additions and 0 deletions
@@ -0,0 +1,190 @@
+# ============================================================================
+# Dockerfile - Flask 应用容器镜像构建文件
+# ============================================================================
+# 项目名称：flask_naivevue
+# 功能描述：构建 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_naivevue" \
+      org.opencontainers.image.description="Flask Backend Service for 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_naivevue"
+
+# 兼容旧版 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_naivevue:latest .
+#
+# 2. 构建时指定版本号：
+#    docker build -t flask_naivevue:v1.0.0 .
+#
+# 3. 使用构建参数（多环境构建）：
+#    docker build --build-arg ENV=production -t flask_naivevue:prod .
+#
+# 4. 查看镜像层信息：
+#    docker history flask_naivevue:latest
+#
+# 5. 运行容器测试：
+#    docker run -d -p 8021:8021 flask_naivevue:latest
+#
+# 6. 进入容器调试：
+#    docker run -it --entrypoint /bin/bash flask_naivevue:latest
@@ -0,0 +1,168 @@
+version: '3.7'
+
+# ============================================================================
+# Docker Compose 配置文件 - Flask 后端服务
+# ============================================================================
+# 项目名称：flask_naivevue
+# 功能描述：Flask 应用服务容器化部署配置
+# 维护团队：后端架构组
+# 最后更新：2026-07-23
+# 环境类型：开发/测试/生产（通过环境变量区分）
+# ============================================================================
+
+# 应用服务
+services:
+  # 后端服务
+  flask_naivevue:
+    # ------------------------------------------------------------------------
+    # 镜像与构建配置
+    # ------------------------------------------------------------------------
+    # 镜像名称（命名规范：项目名/服务名，建议使用私有仓库地址）
+    image: flask_naivevue
+    # 容器实例名称（用于 docker ps 和日志过滤）
+    container_name: flask_naivevue
+    # 镜像构建配置（当镜像不存在时自动构建）
+    build:
+      context: ../          # 构建上下文路径（项目根目录，Dockerfile 在 docker/ 下）
+      dockerfile: docker/Dockerfile  # Dockerfile 文件名
+    #build: .              # 旧版构建语法（已注释，保留兼容）
+
+    # ------------------------------------------------------------------------
+    # 安全与权限配置
+    # ------------------------------------------------------------------------
+    # 【安全警告】privileged: true 授予容器所有宿主机权限
+    # 风险等级：高危（容器逃逸风险）
+    # 建议：生产环境必须改为 false，并使用 cap_add 精确授权
+    # 已加固：privileged 高危，改为 false
+    privileged: false
+
+    # 容器内运行的用户（安全最佳实践）
+    # 当前使用 root（不推荐），建议在 Dockerfile 中创建专用用户
+    # 已加固：使用 Dockerfile 中创建的非特权用户
+    user: flask_user
+
+    # ------------------------------------------------------------------------
+    # 服务高可用配置
+    # ------------------------------------------------------------------------
+    # 重启策略：always（始终重启，保证服务连续性）
+    # 其他可选值：no | on-failure[:max-retries] | unless-stopped
+    # 生产环境建议：unless-stopped（除非手动停止，否则自动重启）
+    restart: always
+
+    # ------------------------------------------------------------------------
+    # 网络配置
+    # ------------------------------------------------------------------------
+    # 网络模式：host（容器直接使用宿主机网络栈）
+    # 优点：网络性能高，无 NAT 开销
+    # 缺点：网络隔离性差，端口冲突风险，不适用于多容器编排
+    # 已加固：改用默认 bridge 网络（配合 ports 映射）
+
+    # 端口映射（仅在非 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 src.wsgi: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_naivevue
+#
+# 3. 停止服务：
+#    docker-compose down
+#
+# 4. 重新构建并启动（应用代码更新后）：
+#    docker-compose up -d --build
+#
+# 5. 进入容器调试：
+#    docker exec -it flask_naivevue /bin/bash
+#
+# 6. 查看资源使用情况：
+#    docker stats flask_naivevue
+#
+# 7. 查看容器详细配置（含资源限制）：
+#    docker inspect flask_naivevue | 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）检测漏洞
+# □ 资源限制值根据实际压测结果动态调整
+# ============================================================================