企业官网建设流程全解析

1. 部署前先想清楚：为什么非要用 Docker + Nginx

1.1 这套组合到底解决了什么问题

Python Web 应用部署，最老派的玩法是直接在一台服务器上装 Python 环境、pip install 依赖、然后用 systemd 挂一个 Gunicorn 进程。这套玩法在小项目上完全够用，但一旦环境复杂起来就非常难受。换一台机器、换一个 Python 版本、换一次操作系统，所有依赖都要重新折腾一遍，经常是开发环境跑得好好的，一到生产就各种诡异报错。

Docker 解决的是"环境一致"的问题。把 Python 版本、系统依赖、pip 安装的包、启动命令全部写进 Dockerfile，构建成镜像后，镜像到哪儿跑起来都是一样的。它本质上就是把"应用 + 运行时 + 依赖"整个打包带走。你不需要再去纠结服务器上到底是 Ubuntu 还是 Debian，Python 是 3.10 还是 3.11，因为镜像里已经写死了。

Nginx 解决的则是"对外服务"的问题。Python 应用本身一般跑在 Gunicorn 这类 WSGI 服务器上，监听内网端口比如 8000。你不能直接把应用裸奔着暴露到公网：一方面 WSGI 服务器直接面对公网流量容易出问题，另一方面端口管理、HTTPS 证书、静态资源分发这些事需要更专业的工具。Nginx 作为反向代理，把公网请求收进来，该转给 Gunicorn 的转给 Gunicorn，该直接回静态文件的直接回，各司其职。

我见过不少人一上来就纠结"要不要用 Docker"，其实这个问题应该反过来问：你是不是经常遇到环境不一致、依赖冲突、部署回滚困难？如果是，答案就很简单，用。如果你只想在一台固定的服务器上长期跑一个简单项目，也不打算迁移，那不用也行，但一旦项目生长起来，该补的课迟早要补上。

1.2 什么时候不需要这套组合，什么时候必须用

先泼一盆冷水：不是任何项目都非 Docker + Nginx 不可。

适合简化部署的场景有三个特征：项目是单一 Flask/Django 应用、流量很小、发布频率很低。这种场景直接用 systemd + Gunicorn 就能撑住。我最初几个项目就是这么跑的，写一个 Systemd Unit 文件，开个三五个 worker，管理者后台和定时任务，也能稳定跑几个月。

但一旦出现以下信号之一，就说明该切换到容器化方案了：

• 依赖里有编译型包（pandas、numpy、pydantic 这类），在开发机装得好好的，服务器上死活装不上，因为编译工具链或 Python 版本不一致
• 需要同时部署 Web 应用、Redis、MySQL、Celery worker 等多个服务，手动管理互相打架
• 想在一台服务器上跑多个项目，端口冲突、Python 版本冲突、依赖互相污染
• 需要频繁发布，希望回滚像"切换镜像标签"一样简单

至于 Nginx，但凡应用要暴露到公网、要上 HTTPS、要做静态资源缓存，它就绕不开。我也见过直接把 Flask 跑在公网 5000 端口上的做法，内网测试无所谓，公网这么干基本就是等着被扫描、被薅流量、被漏洞打穿。所以我的结论是：Docker 负责让应用"走哪儿都一样"，Nginx 负责让应用"对公网体面"，两个配合起来，部署从"玄学"变成"流水线"。

2. Python Web 应用的 Docker 化改造

2.1 一个能直接跑的 Dockerfile 长什么样

Dockerfile 是整个容器化的核心。下面这个例子以 Flask + Gunicorn 为例，换成 Django 也差不多，只是 CMD 里的 Gunicorn 参数要加项目配置：

FROM python:3.11-slim WORKDIR /app 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 . . EXPOSE 8000 CMD ["gunicorn", "app:app", "-b", "0.0.0.0:8000", "-w", "4", "--timeout", "60"]

逐个说几个关键点：

