Ubuntu 22.04 生产环境部署 FastAPI + Uvicorn + Nginx 实战

Ubuntu 22.04 生产环境部署 FastAPI + Uvicorn + Nginx 实战

在生产环境下，单纯使用 Uvicorn 监听外部请求存在性能和安全风险。为了构建一个高可用、可维护的 Python Web 服务平台，我们采用如下部署架构：

Internet │ ▼ Nginx (反向代理 + SSL/TLS) │ proxy_pass ▼ Uvicorn Workers (基于 uvloop + Gunicorn 管理) │ FastAPI Application │ PostgreSQL / Redis / 后端微服务 

这套方案适用于高并发 API 服务、微服务架构中的 HTTP 接口部署，以及需要 TLS/HTTPS 安全访问的生产环境。

服务器硬件与系统建议

为了保证并发请求的稳定性和日志写入速度，推荐以下配置：

项目	推荐配置	说明
CPU	4 核及以上	确保并发处理能力
内存	8GB 以上	满足 Python GC 及缓存需求
磁盘	NVMe 150GB 以上	提升 I/O 性能
网络	公网带宽 100Mbps	保障 API 对外访问质量
系统	Ubuntu 22.04 LTS	选择最新稳定版

外网访问建议部署具有 DDoS 防护的 BGP 线路服务器，例如 CN2 或电信直连方案，以降低网络抖动和丢包率。

系统初始化与依赖安装

更新系统

首先确保系统是最新的，这能减少潜在的安全漏洞。

sudo apt update && sudo apt upgrade -y
sudo reboot

安装 Python 环境与必备工具

我们需要 Python 3.10 及其开发库，同时安装 Nginx 和防火墙工具。

# 安装 Python3.10
sudo apt install -y python3.10 python3.10-venv python3.10-dev python3-pip build-essential

# 常用工具
sudo apt install -y nginx ufw git

建立虚拟环境

进入应用目录 /opt/fastapi_app，创建隔离的 Python 环境。

sudo mkdir -p /opt/fastapi_app
sudo chown $USER:$USER /opt/fastapi_app
cd /opt/fastapi_app
python3.10 -m venv venv
source venv/bin/activate

应用代码结构与示例

最简 FastAPI 项目结构

合理的目录结构有助于后期维护：

fastapi_app/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1.py
├── requirements.txt
└── logging.conf

示例代码

app/main.py

这里定义主应用入口和健康检查接口。

from fastapi import FastAPI
import uvicorn

app = FastAPI(title="示例 FastAPI 服务")

@app.get("/health")
def health_check():
    return {"status": "OK"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

app/api/v1.py

将业务逻辑按版本拆分，方便扩展。

from fastapi import APIRouter

router = APIRouter(prefix="/v1")

@router.get("/ping")
def ping():
    return {"message": "pong"}

requirements.txt

锁定关键依赖版本，避免环境差异。

fastapi==0.99.1
uvicorn==0.23.2
gunicorn==20.1.0

使用 Gunicorn 管理 Uvicorn Workers

单进程 Uvicorn 无法满足生产级并发，Gunicorn 配合 Uvicorn Worker 是最佳实践。

Gunicorn + Uvicorn 配置

创建启动脚本 gunicorn_conf.py，根据 CPU 核心数动态调整 worker 数量。

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "uvicorn.workers.UvicornWorker"
bind = "127.0.0.1:8000"
timeout = 30
keepalive = 5

# 日志路径
errorlog = "/opt/fastapi_app/logs/gunicorn.error.log"
accesslog = "/opt/fastapi_app/logs/gunicorn.access.log"
loglevel = "info"

启动命令

准备好日志目录后，即可启动服务。

mkdir -p logs
gunicorn app.main:app -c gunicorn_conf.py

Nginx 反向代理配置

Nginx 负责处理静态资源、SSL 终止及负载均衡。

Nginx 配置文件

创建 /etc/nginx/sites-available/fastapi：

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass http://127.0.0.1:8000;
    }

    location /static/ {
        alias /opt/fastapi_app/app/static/;
    }
}

启用配置并重启 Nginx：

sudo ln -s /etc/nginx/sites-available/fastapi /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

生产环境 SSL/TLS

使用 Certbot 获取免费 Let's Encrypt 证书，自动续期无需人工干预。

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com

检查自动续期状态：

sudo systemctl status certbot.timer

防火墙与安全

启用 UFW 限制入站流量，仅开放必要端口。

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

日志、监控与性能指标

日志策略

合理管理日志文件，防止磁盘爆满。结合 logrotate 定期清理。

sudo nano /etc/logrotate.d/fastapi

内容示例：

/opt/fastapi_app/logs/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    copytruncate
}

监控指标

指标	采集方式
CPU 利用率	top / htop / vmstat
内存使用	free -m
进程状态	ps aux
网络延迟	MTR / traceroute
99% 响应时间	external 接口监控

压力测试与性能评测

使用 wrk 进行压测，观察不同并发下的表现。

wrk -t4 -c500 -d60s http://example.com/health

参考数据（受网络和硬件影响）：

并发连接数	平均响应时间 (ms)	吞吐 (req/s)
100	18.5	5200
300	42.7	4800
500	96.3	3500

故障排查与常见问题

502 Bad Gateway

常见原因包括：

• Uvicorn/Gunicorn 未运行
• Nginx 配置 proxy_pass 地址错误
• 端口被防火墙阻断

超时

如果业务逻辑耗时较长，可适当调大 Gunicorn timeout，或优化代码减少阻塞调用。

后续优化建议

使用 Supervisor 管理进程

相比直接后台运行，Supervisor 能更好地管理进程生命周期。

sudo apt install supervisor
sudo nano /etc/supervisor/conf.d/fastapi.conf

内容：

[program:fastapi]
command=/opt/fastapi_app/venv/bin/gunicorn app.main:app -c /opt/fastapi_app/gunicorn_conf.py
directory=/opt/fastapi_app
autostart=true
autorestart=true
stderr_logfile=/opt/fastapi_app/logs/fastapi.err.log
stdout_logfile=/opt/fastapi_app/logs/fastapi.out.log

重载配置：

sudo supervisorctl reread
sudo supervisorctl update

HTTPS 强制 HSTS

在 Nginx SSL 配置中添加 HSTS 头，增强安全性。

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

总结

至此，你已经完成了一个基于 Ubuntu 22.04 + FastAPI + Uvicorn + Nginx 的生产级 Python Web 服务部署。这套方案涵盖了架构设计、配置细节、性能测试、日志监控等关键环节。

接下来可根据业务规模，结合 Redis 缓存、PostgreSQL 数据库以及 CI/CD 自动化部署进一步提升系统稳定性与可维护性。如需更深入的性能调优或结合 Kubernetes / Docker 部署方案，可在此基础上继续拓展。