如何在宝塔面板部署FastAPI应用_使用Gunicorn结合Uvicorn运行-php教程-PHP中文网

宝塔中gunicorn启动fastapi未生效，主因是worker_class未正确设为uvicorn.workers.uvicornworker，需在配置页手动指定并重启项目，同时确保uvicorn[standard]已安装、端口与反向代理一致。

如何在宝塔面板部署fastapi应用_使用gunicorn结合uvicorn运行

宝塔里选 Gunicorn 启动方式但没生效？检查 worker_class 是否被覆盖

宝塔 Python 项目管理器默认会写入一个 worker_class 配置，常见值是 geventwebsocket.gunicorn.workers.GeventWebSocketWorker 或空值。如果没手动改，Gunicorn 实际运行的是同步 worker，FastAPI 请求会卡住或报 RuntimeWarning: coroutine 'app' was never awaited。

必须进入项目「配置」页，找到 worker_class 这一项，明确改成：

uvicorn.workers.UvicornWorker

注意大小写和点号不能错——UvicornWorker 的 U 和 W 必须大写，少一个字母或写成下划线都会回退到 sync 模式，且无明显报错。

改完后务必先「停止项目」再「启动」，重启不生效
如果配置页看不到 worker_class 字段，说明宝塔版本较旧，需在项目根目录手动添加 gunicorn.conf.py 文件并填入 worker_class = "uvicorn.workers.UvicornWorker"
确认 uvicorn[standard] 已安装（不是只装 uvicorn），否则 UvicornWorker 类根本不存在

启动命令里的 --bind 端口和宝塔反向代理怎么对齐

宝塔 Python 项目管理器的「启动命令」框里填的不是 uvicorn 命令，而是 gunicorn 命令；其中 --bind 指定的是 Gunicorn 监听的内部端口，这个端口必须和后续「反向代理」规则的目标端口完全一致。

例如你在启动命令中写了：

gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:22201

那么反向代理就必须设为：目标 URL 填 http://127.0.0.1:22201（不能写 localhost，宝塔某些版本解析失败）。

端口号建议避开 1–1024 和常用服务端口（如 8000、8080），选 20000 以上更稳妥
--bind 不要加 https 或域名，只能是 IP:PORT 格式；HTTPS 全由 Nginx 反向代理层处理
如果启动后日志里反复出现 Connection refused，优先检查这个端口是否被其他进程占用（lsof -i :22201）

为什么用 Gunicorn 包一层 Uvicorn，而不是直接跑 Uvicorn

Uvicorn 单进程异步能力强，但生产环境不能只靠它：uvicorn main:app --reload --host 0.0.0.0 --port 8000 只适合开发调试。上线后必须用 Gunicorn 管理进程生命周期。

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

核心差异在三件事：

崩溃隔离：一个 Uvicorn worker 崩溃，Gunicorn 自动拉起新进程，不影响其他 worker
平滑重启：发 SIGUSR2 信号可滚动更新代码，用户无感知；Uvicorn 本身不支持
资源限制：Gunicorn 可配 --max-requests、--timeout 防内存泄漏，Uvicorn 命令行没这些

别被「ASGI 服务器」名头误导——Uvicorn 不是运维级服务组件，它只是协议实现；Gunicorn 才是那个真正扛住线上流量的守门人。

requirements.txt 安装失败或模块找不到？重点查 Python 路径和虚拟环境

宝塔创建 Python 项目时会自动建虚拟环境，路径类似 /www/wwwroot/fastapi_project/venv。但如果「Python 版本」选错（比如项目用 3.10，却选了面板里 3.8 的解释器），或「启动用户」设为 www 但 pip 安装时用了 root，就会出现 ModuleNotFoundError: No module named 'fastapi'。

验证方法：进项目根目录，执行：

source venv/bin/activate && python -c "import fastapi; print(fastapi.__version__)"

如果报错，说明环境没激活或包没装对。

勾选「是否安装模块依赖」后，宝塔调用的是虚拟环境里的 pip，不是系统 pip
确保 requirements.txt 在项目根目录，且第一行不要有空格或 BOM 头
若依赖含编译型包（如 numpy），宝塔需提前安装 gcc、python3-devel 等系统依赖

最常被忽略的一点：Gunicorn 启动时读取的是项目目录下的 venv，不是你本地开发机的环境——哪怕代码一模一样，缺一个 uvicorn[standard] 就会静默降级成同步模式。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！