Python Web应用容器化部署实战：Docker + Nginx 从入门到上线-迪斯科星球

我在企业里做过不少 Python Web 项目的上线部署，从最早直接拿python3 manage.py runserver顶着跑，到后来用 systemd、Gunicorn、Nginx 手动搭环境，再到最近两年全面切到 Docker + Nginx 这套方案。中间踩过的坑加起来，能写一本小册子。这篇就结合我实际部署的经验，把"Python Web 应用容器化 + Nginx 反向代理"这条路从头到尾捋一遍。

这篇文章适合谁看？两类人。一类是刚接触云服务器、第一次要把自己写的 Flask / Django / FastAPI 项目从"本机能跑"变成"服务器上稳定跑"，另一类是已经用 Docker 部署过简单服务、但没搞明白 Nginx 到底在里面扮演什么角色、以及容器间网络该怎么配的开发者。不管你是哪类，读完应该都能照着操作，把一台干净的服务器变成一个能扛住真实流量的 Python Web 应用节点。

1. 为什么是 Docker + Nginx？这套组合到底解决了什么问题

先说结论：Docker 解决的是"应用环境一致性"和"进程托管"问题，Nginx 解决的是"外部流量接入"和"静态资源高效分发"问题。两者各管一段，配合起来刚刚好。

1.1 服务器上部署 Python Web 的三种主流姿势对比

先说第一种，也是不少人刚开始用的方式——直接在你的云服务器上装 Python 环境、用虚拟环境装依赖、再用 systemd 托管 Gunicorn / uWSGI。这套方案的优点是直观、排查问题简单，但缺点很致命——环境隔离差。你在这台服务器上还要跑 Redis、跑数据库、跑其他任务，Python 依赖一旦互相冲突，处理起来就是一场灾难。而且换一台新服务器，环境配置要重来一遍。

第二种是直接上 Docker Compose，把 Web 应用、数据库、缓存全部容器化。这也是我目前生产环境在用的方式，它最核心的价值是可复现性——你本地能跑，服务器上就一定能跑，因为整个应用运行环境（Python 版本、系统依赖、环境变量）都封在了镜像里。同时，多服务之间的启动顺序、网络连通性也能交给 Compose 编排管理。

第三种是把 Kubernetes 也拉进来，适合多节点集群、需要自动扩缩容的场景。但说实话，大部分 Python Web 项目的流量规模，一台 4C8G 的服务器足够了，直接上 K8s 反而复杂度爆炸，不适合作为团队或个人首个上线方案。

至于 Nginx，它在整个链路中做得事情其实不像名字看起来那么简单。很多初学者会问，Nginx 不是应该处理静态文件吗？为什么我动态请求也要走它？这里面有一个核心的架构认知：

Python 的 WSGI 服务器（Gunicorn / uWSGI / Uvicorn）不应该直接暴露给公网。

原因有三点：一是它们对恶意请求的防护能力很弱，比如慢速连接攻击、超大 Header 请求等；二是它们不擅长处理静态资源，让 Gunicorn 去返回图片和 CSS，纯属浪费 CPU；三是 SSL 证书配置、HTTP/2 支持、请求体大小限制这些 Web 服务器层面的能力，Nginx 天然就比 Gunicorn 成熟得多。所以标准生产架构是：外部请求 → Nginx（监听 80/443）→ 反向代理到容器内部的 Gunicorn 端口（比如 8000）。

1.2 Docker 部署架构的基本单元拆解

我常用的 Python Web 应用 Docker 部署架构，可以拆成这几个部分来理解：

应用容器：你写的业务代码，配合 Gunicorn / Uvicorn 启动，监听容器内的 8000 端口，对外不暴露端口到宿主机。
数据库容器：PostgreSQL / MySQL，数据目录通过 volume 持久化存到宿主机磁盘。
缓存容器：Redis，如果 Web 应用有会话、缓存队列需求就用上。
Nginx 容器：作为整个架构的流量入口，监听宿主机的 80 / 443 端口，把请求转发到应用容器内部端口。
构建上下文：前端构建产物（若有）、Python 依赖、配置文件等，通过 Dockerfile 或者 bind mount 传入容器。

