在代理后方¶

在许多情况下，你会在 FastAPI 应用前使用代理，如 Traefik 或 Nginx。

这些代理可以处理 HTTPS 证书和其他事项。

代理转发头信息¶

位于你应用程序前方的代理通常会在将请求发送到你的 服务器 之前动态设置一些头部信息，以让服务器知道请求被转发自代理，使其了解原始（公开）URL，包括域名，以及它正在使用 HTTPS 等。

服务器 程序（例如通过 FastAPI CLI 的 Uvicorn）能够解释这些头部信息，然后将该信息传递给你的应用程序。

但出于安全考虑，由于服务器不知道它位于可信代理后方，它不会解释这些头部信息。

技术细节

代理头部信息包括：

启用代理转发头信息¶

你可以使用 CLI 选项 --forwarded-allow-ips 启动 FastAPI CLI，并传递应被信任以读取这些转发头部信息的 IP 地址。

如果你将其设置为 --forwarded-allow-ips="*"，它将信任所有传入的 IP。

如果你的 服务器 位于可信代理后方，并且只有代理与之通信，这将使其接受该代理的任何 IP。

$ fastapi run --forwarded-allow-ips="*"

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

使用 HTTPS 的重定向¶

例如，假设你定义了一个 路径操作 /items/：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
def read_items():
    return ["plumbus", "portal gun"]

如果客户端尝试访问 /items，默认情况下，它将被重定向到 /items/。

但在设置 CLI 选项 --forwarded-allow-ips 之前，它可能会重定向到 http://localhost:8000/items/。

但也许你的应用程序托管在 https://mysuperapp.com，重定向应该指向 https://mysuperapp.com/items/。

通过设置 --proxy-headers，现在 FastAPI 将能够重定向到正确的位置。😎

https://mysuperapp.com/items/

Tip

如果你想了解更多关于 HTTPS 的信息，请查看指南关于 HTTPS。

代理转发头信息的工作原理¶

以下是代理如何在客户端和 应用程序服务器 之间添加转发头部信息的可视化表示：

sequenceDiagram
    participant Client
    participant Proxy as Proxy/Load Balancer
    participant Server as FastAPI Server

    Client->>Proxy: HTTPS 请求<br/>Host: mysuperapp.com<br/>Path: /items

    Note over Proxy: 代理添加转发头部信息

    Proxy->>Server: HTTP 请求<br/>X-Forwarded-For: [客户端 IP]<br/>X-Forwarded-Proto: https<br/>X-Forwarded-Host: mysuperapp.com<br/>Path: /items

    Note over Server: 服务器解释头部信息<br/>（如果设置了 --forwarded-allow-ips）

    Server->>Proxy: HTTP 响应<br/>包含正确的 HTTPS URL

    Proxy->>Client: HTTPS 响应

代理拦截原始客户端请求，并在将请求传递给 应用程序服务器 之前添加特殊的转发头部信息（X-Forwarded-*）。

这些头部信息保留了原本会丢失的原始请求信息：

X-Forwarded-For：原始客户端的 IP 地址
X-Forwarded-Proto：原始协议（https）
X-Forwarded-Host：原始主机（mysuperapp.com）

当 FastAPI CLI 配置了 --forwarded-allow-ips 时，它会信任这些头部信息并使用它们，例如在重定向中生成正确的 URL。

带有剥离路径前缀的代理¶

你可能有一个为你的应用程序添加路径前缀的代理。

在这种情况下，你可以使用 root_path 来配置你的应用程序。

root_path 是 ASGI 规范（FastAPI 基于 Starlette 构建）提供的一种机制。

root_path 用于处理这些特定情况。

并且在挂载子应用程序时也会在内部使用。

在这种情况下，拥有一个带有剥离路径前缀的代理意味着你可以在代码中声明一个路径 /app，但随后你在顶层添加一个层（代理），将你的 FastAPI 应用程序放在一个类似 /api/v1 的路径下。

在这种情况下，原始路径 /app 实际上将在 /api/v1/app 提供服务。

即使你所有的代码都是假设只有 /app 而编写的。

Python 3.8+

from fastapi import FastAPI, Request

app = FastAPI()


@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "root_path": request.scope.get("root_path")}

代理会在将请求传输到应用服务器（可能是通过 FastAPI CLI 的 Uvicorn）之前动态 “剥离” 路径前缀，使你的应用程序相信它正在 /app 提供服务，因此你无需更新所有代码以包含前缀 /api/v1。

到这里为止，一切都会正常工作。

但是，当你打开集成的文档 UI（前端）时，它会期望在 /openapi.json 获取 OpenAPI 模式，而不是 /api/v1/openapi.json。

因此，前端（在浏览器中运行）会尝试访问 /openapi.json 并且无法获取 OpenAPI 模式。

因为我们的应用程序有一个 /api/v1 的路径前缀代理，前端需要在 /api/v1/openapi.json 获取 OpenAPI 模式。

