企业官网建设流程全解析

说实话，把 Python Web 应用从本地跑起来到正式落到服务器上，这个过程的坑比写业务代码多得多。我前后部署过十几个项目，从最早直接用nohup python app.py裸奔，到后来换成 Docker + Nginx 这套标准组合，中间踩过的坑足够写一本书了。这篇就把完整的部署思路、配置文件和排查过程整理出来，给准备上线或者正在被服务器折腾的朋友一份可以直接抄作业的模板。文章会覆盖 Django 和 Flask 两种常见框架，重点讲清楚 Docker 怎么把应用打包成集装箱、Nginx 怎么在前面做反向代理、静态文件怎么处理，以及上线之后最常遇到的几个问题应该怎么查。

1. 整体设计：为什么部署方案要选 Docker + Nginx

1.1 裸机部署的痛点

先说结论：如果你只有一个 Python 小项目想快速上线试试水，直接在服务器上装个 Python 环境，pip install -r requirements.txt，然后nohup python app.py &也能跑。但只要你需要迁移服务器、增加一台机器、或者升级依赖版本，这套"裸奔方案"立刻会变成灾难。

我记得有一次帮朋友迁移一个 Flask 项目，旧服务器上 Python 3.6、系统自带的 libxml2、还有一堆编译安装的依赖，到了新服务器上全部要重来一遍，折腾了整整一下午。最难受的是你根本不知道当初是怎么装上的，有些依赖是编译安装的，有些是 pip 装的，还有些是 apt 装的，环境完全不可复现。

这就是痛点所在：裸机部署把"应用"和"服务器环境"死死绑在一起，环境稍有不同，行为就千差万别。而 Docker 的核心价值恰恰是把这个绑定切断。

1.2 Docker 解决的核心问题

Docker 的本质是给应用做了一个快照，把代码、依赖、Python 解释器、系统库全部打包进镜像。这个镜像在任何装了 Docker 的服务器上行为一致。你可以理解为：以前搬家要把家具拆了运过去再重新组装，现在直接整个货柜吊走，到地方就不用拼了。

对我们做部署的人来说，Docker 带来的实际好处有三个：

• 环境一致性：本地能跑，服务器就能跑，不会出现"在我机器上好好的"这种问题。
• 隔离性：应用和应用的依赖互不干扰，一个项目用 Python 3.8，另一个用 3.11，互不影响。
• 快速回滚：镜像是有版本的，新版本出了问题，直接切回旧镜像，秒级恢复。

当然 Docker 也有学习成本，但相比它解决的问题，这个成本非常值得。

1.3 Nginx 在架构里的位置

有了 Docker 容器，应用已经能跑了，但还缺一个入口。直接用容器暴露端口对外提供服务，会有几个问题：一是 Python 的 WSGI 服务器（如 Gunicorn）处理静态文件能力弱，二是多应用共用一台服务器时端口管理混乱，三是没有统一的位置做 HTTPS 终结。

Nginx 放在最前面，扮演的是"门卫 + 快递分拣员"的角色。用户请求先到 Nginx，它根据路径和域名把请求分发到不同的容器；静态文件、图片、CSS、JS 这些直接在 Nginx 层处理，不劳烦 Python 进程；同时 HTTPS 证书也在 Nginx 层统一管理，任何 Web 应用不需要关心证书怎么配。

这套架构的完整链路长这样：

用户请求 → Nginx（80/443端口） → 反向代理 → 容器内的 Gunicorn → Python 应用 ↓ 静态文件直接返回

这样的好处是：Nginx 只干 Nginx 擅长的事，Python 只干 Python 擅长的事，各司其职，出了问题排查范围也小。

2. 环境准备与基础选型

2.1 服务器初始化的必要步骤

我习惯在新服务器上先做三件事，这三件事能让后面少出很多莫名其妙的问题。

第一，更新系统软件源。Ubuntu 服务器上执行apt update && apt upgrade -y，CentOS 则是yum update -y。这一步不是可选项，很多部署问题追根溯源都是系统包版本太老导致的。

