把Python Web应用部署到生产服务器一直是许多开发者从开发走向运维的第一道坎。本地跑得好好的Flask或Django项目一旦放到Linux服务器上各种依赖缺失、端口冲突、静态文件路径找不到、进程被kill的问题就全冒出来了。我早期也踩过不少坑后来逐渐形成了一套稳定可靠的方案Docker打包应用 Nginx做反向代理再配合Docker Compose管理数据库、缓存和应用容器基本上可以复用到绝大多数的Python Web项目。这套组合不仅能解决环境一致性问题还能明显降低后续维护和扩容的复杂度。这篇内容会从整体架构、Dockerfile编写、Nginx配置到上线排错一条龙讲透适合刚接触部署的开发者也适合正在优化现有部署流程的同学参考。1. 部署方案的整体设计与选型思路1.1 为什么用Docker而不是直接在服务器装环境很多人会问直接在一台干净的Ubuntu服务器上装Python、pip、MySQL再跑一个systemd服务不行吗当然可以但问题在于环境一致性。你在本地开发时用的Python是3.11服务器上系统自带的可能是3.8本地用的某个C扩展编译好了服务器上因为头文件缺失又得重新编译。Docker通过镜像把操作系统层、Python解释器、依赖库、源码全部打包在一起让应用在任何有Docker引擎的机器上以相同方式运行彻底绕开了“在我电脑上是好的”这类尴尬场景。还有一点很重要Docker让多应用隔离变得容易。一台2核4G的服务器可以同时跑几个Python服务每个服务有自己的端口、文件系统和网络栈。如果直接部署在宿主机上两个应用都依赖Flask版本不同或者一个应用用到Redis、另一个也用到Redis版本和配置很容易互相干扰。用Docker后每个服务跑在独立容器里启动、删除、升级都不影响宿主机的其他进程。生产环境里建议用Docker Compose来管理多容器应用。Compose用一个YAML文件描述所有服务一条docker-compose up -d就能把Nginx、Python应用、MySQL、Redis全部拉起来。这对小型团队来说比Kubernetes轻太多而且学习和运维成本低。后面我会详细拆解Compose文件的写法。1.2 为什么需要Nginx放在应用前面直接用Gunicorn监听80端口也能让Flask或Django应用工作。但生产环境和本地不同有几个现实问题首先是并发和性能。单台Gunicorn默认的worker数量有限对静态文件频繁的请求会白白消耗Python进程的资源。其次HTTPS卸载。证书的加解密对Python进程来说是额外开销Nginx作为C语言实现的高性能Web服务器处理TLS和静态文件都比Python高效得多。Nginx的位置更像一个流量入口。它接收来自外部的HTTP请求判断是请求/api还是/static静态资源直接由Nginx返回动态请求才通过反向代理转发到Python应用。这样做的好处是多层明确分工Nginx负责网关、路由、限流、日志Python专注业务逻辑。另外如果以后要多开几个Python实例做负载均衡Nginx只需要加多几个upstream节点非常方便。一个典型的请求流程是浏览器访问域名 - DNS解析 - 服务器Nginx监听80端口 - Nginx匹配location规则 - 动态请求转发到容器内的Gunicorn - Gunicorn处理WSGI请求交给Flask/Django应用 - 返回响应后原路返回。这条链路里每个环节都承担明确职责排错时也更容易定位。1.3 整体架构容器编排与网络模型以最常见的Django或Flask项目为例整个部署架构通常包含这些角色角色技术选项职责入口代理Nginx监听80/443转发请求处理静态文件Python应用Flask/Django Gunicorn执行业务逻辑处理Web请求数据库PostgreSQL/MySQL持久化业务数据缓存/队列Redis缓存热点数据、异步任务队列持久化Docker volume保存数据库文件、上传文件在Docker网络中Nginx和Python应用通常放在同一个自定义网络中通过容器名互相访问。比如Nginx配置里把请求代理到http://web:8000这里的web是Python容器的服务名Docker内置DNS会自动解析成对应容器的IP。这样既不需要关心容器的随机IP也不用把端口暴露到公网安全性更高。只有Nginx端口映射到宿主机数据库和Redis端口只在内部网络暴露外部无法直接访问。2. 环境准备与基础配置2.1 服务器选型与初始化检查部署前先确认服务器的基本情况。我常在腾讯云、阿里云或AWS上的Ubuntu 22.04 LTS或20.04 LTS做部署如果你用的是CentOS命令会略有差异但核心思路一样。购买服务器后建议立即做三件事更新系统、创建非root用户、开启防火墙。更新系统的目的是避免依赖源版本过旧。SSH登录后先执行sudo apt update sudo apt upgrade -y然后创建一个日常使用的用户sudo adduser deploy sudo usermod -aG sudo deploy之后用deploy用户登录避免直接使用root因为一旦应用被入侵root权限的破坏力太大。防火墙方面Ubuntu自带ufw先允许SSH端口再启用sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable这里提醒一句千万先允许OpenSSH再重启防火墙否则SSH连不上只能去控制台强制重置很麻烦。2.2 安装Docker与Docker Compose生产服务器上安装Docker推荐用官方脚本但注意脚本来源。现在很多教程让你curl一段脚本直接执行实际上官方确实提供了一条命令curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh安装完检查版本docker --versionDocker Compose在Docker 20.10以上版本通常已经包含docker compose插件如果没有就单独安装。验证docker compose version把当前用户加入docker组免得每次都sudosudo usermod -aG docker deploy newgrp docker注意加完组之后需要重新登录SSH才生效。这个细节我漏过好几次导致后面命令一直报权限错误还以为是Docker坏了。2.3 项目结构的规范化改造很多Python项目本地能跑但部署时一团乱麻问题就出在项目结构没有好好整理。我一般会把Web项目按这样的目录组织myproject/ ├── app/ │ ├── __init__.py │ ├── views.py │ ├── models.py │ └── ... ├── static/ ├── templates/ ├── requirements.txt ├── Dockerfile ├── docker-compose.yml ├── nginx/ │ └── app.conf ├── .dockerignore └── manage.py如果是DjangoDocker构建时会读取Dockerfile所在的目录作为上下文把整个目录打包发送给Docker守护进程。如果项目里塞了虚拟环境目录、.git目录、大体积上传文件构建会变得极慢。这时候.dockerignore就派上用场它和.gitignore类似__pycache__ *.pyc .env .git venv .venv logs upload/*这个文件必须在Dockerfile同目录下并且名字不能写错否则等你盯着构建进度条发呆的时候就知道它有多重要了。3. Docker化Python Web应用的核心细节3.1 编写多阶段Dockerfile写Dockerfile之前要明确基础镜像的选择。Python官方镜像有slim和alpine等变体。生产环境我倾向于用python:3.11-slim因为基于Debian兼容性比Alpine好Alpine使用musl libc一些Python的C扩展可能编译失败虽然镜像体积小但踩坑成本不划算。多阶段构建的好处是把编译环境和运行环境分离最终镜像只保留运行依赖。下面是一个比较完整的示例# 第一阶段安装依赖并构建 FROM python:3.11-slim AS builder WORKDIR /app ENV PIP_NO_CACHE_DIR1 # 先复制requirements利用Docker缓存层 COPY requirements.txt . RUN pip install --prefix/install -r requirements.txt # 第二阶段运行环境 FROM python:3.11-slim RUN useradd --create-home --shell /bin/bash deploy WORKDIR /app # 从第一阶段拷贝已安装的依赖 COPY --frombuilder /install /usr/local COPY --chowndeploy:deploy . . USER deploy EXPOSE 8000 CMD [gunicorn, app:app, -b, 0.0.0.0:8000, -w, 4, -k, uvicorn.workers.UvicornWorker]注意这里有一个细节COPY --frombuilder /install /usr/local把预装的依赖放进了运行镜像的Python路径避免了在运行环境再执行pip install既缩短了构建时间也缩小了镜像体积。如果你用的是FastAPI建议把worker改成uvicorn.workers.UvicornWorker让Gunicorn管理异步workerFlask和Django用默认的sync worker就行。另外很多应用需要连接到数据库或Redis连接信息会通过环境变量传入。千万不要把密码硬编码到Dockerfile里应该用docker-compose.yml里的environment字段配合.env文件来管理。3.2 Gunicorn worker数量的计算逻辑Gunicorn的-w参数不是越大越好。每个worker都是一个独立的Python进程都吃内存。一般2核4G的服务器建议4个worker4核8G可以跑到8个。经验公式是worker数 CPU核数 * 2 1这是Gunicorn官方文档给出的推荐。如果你的应用涉及同步阻塞操作可以适当增加但一旦内存超限Linux内核会触发OOM killer直接把容器杀掉那可比请求慢严重多了。还有一点是超时设置。默认900秒太大对于接口请求并不适合。我一般加--timeout 120如果你的应用有长时间任务最好把任务放到Celery之类的异步队列里而不是让HTTP请求一直挂着。在docker-compose里可以用command覆盖默认CMD。3.3 使用docker-compose编排多服务docker-compose.yml是整个部署的“接线图”。写一份基础但完整的配置version: 3.9 services: web: build: context: . dockerfile: Dockerfile image: myproject-web:latest restart: unless-stopped expose: - 8000 environment: - DB_HOSTdb - DB_PORT5432 - DB_USERpostgres - DB_PASSWORD${DB_PASSWORD} - REDIS_HOSTredis volumes: - static_data:/app/staticfiles depends_on: - db - redis db: image: postgres:15 restart: unless-stopped environment: - POSTGRES_DBmyproject - POSTGRES_USERpostgres - POSTGRES_PASSWORD${DB_PASSWORD} volumes: - pg_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 5s timeout: 5s retries: 5 redis: image: redis:7-alpine restart: unless-stopped command: redis-server --appendonly yes volumes: - redis_data:/data nginx: image: nginx:1.25-alpine restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./nginx:/etc/nginx/conf.d - static_data:/static depends_on: - web volumes: pg_data: redis_data: static_data:这里有个很关键的坑expose和ports的区别。web服务只用了expose表示只在Docker内部网络开放8000端口宿主机和外部网络访问不到。只有Nginx对外暴露了80和443。这样的安全边界能防止应用端口直接被公网扫描。数据库和Redis甚至没有暴露到宿主机只给内部网络访问外部攻击面大大减少。depends_on只控制启动顺序不等于“服务可用”。比如web启动时可能发现db还没初始化完成就会报连接失败。所以更稳妥的方式是给数据库加healthcheck并在web里用健康检查判断或者让web应用的启动逻辑支持多次重试连接数据库。3.4 镜像构建的策略与缓存优化每次改一行代码就重新构建整个镜像显然不现实。Dockerfile里面每一行指令都会生成一个缓存层如果指令没有变化后续构建会复用之前生成的层。所以要把改动频率最低的部分放在Dockerfile前面。我通常先复制requirements.txt并安装依赖再复制整个应用代码。这样只要依赖没改pip install这一层就不会重复执行构建速度可以快很多。配合阿里云或腾讯云镜像加速器还能进一步缩短时间。如果你是个人项目也可以用docker build --cache-from手动指定缓存来源。还有一个实操建议给镜像打上明确的taglatest只适合折腾生产环境最好用Git提交对应的tag来标记比如myproject-web:1.2.3。这样回滚时只需要指定旧镜像tag不用重新构建。4. Nginx配置与反向代理实现4.1 理解Nginx的location工作流Nginx配置文件的核心是location块。请求进来后Nginx先根据URI匹配server块然后逐个匹配location规则。匹配规则分前缀匹配和正则匹配顺序会影响最终处理方式。我写了一个非常简洁但适用的例子server { listen 80; server_name api.example.com; location /static/ { alias /static/; expires 30d; access_log off; } location /media/ { alias /static/media/; expires 7d; } location / { proxy_pass http://web:8000; 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; } }这里有几个关键点。/static/和/media/分别对应Django的静态文件和用户上传文件Nginx直接处理静态文件不走Python响应快得多。location /是兜底规则所有没匹配到上面规则的动态请求都会转发给web容器的Gunicorn。alias和root的区别要注意alias /static/表示访问/static/xxx时实际取的是/static/xxx如果是root /static实际取/static/static/xxx路径就错了。反向代理里必须顺手设置三个头Host、X-Real-IP、X-Forwarded-For。特别是当Django的DEBUGFalse时如果请求Host和ALLOWED_HOSTS不匹配Django会直接返回400而X-Forwarded-For能让应用拿到真实用户IP不设置的话日志里全是Nginx容器的IP。4.2 使用upstream实现负载均衡如果你准备把Python应用扩到多个实例Nginx的upstream块是最简单的扩展方式upstream web_backend { least_conn; server web1:8000 weight2; server web2:8000 weight1; } server { listen 80; location / { proxy_pass http://web_backend; } }least_conn会把请求转发给当前连接数最少的实例适合处理时间不均的接口。weight参数可以控制权重比如主服务器多分担一点流量。这种方式可以配合Docker Compose的--scale web3使用但要注意数据库和静态文件必须共享存储否则用户上传的文件和数据库数据会对不上。4.3 HTTPS与SSL证书配置现在部署Web应用不配HTTPS基本说不过去。Let‘s Encrypt的免费证书是首选。建议直接用Certbot自动申请和续期sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d api.example.comCertbot会自动修改Nginx配置把80端口的请求重定向到443并配置证书路径。如果你不希望通过工具改配置也可以手动申请然后手动指定证书路径server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem; location / { proxy_pass http://web:8000; } } server { listen 80; server_name api.example.com; return 301 https://$host$request_uri; }这里有一个很常见的问题如果应用是Django并且启用了安全相关选项需要在Django的配置里设置SECURE_PROXY_SSL_HEADER (HTTP_X_FORWARDED_PROTO, https) CSRF_TRUSTED_ORIGINS [https://api.example.com]否则Django会认为请求是HTTP导致is_secure()返回False重定向和CSRF校验各种异常。这属于典型的“Nginx配好了应用层面却不知道自己在HTTPS背后”的乌龙。4.4 Nginx日志与错误排查配置Nginx排错靠日志。默认日志在/var/log/nginx/但容器环境下Nginx是独立容器日志会输出到容器的stdout通过docker logs nginx查看。如果想保留详细日志建议在server块里做配置log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for; access_log /var/log/nginx/api_access.log main; error_log /var/log/nginx/api_error.log warn;$http_x_forwarded_for很有价值尤其是在前面还有CDN或负载均衡器时能记录到真实用户IP。Nginx返回502时error.log会留下“upstream prematurely closed connection”之类的信息光看页面报错根本定位不了问题。5. 完整部署流程与上线实操5.1 本地构建镜像并推送项目开发完成后先在本地把镜像构建出来跑一遍确保没有低级错误docker build -t yourname/myproject-web:1.0.0 .如果本地已经能通过docker run -p 8000:8000 yourname/myproject-web:1.0.0正常访问说明镜像没问题。接下来需要把镜像推送到镜像仓库我常用Docker Hub或阿里云镜像仓库。推送到远程仓库的好处是服务器不需要构建环境直接从仓库拉取镜像即可部署速度更快。docker tag yourname/myproject-web:1.0.0 registry.cn-hangzhou.aliyuncs.com/yournamespace/myproject-web:1.0.0 docker push registry.cn-hangzhou.aliyuncs.com/yournamespace/myproject-web:1.0.0内网部署场景还可以搭一个Harbor或Registry但个人项目没必要搞这么重。注意镜像仓库的凭证不要写在命令行历史里用docker login交互式输入就好。5.2 在服务器上拉取镜像并启动SSH登录服务器进入项目目录拉取代码和配置文件cd /srv/myproject git pull origin main然后修改.env文件里面填好数据库密码、SECRET_KEY等敏感信息。启动前先检查Compose配置是否正确docker compose config这条命令会校验YAML格式和语法有问题会在启动前暴露。接着执行docker compose pull docker compose up -d-d表示后台运行。第一次启动会先拉取基础镜像并构建耐心等镜像下载。启动完确认状态docker compose ps如果显示running并且健康检查通过再用curl看Nginx返回curl -I http://localhost如果看到200说明部署成功。如果返回502按第6节的方法查日志。5.3 数据库迁移与初始化Django项目部署后第一件事就是跑迁移。进入web容器docker compose exec web python manage.py migrate --noinput还有创建管理员docker compose exec web python manage.py createsuperuser如果你是Flask SQLAlchemy可以用相同的思路执行初始化脚本。这里提醒一下不要在Dockerfile里自动执行migrate因为启动时数据库可能还没就绪最好在部署时手动执行或者用部署脚本统一处理。5.4 更新发布的流程与回滚每次发新版本按这个顺序来# 1. 本地构建新镜像并推送 # 2. 服务器上拉取新代码如果配置在项目里 git pull origin main # 3. 重新构建镜像 docker compose build web # 4. 启动新版本 docker compose up -d如果新版本有问题回滚很简单重新指定旧镜像tagdocker compose up -d --no-deps --force-recreate web配合image标签指定旧版本再加--force-recreate强制重建容器。这样做的好处是旧版本不用推倒重来几秒钟就能切回去。为了保险每次部署前备份数据库是值得养成的习惯尤其是涉及数据结构的变更。6. 常见问题与排查技巧实录6.1 502 Bad Gateway与504 Timeout502和504是Nginx无法从上游应用拿到正常响应时最常见的状态码。502说明Nginx连不上后端504说明后端连上了但响应超时。排查步骤先看容器docker compose ps如果web容器退出了看日志docker compose logs web通常会有ModuleNotFoundError或端口监听失败这样的信息。如果容器在运行从Nginx容器内部手动测试docker compose exec nginx curl http://web:8000/health如果返回空或者连接拒绝说明Gunicorn没有启动或绑定了错误的IP。Gunicorn默认绑定127.0.0.1但容器内部外部访问需要通过0.0.0.0所以Dockerfile里的-b 0.0.0.0:8000必须写对。还有一种常见情况web容器还在启动中Nginx已经准备好了导致请求时后端还没就绪。这时可以给depends_on增加service_healthy条件。6.2 静态文件404或样式丢失部署Django后页面能访问但所有静态文件都404通常有两个原因。第一STATIC_ROOT配置不对或没有执行collectstatic。在Docker环境中需要运行docker compose exec web python manage.py collectstatic --noinput第二Nginx的alias路径和挂载卷路径不一致。看第4.1节Nginx通过volumes挂载了static_data:/static那么Nginx配置中的alias /static/实际指向容器内的/static/而Django的静态文件要写到这个共享卷里。在docker-compose中web服务也有static_data:/app/staticfiles所以collectstatic产出的文件会最终落到Nginx可访问的/static。如果你发现刷新页面静态文件还是旧版本那多半是浏览器缓存或Nginx缓存。生产环境可以在静态文件URL后加版本参数比如/static/css/app.css?v20240601或者修改Nginx的expires配置。6.3 数据库连接失败启动后Python应用一直报connection refused检查Compose里的DB_HOST。容器间通信要用db这种服务名而不是localhost或宿主机IP。还有一个细节PostgreSQL默认监听localhost官方镜像通常没问题但如果你自建数据库必须让PostgreSQL监听0.0.0.0以便其他容器访问同时设置强密码和访问权限。另外当数据库容器是首次启动它会初始化数据目录这个过程中健康检查为starting是正常的。应用如果在这个阶段尝试连接会看到连接失败。解决办法是在应用启动脚本里加一个等待循环#!/bin/bash echo Waiting for database... while ! nc -z db 5432; do sleep 1 done exec $或者直接用Python的connect with retry。在线上环境我更推荐用depends_on加上condition: service_healthy这样Compose会在数据库健康检查通过后才启动web容器。6.4 端口被占用与防火墙问题启动Nginx时提示bind() to 0.0.0.0:80 failed说明宿主机80端口已经被占用。可以用ss -lntp查看占用进程。常见的一个坑是systemd自带的一些服务占用了端口比如caddy、apache2或之前的Nginx进程没清理干净。容器模式下确保宿主机没有其他Nginx在跑或者修改Nginx对外映射端口。防火墙忘了放行80/443也是新手常踩的坑表现是服务器本地curl正常但外部浏览器无法访问。用curl -I http://服务器IP从本机检查Nginx再从另外一台机器测试公网访问。如果公网不通依次查云安全组、ufw规则、ECS安全组规则。别漏掉安全组很多云厂商默认只开放22端口。6.5 容器一直自动重启restart: unless-stopped的语义是只要容器异常退出它就会不断重启。如果应用启动即崩溃你会看到容器反复进入Restarting状态。按上面方法查日志即可。但有一种情况进程明明正常运行容器却被杀掉多半是内存溢出。用docker stats查看资源占用如果接近宿主机内存上限增大Gunicorn的max-requests或减少worker数同时检查是不是有内存泄漏。对于长期运行的服务给每个容器设置mem_limit是防止整台服务器被拖垮的有效手段services: web: mem_limit: 1g6.6 时间不同步导致请求签名失败有些Web应用涉及时间戳签名比如对接支付接口或生成JWT。服务器时间漂移会导致签名校验失败。在容器环境里建议在docker-compose中给服务挂载/etc/localtime:/etc/localtime:ro同时宿主机启用NTP时间同步sudo timedatectl set-ntp true sudo timedatectl status如果你的服务涉及跨时区最好在应用层统一使用UTC只在展示层转换本地时间否则各种时间戳问题会让人排查到头秃。6.7 上传文件大小限制Nginx默认允许请求体最大为1MB上传大文件会直接返回413。在Nginx的server或location块中加入client_max_body_size 20m;同时Gunicorn和Django也有对应限制。如果上传超过几十MB建议改走对象存储不要全压在一台小服务器上毕竟带宽和磁盘都会成为瓶颈。6.8 日志排查的组合拳部署问题最忌瞎猜我的排查顺序基本固定下来步骤操作目的1docker compose ps确认容器状态2docker compose logs web --tail 100看应用日志3docker compose logs nginx --tail 100看Nginx日志4curl -I http://localhost确认整体入口5curl http://web:8000/health确认后端内部连通性6docker compose exec web python manage.py checkDjango检查配置这套流程能从入口到应用一层层缩小问题范围。多数情况下问题不是同时出现在多个环节的把位置定位到单个容器之后解决就只是时间问题了。有一点我特别想说部署这事别怕踩坑。我第一次完整部署时光是Docker network配置就折腾了三个小时后来才搞清楚容器名不是IP。但正是这些细节让后面的操作越来越顺手。如果你正在从“本地跑通”走向“上线可访问”尽量在一开始就用Docker Compose把Nginx、Gunicorn、数据库全部编排好哪怕感觉“杀鸡用牛刀”也比以后每次新增服务都要手动处理端口和依赖要轻松得多。这套流程我实际跑了两年多稳定性完全够用。