graph LR

browser("浏览器")
proxy["代理在 http://0.0.0.0:9999/api/v1/app"]
server["服务器在 http://127.0.0.1:8000/app"]

browser --> proxy
proxy --> server

Tip

IP 0.0.0.0 通常用于表示程序监听该机器/服务器上所有可用的 IP。

文档 UI 还需要 OpenAPI 模式来声明此 API server 位于 /api/v1（在代理后方）。例如：

{
    "openapi": "3.1.0",
    // 更多内容
    "servers": [
        {
            "url": "/api/v1"
        }
    ],
    "paths": {
            // 更多内容
    }
}

在这个例子中，“代理”可能是类似 Traefik 的东西。而服务器可能是类似 FastAPI CLI 与 Uvicorn，运行你的 FastAPI 应用程序。

提供 `root_path`¶

为了实现这一点，你可以使用命令行选项 --root-path，例如：

$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

如果你使用 Hypercorn，它也有选项 --root-path。

技术细节

ASGI 规范为此用例定义了 root_path。

而 --root-path 命令行选项提供了该 root_path。

检查当前的 `root_path`¶

你可以获取你的应用程序为每个请求使用的当前 root_path，它是 scope 字典的一部分（这是 ASGI 规范的一部分）。

这里我们将其包含在消息中仅用于演示目的。

Python 3.8+

from fastapi import FastAPI, Request

app = FastAPI()


@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "root_path": request.scope.get("root_path")}

然后，如果你启动 Uvicorn：

$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

响应将类似于：

{
    "message": "Hello World",
    "root_path": "/api/v1"
}

在 FastAPI 应用中设置 `root_path`¶

或者，如果你没有提供像 --root-path 或等效命令行选项的方法，你可以在创建 FastAPI 应用时设置 root_path 参数：

Python 3.8+

from fastapi import FastAPI, Request

app = FastAPI(root_path="/api/v1")


@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "root_path": request.scope.get("root_path")}

将 root_path 传递给 FastAPI 相当于将 --root-path 命令行选项传递给 Uvicorn 或 Hypercorn。

关于 `root_path`¶

请记住，服务器（Uvicorn）不会将该 root_path 用于任何其他用途，除了将其传递给应用程序。

但是如果你在浏览器中访问 http://127.0.0.1:8000/app，你将看到正常响应：

{
    "message": "Hello World",
    "root_path": "/api/v1"
}

因此，它不会期望在 http://127.0.0.1:8000/api/v1/app 被访问。

Uvicorn 将期望代理在 http://127.0.0.1:8000/app 访问 Uvicorn，然后代理将负责在其上添加额外的 /api/v1 前缀。

关于带有剥离路径前缀的代理¶

请记住，带有剥离路径前缀的代理只是配置方式之一。

可能在许多情况下，默认情况是代理没有剥离路径前缀。

在这种情况下（没有剥离路径前缀），代理将监听类似 https://myawesomeapp.com 的内容，然后如果浏览器访问 https://myawesomeapp.com/api/v1/app 并且你的服务器（例如 Uvicorn）监听 http://127.0.0.1:8000，代理（没有剥离路径前缀）将在相同路径访问 Uvicorn：http://127.0.0.1:8000/api/v1/app。

使用 Traefik 在本地测试¶

你可以使用 Traefik 轻松地在本地运行带有剥离路径前缀的实验。

下载 Traefik，它是一个单独的二进制文件，你可以解压缩文件并直接从终端运行它。

然后创建一个文件 traefik.toml，内容如下：

[entryPoints]
  [entryPoints.http]
    address = ":9999"

[providers]
  [providers.file]
    filename = "routes.toml"

这告诉 Traefik 监听端口 9999 并使用另一个文件 routes.toml。

Tip

我们使用端口 9999 而不是标准 HTTP 端口 80，这样你就不需要以管理员（sudo）权限运行它。

现在创建另一个文件 routes.toml：

[http]
  [http.middlewares]

    [http.middlewares.api-stripprefix.stripPrefix]
      prefixes = ["/api/v1"]

  [http.routers]

    [http.routers.app-http]
      entryPoints = ["http"]
      service = "app"
      rule = "PathPrefix(`/api/v1`)"
      middlewares = ["api-strippprefix"]

  [http.services]

    [http.services.app]
      [http.services.app.loadBalancer]
        [[http.services.app.loadBalancer.servers]]
          url = "http://127.0.0.1:8000"

此文件配置 Traefik 使用路径前缀 /api/v1。

然后 Traefik 会将其请求重定向到你在 http://127.0.0.1:8000 上运行的 Uvicorn。

现在启动 Traefik：

$ ./traefik --configFile=traefik.toml

INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml

现在使用 --root-path 选项启动你的应用：

$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

检查响应¶