第二，创建一个非 root 的部署用户。日常维护用 deploy 之类的普通用户操作，只有需要安装系统级软件时才 sudo。这个习惯能避免很多手滑事故，比如在 root 下误执行rm -rf没有回收站可后悔。

第三，配置基础的防火墙。只放行 22（SSH）、80、443 端口。Docker 默认会往 iptables 里写规则，如果防火墙和 Docker 的端口映射叠加，容易出现"外部访问不了但容器内正常"的怪问题，这块后面专门讲。

2.2 Docker 及 Docker Compose 安装

安装 Docker 的方式，我建议直接用官方脚本，简单且不会装到过时版本：

curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun systemctl enable docker && systemctl start docker

装完验证一下：docker version，能看到 Client 和 Server 两段信息就没问题。如果只有 Client 没有 Server，说明 docker 服务没起来，检查systemctl status docker。

Docker Compose 是编排多容器的利器，即使你这个项目只有一个容器，我也建议用 Composer 来管理，因为配置都在一个 YAML 文件里，可复现、可版本管理。安装方式：

curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose chmod +x /usr/local/bin/docker-compose docker-compose --version

注意：现在新版 Docker 已经内置了docker compose插件（不带横杠），但我还是习惯用独立的docker-compose命令，因为很多旧脚本和文档都用这个，兼容性好一些。

2.3 Python 基础镜像怎么选

基础镜像选择直接关系到镜像体积和构建速度。我用过三种，给你们一个参考：

Alpine 虽然小，但它用的是 musl libc，很多 Python 包在编译时会出现奇怪的兼容问题，比如某些数据库驱动装不上。我早期贪体积用过一次 Alpine，装psycopg2编译报错，后来换了slim五分钟搞定。记住一句话：体积是小事，稳定是大事。

这里多说一句，如果你的项目依赖里有pandas、numpy、scipy这类重量级科学计算库，直接选python:3.11完整版，避免编译依赖的二次折腾。我见过有人为了省 200MB 体积，在 slim 镜像里手动装一堆编译工具，最后镜像反而比完整版还大。

3. 核心细节：Dockerfile 设计与进程管理

3.1 Dockerfile 逐行拆解

直接给一份我常用的 Dockerfile，以 Django 项目为例：

# 基础镜像 FROM python:3.11-slim # 设置环境变量，避免 Python 产生字节码、日志不输出 ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 # 系统依赖，一次性装齐并清理缓存 RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ libpq-dev \ curl \ && rm -rf /var/lib/apt/lists/* # 设置工作目录 WORKDIR /app # 先复制依赖文件，利用 Docker 缓存层 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 再复制项目代码 COPY . . # 收集静态文件 RUN python manage.py collectstatic --noinput # 暴露端口 EXPOSE 8000 # 容器启动命令 CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "3"]

这份 Dockerfile 有几个细节值得单独说明。

第一，COPY requirements.txt .和RUN pip install放在复制项目代码之前，这是利用 Docker 层缓存的关键技巧。因为项目代码是经常变的，而requirements.txt一般很少变，这样构建时只要依赖没变，就直接命中缓存，省去重复安装依赖的时间。我见过有人把COPY . .放在最前面，每次改一行代码就要全量重装依赖，构建一次十几分钟，非常痛苦。

第二，环境变量PYTHONDONTWRITEBYTECODE=1是让 Python 不要生成__pycache__文件，PYTHONUNBUFFERED=1是让日志实时输出到标准输出，不然用docker logs看日志会有延迟。这两个变量看着不起眼，排查问题的时候作用很大。

第三，CMD用的是 Gunicorn，而不用 Flask 自带的开发服务器，原因下面单独说。

3.2 为什么是 Gunicorn 而不是开发服务器

Flask 和 Django 自带的服务器是开发用的，能力上限大概在几百个并发请求，而且进程是单线程的，一个请求卡住，后面的全部排队。更致命的是，开发服务器的安全性没有经过生产验证，历史上爆过不少漏洞。生产环境必须用 WSGI 服务器。