• 基础镜像选 slim 版本而不是完整版。完整镜像带一堆用不到的开发工具，体积差出一倍不止。等你后面用上多阶段构建，体积还能进一步压缩。
• apt-get 装 build-essential 是因为很多依赖包安装时需要现场编译。如果确定项目不需要编译任何 C 扩展，可以删掉这行，镜像体积更小。
• pip install 加 --no-cache-dir，避免把 pip 的下载缓存打进镜像，同样是体积优化。
• CMD 用 gunicorn，别用 Flask 自带的开发服务器 python app.py。Flask 内置服务器是开发用的，性能差、默认单进程、也没有并发防护能力，拿到生产环境就是事故隐患。

写完之后在项目根目录构建：

docker build -t my-web-app:latest .

构建成功后先本地跑一遍验证：

docker run -p 8000:8000 my-web-app:latest

curl 一下 http://localhost:8000 能正常返回页面，说明镜像本身没有基础问题。这一步做扎实了，后面上服务器基本不会出幺蛾子。

2.2 requirements.txt 的版本锁定与依赖治理

部署踩坑的重灾区是 requirements.txt 里没锁版本。比如你写的是 Flask>=2.0，一个月后 Flask 发新版本，pip 在构建镜像时解析到最新版，行为变了，应用就炸了。我的做法是在开发环境生成一份锁定的完整清单，并且只装项目真正用到的顶层包，不要图省事一把梭。

pip freeze > requirements.txt

要注意 pip freeze 会把所有隐式依赖也打进去。比如手动装了 flask，它依赖 click、jinja2、werkzeug，freeze 会把它们全部列出来。这其实是好事，构建镜像时只安装一遍，版本和开发环境完全一致，最稳妥。缺点是一堆带 == 的版本号看着不美观，但"丑"换"稳"是值得的。

Django 项目格外注意一点：不要在生产构建镜像时跑数据库迁移。镜像应该只负责"打包代码和依赖"，迁移这种依赖数据库状态的运行时动作，应该在容器启动后或发布流程里单独执行，否则很容易出现新版本代码配旧数据库 schema 的尴尬状态。

2.3 多阶段构建：把镜像从 1G 压到 200M

镜像体积本地玩可能没人在意，传服务器和镜像仓库时就显形了。我见过一个 Django 项目直接 pip 装了一堆东西，镜像打到 1.5G，每次发布光传镜像就等十分钟，非常难受。

多阶段构建的原理很好理解：先在一个"工具齐全"的镜像里编译依赖，最后只把产物拷进一个干净的"精简"镜像里。中间用的编译工具不会残留到最终产物里：

# 阶段一：构建依赖 FROM python:3.11-slim AS builder WORKDIR /app 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 wheel --no-cache-dir --wheel-dir /app/wheels -r requirements.txt # 阶段二：运行镜像 FROM python:3.11-slim WORKDIR /app COPY --from=builder /app/wheels /app/wheels COPY --from=builder /usr/lib/x86_64-linux-gnu/libpq.so* /usr/lib/x86_64-linux-gnu/ RUN pip install --no-cache-dir /app/wheels/* && rm -rf /app/wheels COPY . . EXPOSE 8000 CMD ["gunicorn", "app:app", "-b", "0.0.0.0:8000", "-w", "4", "--timeout", "60"]

这个写法里，pip wheel 先把依赖批量打成 wheel 包，第二阶段直接安装打包好的 wheel，不需要任何编译工具，最终镜像里自然也不会有 gcc、make 这类体积大户。实测下来，Django + 常用依赖的镜像可以从 1G 级别降到 200M 左右。

注意：如果你的服务器是 ARM 架构（部分云主机、开发板），COPY libpq 那行的路径要做调整。在苹果芯片的 Mac 上构建镜像时默认会带 amd64 和 arm64 两个架构层，传到服务器跑最省事的做法是构建时指定 --platform linux/amd64，避免架构不匹配导致的诡异行为。

3. Nginx 反向代理与静态资源分发

3.1 最小可用的反向代理配置

Nginx 在这套架构里扮演"门口接待员"。它监听 80 端口，所有外部请求先到它这里，再由它按规则转给后端容器或静态文件目录。最基础的一份配置长这样：