这里要特别强调一个设计原则：不要把数据库和 Web 应用装在同一个容器里。数据库有自己的数据持久化需求、备份机制和故障恢复逻辑，跟无状态的 Web 应用容器混在一起，不管是容器升级还是数据恢复，都会非常被动。

1.3 部署流程的全景图

我实际用的部署流程大致是这样一条链：

本地开发、提交代码到 Git 仓库（包括 Dockerfile 和 docker-compose.yml）。
登录到服务器，拉取代码。
构建镜像并启动容器：docker compose up -d --build。
Nginx 容器通过 Docker 内部网络解析应用容器名，完成反向代理。
修改 DNS 解析到服务器 IP，访问域名验证。
后续升级就是"拉代码 + 重建容器"，整个过程可以控制在几分钟内。

下面我从环境搭建开始，一步步往下讲。

2. 服务器环境准备与 Docker 安装——最容易忽略的细节

很多教程上来就直接写 Dockerfile，把环境准备一笔带过。但根据我的实际经验，环境准备阶段有几个点没做好，后面排查问题会特别头痛。

2.1 服务器选型与系统镜像选择

部署 Python Web 应用，服务器配置不需要太高。一个基础配置是 1 核 2G 内存跑小应用，我个人更建议至少 2 核 4G，因为 Docker 本身要占一点内存，Gunicorn 多 worker 模式 + 数据库一起跑，2G 内存会比较紧凑。

系统镜像，我目前在用 Ubuntu 22.04 LTS。选择它的原因：一是 Docker 官方对 Ubuntu 的支持最完善、兼容性问题最少；二是社区资料多，遇到问题搜解决方案最容易；三是 LTS 版本有长期维护支持，不用频繁操心系统升级。CentOS 曾经也是很多人首选，但现在维护周期变了，新项目我都不太推荐再用了。

2.2 用官方脚本安装 Docker 并解决权限问题

在 Ubuntu 上安装 Docker 最省事的方式就是用官方安装脚本。这里贴一下我实际的执行过程：

# 更新系统基础包 sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release # 安装 Docker 官方脚本 curl -fsSL https://get.docker.com | bash -s docker # 查看安装版本，确认安装成功 docker --version # 安装 docker compose 插件 sudo apt install -y docker-compose-plugin # 验证 compose 版本 docker compose version

这里有一个细节很多人踩坑：执行docker ps的时候会遇到 permission denied，这是因为当前用户不在 docker 用户组里。用 root 身份或者加 sudo 当然能跑，但对后续自动化部署不友好。正确的做法是把当前用户加入 docker 组：

sudo usermod -aG docker $USER # 重新登录 shell 或者执行以下命令使组权限生效 newgrp docker

还有一点要提醒，虽然 Docker 容器本身做了隔离，但如果容器配置不当，容器里的 root 用户确实可能影响宿主机。所以只在需要的时候给容器加--privileged权限，我在生产环境里基本不用这个参数。

2.3 Dockerfile 与 Compose 文件目录规划

我强烈建议在项目根目录下直接把 Dockerfile 和 docker-compose.yml 建好，这样整个部署配置和业务代码放在一起，版本管理也是统一的。推荐的目录结构大致如下：

my_python_project/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口文件为例 │ ├── config.py │ └── routers/ ├── requirements.txt ├── Dockerfile ├── docker-compose.yml ├── nginx/ │ └── conf.d/ │ └── default.conf └── .env.example # 环境变量模板

这个结构同时兼顾了构建上下文、Nginx 配置挂载和环境变量管理，后面你会看到它怎么配合工作。

3. 编写一份能直接上生产的 Dockerfile——多阶段构建与依赖缓存技巧

Dockerfile 是整个容器化部署的核心，它的编写质量直接影响镜像大小、构建速度和运行效率。我见过不少项目把 Dockerfile 写得极其随意——pip install直接全量拷贝代码再装依赖，镜像体积直接奔着 1GB 就去了。下面给你看一份我实际在用的 Dockerfile，然后拆开讲每个关键决策背后的原因。