我推荐 Gunicorn，三个理由：配置简单、性能稳定、生态成熟。上面配置里的--workers 3是启动 3 个 worker 进程，实际生产可以根据 CPU 核心数调整，经验公式是2 * CPU核心数 + 1。在 2 核服务器上，5 个 worker 差不多是甜点值。

还有一个参数容易被忽略：--timeout。Gunicorn 默认的 worker 超时时间是 30 秒，如果你的某个接口是耗时操作（比如导出 Excel、调用外部 API），30 秒没响应就会被 Gunicorn 杀掉，表现为"请求突然断开、进程重启"。我在一个数据处理项目里就遇到过，接口处理 40 秒，Gunicorn 杀了好几次 worker，客户端收到 502。后来加了--timeout 120就正常了。

3.3 多阶段构建：用不上就先别折腾

多阶段构建是 Docker 的高级技巧，思路是先用一个完整的编译环境装依赖，再把编译好的产物复制到精简的运行镜像里。好处是最终镜像不包含编译工具，能小很多。

但我的观点是：如果你不是对镜像体积有极致追求，初期完全没必要上多阶段构建。原因很实际：多阶段构建的 Dockerfile 更复杂，出问题排查难度更高，而且 Python 的依赖很多是纯 Python 包或者有预编译 wheel，直接pip install出来的体积增加并不夸张。一个 300MB 的镜像和一个 150MB 的镜像，对个人项目的服务器来说差异不大。先把基础链路跑通，体积优化可以等稳定了再说。

4. 实操：用 docker-compose 编排整个应用

4.1 docker-compose.yml 完整示例

不管项目多简单，我都建议用docker-compose.yml来管理。一份最简配置长这样：

version: "3.8" services: web: build: . container_name: myproject-web restart: always expose: - "8000" volumes: - static_volume:/app/staticfiles - media_volume:/app/media env_file: - .env.prod networks: - app_network nginx: image: nginx:1.25-alpine container_name: myproject-nginx restart: always ports: - "80:80" - "443:443" volumes: - ./nginx/conf.d:/etc/nginx/conf.d - static_volume:/app/staticfiles - media_volume:/app/media - ./certbot/conf:/etc/letsencrypt depends_on: - web networks: - app_network volumes: static_volume: media_volume: networks: app_network: driver: bridge

这里有三个关键设计点。

第一，web服务只用了expose而不是ports。expose只是声明容器对外提供端口，但并不映射到宿主机。宿主机上只有 Nginx 的 80/443 端口对外暴露，外部请求无法直接访问 8000 端口，这样可以避免绕过 Nginx 直接打到应用上。

第二，静态文件和媒体文件是通过 named volume 共享的。web容器在启动时通过collectstatic把静态文件收集到/app/staticfiles，nginx容器挂载同一个 volume，直接从/app/staticfiles读取文件。两个容器之间通过 volume 实现了文件共享，不需要把文件复制到宿主机。

第三，depends_on让 Nginx 等web启动后再启动。不过它只保证web容器创建了，并不能保证应用已经就绪。更进一步可以用 healthcheck，但小项目用depends_on加一个启动延迟就够用了。

4.2 网络与端口映射背后的原理

Docker 默认给每个 compose 项目创建一个自定义 bridge 网络，同一个网络里的容器可以通过服务名互相访问。在这个例子里，nginx容器里配置proxy_pass http://web:8000，Docker 内置的 DNS 会把web解析到对应的容器 IP 上。

这里容易踩坑的是端口映射。如果多个项目都要用 80 端口，就会冲突。解决方案有几个：

• 改端口映射，比如8080:80，但用户访问时需要带端口号，体验差。
• 在 Nginx 里根据域名分流，所有项目的 Nginx 都只暴露 80 端口，但在宿主机 Nginx 做一层转发。
• 如果你只有一个 Nginx 容器，把多个项目的配置都放进同一个容器里，用server_name区分。

