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

应用代码结构与示例

最简 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
}

监控指标

压力测试与性能评测

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

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

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

故障排查与常见问题

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 部署方案，可在此基础上继续拓展。