diff --git a/.jenkins/Dockerfile b/.jenkins/Dockerfile index bd5f9bb..e4acf42 100644 --- a/.jenkins/Dockerfile +++ b/.jenkins/Dockerfile @@ -1,75 +1,167 @@ # ============================================================ # 基础镜像参数 # ============================================================ +# VAR_BASE_IMAGE 通过 docker build --build-arg 传入， +# 例如：--build-arg VAR_BASE_IMAGE=python:3.12-slim +# 用 ARG 而不是直接 FROM xxx，方便在 CI 中动态切换基础镜像 ARG VAR_BASE_IMAGE # ============================================================ # 阶段一：builder —— 负责编译依赖 +# 说明： +# - 这一阶段会安装 gcc/make/cmake 等编译工具 +# - 编译好的 Python 依赖会安装到 /install 前缀 +# - 最终该阶段整体被丢弃，编译工具不会进入 runtime 镜像 # ============================================================ FROM ${VAR_BASE_IMAGE} AS builder +# 镜像作者信息（仅元数据，不影响体积） LABEL MAINTAINER="djangoadmin@126.com" +# ------------------------------------------------------------ +# 编译阶段的环境变量 +# PYTHONUNBUFFERED=1 : Python 输出不缓冲，日志实时可见 +# PYTHONDONTWRITEBYTECODE=1 : 不生成 .pyc，避免污染构建产物 +# PIP_NO_CACHE_DIR=1 : pip 不缓存 wheel，减小体积 +# PIP_DISABLE_PIP_VERSION_CHECK=1 : 关闭 pip 版本检查，加快安装 +# ------------------------------------------------------------ ENV PYTHONUNBUFFERED=1 \ PYTHONDONTWRITEBYTECODE=1 \ PIP_NO_CACHE_DIR=1 \ PIP_DISABLE_PIP_VERSION_CHECK=1 +# ------------------------------------------------------------ # 安装编译所需工具链 +# yum-utils / net-tools : 系统工具 +# gcc / gcc-c++ : C/C++ 编译器，编译 C 扩展必需 +# make / cmake : 构建工具 +# openssl-devel : 编译 _ssl / cryptography 相关依赖 +# bzip2-devel : 编译 _bz2 模块 +# libffi-devel : 编译 _ctypes 模块 +# mysql-devel : 编译 mysqlclient 等 MySQL 驱动 +# 末尾清理 yum 缓存，避免缓存被打进镜像层 +# ------------------------------------------------------------ RUN yum install -y yum-utils net-tools && \ yum install -y gcc gcc-c++ make cmake \ openssl-devel bzip2-devel libffi-devel mysql-devel && \ yum clean all && rm -rf /var/cache/yum -# 配置 pip 国内镜像源 +# ------------------------------------------------------------ +# 配置 pip 国内镜像源并升级 pip +# - global.index-url : 指定阿里云 PyPI 镜像 +# - install.trusted-host : 允许 http 源的 host +# - 升级 pip / setuptools / wheel，避免老版本解析依赖出错 +# ------------------------------------------------------------ RUN pip3 config set global.index-url http://mirrors.aliyun.com/pypi/simple && \ pip3 config set install.trusted-host mirrors.aliyun.com && \ python3 -m pip install --upgrade pip setuptools wheel +# ------------------------------------------------------------ # 拷贝依赖清单 +# VAR_PYFILE_PATH 由 --build-arg 传入，指向项目目录 +# 这里只拷贝 requirements.txt，而不是整个项目目录， +# 目的是：当项目源码变化但 requirements.txt 未变时， +# 可以复用 pip install 这一层的缓存，加快构建 +# ------------------------------------------------------------ ARG VAR_PYFILE_PATH WORKDIR /opt/apps COPY ${VAR_PYFILE_PATH}/requirements.txt ./ -# 将依赖安装到 /install 前缀，便于后续拷贝 +# ------------------------------------------------------------ +# 将依赖安装到 /install 前缀，便于后续整体拷贝到 runtime +# --prefix=/install : 依赖会被装到 /install/lib/pythonX.Y/site-packages +# uwsgi 单独安装（生产环境 WSGI 服务器） +# ------------------------------------------------------------ RUN pip3 install --prefix=/install -r requirements.txt && \ pip3 install --prefix=/install uwsgi # ============================================================ # 阶段二：runtime —— 只保留运行时内容 +# 说明： +# - 不再安装 gcc/make/cmake 等编译工具 +# - 只装运行时需要的动态库 +# - 从 builder 拷贝编译好的依赖 # ============================================================ FROM ${VAR_BASE_IMAGE} AS runtime +# 镜像作者信息 LABEL MAINTAINER="djangoadmin@126.com" +# ------------------------------------------------------------ +# 运行时环境变量 +# PYTHONUNBUFFERED=1 : 日志实时输出，便于 docker logs 观察 +# PYTHONDONTWRITEBYTECODE=1 : 不写 .pyc，避免容器内产生垃圾文件 +# ------------------------------------------------------------ ENV PYTHONUNBUFFERED=1 \ PYTHONDONTWRITEBYTECODE=1 -# 运行期参数 +# ------------------------------------------------------------ +# 运行期参数（由 --build-arg 传入） +# VAR_PROFILES : 配置 profile（如 dev / prod） +# VAR_PORT : 应用监听端口 +# VAR_PYFILE : 启动入口文件名（不含 .py） +# VAR_PYFILE_PATH : 项目源码目录 +# ------------------------------------------------------------ ARG VAR_PROFILES ARG VAR_PORT ARG VAR_PYFILE ARG VAR_PYFILE_PATH +# ------------------------------------------------------------ +# 把 ARG 转成 ENV，这样在容器运行期也能读取到这些变量 +# PORT : 供 EXPOSE 和 CMD 使用 +# PYFILE : 入口文件名 +# PROFILES : 应用读取的 profile +# ------------------------------------------------------------ ENV PORT=${VAR_PORT} \ PYFILE=${VAR_PYFILE} \ PROFILES=${VAR_PROFILES} +# ------------------------------------------------------------ # 只安装运行期需要的动态库（不再需要 gcc/make/cmake 等） +# net-tools : netstat 等网络排查工具 +# openssl-devel : 若应用运行期需要 SSL 头文件可保留； +# 若纯粹运行，可改为 openssl-libs 更省体积 +# bzip2-devel : 同上，运行期一般只需 bzip2-libs +# libffi-devel : 运行期一般只需 libffi +# mysql-devel : 运行期一般只需 mysql-libs +# 提示：如果确定运行时不需要 -devel 头文件，可替换为对应的 -libs 包， +# 可进一步减小镜像体积 +# ------------------------------------------------------------ RUN yum install -y net-tools openssl-devel bzip2-devel libffi-devel mysql-devel && \ yum clean all && rm -rf /var/cache/yum +# ------------------------------------------------------------ # 从 builder 阶段拷贝已编译好的 Python 依赖 +# /install 下的内容会被合并到 /usr/local +# 这样 pip 安装的包就能被 runtime 阶段的 python 找到 +# ------------------------------------------------------------ COPY --from=builder /install /usr/local +# ------------------------------------------------------------ # 创建工作区 +# ------------------------------------------------------------ WORKDIR /opt/apps +# ------------------------------------------------------------ # 拷贝项目源码 +# 注意：这里会把 VAR_PYFILE_PATH 目录下所有内容拷进 /opt/apps +# 建议配合 .dockerignore 排除 .git、__pycache__、本地虚拟环境等 +# ------------------------------------------------------------ COPY ${VAR_PYFILE_PATH}/ ./ -# 暴露端口 +# ------------------------------------------------------------ +# 暴露端口（仅声明，实际映射由 docker run -p 决定） +# ------------------------------------------------------------ EXPOSE ${PORT} -# 启动 +# ------------------------------------------------------------ +# 启动命令 +# 使用 sh -c 以便解析 ${PYFILE}、${PORT} 环境变量 +# 注意：runserver 仅适合开发/调试； +# 生产环境建议改为 uwsgi / gunicorn，例如： +# CMD ["sh","-c","uwsgi --http 0.0.0.0:${PORT} \ +# --module ${PYFILE}.wsgi:application \ +# --processes 4 --threads 2"] +# ------------------------------------------------------------ CMD ["sh", "-c", "python3 ${PYFILE}.py runserver 0.0.0.0:${PORT} --noreload"] \ No newline at end of file