我现在的方案是：一个 Nginx 容器，通过server_name配置多个虚拟主机，不同域名走不同的proxy_pass指向不同的应用容器。这样一个服务器上跑四五个应用，都只占 80/443 端口，配置管理也不混乱。

4.3 敏感信息放哪：env_file 与 .env 的正确用法

直接在docker-compose.yml里写数据库密码、SECRET_KEY 是大忌。一旦这个文件被推到公共仓库，等于把数据库裸奔。我一般用env_file指向一个.env.prod文件：

DJANGO_SECRET_KEY=xxx DB_PASSWORD=xxx REDIS_PASSWORD=xxx

在项目代码里通过os.environ.get("DJANGO_SECRET_KEY")读取。.env.prod文件本身写进.gitignore，绝不入库。配合.env.example放在仓库里，给后来的人一个配置模板，这样谁拿到代码都知道该填哪些变量，又不会泄露真实密钥。

注意：docker-compose.yml里的environment:和env_file:是有区别的。environment是明文写死，env_file是从文件读取。文件读取有个好处是改配置不用改 compose 文件本身，只要重新docker-compose up -d即可生效。

5. Nginx 反向代理配置详解

5.1 基础配置：一个能用的最小模板

先给一份最小可用的 Nginx 站点配置：

server { listen 80; server_name example.com www.example.com; # 静态文件直接由 Nginx 处理 location /static/ { alias /app/staticfiles/; expires 30d; add_header Cache-Control "public, immutable"; } location /media/ { alias /app/media/; expires 7d; } # 其余请求反代到 Gunicorn 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; proxy_connect_timeout 60s; proxy_read_timeout 120s; } }

几个字段的用意：

• proxy_set_header Host $host：保证 Django/Flask 收到的 Host 头和浏览器里的一致，不然 Django 的 CSRF 校验和站点头像会出问题。
• X-Forwarded-For：把用户的真实 IP 传给后端，Django 里可以配置USE_X_FORWARDED_HOST = True和SECURE_PROXY_SSL_HEADER来正确识别。
• proxy_read_timeout 120s：配合 Gunicorn 的--timeout 120，两边的超时设置要一致，否则会出现"Nginx 已经超时了，Gunicorn 还在处理"的情况。

5.2 location 匹配机制：为什么顺序这么重要

Nginx 的 location 匹配有一套固定规则，真的值得花十分钟搞清楚，因为 90% 的"页面加载不出来、样式全丢了"都和它有关。

Nginx 匹配 location 的顺序是：

1. 先做精确匹配location = /xxx，命中直接返回。
2. 再处理前缀匹配location ^~ /xxx，^~表示一旦匹配就不再继续找正则。
3. 然后按顺序匹配正则location ~ /xxx，第一个匹配的正则生效。
4. 最后是普通前缀匹配，取最长前缀。

最常见的坑是正则 location 的顺序。如果你写了两个正则：

location ~ \.php$ { ... } location ~ \.(js|css)$ { ... }

第一个正则命中了就不会再看第二个了。所以正则 location 的顺序非常重要，宽泛的一定要放后面。

另外注意location /static/用的是alias还是root，很多新手在这里翻车。alias /app/staticfiles/的意思是 URL 中的/static/xxx.css对应文件系统里的/app/staticfiles/xxx.css。如果用root /app/staticfiles/，那 Nginx 找的是/app/staticfiles/static/xxx.css，会多一层路径，结果就是 404。

5.3 静态文件到底交给谁处理

这个问题在部署时必问。我直接给结论：静态文件一定要交给 Nginx，不要让 Django 处理。生产环境下，Django 的django.contrib.staticfiles和 Flask 的static路由都是 Python 进程在干活，性能差一个量级。Nginx 处理静态文件的能力强太多，还能顺带做缓存和压缩。

Django 这边要做两件事：

• settings.py里设置STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')，并配置STATIC_URL = '/static/'。
• 执行python manage.py collectstatic把所有 app 的静态文件集中到STATIC_ROOT。

Flask 更简单，只需要把static目录挂载给 Nginx，然后在 Flask 应用里关闭自己的静态文件路由即可。

还有一点，如果用了白鹤的 CDN 或者对象存储，可以直接把静态文件托管到这些平台上，Nginx 配置一个 302 重定向或者直接 403 拦截。但对小项目来说，Nginx 本地处理完全够用，没必要引入额外依赖。

5.4 HTTPS 配置：Let's Encrypt 与容器化部署

现在的网站不在 HTTPS 下跑基本说不过去，浏览器都直接标"不安全"。我用的是 Let's Encrypt 免费证书，配合自动续期。

容器化部署下，证书有两种放法：

• 装 certbot 在宿主机上，证书文件挂载进 Nginx 容器。
• 用专门的 certbot 容器申请证书，然后把证书目录共享给 Nginx 容器。

我倾向第二种，因为 Server 上装一堆工具和 Docker 的隔离理念相悖。certbot 容器的临时步骤如下：

docker run -it --rm -v /path/to/certbot/conf:/etc/letsencrypt \ -v /path/to/certbot/www:/var/www/certbot \ certbot/certbot certonly --webroot -w /var/www/certbot \ -d example.com -d www.example.com

申请完成后，Nginx 配置里加上：

listen 443 ssl; ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

自动续期可以用 cron 定时执行docker run命令跑一遍 renew。证书有效期是 90 天，续期脚本建议每周跑一次，错开各种边缘情况。

6. 上线全流程与常见问题排查

6.1 从代码到上线的完整命令序列

假设你本地代码已经推到 Git 仓库，服务器上也已经装了 Docker，完整上线流程是这样：

# 1. 登录服务器，拉取代码 cd /opt/projects git clone git@github.com:yourname/yourproject.git cd yourproject # 2. 检查配置文件 ls -la # 确认 .env.prod 是否就位 cat docker-compose.yml # 3. 构建并启动 docker-compose build docker-compose up -d # 4. 查看容器状态和日志 docker-compose ps docker logs -f myproject-web # 5. 验证数据库迁移 docker-compose exec web python manage.py migrate # 6. 创建管理员账号（可选） docker-compose exec web python manage.py createsuperuser # 7. 测试访问 curl -I http://localhost

这个流程跑通一次以后，后续发版只需要两步：

docker-compose build web && docker-compose up -d

没错，就是这么简单。有了 Docker，发版不再需要你在服务器上手动改文件、重启进程、祈祷不要出错，一切都在镜像构建的环节完成。版本升级出了问题的回滚也是秒级：

docker-compose pull # 如果用了镜像仓库 # 或者直接重新 build 旧版本代码

6.2 高频问题排查实录

把我这几年遇到的高频问题整理成一张速查表，很多问题都是共性存在的：

这里单独说一个我印象极深的坑。有一次我在服务器上部署完，浏览器访问一直转圈，SSH 进去看啥都正常，Nginx 日志也没有报错。后来排查了好久，发现是服务器防火墙把 80 端口给拦了。Docker 的端口映射本质上是 iptables DNAT，如果防火墙规则里 80 端口没放行，Nginx 容器监听 80 没问题，但从外面访问就直接被防火墙丢弃了。检查防火墙规则是个排查第一步，别上来就改代码。

另一个常见问题是 Django 的ALLOWED_HOSTS。如果你忘了把域名加进去，Django 会直接拒绝响应，Nginx 会显示 400 错误而不是 502。这个很奇怪，因为 Nginx 日志里正常，Django 日志里能看到DisallowedHost的错误信息。解决办法是在settings.py里加：

ALLOWED_HOSTS = ["example.com", "www.example.com", "IP地址"]

6.3 日常维护：日志、备份与资源监控

上线只是开始，维护才是持久战。分享几个我每天/每周会做的事：

日志方面，docker logs命令支持--since和--tail参数，排查问题很方便：

docker logs --tail 100 --since 1h myproject-web

但记住，容器一旦删掉重建，日志就没了。如果需要长期留存日志，最好把日志挂载到宿主机：

volumes: - ./logs:/app/logs

或者在 Nginx 容器里把访问日志输出到挂载目录。

备份方面，数据库备份我用 cron 每天凌晨跑一次：

0 2 * * * docker exec myproject-db pg_dump -U user dbname > /backup/db_$(date +\%Y\%m\%d).sql

保留最近七天的备份就够用了，别让备份文件把磁盘塞满。清理旧的：

find /backup -name "*.sql" -mtime +7 -delete

资源监控方面，最简单的方式是docker stats看实时的 CPU 和内存占用。如果发现容器内存一直涨，多半是应用有内存泄漏。对 Gunicorn 来说，可以配置--max-requests让 worker 处理一定数量请求后自动重启，变相缓解内存泄漏问题：

CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "3", "--max-requests", "1000", "--max-requests-jitter", "100"]

