如何在服务器 Ubuntu 22.04 上部署 FastAPI + Uvicorn + Nginx 生产级 Python Web 服务指南

本文从基础环境准备、部署架构设计、性能调优、安全配置到监控指标采集，全流程讲解如何在 Ubuntu 22.04 服务器 上构建一个可用于生产环境的 FastAPI + Uvicorn + Nginx Python Web 服务平台。A5数据重点聚焦实战细节、系统参数配置、性能评测与问题排查方法，适合有一定 Linux / 网络 / Python 经验的开发与运维人员阅读。

一、目标架构与适用场景

在生产环境下，单纯使用 Uvicorn 监听外部请求存在性能和安全风险，因此我们采用如下部署架构：

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

适用场景包括：

• 高并发 API 服务
• 微服务架构中 HTTP 接口部署
• 需要TLS/HTTPS安全访问的生产环境

二、香港服务器www.a5idc.com硬件与系统建议

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

三、系统初始化与依赖安装

3.1 系统更新

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

3.2 安装 Python 环境与必备工具

# 安装 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

3.3 建立虚拟环境

进入应用目录 /opt/fastapi_app：

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

四、应用代码结构与示例

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;

结语

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

如需更深入的性能调优或结合 Kubernetes / Docker 部署方案，也可以在此基础上拓展讨论。