现在，如果你访问带有 Uvicorn 端口的 URL：http://127.0.0.1:8000/app，你将看到正常响应：

{
    "message": "Hello World",
    "root_path": "/api/v1"
}

Tip

请注意，即使你在 http://127.0.0.1:8000/app 访问它，它也会显示 root_path 为 /api/v1，取自选项 --root-path。

现在打开带有 Traefik 端口的 URL，包括路径前缀：http://127.0.0.1:9999/api/v1/app。

我们得到相同的响应：

{
    "message": "Hello World",
    "root_path": "/api/v1"
}

但这次是在代理提供的带有前缀路径的 URL：/api/v1。

当然，这里的想法是每个人都会通过代理访问应用程序，因此带有路径前缀 /api/v1 的版本是“正确”的。

而没有路径前缀的版本（http://127.0.0.1:8000/app），由 Uvicorn 直接提供，将专门用于代理（Traefik）访问它。

这演示了代理（Traefik）如何使用路径前缀以及服务器（Uvicorn）如何使用来自选项 --root-path 的 root_path。

检查文档 UI¶

但这里是有趣的部分。✨

访问应用程序的“官方”方式是通过我们定义的带有路径前缀的代理。因此，正如我们所期望的，如果你尝试由 Uvicorn 直接提供、URL 中没有路径前缀的文档 UI，它将无法工作，因为它期望通过代理访问。

你可以在 http://127.0.0.1:8000/docs 检查它：

但如果我们通过代理使用端口 9999 在“官方”URL /api/v1/docs 访问文档 UI，它会正确工作！🎉

你可以在 http://127.0.0.1:9999/api/v1/docs 检查它：

正如我们所期望的。✔️

这是因为 FastAPI 使用这个 root_path 来创建 OpenAPI 中的默认 server，并使用 root_path 提供的 URL。

附加服务器¶

Warning

这是一个更高级的用例。可以随意跳过。

默认情况下，FastAPI 将在 OpenAPI 模式中创建一个带有 root_path URL 的 server。

但你也可以提供其他替代的 servers，例如，如果你希望 相同的 文档 UI 与暂存和生产环境交互。

如果你传递一个自定义的 servers 列表，并且存在 root_path（因为你的 API 位于代理后方），FastAPI 将在列表开头插入一个带有此 root_path 的“服务器”。

例如：

Python 3.8+

from fastapi import FastAPI, Request

app = FastAPI(
    servers=[
        {"url": "https://stag.example.com", "description": "Staging environment"},
        {"url": "https://prod.example.com", "description": "Production environment"},
    ],
    root_path="/api/v1",
)


@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "root_path": request.scope.get("root_path")}

将生成类似以下的 OpenAPI 模式：

{
    "openapi": "3.1.0",
    // 更多内容
    "servers": [
        {
            "url": "/api/v1"
        },
        {
            "url": "https://stag.example.com",
            "description": "暂存环境"
        },
        {
            "url": "https://prod.example.com",
            "description": "生产环境"
        }
    ],
    "paths": {
            // 更多内容
    }
}

Tip

请注意自动生成的服务器，其 url 值为 /api/v1，取自 root_path。

在 http://127.0.0.1:9999/api/v1/docs 的文档 UI 中，它将看起来像：

Tip

文档 UI 将与你选择的服务器交互。

禁用来自 `root_path` 的自动服务器¶

如果你不希望 FastAPI 包含使用 root_path 的自动服务器，你可以使用参数 root_path_in_servers=False：

Python 3.8+

from fastapi import FastAPI, Request

app = FastAPI(
    servers=[
        {"url": "https://stag.example.com", "description": "Staging environment"},
        {"url": "https://prod.example.com", "description": "Production environment"},
    ],
    root_path="/api/v1",
    root_path_in_servers=False,
)


@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "root_path": request.scope.get("root_path")}

然后它不会将其包含在 OpenAPI 模式中。

挂载子应用程序¶

如果你需要在同时使用带有 root_path 的代理时挂载子应用程序（如子应用程序 - 挂载中所述），你可以正常进行，如你所期望的那样。

FastAPI 将在内部智能地使用 root_path，因此它将正常工作。✨

在代理后方¶

代理转发头信息¶

启用代理转发头信息¶

使用 HTTPS 的重定向¶

代理转发头信息的工作原理¶

带有剥离路径前缀的代理¶

提供 root_path¶

检查当前的 root_path¶

在 FastAPI 应用中设置 root_path¶

关于 root_path¶

关于带有剥离路径前缀的代理¶

使用 Traefik 在本地测试¶

检查响应¶

检查文档 UI¶

附加服务器¶

禁用来自 root_path 的自动服务器¶

挂载子应用程序¶

提供 `root_path`¶

检查当前的 `root_path`¶

在 FastAPI 应用中设置 `root_path`¶

关于 `root_path`¶

禁用来自 `root_path` 的自动服务器¶