FastAPI部署在AWS ALB后root-path配置异常问题咨询

你的问题核心在于AWS ALB的路径转发行为和对FastAPI --root-path参数的作用误解：

1. ALB监听器规则用/api/v1/匹配路径时，默认会完整保留该路径前缀转发给后端应用。也就是说，当你访问ALB域名/api/v1/时，ALB实际发送给FastAPI的请求路径是/api/v1/，而非去掉前缀后的/。
2. FastAPI的--root-path参数并非用来修改请求路径的匹配逻辑，它的作用是告知应用自身被部署在反向代理的/api/v1路径下，主要用于生成正确的OpenAPI文档链接、自动重定向等场景，不会把传入的/api/v1/路径映射到应用的根路径/。

所以当请求带着/api/v1/到达FastAPI时，它会直接匹配你代码里定义的@app.get("/api/v1/")端点，这就是你看到当前响应的原因。

你有两种可选方案，无需手动给所有端点硬编码/api/v1前缀：

方案一：修改ALB监听器规则，添加路径重写 #

把ALB的监听器规则从单纯的路径匹配，改成路径重写：

• 将路径模式设置为/api/v1/*
• 配置重写规则为/$1（即去掉/api/v1前缀，把剩余路径转发给后端）

配置完成后：

• 用户访问ALB域名/api/v1/时，ALB会转发/给FastAPI，匹配根路径@app.get("/")端点
• 用户访问ALB域名/api/v1/xxx时，ALB会转发/xxx给FastAPI，匹配应用里的@app.get("/xxx")端点

方案二：用FastAPI的APIRouter统一添加前缀 #

如果不想修改ALB配置，可以在代码里用APIRouter给所有端点统一加上前缀，同时保留--root-path配置：

from typing import Union
from fastapi import FastAPI, APIRouter

# 创建带前缀的路由
router = APIRouter(prefix="/api/v1")

@router.get("/")
def read_root():
    print("Root path hit")
    return {"App": "Fargate"}

# 其他端点统一挂载到该路由下
@router.get("/test")
def test_endpoint():
    return {"msg": "Test"}

# 将路由挂载到主应用
app = FastAPI()
app.include_router(router)

这种方式下，ALB转发的/api/v1/会直接匹配router的根路径，同时--root-path参数依然能正确生成文档路径。

不需要手动给每个端点都添加/api/v1前缀，上述两种方案都能优雅解决路径匹配问题。如果选择方案一，记得保持FastAPI代码里只有根路径/的端点，避免路径冲突。

内容的提问来源于stack exchange，提问作者Muhammad Raihan Muhaimin