有勇气的牛排博客
☰

gunicorn启动fastapi项目

有勇气的牛排 86 Python 2025-04-14 22:26:50

1 前言

1.1 Gunicorn 是什么？

Gunicorn（Green Unicorn）是一个 Python WSGI HTTP 服务器，用于生产环境运行 Python Web 应用（如 Flask、Django、FastAPI）。

特点：

  • 支持多进程（worker）
  • 支持日志、信号处理、守护进程等
  • 稳定高效，广泛用于部署生产环境服务

1.2 uvicorn 是什么？

Uvicorn 是一个基于 uvloop 和 httptools 的 异步 ASGI 服务器，是 FastAPI 推荐的服务器。

  • 支持异步请求处理
  • 更适合现代异步框架（如 FastAPI、Starlette）

1.3 uvicorn启动方式 vs Gunicorn 启动

项目 uvicorn.run() 启动 gunicorn + UvicornWorker 启动
用途 本地开发、调试 生产部署
启动命令 uvicorn main:app --reload gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
多进程 ❌ 单进程 ✅ 支持多 worker（并发更强）
热重载 ✅ 开发环境推荐 ❌ 默认关闭，可结合其它方案
守护进程 ❌ ✅ 支持 --daemon 后台运行
日志管理 简单 更专业、更灵活
健壮性 异常自动退出 崩溃自动重启 worker，容错强

1.4 推荐使用方式

场景 推荐方式
本地开发 uvicorn main:app --reload
生产部署 gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

本地开发推荐启动程序代码块。

if __name__ == "__main__":
    # uvicorn.run(app, host="0.0.0.0", port=8090)
    uvicorn.run(
        app,
        host="0.0.0.0",
        # port=8090,
        port=Env().port,
        timeout_keep_alive=300,  # 设置长时间的保持活跃超时（秒）
        timeout_graceful_shutdown=60,  # 设置优雅关闭的超时
    )

在生产部署中，gunicorn 启动方式更推荐通过配置文件启动。

1.5 Gunicorn 是如何支持 FastAPI 的？

Gunicorn 本身是 WSGI 服务器，而 FastAPI 是基于 ASGI 的。

因此我们使用：

gunicorn main:app -k uvicorn.workers.UvicornWorker

这里的 -k uvicorn.workers.UvicornWorker 就是使用 Uvicorn 作为 ASGI worker 适配器，让 Gunicorn 能运行 FastAPI。

2 FastAPI案例

main.py

from fastapi import FastAPI
from app.routes import router

app = FastAPI()
app.include_router(router)

routes.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def read_root():
    return {"message": "Gunicorn案例测试"}

3 requirements.txt

依赖文件

fastapi
uvicorn[standard]
gunicorn

fastapi==0.115.5
uvicorn==0.32.1
gunicorn==23.0.0

4 命令启动参考

gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
参数 说明
app.main:app 指定 FastAPI 应用位置，模块路径:对象 格式
-w 4 启动 4 个 worker（根据 CPU 核数调整）
-k uvicorn.workers.UvicornWorker 使用 Uvicorn 的异步 worker
--bind 0.0.0.0:8000 绑定端口和 IP 地址

5 通过配置文件启动

启动命令(可配合shell脚本进行一键启动)

gunicorn main:app -c gunicorn.conf.py

gunicorn.conf.py

# 应用模块路径
bind = "0.0.0.0:8000"

# worker 数量，建议 = CPU核心数 * 2 + 1
workers = 4

# 使用异步 worker 适配 FastAPI
worker_class = "uvicorn.workers.UvicornWorker"

# 日志等级
loglevel = "info"

# 日志文件（可选）
accesslog = "log/gunicorn_access.log"
errorlog = "log/gunicorn_error.log"

# 设置最大请求处理时间（秒）
timeout = 60

# 设置 pid 文件路径（可选）
pidfile = "gunicorn.pid"

# 设置守护进程（可选）
daemon = True

shell脚本授权

chmod +x start.sh
./start.sh

gunicorn启动fastapi项目

6 docker配置

6.1 Dockerfile

# 基础镜像
FROM python:3.10-slim

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY . /app

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 启动命令
CMD ["gunicorn", "app.main:app", "-c", "gunicorn.conf.py"]

6.2 docker-compose.yml

version: "3"
services:
  fastapi:
    build: .
    ports:
      - "8000:8000"
    restart: always

6.3 启动

6.3.1 构建镜像

docker build -t fastapi-app .

6.3.2 运行容器

docker run -d -p 8000:8000 --name fastapi-container fastapi-app

或者使用 docker-compose：

docker-compose up -d

留言

专栏
文章
加入群聊
程序员兼职接单交流
编程交流