server { listen 80; server_name example.com www.example.com; client_max_body_size 50m; location /static/ { alias /var/www/myapp/static/; expires 30d; add_header Cache-Control "public, no-transform"; } location /media/ { alias /var/www/myapp/media/; } 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; } }

几个配置项逐个解释：

• server_name 用来区分同机多站。多个域名挂一台服务器时，Nginx 就是靠它做"虚拟主机"分流。
• client_max_body_size 是上传体积上限。不配置默认只有 1M，用户传图传附件直接 413。
• 静态文件 alias 指向容器外的目录，Nginx 直接读磁盘文件，不经过 Python 进程，速度飞快。

代理头信息非常重要。Gunicorn 和后端应用收到的是 Nginx 转来的请求，不传 X-Forwarded-For，后端日志看不到真实用户 IP；不传 X-Forwarded-Proto，Django 的 HTTPS 判断会出错，生成 URL 全变成 http 前缀，跳转和回调全乱套。

3.2 静态文件：放容器里还是放宿主机

这是新手最容易纠结的问题。我的建议分三类处理：

第一类是项目代码里自带的 static 资源，比如 CSS、JS、图片。最省心的方式是构建镜像时 COPY 进去，再用 Docker volume 挂载到宿主机目录，Nginx 的 alias 指向这个目录。这样发版时静态文件跟着代码走，服务器上不用手动同步。

第二类是用户上传的 media 文件。这类必须挂到宿主机目录，否则容器重启后文件全丢。Docker 容器是无状态的，容器可写层里的内容在容器销毁后不复存在。很多人上传的用户头像重启一次全没了，原因就是写在了容器可写层里。compose 里这样挂载：

services: web: image: my-web-app:latest volumes: - /data/myapp/media:/app/media

宿主机 /data/myapp/media 与容器 /app/media 打通，Nginx 对应位置：

location /media/ { alias /data/myapp/media/; }

第三类是动态生成的临时文件，比如报表 PDF、缩略图。建议由后端写到共享目录，Nginx 读取，并且定期清理，防止磁盘被撑满。

3.3 Nginx 的经典坑：SSL 证书替换不生效

热词里有一条"nginx替换ssl证书不生效"，这个我到现场排查过多回，也自己踩过。把新证书文件覆盖到证书路径，nginx -t 测试通过，systemctl reload 也执行了，但浏览器拿到的还是旧证书。

原因大概率是 Nginx 配置里的证书路径没变，文件名也没变，覆盖文件后 worker 进程仍然持有旧文件的句柄。简单说，磁盘上的文件换了，内存里被 worker 加载的证书还是旧的，reload 不一定刷新到这个状态。

解决思路有三条：

• 把配置改成指向新文件名（比如 fullchain_new.pem），不同文件名会强制 Nginx 重新加载完整配置。
• 替换证书后用 nginx -s reload，有的场景还需要重启整个 Nginx 进程才能彻底生效。
• 更规范的做法是用 symlink 指向当前版本的证书文件，替换时换 symlink 指向，而不是直接覆盖文件内容。

ln -s /etc/letsencrypt/live/example.com/fullchain.pem /etc/nginx/certs/fullchain.pem

换证书时只更新 symlink 指向再 reload，就不会出现"看似替换了但没生效"的问题。

经验之谈：涉及 HTTPS 的任何操作，先跑 nginx -t 验证配置再做 reload。强制 reload 瞬间配置有误，可能导致服务中断。

4. 用 docker-compose 编排整套服务

4.1 为什么需要一个编排文件

单容器部署简单，但现实里很少只有一个容器。Web 应用 + MySQL + Redis + Celery worker，几个服务互相依赖。手动一个个 docker run 太痛苦，也没法把整套环境配置沉淀成文件。docker-compose.yml 解决的就是这个问题：一份 YAML 描述所有服务、网络、数据卷、环境变量，一条命令拉起整套，一条命令拆掉。