3.1 生产环境 Dockerfile 的参考模板

假设这是一个 FastAPI 项目：

# 阶段一：依赖解析与构建环境 FROM python:3.11-slim as builder WORKDIR /app # 先拷贝依赖文件，这一步是为了利用 Docker 缓存层 COPY requirements.txt . RUN pip install --no-cache-dir --prefix=/install -r requirements.txt # 阶段二：精简运行环境 FROM python:3.11-slim RUN useradd --create-home appuser WORKDIR /app COPY --from=builder /install /usr/local # 将项目代码拷入容器 COPY ./app ./app # 切换普通用户运行，降低安全风险 USER appuser EXPOSE 8000 CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000", "--workers", "3"]

这里有几个关键决策值得解释：

第一，为什么用 python:3.11-slim 而不是 python:3.11？slim 版本是基于 Debian 的精简版，去了大量不必要的系统包和文档，体积能小不少。但它仍然保留了 curl、gnupg 等基础工具，用来排查容器问题够用了。python:alpine 更小，但 Alpine 用了 musl libc，和很多 Python 扩展包的编译环境不兼容，比如某些需要 C 扩展的库就得额外装编译工具链，反而得不偿失。

第二，多阶段构建的意义。第一阶段单独做依赖安装，生成一个/install目录；第二阶段把/install里的内容直接拷贝到运行镜像的系统路径。这样做的好处是构建镜像里编译和缓存产生的临时文件不会留在最终运行镜像里。尤其对于包含 pandas、numpy、psycopg2 这类带 C 扩展的库，编译过程会产生大量中间文件，多阶段构建可以把它们一次性隔离掉。

第三，为什么要先拷贝 requirements.txt 再拷贝代码？这是 Docker 缓存机制里的一个经典技巧。Docker 在构建每一层时，如果对应的指令和依赖的文件内容都没有变化，就直接复用之前的缓存。如果你先 COPY 整个项目再装依赖，那么只要项目代码有任何一行变动，pip install 就会重新执行，拉依赖的时间成本非常高（特别是网络条件一般的时候）。把依赖层放在代码层之前，只要 requirements.txt 不变，pip install 成功的那一层缓存就能一直复用，代码迭代的构建速度会大幅提升。

3.2 依赖安装的加速方式与镜像源选择

在国内服务器上装 Python 依赖，默认走官方 PyPI 源会慢到你怀疑人生，几十个依赖装个十分钟很正常。实际生产环境中，我一般会在 Dockerfile 里设置国内镜像源：

RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

这样在构建阶段就会自动走镜像源拉取。要注意的是，如果基础镜像里的pip config粒度不够，也可以直接在命令里指定：

RUN pip install --no-cache-dir --index-url https://pypi.tuna.tsinghua.edu.cn/simple --prefix=/install -r requirements.txt

3.3 关于健康检查的一个补充技巧

Docker 自带 HEALTHCHECK 指令，可以让 Docker 周期性地检查容器是否还处于"健康"状态，方便后面编排和排查问题。对 FastAPI 这类项目，可以加这样一个探针（假设应用里已经实现了/healthz接口）：

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')" || exit 1

不过这个探针是发给应用的，对网络层不敏感。真正要帮 Nginx 或者上游负载均衡做判断的，是下面要讲的 Compose 里的 healthcheck 配置。Dockerfile 里的 HEALTHCHECK 和 Compose 里的 healthcheck，两者作用域不一样，前者用于docker inspect展示容器状态，后者用于编排器判断依赖服务是否可用。

4. docker-compose.yml 编排细节——端口、网络、数据卷、环境变量的全链路设计

单容器部署没太大意思，真实项目几乎都是"应用 + 数据库 + 缓存"的联动组合。这时候 docker-compose.yml 就派上大用场了。

4.1 一个能直接落地的编排文件参考

下面是我常用的编排文件模板，以 FastAPI + PostgreSQL + Redis + Nginx 的组合为例：

