老实说我第一次把Python Web应用部署到服务器时压根没打算用Docker。直接在服务器上装Python 3pip install依赖再写个systemd服务把Gunicorn拉起来感觉也够用。但真正上线之后问题就来了同一台机器上要跑好几个项目依赖互相打架某个第三方库要求系统里有特定版本的底层库一升级就翻车更别提更新代码后忘重启进程、服务器重启后服务没自启这类低级事故。后来我花了一个周末把项目整体迁移到Docker并用Nginx统一接管流量入口这套组合用到现在稳定性提升了好几个档次。这篇就把整条部署链路从头到尾拆开讲包括方案选型、Dockerfile编写、Compose编排、Nginx反向代理配置、上线更新和问题排查。适合刚把第一个Web项目写到能跑、准备让它上线见人的开发者也适合小团队想要一套规范部署流程的参考。1. 部署方案选型为什么是Docker加Nginx1.1 裸机部署的坑我都替你踩过了先说我最初用裸机部署遇到的问题。最简单的做法是服务器装好系统按项目文档把Python、pip、虚拟环境一个个装好依赖装进虚拟环境再通过systemd把Gunicorn拉起来。这套东西在单项目、单版本、几天才发布一次的场景下确实够用。但一旦项目多起来虚拟环境之间依赖打架、Python版本互不兼容、某个依赖需要系统级库而其他项目又需要另一个版本的系统级库就会变成没完没了的扯皮。举个真实例子。我用过一个第三方OCR库要求系统必须有libGL.so.1但同一台服务器上另一个项目的主人升级了图形相关的系统包直接把我的依赖弄坏了服务莫名其妙启动失败。我当时差点怀疑是自己的代码有问题排查了大半天才定位到是系统包被改动。这种事在裸机部署里实在太常见了。更别说更新代码后忘记重启进程、服务器重启后没有设置自启几乎每个维护过裸机项目的人都经历过。容器化解决的问题就是“把依赖和应用一起打包环境互不干扰”。你把自己需要的Python版本、系统库、运行参数全部写进镜像把镜像当成一个独立沙箱跑到哪儿行为都一样。镜像在本地怎么跑服务器上也怎么跑差别只在于底层CPU架构和内核版本。这种可移植性才是生产环境稳定性的真正基石。1.2 多层组合里Nginx到底扮演什么角色Docker容器已经能打包应用了为什么还要在外面套一层Nginx这个问题我一开始也没想明白总觉得多一层就多一份麻烦。后来才意识到Python Web应用通常跑在Gunicorn这类WSGI服务器上而Gunicorn的设计核心是处理动态请求静态文件、并发连接、反向代理这些事它并不擅长。Nginx站在应用前面把静态资源请求拦截下来直接返回文件把动态请求通过代理转发给Gunicorn两边各干各擅长的活。更重要的是Nginx提供了链路中几乎所有流量入口能力HTTP/2支持、HTTPS证书终止、缓存控制、请求头转发、限流、访问日志统一管理、多应用按域名分流。如果这些功能都让应用层自己做代码复杂度会直线上升也不利于后续运维。用Docker部署应用、Nginx做流量门卫是Python Web生态里非常成熟的一套组合社区文档多、踩坑经验全个人开发者和小团队都够用。我把三种方案放在一起对比过差别其实很明显方案环境隔离扩展性运维复杂度适合场景裸机 systemd差靠虚拟环境一般需手动配置低起步后期升高单项目、快速验证纯Docker运行应用好容器隔离好可以水平扩展中多项目、环境差异大Docker Nginx好隔离清楚很好入口统一管理中高但收益明确生产级Web服务、多站点前两种方案在特定场景下也能用但如果你要长期维护一个对外提供服务的Python Web项目我更推荐一步到位选第三种。这不是纸上谈兵是我踩过坑之后得出的结论。2. 服务器准备与Docker环境安装2.1 服务器选型与系统初始化建议部署前先把服务器准备好。对个人项目或小型团队内部系统扛住几百到几千的日活用户量2核4G内存的云服务器起步绰绰有余。如果是纯展示型项目1核2G也能跑但建议别低于这个配置编译Python依赖时内存不够会导致进程被杀体验非常崩溃。我自己的经验是2核4G同时跑容器化应用和Nginx日常内存占用大概能控制在60%左右留有安全余量。系统我推荐Debian或Ubuntu的LTS版本这两个发行版对服务器场景成熟稳定Docker官方和社区支持最好。拿到手后先改掉默认SSH端口或者在安全组里限制管理端口来源IP新建一个普通用户并加入sudo组禁止root直接登录。这些是基本功别嫌麻烦。然后创建一个swap分区或swap文件容量大约和物理内存持平避免编译阶段出现OOM Killer把进程杀掉。这些步骤做完顺手执行apt update apt upgrade -y把系统包更新一遍更新完最好先重启一次。干净、稳定的底子是后面所有部署操作的基础。2.2 装Docker两条路线我推荐后者安装Docker有两个常用渠道。一是用Docker的官方安装脚本curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh一条命令搞定适合快速搭建。二是按官方文档分步走添加官方GPG密钥、加软件源、apt安装docker-ce和docker-compose-plugin。我倾向于第二种分步走的方式因为能清楚看到每一步做了什么也方便日后排除问题。不过官方脚本在测试环境我也常用胜在快。这里有个细节要强调新版Docker已经默认集成Compose V2插件命令是docker compose中间没有横杠。如果你查资料看到老教程里写docker-compose它们有细微差别。下面所有命令我都用新版风格。装完先验证sudo docker version sudo docker run hello-world看到“Hello from Docker”说明守护进程工作正常。顺便把当前用户加入docker组避免每条命令都加sudosudo usermod -aG docker $USER然后重新登录一次。注意加入docker组意味着该用户基本等于拥有root权限个人开发机这么做没问题多人共用的服务器上要谨慎。2.3 镜像加速源配置Docker要从镜像仓库拉取基础镜像国内服务器直接连接官方镜像仓库的速度时好时坏建议在安装完成后立刻配置镜像加速源。编辑/etc/docker/daemon.json向服务器所在云厂商的官方文档或客服要它们提供的镜像加速地址填入registry-mirrors数组即可。修改后执行sudo systemctl restart docker生效。配置完成后用docker info检查看到Registry Mirrors那一行列出了你填的地址就说明配置成功。这一步我每次装新服务器都会做拉取依赖较多的镜像时节省的时间尤其明显。3. 编写Dockerfile把Python应用变成可移植的镜像3.1 基础镜像怎么选写Dockerfile的第一步是选基础镜像。Python官方镜像有好几个tagpython:3.11、python:3.11-slim、python:3.11-alpine。python:3.11体积最大带了很多编译器和开发工具适合本地调试slim基于Debian精简版体积小不少保留常用系统库alpine基于Alpine Linux体积最小但有些Python包没有预编译的wheel装的时候需要现场编译反而会踩很多C库兼容性问题的坑。我自己实际项目里默认用python:3.11-slim。它体积适中、glibc兼容性好、几乎不会遇到编译底层依赖的问题。Alpine看着体积小但生产环境里如果遇到某个包要编译就要额外装gcc和一堆头文件镜像反而会变大维护成本也高。至于完整版python:3.11构建缓存阶段可能快一点点但服务器上没必要徒增体积。确定镜像tag的时候建议同时固定小版本号比如python:3.11.7-slim不要用latest。latest每次构建结果可能都不同哪天基础镜像更新了你的应用不兼容复查起来很痛苦。3.2 逐行拆解Dockerfile下面是我一份精简但完整的Dockerfile适用于绝大多数Flask或Django项目FROM python:3.11-slim WORKDIR /app ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 RUN apt-get update \ apt-get install -y --no-install-recommends \ build-essential \ libpq-dev \ rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . RUN useradd -m appuser USER appuser EXPOSE 8000 CMD [gunicorn, app:app, -b, 0.0.0.0:8000, -w, 4, --access-logfile, -]这里每一行都有它的用意WORKDIR /app设置工作目录后面所有相对路径都以它为基础。PYTHONDONTWRITEBYTECODE1禁止生成__pycache__容器里这些缓存文件占空间又没用PYTHONUNBUFFERED1让Python日志直接输出到标准输出否则容器里很难通过docker logs看到实时日志。apt-get那行开头加update装完立刻清理apt缓存列表避免把无用文件写进镜像层。COPY requirements.txt放在COPY .之前是为了利用Docker的分层缓存。依赖安装通常是Dockerfile里最耗时的步骤而requirements.txt变化频率远低于源码。只要这个文件没变这一层缓存就能直接复用构建速度会快非常多这个优化在CI流水线上尤其有效。3.3 非root用户与启动命令容器默认以root身份运行这其实是个风险点。万一应用代码有安全漏洞攻击者拿到的是容器内的root权限虽然还隔着容器边界但做纵深防御总没错。我在镜像里新建了一个普通用户appuser然后通过USER appuser切换过去。应用代码运行在没有特权的用户下是Docker官方也推荐的做法。启动命令用Gunicorn参数里-w 4表示开四个worker进程这个数字通常参考CPU核数一般取2乘以CPU核心数加1。4核机器开4到6个都合理不是越大越好因为每个worker都占内存线程调度开销也会增加。--access-logfile -把访问日志打到标准输出跟应用日志一起归容器日志系统管排查时最方便。如果你的应用只是个定时任务或者一次性脚本不依赖Web框架CMD直接换成python main.py就行部署思路完全一致。4. 用Docker Compose把应用和Nginx编排到一起4.1 多容器协作为什么必须上Compose前面只构建了应用镜像但真实部署还要一个Nginx容器做代理。如果全靠docker run手动启动容器每次都要记一堆参数端口映射、数据卷、环境变量、网络稍一疏忽就会配错。Docker Compose的价值在于用一份声明式YAML文件把服务间的依赖关系、网络、数据卷全部定义好一条docker compose up -d就能拉起整个服务栈也能一键停止和重启。对我来说Compose更大的价值是“配置即文档”。团队来了新人看一遍docker-compose.yml就知道系统有哪些组件、各自怎么连接比翻聊天记录里零散的命令靠谱太多。所以在生产环境即使只有一个应用我也建议用Compose管理不要习惯于手敲docker run。4.2 docker-compose.yml关键内容讲解下面这份配置定义了两个服务一个是应用容器、一个是Nginx容器格式是Compose V2services: web: build: . container_name: mysite-web restart: unless-stopped expose: - 8000 env_file: - .env volumes: - static_data:/app/staticfiles nginx: image: nginx:1.27-alpine container_name: mysite-nginx restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro - static_data:/app/staticfiles:ro depends_on: - web volumes: static_data:注意应用容器里我用的是expose而不是ports这两个的区别很多人会弄混。ports会把容器端口映射到宿主机上比如8000:8000相当于对外暴露一个8000端口expose只是声明容器自身监听了8000端口只有同在一个Docker网络里的其他容器才能访问。这里Nginx和应用容器同属默认网络Nginx可以通过服务名web直接访问web:8000完全不需要把8000端口映射到宿主机。这样宿主机上只开80和443两个Nginx端口安全性更好端口管理也更清爽。restart: unless-stopped是很值得用的启动策略容器崩溃或宿主机重启后只要不是开发者显式执行了docker stop容器都会自动重新拉起。depends_on让Nginx容器等待应用容器先启动避免启动顺序颠倒导致应用刚起来时Nginx报一连串上游连接失败。注意它只控制启动顺序不保证应用内部已经完全可用所以应用本身还得有重连容错能力。4.3 数据卷与环境变量Django项目里用户上传的文件属于持久化数据而容器删除后什么都没了这个问题必须用数据卷解决。上面配置里我定义了一个命名卷static_data同时挂载到应用容器和Nginx容器。应用容器负责在启动时收集静态文件并写入卷里Nginx容器以只读方式挂载同一块卷直接从里面读文件返回给用户。两个容器通过数据卷共享文件这是Nginx能高效处理静态资源的关键。Django的collectstatic是每次发布时手动执行的命令我没把它写进Dockerfile因为镜像构建时不方便执行需要数据库连接的步骤。更常见的做法是在Compose里再定义一个一次性命令服务或者发布后手动执行docker compose exec web python manage.py collectstatic --noinput。这个细节后面更新流程部分会再提。敏感配置比如数据库密码、SECRET_KEY不要写进镜像。我用的env_file指向项目目录下的.env文件该文件不要提交到Git仓库在服务器上单独维护。这样镜像可以安全地推到私有镜像仓库也不会把密钥泄露出去。5. Nginx反向代理配置要点5.1 反向代理到底在做什么Nginx在Python部署里的角色可以理解成一个前台大堂经理。访客请求先到达NginxNginx根据路径和域名判断该找谁处理静态文件就地取货直接返回动态请求则交给后面Gunicorn的worker去算。对客户端来说它只跟Nginx打交道完全感知不到后面还有一层应用容器。相比让Gunicorn直接对公网提供服务Nginx作为唯一对外入口的好处很实际一是可以统一开启HTTPS、HTTP/2、Gzip二是可以做请求体大小限制防止客户端POST超大内容压垮应用三是能积累完整访问日志方便统计和排查四是如果有两个Web应用跑在同一台服务器可以用不同域名甚至不同路径顺畅分流。这些能力在应用层自己实现会很别扭在Nginx一层配置就要清爽得多。5.2 一份可以直接抄的Nginx配置我常用的Nginx站点配置放在项目目录下名字叫nginx.conf通过Compose挂载到/etc/nginx/conf.d/default.confupstream web_backend { server web:8000; } server { listen 80; server_name example.com; client_max_body_size 10m; location /static/ { alias /app/staticfiles/; expires 7d; add_header Cache-Control public; } location / { proxy_pass http://web_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }upstream段定义了一个后端服务组指向Compose网络里的web服务名加端口。server_name换成你自己的域名。client_max_body_size 10m按业务来调如果项目涉及文件上传就调大一点比如50m否则上传大文件时会碰到413错误。关键在于location的匹配顺序。/static/开头的请求先被匹配到静态资源处理分支用alias把URL路径映射到容器内的静态文件目录然后设置7天的缓存过期时间和Cache-Control。其余请求全部落入第二个location /分支通过proxy_pass转发给Gunicorn。转发时要格外注意那几个proxy_set_header。Host不设置的话Gunicorn收到的域名会变成web:8000这类内网地址Django如果启用了ALLOWED_HOSTS校验就会直接拒绝请求X-Real-IP和X-Forwarded-For是为了让Nginx后面的应用拿到用户真实IP否则所有请求看起来都来自Nginx容器本身X-Forwarded-Proto则告诉应用原始请求是HTTP还是HTTPSDjango根据它来生成正确的跳转链接。注意docker compose里的服务名和Nginxupstream里的server名称必须一致并且在同一个Docker网络内否则Nginx会报host not found in upstream。还有一个常见的坑如果用了HTTPSDjango的CSRF_TRUSTED_ORIGINS和SESSION_COOKIE_SECURE这类配置必须和实际域名对应否则会出现登录后立即失效这类问题。我建议在发布前把和域名相关的Django配置和Nginx配置放在一起核对一遍。5.3 HTTP/2、HTTPS证书与安全基础配置现代浏览器基本都支持HTTP/2开启后同一连接可以并行传输多个资源体感提升非常明显。Nginx镜像通常默认编译了HTTP/2模块配置里在监听443端口的server块加一个listen 443 ssl http2即可。在此基础上加几句安全响应头是成本低但收益不错的做法add_header X-Content-Type-Options nosniff always; add_header X-Frame-Options SAMEORIGIN;HTTPS证书方面目前最省心的路线是用免费证书签发工具配合自动部署。主流方式是在服务器上安装certbot申请证书后把证书目录挂载进Nginx容器再配置一个443端口的server块引用证书路径。certbot还支持定时自动续期只要续期任务能执行证书就不会过期。如果你不想手动维护还有一些反向代理管理工具支持证书全自动申请和部署效果类似。这部分涉及域名验证方式和DNS服务商的差异每家步骤不太一样按你所用工具的官方文档操作最稳。5.4 多站点共存的拓展思路一台服务器上跑多个Python项目Nginx的配置可以按域名拆成多个server块每个server块指向各自后端服务。既然应用在Compose里最简单的方式是让多个Compose项目共享同一个Nginx实例或者干脆每个项目自带Nginx容器然后用宿主机不同端口映射出去外面再套一层宿主Nginx做统一入口。我自己在大规模扩展之前常用方案是套一层宿主Nginx宿主机只开80和443按server_name分流到各个Compose项目的Nginx端口。这样每个项目的配置彼此独立互不可见升级互不干扰。唯一要注意的是宿主Nginx和容器Nginx之间不要出现端口冲突端口规划一定要提前写清楚。6. 上线、更新与日志排查的完整闭环6.1 第一次从零上线的完整命令流程假设你已经写好了Dockerfile、docker-compose.yml和nginx.conf项目目录里配置齐全接下来是一套照着敲的流程# 构建并推送到镜像仓库以你的私有仓库为例 docker build -t registry.example.com/mysite-web:20250101 . docker push registry.example.com/mysite-web:20250101 # 服务器上拉镜像并启动 cd /opt/mysite docker compose pull docker compose up -d第一次部署没现成镜像也可以直接走docker compose up -d --build让服务器本地构建。但我不建议在服务器上长期保留源码和构建环境更规范的方式是让构建发生在本地或CI流水线服务器只负责跑镜像。这样服务器上不需要装任何编译工具镜像层面也更容易追踪版本。启动完成后用docker compose ps看容器状态再用curl -I http://127.0.0.1做一次本机健康检查。看到HTTP 200和Nginx的Server头说明最外层Nginx已经正常响应。如果要使用域名记得先在DNS服务商处把域名解析到服务器IP并在云服务商的安全组或防火墙里放行80和443端口。6.2 日常更新流程如何做到零停机项目上线之后更新代码是常态。容器化后更新标准流程是本地或CI构建新版本镜像推送到镜像仓库服务器执行docker compose pull拉取新镜像然后docker compose up -d重建容器。因为Compose检测到镜像ID变了会先停旧容器再创建新容器中间停机时间只有几秒钟。对要求不能中断服务的项目可以把两个容器交替启动或者用Nginx自带的nginx -s reload配合灰度切换来减少抖动。小团队早期阶段不需要一上来就上K8s保持镜像版本可回溯、发布步骤可重复就已经比裸机时代强太多。我给项目打的镜像tag通常包含日期比如20250101一旦新版本出问题回滚只需要把tag改回上一个日期再docker compose up -d逻辑非常简单。6.3 日志、健康检查和资源占用容器日志统一走标准输出之后排查问题很省事docker compose logs -f web实时看应用日志docker compose logs -f nginx看访问日志和错误日志。Docker里docker logs查看的容器输出默认会不断累积长时间跑的项目如果不处理宿主机磁盘会被慢慢占满。这里有两个对策一是在Compose配置里加logging选项限制日志文件大小和保留数量二是系统层面配置日志轮转。我习惯两种都做磁盘被打满导致的故障比代码问题更隐蔽也更致命。健康检查也是我后来才补上的习惯。Dockerfile里可以加HEALTHCHECK指令或用Compose的healthcheck字段定期向应用健康检查地址发起请求。一个简单的Dockerfile健康检查示例HEALTHCHECK --interval30s --timeout3s --retries3 \ CMD curl -f http://localhost:8000/health || exit 1注意这个例子需要镜像里有curl所以基础镜像安装阶段别忘记把curl装上。健康检查状态可以在docker inspect里看到也能被监控系统拉取算是成本很低的一道保险。7. 常见问题与排查技巧实录7.1 502 Bad Gateway这是我被问得最多的问题。页面显示502说明Nginx已经正常收到请求但它向上游转发时发现目标不可用。最常见的原因有三个应用容器没起来或正在重启、应用监听的端口和Nginx配置的端口不一致、Gunicorn worker数开太多导致内存不足。排查顺序很固定第一步看容器状态docker compose ps如果状态是Exited就去docker compose logs web看日志第二步检查Nginx配置里的proxy_pass里写的服务名和端口是否与Compose服务定义一致第三步看宿主机内存占用free -h如果内存占满很多容器应用会被系统杀掉日志里可能有Killed字样。按这三步走绝大多数502都能定位。7.2 容器启动后立即退出docker compose up -d后容器一直处于重启状态通常是启动命令本身有问题应用启动就抛异常退出。最强排查工具是docker compose logs日志里会直接显示异常堆栈。一个特别容易踩的坑是应用读了宿主机不存在的环境变量比如Compose配置了env_file但服务器上没创建对应的.env文件或者应用在启动时读取某个路径下的配置文件但容器里没有挂载对应数据卷。这类问题比502更隐蔽因为它们不会出现在Nginx日志里。我建议应用启动阶段就把关键配置校验做充分启动失败时立刻把缺失配置项写入日志否则每次排错都要对着环境变量、数据卷和代码逐个猜测。7.3 端口绑定冲突如果同时跑多个项目宿主机端口很容易打架。比如项目A的Nginx已经占了宿主机80端口项目B的Nginx再想监听80启动就会报Address already in use。解决办法是项目B的Nginx映射到其他端口比如8080:80然后在宿主Nginx层按域名分流。端口规划建议写进项目文档不要靠记忆因为容器重启后端口一旦冲突服务之间会互相影响排查起来要花不少时间。7.4 数据卷问题文件上传成功却打不开静态文件如果同时被Web应用和Nginx读取一定要确认它们读的是同一个数据卷。我有一次配置两个容器分别挂载了不同路径运行时没有任何报错但用户上传的图片在页面上就是不显示排查半天发现应用写到卷ANginx读的是卷B同名路径下完全不是同一份文件。出现这类诡异问题时先检查数据卷定义和挂载路径是否完全一致用docker compose exec nginx ls -l进Nginx容器看看文件到底在不在。把几个高频问题整理成速查表排查时快速翻现象首选排查命令常见根因页面502docker compose logs web应用异常、端口不匹配、内存溢出容器反复重启docker compose logs --tail100启动报错、配置缺失端口冲突docker compose ps多个项目端口重叠静态文件404ls 数据卷里的实际文件两容器卷路径不一致日志占满磁盘docker system df缺少日志轮转策略这些坑我都实打实踩过整理成清单比翻官方文档快得多。你把同样经验在部署过程中收集下来下次再遇到就是五分钟定位的事。在这套方案落地之后我自己的项目几乎不再出现“环境搞坏”这种低级事故。最让我意外的是后来团队来了新人对着Compose文件就能把服务拉起来运维成本真的降下来了。要说唯一需要预留学习时间的部分反而是Dockerfile和Compose的细节网上资料很散踩坑经验只能靠实践攒。如果你正在为部署稳定性头疼我的建议是别急着上更重的调度系统先把这一套跑明白。