使用代理请求FastAPI服务器返回503错误的排查求助

核心问题定位 #

代理请求返回503，本质是FastAPI服务未正确识别代理传递的请求，或CI环境下网络连通性配置存在偏差——毕竟代理本身已验证可用，问题出在FastAPI侧的请求接收规则或网络配置上。

具体解决方案 #

1. 让FastAPI信任代理来源 #

FastAPI默认不会信任外部代理的请求头，需显式开启代理信任配置，确保能识别代理传递的真实请求信息。修改main.py：

from fastapi import FastAPI, Request
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()

# 开启代理信任，允许解析X-Forwarded-*系列头
app.state.trust_proxy = True

# 添加主机信任中间件，CI环境可放宽限制
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["*"]  # 生产环境需替换为具体域名，CI环境临时用通配符
)

@app.get("/")
async def root():
    return {"status": "ok"}

# 可选：添加接口验证代理头是否正确传递
@app.get("/check-proxy")
async def check_proxy(request: Request):
    return {
        "client_ip": request.client.host,
        "forwarded_for": request.headers.get("X-Forwarded-For")
    }

2. 调整Docker容器网络配置（针对docker-compose启动的FastAPI） #

确保FastAPI容器使用桥接网络，且允许代理IP访问。修改docker-compose.yml：

version: '3.8'
services:
  fastapi-test:
    build: .
    ports:
      - "8000:8000"
    networks:
      - test-net
    environment:
      - FORWARDED_ALLOW_IPS=*  # 允许所有代理IP，CI环境可指定代理具体IP

networks:
  test-net:
    driver: bridge

3. CI/CD任务中指定正确的FastAPI访问地址 #

下载器作为独立CI任务，不能用localhost访问FastAPI（localhost指向下载器自身容器），需用CI服务发现的地址或容器服务名。示例.gitlab-ci.yml配置：

stages:
  - test

test-downloader:
  stage: test
  image: your-downloader-image
  variables:
    FASTAPI_TARGET: "http://fastapi-test:8000"
    PROXY_ADDR: "http://your-proxy-service:port"
  script:
    - your-downloader-cli --url $FASTAPI_TARGET --proxy $PROXY_ADDR
  services:
    - name: your-fastapi-image
      alias: fastapi-test

4. 验证代理请求链路 #

用下载器通过代理请求/check-proxy接口，查看返回的forwarded_for字段是否包含代理IP，确认请求是否真的到达FastAPI服务。

关键注意事项 #

• 严格保持下载器任务独立，通过CI服务依赖或环境变量关联FastAPI，不嵌入docker-compose。
• CI环境中确保FastAPI与下载器任务处于同一网络，或通过CI平台的服务发现机制连通。
• 确认下载器使用的代理协议（HTTP/HTTPS）与FastAPI服务协议匹配，避免协议不匹配导致的隐性错误。

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