一个常见的 compose 文件：

version: "3.8" services: web: build: . container_name: myapp_web restart: always ports: - "8000:8000" environment: - DB_HOST=db - DB_PORT=5432 - REDIS_HOST=redis depends_on: - db - redis volumes: - /data/myapp/media:/app/media db: image: mysql:8.0 restart: always environment: MYSQL_ROOT_PASSWORD: "your_password" MYSQL_DATABASE: myapp MYSQL_USER: myapp MYSQL_PASSWORD: "your_password" volumes: - db_data:/var/lib/mysql ports: - "3306:3306" redis: image: redis:7-alpine restart: always command: ["redis-server", "--appendonly", "yes"] volumes: - redis_data:/data volumes: db_data: redis_data:

两个关键细节：

• restart: always 保证服务崩溃或服务器重启后自动拉起，生产环境必备。
• depends_on 只控制启动顺序，不保证数据库已经完全就绪。Python 应用启动时连不上 MySQL，需要在代码里做重试，或者配合健康检查。

4.2 环境变量与数据卷的正确用法

把数据库密码、密钥直接写进 compose 文件，等于把秘密贴在门框上。更稳的做法是用 .env 文件：

services: db: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}

项目目录放一个 .env 文件，docker compose 读取时会自动加载。注意 .env 要写进 .gitignore，千万不能提交到仓库。这个坑我见过不止一次，数据库密码被人扫到，直接把服务器薅成矿机。

数据卷这块重点说持久化。MySQL、Redis 这类有状态服务，数据目录必须挂载到 volume 或宿主机目录，否则容器销毁数据就没了。上面配置里的 db_data 和 redis_data 是命名卷，docker compose down 不会删除它们，服务重建后数据还在。用宿主机目录还是命名卷？我的习惯是数据库用命名卷，便于隔离管理；用户上传的媒体文件用宿主机目录，方便备份和 Nginx 直读。

4.3 日志管理的血泪经验

容器日志默认写到宿主机的 JSON 文件里，时间长了能把磁盘塞满。我经历过磁盘被日志写满导致整个服务器卡死的深夜，从此所有 compose 服务都配置日志轮转：

services: web: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

单份日志超过 10M 自动切新文件，最多保留 3 份。配合 cron 任务定期清理历史镜像和未使用卷，磁盘问题基本能杜绝。

5. 从零到上线的完整部署流程

5.1 服务器基础准备

服务器到手后，第一步不是装 Docker，而是做基础安全配置：

• 禁用 root 密码登录，改用密钥登录
• 修改 SSH 默认端口
• 安装 fail2ban 防爆破
• 防火墙只开放 80、443、SSH 端口

这些完成后，再装 Docker：

curl -fsSL https://get.docker.com | sh

装完执行：

sudo systemctl enable docker sudo systemctl start docker

顺手把当前用户加入 docker 组，避免每次敲 sudo：

sudo usermod -aG docker $USER

然后重新登录。Docker 装好后，把项目放到服务器，两种常用方式：git 拉代码再构建镜像，或者直接把项目目录打包传上去。我强烈推荐 git 方式，发布流程可追溯、可回滚。手动打包传文件，第二天你自己都不知道服务器上跑的是哪个版本。

注意：官方安装脚本在某些网络受限环境会失败。如果遇到，改用包管理器安装 docker.io，或者配置镜像加速源，别在官方脚本上硬磕。

5.2 构建镜像与启动服务

假设项目已经在服务器 /opt/myapp 下：

cd /opt/myapp docker compose build docker compose up -d

首次构建比较慢，之后有层缓存会快很多。但需要注意，docker compose build 的缓存命中率取决于 Dockerfile 里 COPY 的顺序。经验是 COPY requirements.txt 放在 COPY . 之前，这样只有依赖文件变化才会重装 pip，纯代码变更走的是后面几层，构建秒级完成。

启动后检查：

docker compose ps

服务是 up 状态后，在宿主机上 curl 容器端口：

curl -I http://127.0.0.1:8000

