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

3.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

4.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"

4.2 启动命令

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

五、Nginx 反向代理配置

5.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

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

8.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
}

8.2 监控指标

九、压力测试与性能评测

使用 wrk 压测：

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

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

十、故障排查与常见问题

10.1 502 Bad Gateway

检查：

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

10.2 超时

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

十一、后续优化建议

11.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

11.2 HTTPS 强制 HSTS

在 Nginx SSL 配置中添加：

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