--max-requests-jitter是给重启加一点随机偏移，避免所有 worker 同时重启造成请求瞬间中断。这个参数是我在线上被教育之后加上的。

7. 多项目共存与进阶扩展

7.1 一台服务器跑多个应用

做个人项目多了以后，一个服务器上往往要跑好几个服务：一个 Django 博客、一个 Flask API、一个静态网站。我现在的服务器上跑了四个应用，全部共用一个 Nginx 容器。

核心思路是把每个应用的路由配置成独立的配置文件，然后挂载到 Nginx 容器的conf.d目录里：

project/ └── nginx/ ├── blog.conf ├── api.conf └── static-site.conf

每个配置文件都是一个server块，用server_name区分域名：

# blog.conf server { listen 80; server_name blog.example.com; location / { proxy_pass http://blog-web:8000; } } # api.conf server { listen 80; server_name api.example.com; location / { proxy_pass http://api-web:5000; } }

新增一个应用，只需要在conf.d里放一个文件，然后docker exec nginx nginx -s reload，Nginx 会平滑重载配置，不会中断现有连接。

7.2 数据卷备份与迁移

如果你要迁移服务器，数据卷的迁移是个容易被忽略的环节。方法是把卷打包成 tar 备份：

docker run --rm -v myvolume:/data -v $(pwd):/backup alpine tar czf /backup/myvolume.tar.gz -C /data .

