面向0基础的FastAPI教程：7.部署上线 —— 让系统 “跑在服务器上”

前面七篇我们完成了开发阶段的所有工作：接口写好了、认证做了、日志和测试也有了。现在要进入部署阶段—— 把代码从本地电脑搬到服务器上，让别人能通过域名访问你的系统（比如https://your-domain.com）。

一、先搞懂：企业级部署需要什么？

想象一下：你开了家奶茶店，本地研发了 “奶茶配方”（代码），现在要开分店（服务器）—— 你需要：

对应到技术上，企业级部署的核心组件是：

• Docker：打包应用和环境，确保 “一次构建，到处运行”；
• Uvicorn：FastAPI 的官方 ASGI 服务器（处理高并发请求）；
• Nginx：反向代理（处理静态文件、负载均衡、HTTPS）；
• SSL 证书：让接口用 HTTPS，加密传输数据。

二、部署前的准备

1. 服务器准备

• 买一台云服务器（比如阿里云、腾讯云，选 Ubuntu 22.04 系统，2 核 4G 足够起步）；
• 域名（比如your-domain.com，阿里云 / 腾讯云可以买，然后解析到服务器 IP）。

2. 安装 Docker 和 Docker Compose

Docker 是 “集装箱”，把应用和依赖打包在一起；Docker Compose 是 “集装箱管理器”，管理多个容器（比如 FastAPI、MySQL、Redis）。

（1）安装 Docker（Ubuntu 系统）

# 更新软件源
sudo apt update
# 安装依赖
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
# 添加Docker的GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加Docker软件源
echo "deb [arch=$(dpkg –print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
# 验证Docker是否安装成功（输出Docker版本）
docker –version

（2）安装 Docker Compose

# 下载Docker Compose（版本号可以换最新的，看https://github.com/docker/compose/releases）
sudo curl -L "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# 给执行权限
sudo chmod +x /usr/local/bin/docker-compose
# 验证（输出版本号）
docker-compose –version

三、打包 FastAPI 应用为 Docker 镜像

1. 编写 Dockerfile（核心配置）

Dockerfile 是 “集装箱的建造说明书”，告诉 Docker 怎么打包你的应用。在项目根目录创建Dockerfile：

# 第一阶段：构建依赖（用Python 3.11的官方镜像，体积小）
FROM python:3.11-slim AS builder

# 设置工作目录
WORKDIR /app

# 安装系统依赖（比如gcc，用于编译Python包）
RUN apt update && apt install -y –no-install-recommends gcc python3-dev libpq-dev

# 复制 requirements.txt 到容器
COPY requirements.txt .

# 安装Python依赖到venv（虚拟环境，减少镜像体积）
RUN python -m venv /venv
RUN /venv/bin/pip install –upgrade pip
RUN /venv/bin/pip install -r requirements.txt –no-cache-dir

# 第二阶段：运行应用（用更轻的镜像，体积更小）
FROM python:3.11-slim AS runner

# 设置工作目录
WORKDIR /app

# 从第一阶段复制venv和代码
COPY –from=builder /venv /venv
COPY . .

# 设置环境变量（告诉FastAPI用生产模式）
ENV PYTHONUNBUFFERED=1 \\
PYTHONDONTWRITEBYTECODE=1 \\
PATH="/venv/bin:$PATH"

# 暴露端口（FastAPI运行在8000端口）
EXPOSE 8000

# 启动命令（用Uvicorn运行FastAPI，配置生产参数）
CMD ["uvicorn", "main:app", "–host", "0.0.0.0", "–port", "8000", "–workers", "4", "–proxy-headers", "–forwarded-allow-ips", "*"]

2. 关键配置解释

• 多阶段构建：第一阶段（builder）安装依赖，第二阶段（runner）只复制需要的文件（venv 和代码）—— 这样镜像体积能从几百 MB 缩小到几十 MB；
• 虚拟环境（venv）：隔离 Python 依赖，避免和系统 Python 冲突；
• Uvicorn 参数：
  • –workers 4：启动 4 个工作进程（根据服务器 CPU 核心数调整，比如 2 核用 2，4 核用 4）；
  • –proxy-headers：让 Uvicorn 信任 Nginx 的代理头（比如真实 IP）；
  • –forwarded-allow-ips "*"：允许所有 IP 的代理（生产环境可以限制为 Nginx 的 IP）。

3. 编写 docker-compose.yml（管理多容器）

如果你的系统依赖MySQL或Redis（比如缓存），可以用docker-compose一起管理。创建docker-compose.yml：

version: "3.8"