能收到响应，说明应用已就绪。此时 Nginx 的 proxy_pass 指向 http://127.0.0.1:8000，外部流量从 Nginx 进入。

5.3 Nginx 配置与接管公网流量

我的习惯是 Nginx 直接装在宿主机，不套容器。容器跑 Nginx 虽然也可以，但宿主机安装更省心，维护也更直观。安装、配置、重载三步：

apt update && apt install -y nginx

vim /etc/nginx/sites-available/myapp

nginx -t systemctl reload nginx

写配置时 server_name 改成你的实际域名。第一步先 HTTP 跑通，再接入 HTTPS。不要一上来就同时配证书，出了问题排查难度翻倍。

接 HTTPS 时建议直接用 certbot 之类的自动化工具签发证书，并把续期做成定时任务。证书续期脚本跑完后自动 reload Nginx 即可。自动续期这里有个容易忽略的点：如果证书文件放在 Docker 卷目录里，续期后容器里的 Nginx 不一定能感知到，需要把证书目录挂载进容器或者用宿主机 Nginx。

5.4 发布流程固化

跑过几次手动部署后，建议把流程固化成脚本：

1. 代码推送到仓库
2. 服务器上 git pull
3. docker compose build
4. docker compose down && docker compose up -d
5. 请求健康检查接口确认

回滚也很简单：新镜像有问题，把 compose 里 image 标签指回上一个版本重新 up。

docker images | grep myapp

看历史镜像，挑上一次正常的 tag 回滚。我的习惯是每次构建打清晰 tag，比如 myapp:20250217_v1.2，不用 latest。latest 飘忽不定，出问题时根本不知道回滚到哪个版本。

6. 常见问题与排查技巧实录

6.1 Gunicorn worker 数量怎么定

这个有参考公式，不是随手填。Gunicorn 官方推荐 (2 x CPU 核心数) + 1。但实际操作中，如果应用是 CPU 密集型、重度依赖 Python 的 GIL，这个公式只能当起点，还是要压测后调整。

我的做法是：在一台 2 核服务器上先开 4 个 worker，然后用 wrk 或 ab 简单压一下，观察 CPU、内存和响应时间。如果 CPU 没打满但响应已经变慢，说明代码里有太多同步阻塞，加 worker 救不了，得从代码层面优化。如果 CPU 打满且响应变差，先考虑加配置或加机器。

Gunicorn 的 timeout 参数也值得注意。默认 30 秒，如果应用里有导出文件、调外部 API 这类耗时操作，容易触发 worker 超时被杀。调高到 60 或 120 能避免误杀，但调太高也会把慢接口的问题藏住。我的习惯是调到 60，然后持续观察日志里的超时记录。

6.2 容器网络与端口冲突排查

场景：Nginx 要转发到容器端口，但容器启动后宿主机 curl 不通。先检查一件事：

docker ps

看端口映射是否生效。如果容器用了 --network host，它直接共享宿主机网络，Gunicorn 监听 0.0.0.0:8000 即可，Nginx 直接转发到该端口。如果是默认 bridge 网络，就需要 -p 8000:8000 做端口映射。

另一个常见问题是在 Windows/Mac 上用 Docker Desktop 做端口映射，形态和 Linux 上完全不同。Docker Desktop 的虚拟化机制决定了 127.0.0.1:8000 不一定能直接访问容器，需要检查 docker desktop 的网络配置。这也是我建议生产环境直接上 Linux 的原因之一：部署行为最接近文档描述，少一层抽象。

6.3 数据库连不上、容器退出这类"基本功"排查

我把这类问题整理成速查表：

很多问题本质上都是"没想清楚容器生命周期"或者"配置不一致"。排查时按"进程在不在 - 端口通不通 - 环境变量对不对 - 数据是否在卷上"的顺序推进，基本能定位九成问题。

6.4 Docker Desktop 与 Linux 服务器的行为差异

