前言把 Python 项目做成 Docker 镜像本质上是三件事选一个带 Python 的基础镜像、把依赖装进去、把代码和启动命令放进去。流程不长但几乎每个人第一次写Dockerfile都会踩同一组坑——改一行代码就触发依赖重装、镜像里混进了.env和.git、容器跑起来日志看不到、以 root 身份跑服务。需要先纠正一个说法「导出为镜像」不是把本地环境打包带走。本地装好的虚拟环境venv里写死了绝对路径直接复制进镜像在另一个系统上通常不可用。正确的做法是让镜像自己执行一次安装把requirements.txt或pyproject.toml里的依赖重新装一遍这样镜像才是自洽、可复现的。还要提醒一句基础镜像的选择不要沿用python:2.7这类标签。Python 2.7 已于 2020 年 1 月 1 日停止维护不再有安全更新而镜像里跑什么版本完全由FROM决定不会因为宿主机升级而改变。文中示例统一使用 Python 3.12 的 slim 镜像。本文按「写一个能用的Dockerfile」的顺序展开先给最小可用版本再逐条讲层缓存、依赖声明、.dockerignore、非 root 用户、多阶段构建和启动命令的选择最后列出最容易踩的坑。一、最小可用的 Dockerfile在项目根目录新建一个名为Dockerfile的文本文件没有后缀# 基础镜像标签显式指定版本不要用 latestFROM python:3.12-slim# 设置容器内的工作目录WORKDIR /app# 先只复制依赖清单这样依赖没变时这一层可以复用缓存COPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt# 再复制项目代码COPY . .# 以 exec 形式给出启动命令CMD [python, main.py]构建与运行docker build -t myapp:1.0 .docker run --rm myapp:1.0docker build末尾那个点表示「构建上下文是当前目录」不能省。-t myapp:1.0给镜像打名字和标签。二、层缓存为什么复制顺序不能乱Docker 构建是分层的每一条指令产生一层只要某一层的输入没变就能直接复用缓存。因此顺序至关重要复制顺序改一行业务代码后改一个依赖后先COPY . .再pip install整个依赖重装整个依赖重装先COPY requirements.txt再装依赖最后COPY . .只有最后一层重建依赖层重建# 推荐顺序变化慢的在前变化快的在后FROM python:3.12-slimWORKDIR /app# 1) 系统依赖很少变RUN apt-get update \ apt-get install -y --no-install-recommends curl \ rm -rf /var/lib/apt/lists/*# 2) Python 依赖清单偶尔变COPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt# 3) 源码经常变COPY . .CMD [python, main.py]--no-cache-dir让 pip 不在镜像里留下下载缓存rm -rf /var/lib/apt/lists/*是同一个目的——把安装过程中产生的临时文件在同一层里删掉否则它们依然会占镜像体积。三、.dockerignore控制构建上下文COPY . .会把构建上下文里的所有文件都送进去包括.git、.venv、__pycache__、.env和本地数据库文件。这既拖慢构建也可能把密钥带进镜像。在项目根目录创建.dockerignore与Dockerfile同级.git.gitignore.venvvenv__pycache__*.pyc*.pyo.pytest_cache.mypy_cache.env.env.**.sqlite3*.logDockerfiledocker-compose.yml注意.dockerignore只影响「什么不会被送进构建上下文」不影响容器里已有的文件。它也不能替代权限管理——真正的密钥应该用环境变量或挂载的 secret 传入而不是写死在镜像里。四、启动命令CMD与ENTRYPOINT两者都用来指定容器启动时执行什么区别在于可覆盖性指令能否被docker run的参数覆盖典型用途CMD能docker run image 其他命令会整体替换默认启动方式ENTRYPOINT不能整体替换追加的参数作为它的参数传入把镜像做成「一个可执行程序」两种写法还有 shell 形式与 exec 形式的区别这一点在 Python 项目里后果很实在# exec 形式PID 1 就是 python能正确接收 SIGTERMCMD [python, main.py]# shell 形式实际是 /bin/sh -c python main.py# python 是 sh 的子进程信号不会自动转发CMD python main.py推荐一律写成 exec 形式JSON 数组。容器里 Python 进程作为 PID 1 还有一个额外好处KeyboardInterrupt与优雅退出能正常工作。如果项目是 Web 服务通常写成EXPOSE 8000CMD [python, -m, uvicorn, app:app, --host, 0.0.0.0, --port, 8000]EXPOSE只是文档性质的声明真正把端口映射到宿主机靠docker run -p 8000:8000。五、非 root 用户与多阶段构建默认情况下容器里是 root这不是好习惯。加一个普通用户只需要三行FROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .# 创建普通用户并切换RUN useradd --create-home --uid 10001 appuser \ chown -R appuser:appuser /appUSER appuserCMD [python, main.py]注意USER之后的所有指令都以该用户身份执行所以chown必须在USER之前做完。多阶段构建用来把「编译期需要、运行期不需要」的东西留在中间镜像里。纯 Python 项目如果只装 wheel收益有限但如果依赖里有需要编译的包或者你希望运行镜像里连 pip 的构建工具链都没有就值得用# ---------- 第一阶段安装依赖 ----------FROM python:3.12-slim AS builderWORKDIR /buildCOPY requirements.txt .# 装到一个独立前缀下方便整目录复制RUN pip install --no-cache-dir --prefix/install -r requirements.txt# ---------- 第二阶段运行镜像 ----------FROM python:3.12-slimWORKDIR /app# 只把装好的依赖复制过来构建工具留在上一层COPY --frombuilder /install /usr/localCOPY . .RUN useradd --create-home --uid 10001 appuser \ chown -R appuser:appuser /appUSER appuserCMD [python, main.py]COPY --frombuilder从上一次的构建阶段取文件被引用阶段的内容不会进入最终镜像。六、几个实用的环境变量ENV PYTHONDONTWRITEBYTECODE1 \PYTHONUNBUFFERED1 \PIP_NO_CACHE_DIR1变量作用PYTHONDONTWRITEBYTECODE1不生成.pyc避免容器里出现多余文件PYTHONUNBUFFERED1标准输出不缓冲docker logs能实时看到日志PIP_NO_CACHE_DIR1等价于每次都给 pip 加--no-cache-dirPYTHONUNBUFFERED是排查「程序明明在跑但日志一片空白」的第一手段不加它Python 在非交互式环境下会把 stdout 缓冲起来。完整示例一个可以直接照抄的项目结构myproject/├── Dockerfile├── .dockerignore├── requirements.txt├── main.py└── app/└── __init__.pyFROM python:3.12-slim AS builderENV PIP_NO_CACHE_DIR1WORKDIR /buildCOPY requirements.txt .RUN pip install --prefix/install -r requirements.txtFROM python:3.12-slimENV PYTHONDONTWRITEBYTECODE1 \PYTHONUNBUFFERED1WORKDIR /appCOPY --frombuilder /install /usr/localCOPY . .RUN useradd --create-home --uid 10001 appuser \ chown -R appuser:appuser /appUSER appuserEXPOSE 8000CMD [python, main.py]# 构建docker build -t myapp:1.0 .# 前台运行验证输出docker run --rm -p 8000:8000 myapp:1.0# 后台运行并查看日志docker run -d --name myapp -p 8000:8000 myapp:1.0docker logs -f myapp# 进入容器排查docker run --rm -it myapp:1.0 /bin/sh常见坑点1. 先COPY . .再装依赖改一行代码就全量重装❌ 错误写法FROM python:3.12-slimWORKDIR /appCOPY . .RUN pip install --no-cache-dir -r requirements.txtCMD [python, main.py]✅ 正确写法依赖清单先复制、单独安装源码最后复制FROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .CMD [python, main.py]2. 没有.dockerignore密钥和.git一起进镜像❌ 错误做法什么都不忽略.env里的数据库密码被COPY . .带进镜像层——即使后续删掉它依然留在历史层里。✅ 正确做法加.dockerignore排除.env、.git、.venv密钥改用运行时环境变量或 secret 注入。3. 用了FROM python:latest❌ 错误写法FROM python:latest今天拉到的可能是 3.13明天重建就变成别的版本环境不可复现。✅ 正确写法显式指定次版本FROM python:3.12-slim4. 把本地的 venv 直接复制进镜像❌ 错误写法COPY venv /app/venvENV PATH/app/venv/bin:$PATHvenv 的脚本里写死了创建时的绝对路径换个位置或换个系统就会失效而且里面可能还混着平台相关的二进制包最终镜像还会大出一大截。✅ 正确写法在镜像内重新安装依赖pip install -r requirements.txt或参考上一节的多阶段构建把依赖装到独立前缀再复制。5. 用 shell 形式的CMD信号收不到❌ 错误写法CMD python main.py实际执行的是/bin/sh -c python main.pyPython 是 shell 的子进程docker stop的SIGTERM不会转发给它。✅ 正确写法CMD [python, main.py]6. 日志看不到以为程序没起来❌ 错误现象docker logs什么都没有但服务其实正常响应。✅ 正确做法设置ENV PYTHONUNBUFFERED1让 stdout 不缓冲同时避免在代码里自己重定向或缓冲日志输出。7. Web 服务监听127.0.0.1导致宿主机访问不到❌ 错误写法uvicorn app:app --host 127.0.0.1。容器内的回环地址只对容器自己可见。✅ 正确写法监听所有网卡--host 0.0.0.0再用docker run -p 8000:8000做端口映射。8. 用COPY --from时忘了被引用阶段本身也要能独立构建❌ 错误写法在 builder 阶段只写了COPY requirements.txt .却从其他路径取文件或者引用了不存在的阶段名构建时报failed to solve、invalid from flag value。✅ 正确写法确认AS builder的别名与COPY --frombuilder完全一致且被复制的路径在上一个阶段里确实存在。总结环节关键做法基础镜像FROM python:3.12-slim不要用latest复制顺序依赖清单先、源码后让缓存命中安装依赖pip install --no-cache-dir -r requirements.txt不复制 venv忽略文件用.dockerignore排除.git、.venv、.env启动命令exec 形式CMD [python, main.py]端口EXPOSE只是声明映射靠-p服务要监听0.0.0.0权限创建普通用户并USER切换镜像瘦身多阶段构建 同一层内清理临时文件日志PYTHONUNBUFFERED1把 Python 项目打成镜像的核心思路是「让镜像自己装依赖」而不是搬运本地环境。按「基础镜像 → 系统依赖 → Python 依赖 → 源码 → 用户 → 启动命令」这个顺序写Dockerfile缓存、体积、安全这三件事基本就都照顾到了。
企业数字化 ERP 产品动态
相关推荐
Slurm作业提交与查询指南:从sbatch/srun到排障实践 简介:面向在高性能计算与超算平台开展科研、课程实验和批量计算任务的学生、教师及运维人员,这份国科大超算中心 Slurm 作业调度系统使用指南梳理了从基本概念到常用命令的完整使用路径,可帮助读者理解队列、节点、作业与作业步之间的关系&am… · 2026/11/18 8:29:24
Java Socket+Swing局域网聊天程序设计与实现 简介:ACCP5.0第一学期结业项目是一套面向编程初学者的完整社交应用实战源码,聚焦在线聊天场景,涵盖好友管理、实时通信、头像上传、陌生人权限控制及个人资料维护等核心功能模块,助力学员系统掌握C#开发、WinForms界面设计、SQL S… · 2026/11/14 14:20:07
UG/NX三维模型摆正操作全解析与工程实践 1. UG摆正的概念与背景UG(Unigraphics,现称Siemens NX)作为工业设计领域的标杆软件,其"摆正"功能是三维建模与工程制图中的基础操作。这个看似简单的功能实则蕴含了CAD/CAM系统的核心逻辑——将三维实体按照设计意图或加… · 2026/11/9 17:29:12
福州那里有特种工考试官方回应证书过期怎么复审 福州那里有特种工考试官方回应证书过期怎么复审 证书过期了不知道怎么复审延期,这种焦虑感你不是一个人。特种作业操作证一旦过期,不仅影响日常工作,更可能让你在项目现场被叫停、被罚款,甚至面临法律责任。尤其是在福州,特种作业证的办理和复审流程,直… · 2026/11/18 8:29:03
2026河南最新政策下合江电工证考试时间怎么安排更合适 2026河南最新政策下合江电工证考试时间怎么安排更合适 工地太忙根本没时间复习考试,这是很多电工朋友的真实写照,尤其是在河南许昌的中小型施工企业,工作节奏快、任务重,想要在有限的时间里安排好合江电工证考试时间,几乎是项技术活。2026河南最… · 2026/11/18 8:29:03
临工特种机好吗电子证书怎么考更靠谱 临工特种机好吗电子证书怎么考更靠谱 你是不是正愁不知道去哪报名怕被中介坑?临工特种机好吗这个问题,其实很多准备报考的工人最关心的就是: 能不能直接找官方渠道报名 , 电子证书有没有用 , 到底能不能全国通用… · 2026/11/18 8:29:03
三级电工证属于职称 通过率揭秘这些你必须知道 三级电工证属于职称 通过率揭秘这些你必须知道 你是不是也像很多人一样, 不知道去哪报名怕被中介坑 ?现在网上信息太多,一不小心就掉进坑里。三级电工证属于职称,听起来挺厉害的,但很多人并不清楚它的报考流程、考试难度、通过率如何,甚至不知道它到… · 2026/11/18 8:29:03
商丘考电工证考场在哪多久拿证怎么选培训机构 商丘考电工证考场在哪多久拿证怎么选培训机构 实操考试心里没底怕挂科?商丘电工证考场在哪?多久拿证?这些问题可能正困扰着你。别急,这篇文章从考场地址、考试流程、拿证时间、培训机构选择等多个角度,帮你理清思路,少走弯路。… · 2026/11/18 8:29:03
三级电工证属于职称,真实经历告诉你怎么转证和换地区 三级电工证属于职称,真实经历告诉你怎么转证和换地区 之前考的证在外省能不能转过来?这个问题是很多电工朋友,特别是像我一样在濮阳初次报考的人员最关心的。很多人拿着外地的电工证,想在当地找工作、办业务,却发现证书不被认可,甚至还被要求重新考证,… · 2026/11/18 8:28:03
长春初级电工证怎么考?通过率揭秘全在这里 长春初级电工证怎么考?通过率揭秘全在这里 之前考的证在外省能不能转过来?这几乎是每个想从事电工工作的人都会问的问题。特别是那些在外地打拼多年、手里握着一张“外地电工证”的人,到了长春想继续干这一行,第一反应就是“我的证能用吗?”。今天我们就… · 2026/11/18 8:19:55
国内电工证报考条件与考试时间 低压电工证怎么考?学历不高也能报名,官方报名入口全在这 你是不是经常听说“电工证是入行门槛”,但又担心自己学历不够、经验不足,根本报不了名?别急,今天就带你从零了解【国内电工证】的报考流程、考试内容,还有怎么在 官方报名入口… · 2026/11/18 8:19:53
电工作业时如何断电?电子证书到底能不能全国通用? 电工作业时如何断电?电子证书到底能不能全国通用? 实操考试心里没底怕挂科,特别是电工作业时如何断电这一操作,不仅关系到你能不能拿到证书,更关系到以后能不能顺利上岗。很多人觉得这不过就是“断个电”,但其实这里面的门道可不少,稍有不慎就可能出错… · 2026/11/17 9:06:35
电工证做题最新内部消息:怕考不过白交培训费?三招教你稳过 电工证做题最新内部消息:怕考不过白交培训费?三招教你稳过 你是不是也这样?报名了电工证培训,交了钱,结果一到考试就懵, 怕考不过白交培训费 ?别慌,这是很多初次报考人员的真实写照。而最近, 河南省应急管理厅… · 2026/11/18 0:00:37
许昌电工证在哪复审 别踩坑怕考不过白交培训费 许昌电工证在哪复审 别踩坑怕考不过白交培训费 怕考不过白交培训费,这几乎是每个想考电工证的学员心中的痛。尤其是在许昌,电工证的报考和复审流程复杂,稍有不慎就可能被坑, 千万别踩坑… · 2026/11/18 0:00:37
老式电工证还能用吗?怎么报名别踩坑,河南企业主都在问的实操真相 老式电工证还能用吗?怎么报名别踩坑,河南企业主都在问的实操真相 实操考试心里没底怕挂科?老式电工证还能用吗?怎么报名又怕被坑?这些问题几乎每个准备考电工证的施工企业负责人心里都在打鼓。尤其是河南本地的中小施工企业,很多都在用老式电工证,但随… · 2026/11/18 0:00:37
双极步进电机控制实战:DRV8818PWPR与PIC18F86K22驱动调试 /* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/17 21:47:42
STM32F207ZG + DRV8818PWPR 步进电机驱动实战解析 /* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/17 21:47:42
DRV8818PWPR+dsPIC30F4013工业级双极步进电机控制方案 /* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/17 21:47:42