services:
# FastAPI应用容器
fastapi-app:
build: . # 用当前目录的Dockerfile构建镜像
container_name: fastapi-app
restart: always # 容器挂了自动重启
ports:
– "8000:8000" # 服务器8000端口映射到容器8000端口
environment:
– DATABASE_URL=mysql+pymysql://root:your-db-password@mysql:3306/fastapi_perm_db # 数据库连接（mysql是容器名）
– JWT_SECRET_KEY=your-jwt-secret-key
depends_on:
– mysql # 先启动MySQL再启动FastAPI

# MySQL数据库容器
mysql:
image: mysql:8.0
container_name: mysql
restart: always
environment:
– MYSQL_ROOT_PASSWORD=your-db-password # 根密码
– MYSQL_DATABASE=fastapi_perm_db # 自动创建数据库
volumes:
– mysql-data:/var/lib/mysql # 数据持久化（容器删了数据不丢）
ports:
– "3306:3306" # 服务器3306端口映射到容器3306端口（可选，方便本地连接）

volumes:
mysql-data: # 持久化MySQL数据的卷

四、服务器部署操作

1. 上传代码到服务器

用git或scp把代码传到服务器（比如用git clone https://github.com/yourname/fastapi-perm-system.git）。

2. 构建并启动容器

在服务器的项目根目录运行：

# 构建镜像并启动容器（-d表示后台运行）
docker-compose up -d –build

3. 验证容器是否运行

# 查看容器状态（应该都是up）
docker-compose ps

# 查看FastAPI日志（有没有报错）
docker logs -f fastapi-app

五、配置 Nginx：做 “反向代理” 和 “HTTPS”

现在 FastAPI 运行在服务器的8000端口（比如http://your-server-ip:8000），但用户习惯用http://your-domain.com（80 端口）或https://your-domain.com（443 端口）访问 —— 这需要Nginx做 “反向代理”：把用户的请求转发给 FastAPI 容器。

1. 安装 Nginx

sudo apt update
sudo apt install -y nginx

2. 编写 Nginx 配置文件

创建/etc/nginx/conf.d/fastapi.conf（替换your-domain.com为你的域名）：

server {
listen 80; # 监听80端口（HTTP）
server_name your-domain.com www.your-domain.com; # 你的域名

# 把所有HTTP请求转发到HTTPS
return 301 https://$host$request_uri;
}

server {
listen 443 ssl; # 监听443端口（HTTPS）
server_name your-domain.com www.your-domain.com;

# SSL证书配置（后面用certbot自动生成）
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

# 反向代理配置：把请求转发给FastAPI容器
location / {
proxy_pass http://localhost:8000; # FastAPI运行在服务器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; # 告诉FastAPI用的是HTTPS
}

# 静态文件配置（如果有前端静态文件，比如Vue/React打包后的dist）
# location /static/ {
# root /path/to/your/static/files;
# expires 30d; # 静态文件缓存30天
# }
}

3. 申请 SSL 证书（HTTPS）

用Let's Encrypt（免费证书）给域名加 HTTPS：

# 安装certbot（Let's Encrypt的客户端）
sudo apt install certbot python3-certbot-nginx

# 申请证书（自动配置Nginx）
sudo certbot –nginx -d your-domain.com -d www.your-domain.com

4. 验证 Nginx 配置

# 检查Nginx配置是否正确
sudo nginx -t

# 重启Nginx生效
sudo systemctl restart nginx

六、最终验证：访问你的系统

现在，打开浏览器输入你的域名（比如https://your-domain.com）：

七、常见问题排查

1. 容器启动失败（docker-compose ps 显示 exited）

• 原因：环境变量错误（比如DATABASE_URL的密码不对），或端口被占用；
• 解决：
• 看日志：docker logs -f fastapi-app，找错误原因（比如 “Can't connect to MySQL”）；
• 检查docker-compose.yml的environment配置（比如MYSQL_ROOT_PASSWORD是否和DATABASE_URL一致）。

2. 域名访问不了（显示 “无法访问此网站”）

• 原因：服务器防火墙没开 80/443 端口，或域名没解析到服务器 IP；
• 解决：
• 检查防火墙：sudo ufw allow 80/tcp（允许 HTTP）、sudo ufw allow 443/tcp（允许 HTTPS）；
• 检查域名解析：用ping your-domain.com看是否指向服务器 IP。

3. 接口返回 “502 Bad Gateway”

• 原因：Nginx 找不到 FastAPI 容器（比如 FastAPI 挂了，或端口映射错误）；
• 解决：
• 检查 FastAPI 容器状态：docker-compose ps—— 如果是 exited，重启容器：docker-compose restart fastapi-app；
• 检查 Nginx 配置的proxy_pass是否正确（比如http://localhost:8000是否和 FastAPI 的端口一致）。

八、总结：这篇我们做了什么？

最后：部署后的 “运维小技巧”

到这里，整个FastAPI 企业级项目实战系列就结束了！从 “Hello World” 到 “上线运行”，我们完成了一个完整的企业级系统开发流程。