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

本篇技术指南聚焦 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（服务器）” 经常被用来同时指代两样东西：

概念	通常含义	常见别名	例子
服务器机器	远程/云端的计算机（物理机或虚拟机）	服务器、机器、VM（虚拟机）、节点	一台 Linux 云主机
服务器程序	跑在那台机器上的程序	—	Uvicorn、Hypercorn

在大多数语境下，“服务器”指的是“某台运行着你程序的远程计算机（通常是 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"}

常用参数速查：

参数	说明
main:app	导入字符串：模块名:对象名，等价于 from main import app
--host 0.0.0.0	监听所有网络接口（对外提供服务必须用 0.0.0.0 而非 127.0.0.1）
--port 80	监听端口；示例直接用 80 是因为在容器/服务器里由它作为最终入口（实际裸机部署通常还会在前面加一层反向代理）

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

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

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

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

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

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

主题	文档
HTTPS / TLS 终结	docs/de/docs/deployment/https.md
完整概念与示例工具（Traefik、Caddy、Systemd、Docker 等）	docs/de/docs/deployment/concepts.md
用 --workers 启动多个 Uvicorn Worker 进程	docs/de/docs/deployment/server-workers.md
Docker 容器化部署	docs/de/docs/deployment/docker.md
云端部署	docs/de/docs/deployment/cloud.md
版本管理与依赖锁定	docs/de/docs/deployment/versions.md

（上图来自 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 应用稳定地部署上线。