热词里有"docker desktop 安装教程"，说明很多人在本机折腾 Docker。我多说一句：Docker Desktop 在 Windows/Mac 上本质是跑在一个轻量虚拟机里，文件挂载、端口映射、网络模式都有额外一层转换。本机能跑通不代表 Linux 服务器上一定能直接跑通。

典型的差异包括：文件路径大小写敏感、挂载目录权限不同、容器内文件变化在宿主机不一定实时可见。我的建议是：本机 Docker Desktop 只用来开发调试，最终部署验证一定要在 Linux 环境做一遍，哪怕用一台低配 VPS 跑通再交付生产。

7. 性能优化与安全加固

7.1 静态资源缓存与压缩

前面提的 expires 和 Cache-Control 是第一步。生产环境建议打开 gzip：

gzip on; gzip_vary on; gzip_comp_level 5; gzip_types text/plain text/css application/json application/javascript application/xml image/svg+xml;

开启后，CSS/JS/JSON 体积能减少 60% 以上。但注意别把图片也送进 gzip，JPEG/PNG 本身已经压缩过，再压只能说浪费时间。压缩级别也别调太高，实测 gzip_comp_level 5 和 9 的压缩收益差距很小，但 CPU 开销差距明显，5 是性价比较优的选择。

7.2 容器安全加固的几条基线

安全不是保证绝对，但几条基线一定要做：

• 所有业务容器不要开启特权模式
• 数据库端口不要暴露到公网，只在容器内部网络互访。compose 里把 db 的 ports 删掉，只保留内部网络访问即可
• 环境变量里不存明文敏感信息，配合 .env 或密钥管理工具
• 容器进程用非 root 用户运行，Dockerfile 里加 USER 指令
• 定期更新基础镜像，基础镜像里的系统库同样存在漏洞

Dockerfile 里加这一小段，收益很高：

RUN groupadd -r app && useradd -r -g app app USER app

别小看这一行。容器被攻破后，如果是 root 权限，攻击者几乎可以直接控制宿主机；如果是普通应用用户，操作空间小得多。这个成本极低的操作，能挡掉相当一部分自动化的横向渗透。

7.3 健康检查与监控的起步配置

部署上线只是开始，后续维护才是日常。我强烈建议至少做两件低成本的事：

给容器加 HEALTHCHECK。compose 启动时没有健康检查，容器内部进程虽然活着但可能已经无响应，Docker 不会主动重启它。在 Dockerfile 里加：

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ CMD curl -f http://localhost:8000/health || exit 1

前提是应用里有对应的 /health 端点。这个端点平时没人访问，但关键时刻能自动触发重启，相当于给服务上了一道保险。

日志集中处理方面，至少把 Docker 日志输出到宿主机目录，方便 grep 排查。服务多起来后，再考虑接入集中式日志系统。别等到出问题时才发现日志找不着了。

7.4 进阶：多站点与开发环境的 Nginx 配置

热词里提到"本地 + 虚拟机 多端口 nginx 开发环境多站点自定义域名配置"，这个场景我也经常用。开发阶段一台机器上跑多个项目，靠端口区分很混乱，不如用自定义域名区分。方法是在 /etc/hosts 里加映射：

127.0.0.1 project1.local project2.local

然后 Nginx 里建两个 server 块：

server { listen 80; server_name project1.local; location / { proxy_pass http://127.0.0.1:8001; } } server { listen 80; server_name project2.local; location / { proxy_pass http://127.0.0.1:8002; } }

开发体验直接上一个台阶：不再需要记端口，不同项目用不同域名访问，配置清晰，互不干扰。生产环境的多个站点也是同一套逻辑，只是把 server_name 换成真实域名，把 proxy_pass 指向对应容器或进程即可。

我自己在部署这条路上踩过的坑，很多都是"觉得懂了，一动手就翻车"。Docker + Nginx 这套组合本身不难，难的是把每个环节的小细节都吃透。比如容器无状态导致文件丢失、证书替换不生效、日志撑爆磁盘，这些坑一次两次踩下来就知道怎么回事了。希望这篇记录能让你少走些弯路，把自己的 Python 应用稳稳当当地跑起来。