version: "3.8" services: app: build: context: . dockerfile: Dockerfile container_name: my_app_app restart: unless-stopped expose: - "8000" environment: - DATABASE_URL=postgresql+psycopg2://myuser:mypassword@db:5432/mydb - REDIS_URL=redis://redis:6379/0 - SECRET_KEY=${SECRET_KEY} depends_on: db: condition: service_healthy redis: condition: service_healthy networks: - backend db: image: postgres:15-alpine container_name: my_app_db restart: unless-stopped environment: - POSTGRES_USER=myuser - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - POSTGRES_DB=mydb volumes: - db_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U myuser -d mydb"] interval: 10s timeout: 5s retries: 5 networks: - backend redis: image: redis:7-alpine container_name: my_app_redis restart: unless-stopped command: ["redis-server", "--appendonly", "yes"] volumes: - redis_data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 5 networks: - backend nginx: image: nginx:1.25-alpine container_name: my_app_nginx restart: unless-stopped ports: - "80:80" - "443:443" volumes: - ./nginx/conf.d:/etc/nginx/conf.d:ro - ./static:/static:ro - ./media:/media:ro - certbot_webroot:/var/www/certbot - certbot_certs:/etc/letsencrypt depends_on: - app networks: - backend volumes: db_data: redis_data: certbot_webroot: certbot_certs: networks: backend: driver: bridge

这个文件有几个容易忽略但特别关键的点，我逐个说下。

4.2 expose 和 ports 的区别：为什么 Web 应用容器不暴露端口

新手经常搞混expose和ports。expose只是声明容器内部有哪些端口可供其他容器访问，并不会把端口映射到宿主机外部；ports才会把容器端口映射到宿主机端口，外部网络可以访问到。

在我这个编排里，app 容器只用了 expose "8000"，没有 ports。这意味着外界（包括宿主机）无法直接访问应用端口，只有同一个 Docker 网络内的容器（比如 Nginx）才能访问到它。这是一层额外的安全隔离——你的 Gunicorn 接口不该暴露在公网上，它只应该被 Nginx 转发到。

depends_on里加了condition: service_healthy，它保证了 Web 应用容器启动时，数据库和 Redis 都已经处于健康状态。因为 Python 应用启动时一般会尝试连接数据库、初始化连接池，如果数据库还没就绪，容器很可能启动失败，然后进入重启循环，场面很难看。

4.3 环境变量管理：.env 文件与敏感信息处理

编排文件里的${POSTGRES_PASSWORD}这种写法，是从当前目录下的.env文件读取值的。.env文件不要提交到 Git 仓库，里面放的是跟机器相关的敏感配置，比如数据库密码、JWT 密钥、云服务密钥。提交到仓库的应该是一个.env.example，内容用占位符，方便其他人照着写自己的.env。

我把这个做得更严一点：.env文件权限设置为600（只有文件所有者可读写），避免同一个服务器上其他用户把它读走。

4.4 数据卷的持久化与备份思路

db_data和redis_data这两个命名卷，是把容器内的数据目录映射到 Docker 管理的宿主机目录。这样即使容器挂了、重建了，数据还在。PostgreSQL 和 Redis 都是自己的存储格式，数据必须放在卷里，容器本身千万不要存储任何重要数据。

这里要提一个生产备份思路：直接把宿主机的数据库数据目录打个包并不合适，因为数据库运行时会写缓存和 WAL 日志，裸文件拷贝容易产生不一致。正确方式是用pg_dump定期导出 SQL，然后备份导出文件。我在服务器上放了个 2 行的 cron 任务：

0 3 * * * docker exec my_app_db pg_dump -U myuser mydb | gzip > /backup/mydb_$(date +\%F).sql.gz 0 4 * * * find /backup -name "*.sql.gz" -mtime +7 -delete

每日凌晨 3 点导出数据库并保留 7 天版本，这就够了。对大多数中小项目来说，这种级别的备份已经完全满足恢复需求。

4.5 Compose 网络原理解析