到了新服务器上解压：

docker run --rm -v myvolume:/data -v $(pwd):/backup alpine tar xzf /backup/myvolume.tar.gz -C /data

这个操作相当于把命名的数据卷内容完整导出了一份。加上数据库的 dump 文件，整台服务器的项目迁移基本可以做到"人不动、数据跟着走"。

7.3 后续可以做的优化方向

这套架构跑稳之后，有几个方向可以根据需要陆续补充。一是接入 CI/CD，Git 提交自动触发构建和部署，省去手动 SSH 上线的过程。二是镜像推到私有仓库，服务器不直接 build，而是从仓库拉镜像，这样多台服务器可以共用镜像，回滚也只是切换 tag。三是如果有多个服务之间有依赖（比如 API 服务和后台任务服务），用 Kubernetes 或者 Docker Swarm 做编排，不过对个人项目来说，docker-compose 已经非常够用了，别为了技术而技术。

我个人实际用下来的体会是：部署这件事，前期把架构想清楚比后期反复修补重要得多。Docker + Nginx 这套组合最大的价值不是某个单一工具多厉害，而是把环境复现、进程管理、入口路由、静态文件、证书、日志这些运维琐事都标准化了。标准化之后，不管项目怎么换、服务器怎么换，你的部署流程始终稳定可预期，这才是真正能睡个安稳觉的关键。如果你现在正在手动nohup部署自己的应用，试着把项目迁到这套方案上，第一次可能花两三个小时，但之后每次发版节省的时间和避免的惊吓，绝对值回票价。