Ubuntu 22.04 部署 FastAPI + Uvicorn + Nginx 生产级 Python Web 服务

四、应用代码结构与示例

4.1 最简 FastAPI 项目结构

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

4.2 示例代码

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

5.1 Gunicorn + Uvicorn 配置

创建启动脚本 gunicorn_conf.py：

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"

5.2 启动命令

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

六、Nginx 反向代理配置

6.1 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/;
    }
}

启用配置：

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

九、日志、监控与性能指标

9.1 日志策略

# 日志目录 /opt/fastapi_app/logs/
# Nginx access log /var/log/nginx/access.log

可结合 logrotate 做定期清理：

sudo nano /etc/logrotate.d/fastapi

内容示例：

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

9.2 监控指标

十、压力测试与性能评测

使用 wrk 压测：

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

结果受网络环境、服务器硬件及应用逻辑影响，上表为参考数据。

十一、故障排查与常见问题

11.1 502 Bad Gateway

检查：

• Uvicorn/Gunicorn 是否运行
• Nginx 配置 proxy_pass 是否正确
• 端口是否被防火墙阻断

11.2 超时

Gunicorn timeout 可适当调大，或优化业务逻辑减少阻塞调用。

十二、后续优化建议

12.1 使用 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

12.2 HTTPS 强制 HSTS

在 Nginx SSL 配置中添加：

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

结语

通过本教程，你已经完成了一个基于 Ubuntu 22.04 + FastAPI + Uvicorn + Nginx 的生产级 Python Web 服务部署，涵盖架构设计、配置细节、性能测试、日志监控等关键内容。接下来可根据业务规模，结合 Redis 缓存、PostgreSQL 数据库以及 CI/CD 自动化部署进一步提升系统稳定性与可维护性。