默认情况下，Compose 会为当前项目创建一个名为项目名_default的 bridge 网络。服务之间可以直接用服务名（比如app、db、nginx）作为主机名互相访问，因为 Compose 已经替我们做了 DNS 解析。所以在应用代码里配置数据库地址时，写的是db:5432而不是localhost:5432，这个db就是 Postgres 在 compose 网络里的服务名。

同一个网络里的容器互相访问，走的是容器 IP，跟宿主机 IP 无关。这种机制好就好在——你本地跑 compose 也能用db:5432访问数据库，服务器上跑一模一样，配置不需要改。

5. Nginx 反向代理配置详解——从端口转发到静态资源托管

Nginx 是整个架构中面向用户的最后一公里。它的配置不仅要实现反向代理，还要兼顾性能和安全。

5.1 核心反向代理配置模板

还是以 FastAPI 项目为例，nginx/conf.d/default.conf的参考配置如下：

upstream backend_app { server app:8000; keepalive 32; } server { listen 80; server_name example.com; # 静态文件直接由 Nginx 处理，不走 Python location /static/ { alias /static/; expires 7d; add_header Cache-Control "public, immutable"; } location /media/ { alias /media/; expires 30d; add_header Cache-Control "public"; } # 动态请求全部转发到 Gunicorn location / { proxy_pass http://backend_app; 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; # 显式设置 HTTP 版本为 1.1，否则 proxy 的 keepalive 不生效 proxy_http_version 1.1; proxy_set_header Connection ""; } }

5.2 为什么上游要写`backend_app`而不是`localhost:8000`

upstream里我写的是server app:8000;，这里的app是 docker-compose.yml 里服务名。Nginx 容器和 Web 应用容器在同一个 Docker bridge 网络里，Nginx 启动时会对app这个主机名做 DNS 解析，解析到 Web 应用容器的内网 IP。

也有人写成server http://localhost:8000，这在 Docker 网络里是走不通的，因为 Nginx 容器里的 localhost 是 Nginx 容器自己，不是应用容器。这是新手最容易踩的坑之一。

5.3 静态文件到底应该放哪？

这里有个架构细节要讲清楚：Python Web 框架的 Static 文件处理能力非常弱，Gunicorn 也不应该处理静态文件。所以生产环境的标准做法是，静态文件（CSS、JS、图片）由 Nginx 直接提供，请求根本不会进到 Python 应用里。

实现方式是在 docker-compose.yml 里，把宿主机的./static目录以只读方式挂载到 Nginx 容器内部（/static），同时也在构建镜像时把./static拷进 Web 应用容器（用于本地调试或某些需要调用静态文件的场景）。在 Nginx 配置里用alias /static/把路由前缀映射过去。

如果你用 Django 的collectstatic管理静态文件，建议在 CI/CD 流程里把收集好的staticfiles目录挂载给 Nginx。FastAPI / Flask 项目相对简单，直接把静态资源目录丢过去就行。

5.4 反向代理的 header 传递为什么重要

proxy_set_header这些配置不是可有可无的。这里逐个解释：

Host $host：把外部请求的 Host 头传给后端应用。如果省略，后端看到的 Host 就是 Nginx 容器自身的 IP，一些基于域名做逻辑判断的功能（如站点 URL 生成、SEO 分站）就会出错。
X-Real-IP/X-Forwarded-For：把用户真实 IP 传给后端。你的 Python 应用在记录访问日志、做 IP 限流、地理位置分析时，取的就是这个头。如果不设置，后端看所有请求都来自同一个 IP——就是 Nginx 容器的内网 IP，那各家业务的 IP 相关功能就全部废掉了。
X-Forwarded-Proto：告诉后端用户是通过 HTTP 还是 HTTPS 访问。有些 Web 框架在生成重定向 URL 时依赖这个字段判断协议，不设置的话即使外部是 HTTPS，后端生成的链接也可能变成 HTTP。

如果你的框架层面要读取真实 IP，还需要在应用里配置"信任反向代理"。以 Gunicorn 为例，它的--forwarded-allow-ips参数需要设置成信任来自 Docker 内网的转发请求，否则框架会默认忽略这些头部以作安全防护。

5.5 关于 SSL 证书：从 HTTP 到 HTTPS 的平滑切换

现在部署新站点，没上 HTTPS 已经很不像话了。有两种主流的证书记置方式：

用 Certbot 在宿主机上直接申请证书，然后把证书文件挂载给 Nginx 容器。
用 certbot 容器配合 Nginx 做自动续期，把证书目录挂到/etc/letsencrypt。

我建议用第二种：certbot容器 +certbot_certs卷 + Nginx 的定时续期。它能把证书的申请和续期完全自动化。首次申请可以通过一个 HTTP-01 的 challenge 完成，Nginx 在/var/www/certbot目录下提供验证文件。证书签下来后，再新增一个监听 443 的 server 块，把 HTTP 请求 301 重定向到 HTTPS。

HTTPS server 块的配置，只需要在 5.1 节的 server 块基础上，增加证书路径和 80 端口的重定向即可。等以后你要给站点上 HTTPS，直接加上证书路径就行，重新加载一下 Nginx 配置（nginx -s reload）就能生效。

6. 把服务跑起来：首次启动、日志排查与常见故障定位

写完了 Dockerfile、Compose 文件和 Nginx 配置，终于到了跑服务的环节。我对第一步启动的建议和很多教程不同——不要直接后台启动，先前台跑一遍，把所有输出看一遍再说。

6.1 首次启动的前台调试与后台切换

在你确认配置没有大问题时，执行：

docker compose up

这个命令会前台启动所有服务，把日志实时刷到终端上。绝大多数配置问题都能从日志里看出来。如果一切正常，能看到类似这样的输出：

app_1 | [INFO] Starting gunicorn 23.0.0 app_1 | [INFO] Listening at: http://0.0.0.0:8000 db_1 | PostgreSQL init process complete; ready for server start. nginx_1 | [warn] the "listen ... http2" directive is deprecated

确认没问题后，Ctrl+C 停掉，再用docker compose up -d把服务放后台跑。这里的-d是 detach 的意思，让服务在后台运行。

6.2 三个最常遇到的启动故障与排查路径

故障一：数据库连接失败。典型报错是应用容器启动几秒后退出，日志里写着connection refused或者database "xxx" does not exist。排查链路是：先docker compose ps看 db 容器是否已经 healthy；再docker compose logs db确认数据库是否初始化完成；最后确认应用代码里的DATABASE_URL用的是服务名db:5432而不是localhost:5432。

故障二：Nginx 502 Bad Gateway。这个一般出现在整体能启动但访问时。502 意味着 Nginx 没法连到上游应用。可能原因：应用容器启动失败（docker compose ps看到退出状态）、应用监听端口跟 Nginx 上游配置不一致（应用在 8000，Nginx 转发到 8001）、或者网络没连通。先docker compose logs nginx看错误日志，里面会明确写connect() failed (111: Connection refused)这类信息。

故障三：静态文件 404。启动没问题、接口也通，但页面图片和样式全都加载不出来。先确认 Nginx 容器里/static目录是否有内容，可以docker exec my_app_nginx ls -l /static；再检查 Nginx 配置里的location /static/是否和 docker-compose 挂载路径对得上。注意alias /static/和root /static的效果完全不同，root会把前缀一起拼到路径后面，导致路径变成/static/static/xxx，这个细节写错就是 404。

6.3 日常运维：日志查看、容器重启与服务自愈

服务跑起来后，日志就是你的眼睛。快速查看实时日志的命令要记熟：

# 查看所有服务日志 docker compose logs -f # 只看某个服务的日志，并限制输出行数 docker compose logs -f app --tail=500 # 进入容器内部排查 docker exec -it my_app_app bash

我的实践是，所有日志都打到容器 stdout/stdout，这样 Docker 会自动采集，再结合一些轻量级的日志轮转配置（比如使用json-file驱动并设置max-size: 50m），可以避免日志文件无限膨胀：

logging: driver: "json-file" options: max-size: "50m" max-file: "3"

restart: unless-stopped这个策略保证服务由于异常退出时，Docker 会自动拉起新容器。但它不解决"进程跑着但服务不可用"的假死问题，所以healthcheck的意义就在于主动探测应用的真实可用性，而不只是看进程是否存活。

7. 镜像构建与版本管理的进阶操作

服务能稳定运行之后，就会碰到"怎么优雅地更新版本"这个问题。直接把新代码推到服务器上重建容器当然可行，但有一些细节能让你做得更顺。

7.1 基于 Git 提交哈希打 tag，实现快速回滚

我个人比较认可的方式是，每次发布都基于 Git 提交有点长直接用短哈希作为镜像 tag：

docker build -t my_app:$(git rev-parse --short HEAD) . # 更新 compose 文件里的镜像版本 docker compose up -d

这样每次部署的镜像跟代码提交完全对应，一旦线上出问题，只需要把镜像 tag 切回上一个可行的提交哈希，重新up -d，就能实现秒级回滚。除非你的数据库结构已经变更，否则回滚到旧代码往往比现场改 bug 更稳，也更符合现代发布理念。

7.2 用 Registry 配合部署脚本实现一键发布

如果只有你自己在维护，直接在服务器上构建和运行也完全可行。但当你有多台服务器、或者开始有 CI/CD 的需求后，把镜像推到私有 Registry（或者云服务商的镜像仓库）更合适。

一个可以跑通的流程是：

# 在本地或者构建机上 docker build -t my_registry.example.com/my_app:1.2.3 . docker push my_registry.example.com/my_app:1.2.3 # 在服务器上 docker compose pull app docker compose up -d app

配合 CI 平台（比如在代码仓库提交标签后自动触发构建和推送），整个流程可以做到完全无人值守。不过这些属于进阶玩法，第一次部署不需要太焦虑，先把单个服务器上的 Docker Compose 跑熟练，CI/CD 后面再引入也不迟。

7.3 定时清理无用镜像和构建缓存

服务器磁盘被占满也是我实际遇到过的生产事故。Docker 在反复构建和更新后，会积累很多dangling镜像和构建缓存。可以定期执行以下命令：

docker system prune -f docker builder prune -f

我一般每周执行一次自动清理，防止因磁盘满导致服务无响应。

8. 迁移到生产之前：配置清单与安全加固自查

最后这段不是教你写代码，而是一份我在项目上线前必过的自查清单。很多东西到了线上才发现再改，成本会成倍增加。

8.1 上线前的检查清单

应用配置项是否全部通过环境变量注入？有没有在代码里硬编码数据库地址、密码、密钥？
.env文件是否已经加入.gitignore？密钥是否用足够强度的随机串生成？
数据库、Redis 端口是否暴露到宿主机？如果只给 Web 应用用，不需要暴露任何端口。
Nginx 配置是否限制了请求体大小（client_max_body_size）？防止用户上传大文件时把后端压垮。
是否配置了基础安全相关响应头（如X-Content-Type-Options、X-Frame-Options、Referrer-Policy）？

8.2 容器安全的两个细节

永远不要在容器内用 root 运行你的应用。在 Dockerfile 里通过useradd创建专门用户（如样例里的appuser），并在最后USER appuser切换。一旦容器被攻破，攻击者至少不是在 root 权限下任意操作。
给 Compose 服务通过networks做前后端隔离。如果你的架构里有 Redis 或者内部管理接口，可以考虑拆分成多个网络层，只有 Nginx 所在的入口层能对外暴露端口，数据库、缓存的内部服务完全走封闭的 backend 网络，不与公网有任何交集。

8.3 最后的操作体会

把我这几年的经验浓缩成一句给你的实在话：部署链路其实就三段——构建镜像时保证环境的确定性，编排运行时控制服务之间的依赖和网络，入口层用 Nginx 把用户流量安全地接到应用上。每一段都有自己该踩的坑，但只要你按这个架构思路一步步搭，它基本能覆盖你未来一两年内绝大多数的发布需求。第一次跑通后你会明显感觉到，再往 Web 应用里加新功能、发新版本，都变成了一件很顺手的事情，因为基础设施已经稳定，剩下的就是业务逻辑本身的迭代了。

企业官网建设流程全解析