在生产环境下，单纯使用 Uvicorn 监听外部请求存在性能和安全风险，因此我们采用如下部署架构：
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 以上 | 快速日志写入 |
| 网络 | 公网带宽 100Mbps | API 对外访问 |
| 系统 | Ubuntu 22.04 LTS | 最新稳定版 |
外网访问建议部署具有 DDoS 防护的 BGP 线路服务器，例如 CN2 / 电信直连方案，以降低网络抖动和丢包率。
二、系统初始化与依赖安装
2.1 系统更新
sudo apt update && sudo apt upgrade -y
sudo reboot
2.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
2.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
三、应用代码结构与示例
3.1 最简 FastAPI 项目结构
fastapi_app/
├── app/
│ ├── main.py
│ ├── api/
│ │ └── v1.py
├── requirements.txt
└── logging.conf
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 监控指标
| 指标 | 采集方式 |
|---|---|
| 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 |
结果受网络环境、服务器硬件及应用逻辑影响，上表为参考数据。
十、故障排查与常见问题
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;
