Azure AKS中FastAPI基于路径的Ingress路由失效求助

切换到统一根域名+路径路由后出现404或API文档加载失败，核心原因有两个：

• Ingress未正确重写请求路径，导致后端FastAPI收到带/servicename前缀的请求，而应用本身没有对应路由
• FastAPI默认以根路径/运行，生成的OpenAPI文档、内部跳转链接仍使用根路径，与实际访问路径不匹配

1. 修改Ingress配置（路径重写） #

需要添加Nginx Ingress的路径重写注解，将带/servicename前缀的请求转换为后端服务的根路径请求：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: servicename-api-ingress
  namespace: servicename-api-prod
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-clusterissuer
    # 添加路径重写注解
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    # 启用正则匹配以支持路径分组
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: departmentname.companyname.com
    http:
      paths:
      - path: /servicename(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: servicename-api-service
            port:
              number: 80
  tls:
  - hosts:
      - departmentname.companyname.com
    secretName: servicename-api-tls

配置说明： #

• nginx.ingress.kubernetes.io/rewrite-target: /$2：将匹配到的路径分组$2（即/servicename之后的部分）转发给后端，比如/servicename/api/v1/items会被转发为/api/v1/items
• path: /servicename(/|$)(.*)：用正则匹配所有以/servicename开头的请求，包括/servicename和/servicename/xxx两种格式
• use-regex: "true"：启用正则匹配，确保路径分组规则生效

2. 调整FastAPI应用的根路径 #

FastAPI需要知道自身运行在/servicename路径下，才能生成正确的OpenAPI文档和路由链接，有两种实现方式：

方式一：启动命令中指定root-path #

修改Dockerfile的CMD命令，添加--root-path /servicename参数：

CMD ["pdm", "run", "uvicorn", "companyname.servicename.api.main:app", "--host", "0.0.0.0", "--port", "8080", "--root-path", "/servicename"]

方式二：代码中直接设置root_path #

在FastAPI实例初始化时指定root_path：

from fastapi import FastAPI

app = FastAPI(root_path="/servicename")

# 后续路由定义保持不变

3. 验证步骤 #

1. 应用新的Ingress配置：kubectl apply -f your-ingress-file.yaml
2. 重启FastAPI服务（若修改了Dockerfile，需重新构建镜像并部署）
3. 测试访问：
   • 基础路由：curl https://departmentname.companyname.com/servicename/your-api-path
   • API文档：访问https://departmentname.companyname.com/servicename/docs，确认文档能正常加载且跳转链接正确

内容的提问来源于stack exchange，提问作者h4tt3n