FastAPI 手动运行生产服务器：从 fastapi run 到 ASGI 服务器与 Uvicorn 部署要点

FastAPI 手动运行生产服务器：从 fastapi run 到 ASGI 服务器与 Uvicorn 部署要点

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

本篇技术指南聚焦 FastAPI 部署章节中的“手动运行服务器”这一核心路径：如何使用fastapi run一条命令启动生产服务器、理解 ASGI 协议与 ASGI 服务器程序（Uvicorn 等）的角色、手动安装并直接运行 Uvicorn 的方式，以及生产部署前必须权衡的六大 Deployment 概念。读完本文，你将能够独立在任意一台服务器或容器中把 FastAPI 应用跑起来，并能结合源码确认fastapi命令背后的实现与依赖关系。

一、使用fastapi run命令启动服务器

最直接的方式，就是用fastapi run来运行你的 FastAPI 应用：

$ fastapi run main.py FastAPI Starting production server 🚀 Searching for package file structure from directories with __init__.py files Importing from /home/user/code/awesomeapp module 🐍 main.py code Importing the FastAPI app object from the module with the following code: from main import app app Using import string: main:app server Server started at http://0.0.0.0:8000 server Documentation at http://0.0.0.0:8000/docs Logs: INFO Started server process [2306215] INFO Waiting for application startup. INFO Application startup complete. INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

在绝大多数场景下，这一条命令就够了。😎 你可以在容器里、在服务器上、在 CI 的某个步骤中使用这个命令来启动你的FastAPI应用。

从输出可以读出几个关键信息：

• module/code/app三行：CLI 先找到目标模块（main.py），再从中导入名为app的 FastAPI 对象，最终使用导入字符串main:app；
• server两行：服务器监听http://0.0.0.0:8000，自动生成的交互式文档在http://0.0.0.0:8000/docs；
• 日志部分：Uvicorn 完成了 ASGI 应用的生命周期启动（Waiting for application startup.→Application startup complete.）。

注意Starting production server的提示：fastapi run默认走的是生产模式（不带--reload），而开发时应使用fastapi dev。两者的对比在官方文档中有详细说明（见 测试与部署相关章节 的导航）。

源码印证：fastapi命令入口

fastapi这个可执行命令由当前仓库的打包配置注册。在 pyproject.toml 中：

[project.scripts] fastapi = "fastapi.cli:main"

它指向 fastapi/cli.py 中的main()。这个文件的实现非常简短（fastapi/cli.py）：

try: from fastapi_cli.cli import main as cli_main except ImportError: # pragma: no cover cli_main = None # type: ignore # ty: ignore[unused-ignore-comment] def main() -> None: if not cli_main: # type: ignore[truthy-function] message = 'To use the fastapi command, please install "fastapi[standard]":\n\n\tpip install "fastapi[standard]"\n' print(message) raise RuntimeError(message) # noqa: B904 cli_main()

可以读出两点事实：

1. 核心 CLI 逻辑不在本仓库，而在独立的fastapi-cli包中。FastAPI 仓库只保留一个薄薄的转发层，把run、dev等子命令委托给fastapi_cli.cli.main；
2. 如果未安装fastapi-cli（例如只装了 FastAPI 本体），fastapi命令会打印安装提示并抛出RuntimeError，提示执行pip install "fastapi[standard]"。

而 tests/test_fastapi_cli.py 中恰好覆盖了这两条路径：test_fastapi_cli验证python -m fastapi dev对不存在文件会报错Path does not exist non_existent_file.py；test_fastapi_cli_not_installed验证缺失fastapi-cli时抛出包含To use the fastapi command, please install的异常。

二、ASGI 服务器：理解底层协议

接下来深入一点细节。

FastAPI 采用一个用于构建 Python Web 框架和服务器的标准，称为ASGI（Asynchronous Server Gateway Interface，异步服务器网关接口）。FastAPI 本身就是一个 ASGI Web 框架——你的应用代码（FastAPI()实例）并不直接处理网络 IO，而是通过 ASGI 接口被一个具体的ASGI 服务器程序（如Uvicorn）加载运行。

要在远程服务器上运行一个FastAPI应用（或任何 ASGI 应用），你需要一个 ASGI 服务器程序，fastapi命令内置使用的是 Uvicorn。仓库中还有其他可选的 ASGI 服务器：

• Uvicorn：高性能 ASGI 服务器，fastapi run的默认选择；
• Hypercorn：兼容 HTTP/2 与 Trio 的 ASGI 服务器；
• Daphne：为 Django Channels 开发的 ASGI 服务器；
• Granian：面向 Python 应用的 Rust HTTP 服务器。

具体项目里用哪一个，取决于你的需求（协议支持、生态、性能特征等）；后文的安装与运行流程对任意 ASGI 服务器都类似，细节以各服务器自己的文档为准。

三、术语辨析：服务器机器 vs 服务器程序

文档特别提醒一个容易混淆的命名细节。💡

单词“Server（服务器）”经常被用来同时指代两样东西：

在大多数语境下，“服务器”指的是“某台运行着你程序的远程计算机（通常是 Linux）”，而 Uvicorn 这类程序是跑在上面的“服务器程序”。理解这个区分后，阅读后续 Deployment 概念（进程、Worker、内存）时会顺很多。

四、手动安装 ASGI 服务器程序

