在虚拟专用服务器（VPS）上部署FastAPI应用程序需要执行多个步骤，以确保其高效、安全且可靠地运行。本指南将引导您使用Gunicorn作为应用服务器、Nginx作为反向代理，并通过Certbot实现HTTPS加密来完成部署。以下说明主要适用于基于Ubuntu的系统。

先决条件

开始前请确保您已具备：* 准备就绪的FastAPI应用程序，包含列出所有依赖项的requirements.txt文件。 * 运行Ubuntu（或其他Debian系发行版）的VPS。 * 具备VPS的SSH访问权限。 * 已注册且指向VPS IP地址的域名（非必需，但强烈建议为HTTPS配置）。

1. 连接VPS并更新系统

首先通过SSH连接VPS，更新系统软件包列表。

ssh your_username@your_vps_ip sudo apt update && sudo apt upgrade -y 

2. 安装 Python、Pip 和虚拟环境

安装 Python 3、pip（Python 的包管理器）以及用于创建虚拟环境的 venv 模块。

sudo apt install python3 python3-pip python3-venv -y

3. 克隆您的 FastAPI 应用程序

导航至合适的目录（例如 /var/www/），并从您的版本控制系统（例如 Git）克隆 FastAPI 应用程序。

sudo mkdir -p /var/www/your_fastapi_app
cd /var/www/your_fastapi_app sudo git clone <your_repository_url> .

注意：请将your_fastapi_app和Git网址替换为您的项目信息。

出于安全考虑，建议为应用程序创建专用的非root用户。

sudo adduser your_app_user
sudo usermod -aG sudo your_app_user
sudo chown -R your_app_user:your_app_user /var/www/your_fastapi_project_name 

然后，切换到这个新用户：

su - your_app_user cd /var/www/your_fastapi_project_name

4. 设置虚拟环境并安装依赖项

为项目创建 Python 虚拟环境，并安装应用程序所需依赖项，包括 FastAPI、Gunicorn 和 Uvicorn。

python3 -m venv venv
source venv/bin/activate pip install -r requirements.txt pip install gunicorn "uvicorn[standard]" fastapi 

若未创建requirements.txt文件，可在本地开发环境中通过pip freeze > requirements.txt生成该文件。

5. 测试您的 FastAPI 应用程序（在 VPS 本地环境中）

在配置 Gunicorn 和 Nginx 之前，请使用 Uvicorn 测试您的 FastAPI 应用程序是否运行正常。

uvicorn main:app --host 0.0.0.0 --port 8000 

将 main:app 替换为实际模块和 FastAPI 应用实例名称（例如 your_app_folder.main:app）。您应能通过 http://your_vps_ip:8000 访问应用程序。按下 Ctrl+C 可停止服务器。

6. 配置 Gunicorn

Gunicorn 将作为应用服务器运行，管理 Uvicorn 工作进程以处理请求。

创建 Gunicorn 配置文件（可选但推荐）

在项目目录下创建名为gunicorn_conf.py的文件。

nano gunicorn_conf.py 

添加以下内容：

bind = "127.0.0.1:8000"
workers = 4 # 根据CPU核心数调整（通常建议每核心2-4个worker）
worker_class = "uvicorn.workers.UvicornWorker" 

workers 值可调优；常见建议为 (2 * CPU_CORES) + 1。

测试 Gunicorn

运行 Gunicorn 并加载 FastAPI 应用程序，确保其能正确启动。

gunicorn -c gunicorn_conf.py main:app 

请注意，需将main:app替换为应用程序的入口点。

7. 为 Gunicorn 创建 Systemd 服务

为确保应用程序在系统启动时自动运行并便于管理，请创建一个 Systemd 服务。

sudo nano /etc/systemd/system/your_fastapi_app.service 

添加以下内容，将占位符替换为实际值：

[Unit] Description=为 FastAPI 应用提供服务的 Gunicorn 实例
After=network.target [Service] User=your_app_user
Group=your_app_user WorkingDirectory=/var/www/your_fastapi_project_name
ExecStart=/var/www/your_fastapi_project_name/venv/bin/gunicorn -c /var/www/your_fastapi_project_name/gunicorn_conf.py main:app
Restart=always PrivateTmp=true [Install]
WantedBy=multi-user.target 

字段说明： * User 和 Group：为应用程序创建的非root用户和组。 * 工作目录：指向 FastAPI 项目目录的绝对路径。* 启动命令：启动 Gunicorn 的命令，需包含虚拟环境的 Gunicorn 可执行文件、配置文件及应用程序入口点。 * Restart=always：确保服务崩溃时自动重启。

重新加载 systemd 服务，启动服务并启用开机自启功能。

sudo systemctl daemon-reload sudo systemctl start your_fastapi_app
sudo systemctl enable your_fastapi_app 

检查状态和日志以确保其正常运行无误。

sudo systemctl status your_fastapi_app
sudo journalctl -u your_fastapi_app -f 

8. 配置 Nginx 作为反向代理

Nginx 将作为反向代理，将请求转发至 Gunicorn 应用程序，并处理静态文件及 SSL 相关事务。

安装 Nginx

sudo apt install nginx -y 

创建 Nginx 配置文件

为您的应用创建新的 Nginx 服务器块配置文件。

sudo nano /etc/nginx/sites-available/your_domain 

添加以下内容，将your_domain.com替换为实际域名，将/var/www/your_fastapi_project_name替换为项目路径：

server {  listen 80;
 server_name your_domain.com www.your_domain.com;

 location / {
 proxy_pass http://127.0.0.1:8000;  proxy_set_header Host $host;  proxy_set_header X-Real-IP $remote_addr;  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  proxy_set_header X-Forwarded-Proto $scheme;  }

 # 可选：通过 Nginx 直接提供静态文件  # location /static/ {
 # alias /var/www/your_fastapi_project_name/static/;  # } } 

启用 Nginx 配置

创建符号链接以启用配置，并测试 Nginx 语法错误。

sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/
sudo nginx -t 

如果测试成功，请重启 Nginx。

sudo systemctl restart nginx 

9. 配置防火墙（UFW）

如果启用了防火墙（例如 UFW），则需要允许 80（HTTP）和 443（HTTPS）端口的流量。

sudo ufw allow 'Nginx Full'
sudo ufw enable 

10. 使用Certbot（Let's Encrypt）实现HTTPS加密

强烈建议为应用程序启用HTTPS加密。Certbot可自动完成从Let's Encrypt获取并配置SSL证书的流程。

安装 Certbot

sudo apt install certbot python3-certbot-nginx -y

获取并安装SSL证书

sudo certbot --nginx -d your_domain.com -d www.your_domain.com 

请按提示操作。Certbot将自动修改Nginx配置并设置自动续期。

11. 检查部署状态

现在应可通过域名以 HTTPS 访问您的 FastAPI 应用。打开浏览器访问 https://your_domain.com。

故障排除提示

• 检查 Gunicorn 日志： sudo journalctl -u your_fastapi_app -f
• 检查 Nginx 错误日志： sudo tail -f /var/log/nginx/error.log
• 检查 Nginx 访问日志： sudo tail -f /var/log/nginx/access.log
• 验证 Nginx 配置： sudo nginx -t
• 确保项目目录和虚拟环境的文件权限正确
• 防火墙问题： 仔细检查 UFW 规则。

遵循这些步骤后，您将在VPS上成功部署好生产就绪的FastAPI应用程序，包含Nginx、Gunicorn及HTTPS支持。