[toc]

FastAPI部署笔记

目前FastAPI的部署方式有多种，这里记录一下我常用的几种方式。

方式1：打包为可执行文件 （轻量，本地测试）

用 PyInstaller 将 FastAPI 项目（代码 + Python 解释器 + 所有依赖）打包成单个可执行文件，上传到远程服务器即可运行（无需服务器装 Python 环境）。

1. 在项目根目录下安装 PyInstaller

# 安装 PyInstaller
pip install pyinstaller

2. 编写FastAPI项目的启动脚本（如 main.py），确保项目可以正常运行。

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

3. 编写项目的启动脚本，让项目通过uvicorn服务器运行。

import uvicorn
from main import app

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8888)

4. 使用 PyInstaller 打包项目。

# 打包项目
pyinstaller --onefile --name fastapi-app start.py

打包后会在项目的 dist 目录生成 fastapi-app（Linux环境）/fastapi-app.exe（Windows环境）。

5. 部署

• 将打包后的可执行文件fastapi-app上传到远程服务器。
• 赋予执行权限：chmod +x fastapi-app；
• 在服务器上运行可执行文件即可启动 FastAPI 项目（无需服务器装 Python）。执行命令 ./fastapi-app

方式2：Docker镜像 （推荐，等价“包含运行环境的 jar包”）

将 FastAPI 项目打包为 Docker 镜像（包含 Python 环境 + 代码 + 依赖），上传到远程服务器后仅需 docker run 即可运行。

这种方式最接近 Java “一次打包、处处运行” 的理念。

1. 在项目根目录下创建 Dockerfile 文件。编写该项目的Dockerfile。

# Dockerfile
FROM python:3.10-slim  # 基础镜像，包含 Python 3.10 环境
WORKDIR /app           # 设置工作目录为 /app
COPY requirements.txt .   # 复制项目依赖文件到容器中
RUN pip install --no-cache-dir -r requirements.txt  # 安装项目依赖
COPY . .                                            # 复制项目代码到容器中
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8888"]  # 运行项目到uvicorn服务器中，监听 0.0.0.0:8888

2. 在项目根目录中执行下面命令，构建Docker镜像，并打包镜像

# 构建镜像
docker build -t fastapi-app-image .
# 导出镜像为单个文件
docker save fastapi-app-image > fastapi-app.tar

3. 上传镜像到远程服务器

# 将镜像文件上传到远程服务器
scp fastapi-app.tar root@服务器IP:/tmp/

4. 在远程服务器上加载镜像并运行容器

# 在远程服务器上，将镜像文件加载到docker中
docker load < fastapi-app.tar

# 根据镜像文件创建容器并运行
docker run -d -p 8888:8888 fastapi-app-image