安装 FastAPI 时，standard额外依赖里已经带上了生产服务器 Uvicorn，你可以直接通过fastapi run启动它。但也可以手动安装一个 ASGI 服务器程序，以获得更精细的控制。

例如安装 Uvicorn：

$ uv add "uvicorn[standard]" ---> 100%

其他 ASGI 服务器程序的安装流程与之类似。

Tip：加上[standard]后缀，Uvicorn 会安装并使用一组推荐附加依赖，其中包括uvloop——asyncio的高性能 Drop-in 替代品，能带来显著的并发性能提升。

这一点可以直接在仓库的依赖声明中得到印证。pyproject.toml 中standard额外依赖包含：

standard = [ "fastapi-cli[standard] >=0.0.32", "fastar >= 0.9.0", # For the test client "httpx >=0.23.0,<1.0.0", # For templates "jinja2 >=3.1.5", # For forms and file uploads "python-multipart >=0.0.18", # To validate email fields "email-validator >=2.0.0", # Uvicorn with uvloop "uvicorn[standard] >=0.12.0", # # Settings management "pydantic-settings >=2.0.0", # # Extra Pydantic data types "pydantic-extra-types >=2.0.0", ]

也就是说，如果你用uv add "fastapi[standard]"安装 FastAPI，uvicorn[standard]（含uvloop）已经随包就位，无需再单独安装。而 FastAPI 的核心依赖（pyproject.toml）只有starlette、pydantic、typing-extensions、typing-inspection、annotated-doc——服务器程序不属于核心依赖，这正是“手动安装 ASGI 服务器”这一节存在的原因。

五、手动运行 ASGI 服务器程序

手动安装了 ASGI 服务器后，通常需要传一个特定格式的导入字符串（import string），让服务器找到你的 FastAPI 应用：

$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)

Note：uvicorn main:app中——

• main：指main.py这个 Python“模块”（文件）；
• app：指在main.py里通过app = FastAPI()创建的那个对象。

它等价于：

from main import app

这里引用的main.py就是官方“First Steps”示例（docs_src/first_steps/tutorial001_py310.py）里的最小应用：

from fastapi import FastAPI app = FastAPI() @app.get("/") async def root(): return {"message": "Hello World"}

常用参数速查：

Warning：Uvicorn 等服务器支持--reload选项，在开发期很有用，但它消耗更多资源、稳定性也更差。不要在生产环境中使用--reload。

其他 ASGI 服务器程序都有类似的运行命令，可在各自文档中查阅。

六、Deployment 概念清单：单进程启动之后的事

以上示例都是让服务器程序（如 Uvicorn）以单个进程运行，监听所有 IP（0.0.0.0）上的某个预定义端口（如80）。这是最基本的形态。但在真正的生产环境中，通常还需要处理下面这些概念：

• 安全 – HTTPS；
• 开机自启（Beim Hochfahren ausführen）；
• 自动重启（Neustarts）；
• 复制/Replikation（同时运行的进程数）；
• 内存；
• 启动前的前置步骤（如数据库迁移）。

这些概念与具体的服务器程序无关，而是对任何 Web API 都成立的运维问题。仓库中的后续章节逐一给出具体策略，可按此路线深入：

（上图来自 Deployment 概念章节：一个操作系统里可以同时运行同一程序的多个进程——这是理解 Worker 复制的基础。）

在概念层面，与本文最直接相关的两点是（详见 docs/de/docs/deployment/concepts.md）：

• 一个端口只能被一个进程监听：因此“多进程”方案中必须有一个进程管理器独占该 IP+端口，再把请求分发给各 Worker；Uvicorn 的--workers模式正是“一个 Uvicorn 父进程监听端口、拉起多个 Uvicorn Worker 进程”的结构。server-workers 章节 给出了fastapi run --workers 4 main.py与uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4两种写法及对应日志；
• 内存按进程独立占用：多个进程通常不共享内存。如果代码加载了一个 1 GB 的模型，4 个 Worker 就会占用约 4 GB RAM——规划 Worker 数量时必须把“每个进程的内存足迹 × 进程数”算进服务器容量。

七、小结：一条命令到一套生产策略

把本文的主线串起来：

1. fastapi run main.py是默认推荐的生产启动方式，它经由 pyproject.toml 注册的入口转发到fastapi-cli包，自动发现main:app并启动 Uvicorn，监听0.0.0.0:8000（见 fastapi/cli.py 与 tests/test_fastapi_cli.py）；
2. FastAPI 是 ASGI 框架，任何 ASGI 服务器（Uvicorn、Hypercorn、Daphne、Granian）都可以承载它；fastapi[standard]已含uvicorn[standard]（带uvloop性能优化），也可以uv add "uvicorn[standard]"手动安装；
3. 手动运行 Uvicorn 时使用导入字符串main:app（等价于from main import app），配合--host 0.0.0.0与--port指定监听地址；生产环境禁用--reload；
4. 单进程启动只是起点，HTTPS、开机自启、自动重启、进程复制、内存与启动前步骤这六类 Deployment 概念需要组合后续章节的策略（--workers、Docker、反向代理、Systemd 等）来完整解决。

掌握这条从“一条命令”到“一套策略”的路径，就能在任何服务器或容器环境中把 FastAPI 应用稳定地部署上线。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi