1. 先定方案为什么我选Docker Nginx而不是裸机部署我负责维护过好几个Python Web项目有一段时间特别头疼代码在本地跑得好好的一到服务器上就各种问题。依赖装不上、Python版本对不上、进程没人管、日志找不到、想回滚上个版本还要靠手工备份……折腾到后面部署变成了全组最不愿意碰的活。后来切到Docker Nginx这套组合才算把这摊事彻底理顺了。先给新手朋友梳理一下裸机部署是在服务器上直接装Python环境把代码放上去用systemd或supervisor拉起进程。这种方式坏就坏在服务器的环境会被项目改造——你今天给A项目装了依赖明天B项目升级就可能导致冲突更别说一台机器上同时跑Python 3.8和3.11这种需求。这就像你在一套房子里住了好几个室友大家共享一个厨房总有人搞乱你的调料。Docker要解决的恰恰是这个问题。它把代码运行环境依赖启动命令整个打包进一个镜像里运行起来就是一个容器。容器之间互相隔离每个项目都有自己的独立房间。镜像一旦构建好在本地能跑丢到服务器上就一定能跑——至少不会再因为环境差异导致在我机器上是好的这种经典命题。那Nginx又是干嘛的如果你的Python应用是Flask或者FastAPI一般会通过uvicorn或gunicorn启动监听某个内部端口。你当然可以让它直接监听80端口暴露到公网但这样等于把应用裸奔在Internet上不支持HTTPS卸载、没有反向代理层、静态文件也要让Python进程去读性能和安全都吃亏。Nginx放在最前面作为唯一的流量入口外部请求先进Nginx由它判断哪些请求交给Python容器处理哪些请求直接读静态文件哪些请求要拦下来。这套架构在热词里也经常出现——nginx反向代理docker安装教程nginx安装说明大部分人走到的路线跟我当初是一样的。你如果也想把自己的Python Web应用正式发布到服务器而不是满足于本地能跑那这套组合无论从学习成本、运维复杂度还是后续扩展性来说都是最值得投资的选择。最终的目标架构可以这样理解用户通过域名访问服务器Nginx在443端口接收HTTPS请求然后把请求转发给内部Docker网络里的应用容器应用容器再按需连数据库和缓存。2. 手写一份生产可用的Dockerfile比想象中多三个细节很多人第一次写Dockerfile简单写两行就完事结果等到构建出来的镜像又大又慢甚至到服务器上跑不起来。我在实践中总结下来一份可靠的Dockerfile至少要处理好基础镜像选型、依赖缓存、非root权限这三件事。2.1 基础镜像选型与Python版本要定的多死我的建议是不要用python:latest老老实实锁定版本号。比如项目用的是Python 3.11就写python:3.11-slim。latest镜像今天拉的可能是3.13半年后再拉变成3.14生产环境没人敢承担这种不确定性。至于slim和alpine大多数人看到alpine镜像体积小就想选它。alpine确实小但它是基于musl libc的很多Python扩展包在它上面没有预编译的wheel需要现场编译而编译就得装gcc、make这些工具。我遇到过一个用Pillow的项目在alpine里构建镜像硬生生花了半个多小时而同样的代码在slim镜像里几分钟完成。这不是说alpine不好而是对一个图省事的Web项目来说slim基于Debian兼容性明显更好体积也比完整版小得多。为了更直观我把常见基础镜像对比如下镜像体积兼容性适用场景python:3.11大约1GB最好需要很多系统依赖时python:3.11-slim中等约150MB好一般Python Web项目推荐python:3.11-alpine小约80MB部分扩展需编译对体积敏感且依赖几乎纯Python时2.2 利用依赖缓存别把代码一口气COPY进去如果你这样写COPY . /app RUN pip install -r requirements.txt一旦代码有任何变动整个COPY .这层缓存就会失效后面的pip install不得不重新执行。这意味着你每次提交代码、重新构建镜像都要把全部依赖再下载安装一遍非常浪费时间。正确的姿势是先只COPY依赖清单文件装完依赖再COPY代码。因为Docker是按层做缓存的只要requirements.txt没变pip install这层就会命中缓存。更进一步如果你用的是新版Docker的BuildKit还可以这样# syntaxdocker/dockerfile:1 FROM python:3.11-slim WORKDIR /app RUN --mounttypecache,target/root/.cache/pip \ pip install --upgrade pip COPY requirements.txt . RUN --mounttypecache,target/root/.cache/pip \ pip install -r requirements.txt COPY . .--mounttypecache会把pip的下载缓存目录挂载到构建过程中首次构建还是要全量下载但第二次、第三次构建就快得多了。我在一个依赖繁多的项目里实测反复迭代代码时构建时间可以从4分钟压到40秒左右这个提升是肉眼可见的。2.3 非root用户、时区与启动命令生产环境里容器内建议用非root账号运行应用降低容器逃逸风险。这个习惯一开始就要养成。配合时区设置我的一份完整Dockerfile长这样FROM python:3.11-slim ENV PYTHONUNBUFFERED1 \ PIP_NO_CACHE_DIR1 \ TZAsia/Shanghai WORKDIR /app RUN apt-get update apt-get install -y --no-install-recommends \ curl \ rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . RUN useradd --create-home appuser chown -R appuser:appuser /app USER appuser EXPOSE 8000 CMD [gunicorn, app:app, --bind, 0.0.0.0:8000, --workers, 3, --timeout, 60]几个容易忽略的点PYTHONUNBUFFERED1保证日志实时打到stdout否则docker logs会看不到输出排查问题非常痛苦。启动命令用gunicorn这类生产级WSGI服务器不要用Flask自带的开发服务器开发服务器既慢又不安全。CMD写成数组形式这是一种exec风格信号能正确传给gunicorn进程容器停止时可以做优雅退出。构建验证很简单docker build -t myapp:v1 .然后用docker run --rm -p 8000:8000 myapp:v1浏览器访问http://服务器IP:8000确认应用能起来。3. 用docker-compose把应用、数据库、缓存一起编排起来当项目只需要跑一个应用容器时docker run还凑合。但现实中的Python Web应用基本都要配MySQL、Redis这些依赖服务。如果全用docker run你光记每个容器的参数就要疯掉更别说处理容器间的网络关系了。docker-compose.yml的核心价值就是让你用一份声明式配置把多个服务、网络、数据卷一次性描述清楚一条命令启动、一条命令停止。我把热词里docker安装mysql失败docker安装mysql8.0并使用这类问题归类为绝大部分不是Docker本身的问题而是没有把MySQL容器化的关键细节处理干净。3.1 一份常见的compose结构长什么样假设我们的应用需要MySQL和Redis那么最小可用的compose文件是这样的version: 3.8 services: app: build: . ports: - 8000:8000 env_file: - .env depends_on: db: condition: service_healthy redis: condition: service_healthy networks: - app-net db: image: mysql:8.0 container_name: myapp_db restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD} MYSQL_DATABASE: ${DB_NAME} MYSQL_USER: ${DB_USER} MYSQL_PASSWORD: ${DB_PASSWORD} volumes: - db_data:/var/lib/mysql healthcheck: test: [CMD, mysqladmin, ping, -h, 127.0.0.1] interval: 5s timeout: 3s retries: 10 networks: - app-net redis: image: redis:7-alpine command: redis-server --appendonly yes volumes: - redis_data:/data healthcheck: test: [CMD, redis-cli, ping] interval: 5s timeout: 3s retries: 10 networks: - app-net volumes: db_data: redis_data: networks: app-net:3.2 三个关键设计healthcheck、数据卷、重启策略先讲healthcheck。用depends_on本身只能决定服务启动的先后顺序但MySQL容器启动不等于就绪——MySQL初始化可能要几十秒。如果没有健康检查可能在MySQL还没准备好时就启动应用造成应用连不上数据库而崩溃。健康检查会定期探测比如mysqladmin ping只有状态变为healthydepends_on里的condition: service_healthy才会放行应用容器。这个设计我强烈建议一上来就写进compose里。再讲数据卷。db_data:/var/lib/mysql这行意味着MySQL的数据会持久化到Docker管理的数据卷中。容器删了数据还在。这是数据库容器和临时容器最本质的区别。我见过有人部署数据库容器没挂持久化卷后来不小心docker compose down把数据全删了那种欲哭无泪的场景我不想再经历第二次。然后是重启策略。restart: unless-stopped表示除非你手动停止否则容器挂了会自动拉起。服务器重启也会跟着起来免去了手工启动的麻烦。3.3 环境变量管理.env文件不是可选项上面配置里出现了大量${...}占位符它们来自compose同目录下的.env文件。我建议把所有密码、密钥、数据库连接信息全部放进去并且这个文件永远不要提交到Git仓库只在服务器上创建和维护。.gitignore里必须加上.env。我见过太多人把数据库密码直接写在代码或compose文件里然后传到GitHub上的等被爬虫扫到就晚了。_password、_secret这类命名方式再怎么强调都不过分。启动全部服务只需要docker compose up -d --build-d后台运行--build在启动前构建最新的应用镜像。查看运行状态用docker compose ps看应用日志用docker compose logs -f app。4. Nginx反向代理把公网流量安全送进你的容器到了这一步你的应用和数据库已经容器化跑起来了。下一步就是把它们暴露出去让用户能用域名访问。我喜欢把Nginx称为整个部署体系的大门安全和性能这块大门做得好不好直接决定系统能扛多久。4.1 安装Nginx与最基础的站点配置无论你的服务器是Ubuntu还是CentOS安装都很简单# Ubuntu/Debian apt update apt install nginx -y # CentOS/RHEL yum install nginx -y装完之后配置文件主要在/etc/nginx/目录下。不同发行版对站点的组织方式略有不同建议把配置写成独立的站点文件而不是直接改nginx.conf主文件。以Debian系为例我会在/etc/nginx/sites-available/下新建一个文件比如叫myapp然后软链接到sites-enabled/。基础的反向代理配置如下server { listen 80; server_name example.com; location / { proxy_pass http://127.0.0.1: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; } }这里的proxy_pass是关键它把Nginx收到的请求原样转发给127.0.0.1:8000——也就是我们前面通过docker run -p 8000:8000或compose里ports: - 8000:8000暴露出来的端口。那四行proxy_set_header也很重要。少了它们你的Python应用通过request.remote_addr拿到的永远都是127.0.0.1也就是Nginx的地址而不是用户的真实IP。日志里全是内网地址排查问题你会疯掉。这四行头信息就是把原始请求的Host、真实IP、转发链路、协议类型告诉后端应用。4.2 location匹配机制真的不用背但要懂优先级热词里出现nginx中location工作流机制可见很多人栽在这里。我尽量用通俗的话讲清楚它的优先级排序从高到低是这样的精确匹配location /api/health前缀匹配加^~一旦命中不再检查正则正则匹配location ~ \.(png|jpg)$普通前缀匹配location /static/最长前缀匹配优先实际配置场景里最常见的组合是把静态文件用普通前缀匹配交给Nginx直接读动态请求用/前缀走反向代理。看这个例子server { listen 80; server_name example.com; root /var/www/myapp; location /static/ { alias /var/www/myapp/static/; expires 7d; access_log off; } location /media/ { alias /var/www/myapp/media/; expires 30d; } location / { proxy_pass http://127.0.0.1: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; } }这样的好处是图片、CSS、JS这些静态文件完全不需要经过Python进程Nginx读文件系统的速度比Python处理HTTP请求快好几个数量级。4.3 WebSocket与SSE别让长连接被Nginx掐断热词里出现web端实时视频web页面pdf打印这类场景说明不少人在做实时功能。如果你的应用用了WebSocket比如实时聊天、视频通信Nginx配置需要额外增加两行location /ws/ { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; }WebSocket的连接升级机制依赖Upgrade和Connection头部Nginx默认不做转发要显式设置。proxy_read_timeout 3600s则避免长时间没有消息的WebSocket连接被Nginx按默认60秒超时掐断。做实时推送、视频流这类功能这两行是保命配置。4.4 Nginx不是只能代理容器其他本地服务也行通过反向代理我们可以让Nginx做多个服务的统一入口。比如服务器上还跑了一个本地的API服务或管理面板我只需要再写一个server块或locationserver { listen 80; server_name admin.example.com; location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $host; } }这和热词里本地虚拟机多端口nginx开发环境多站点自定义域名配置的思路完全一致每个站点绑定独立的server_name和端口Nginx做分发。你甚至可以代理ollama这类本地模型服务给外部调用设个apikey校验再统一走Nginx转发安全性和可维护性都高一个档次。5. 域名、HTTPS证书与上线前的安全加固本地用IP加端口访问没问题正式上线就绕不开域名和HTTPS。看热词里有nginx下载教程web服务器安全这些我发现很多新手部署到拿到IP这一步就觉得完事了其实还有三件大事要做域名解析、证书签发、服务器加固。5.1 域名解析在域名服务商后台加一条A记录把example.com和www.example.com都指向服务器的公网IP。解析生效后在服务器上确认一下ping example.com curl http://example.com如果能看到Nginx的默认欢迎页或你的站点内容说明域名和服务器已经接通。5.2 用certbot自动签发Lets Encrypt证书手动去搞证书签发、安装、续期非常折磨人我强烈推荐certbotapt install certbot python3-certbot-nginx -y certbot --nginx -d example.com -d www.example.comcertbot会自动修改Nginx配置把listen 80改成listen 443 ssl自动配好证书路径还会自动添加80转443的跳转。整个过程大概五分钟。别以为证书签完就一劳永逸了。Lets Encrypt证书有效期只有90天所以要设置自动续期crontab -e # 添加一行每个月跑一次续期检查和nginx重载 0 3 1 * * certbot renew --quiet --deploy-hook systemctl reload nginx--deploy-hook只在证书真正续期成功后才触发nginx重载避免空跑。5.3 服务器防火墙与SSH加固热词里web服务器安全这条很多人以为装了软件就叫安全。在暴露到公网之前先把防火墙规则定清楚ufw default deny incoming ufw allow 22/tcp ufw allow 80/tcp ufw allow 443/tcp ufw enable22端口是SSH登录端口80和443是HTTP/HTTPS入口除此之外的端口一律封锁。有人可能会问8000端口不是应用在跑吗外部为什么要访问8000不需要外部只准走80和443到NginxNginx再把流量转发到8000。8000端口对公网不可见这是好事。SSH层面建议把/etc/ssh/sshd_config里的密码登录关掉改用密钥登录PermitRootLogin no PasswordAuthentication no PubkeyAuthentication yes改完记得systemctl restart sshd。如果你的云服务器提供商有安全组记得在控制台同样只放开80、443和22双保险才踏实。5.4 Django/Flask应用自身的安全配置框架层有两个点别漏掉。以Django为例DEBUG False ALLOWED_HOSTS [example.com, www.example.com]DEBUG False一是避免出错时把完整堆栈打印到页面防止泄露代码路径和敏感信息二是提高性能。ALLOWED_HOSTS则限定只有你的域名才能访问防止别人拿IP直连和伪造Host头。如果你用Flask/FastAPI没有ALLOWED_HOSTS这个概念但可以在Nginx层配合server_name和防火墙规则来达到类似效果。6. 部署过程中最常踩的坑四条完整排查链路这一节是我最想写给你们的。我新手阶段踩过的坑足够填满一份表格但挑出最高频的四类分别讲清楚现象 - 排查链路 - 根因 -解决。6.1 容器起不来Docker启动失败与日志诊断现象docker compose up -d后应用容器状态是Exited或者反复重启。排查链路docker compose ps docker compose logs app看日志是最直接的方式。如果没有日志输出用docker ps -a找到容器ID然后docker inspect 容器ID查看容器退出状态码和最后几条日志。常见根因与解法端口被占用如果你本地已有一个进程占着8000端口容器必然起不来。用ss -lntp | grep 8000看清是谁占着改compose里的端口映射即可。启动命令不对比如CMD写错了路径或者缺少启动依赖的模块。日志会直接告诉你ModuleNotFoundError。数据库连不上这种情况的应用容器会反复重启但容器本身没有报错日志里只会看到连接超时。解决办法是检查compose里depends_on的healthcheck是否配置正确以及数据库连接地址是否正确容器内访问数据库要用服务名db而不是127.0.0.1。这里要强调一个新手最常犯的错误在容器内访问宿主机端口。如果你的数据库跑在宿主机上而应用跑在容器里应用访问数据库应该用宿主机在Docker网络中的IP或host.docker.internal不是127.0.0.1——容器内的127.0.0.1是它自己不是宿主机。6.2 网站返回502Nginx与容器之间的断连排查现象浏览器访问域名Nginx返回502 Bad Gateway。排查链路按顺序执行# 1. 确认后端容器是否正常运行 docker compose ps # 2. 在服务器上直接测试应用端口是否响应 curl -I http://127.0.0.1:8000 # 3. 查看Nginx错误日志 tail -100 /var/log/nginx/error.log如果第2步curl正常说明应用没死如果curl报错说明应用容器活着但监听端口不对或者监听地址绑定了127.0.0.1而不是0.0.0.0。这里有个常见误会gunicorn的--bind如果写127.0.0.1:8000它只接受来自同一网络命名空间的请求外部Docker网络转发过来的请求就进不来了。所以容器里必须绑0.0.0.0:8000。如果第2步正常但第3步Nginx报connect() failed (111: Connection refused)说明Nginx的proxy_pass端口填错或写成了不存在的服务。检查Nginx配置里的端口是否和容器暴露端口一致。6.3 上传文件报413调整Nginx请求体大小限制现象上传一个稍大点的文件页面直接报413 Request Entity Too Large。根因Nginx默认client_max_body_size是1MB超过这个大小的请求体会被拒绝。解决在server块里加一行client_max_body_size 50m;这个值按业务需求设一般图片类项目设10m~20m遇到底层上传大文件场景就设50m。千万不要无脑设成1000m太大的请求体对服务器内存和带宽都是压力。6.4 静态文件404或缓存不生效alias路径与权限检查现象页面样式丢失、图片打不开或者改了文件但页面还是旧样子。排查链路先明确静态文件的物理路径。比如项目里静态文件放在/var/www/myapp/static/Nginx配置里的alias必须指向真实存在的目录。路径写错最直观的现象就是404。权限问题也很常见。Nginx的worker进程以www-data用户运行如果静态目录的权限是700且所有者是rootNginx读不了。把目录设置为755或用chown -R www-data:www-data指定给Nginx用户。缓存不生效则要看expires配置。expires 7d意味着浏览器会缓存该静态文件7天这在发布新版本时会导致用户还在看旧文件。解决思路是给静态文件名加版本号或哈希值如main.1a2b3c.css文件内容一变文件名就变浏览器自然会重新拉取。6.5 Docker Desktop虚拟化报错Windows下的一个特殊坑热词里有一条virtualization support not detected docker desktop failed to start这是Windows环境下的老问题。在Windows上用Docker Desktop本质是借助Hyper-V或WSL2运行Linux虚拟机。报这个错通常是因为CPU虚拟化没在BIOS中开启Intel VT-x / AMD-VWindows的Hyper-V功能没打开WSL2没有正确启用解法在BIOS里把虚拟化打开然后在PowerShell管理员权限执行dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all或者改用WSL2wsl --install装完重启再启动Docker Desktop一般就能正常了。这个问题在服务器部署场景里其实不会遇到Linux服务器没有这个限制但如果你是先在Windows上做本地模拟那这个坑早晚会撞上。最后分享几个一直受用的习惯踩了这么多坑之后我自己的日常操作已经固化成几个习惯送给你做参考。看日志永远是第一动作。docker compose logs -f app、tail -f /var/log/nginx/error.log这两条命令基本解决了90%的故障定位。别去猜原因直接看日志日志会告诉你答案。发布新版本的时候我习惯用一个简单的脚本完成三步git pull docker compose build docker compose up -d这套流程简洁可靠配合镜像tag管理想回滚就重新构建旧tag即可。Backup这块数据库容器一定要做定期备份把数据卷里的数据dump到宿主机之外我吃过亏才知道备份不是可选项。安全始终是一个持续过程不是上线那天配置完就结束了。依赖要定期升级Nginx和系统安全补丁要勤更新.env文件要定期检查权限。保持敬畏才能减少半夜被报警短信叫醒的次数。