FastAPI 集成 RAG 接口如何设置 CORS 跨域配置？

在 FastAPI 中集成 RAG 接口时，设置 CORS 跨域配置最直接的方式是使用 fastapi.middleware.cors 中的 CORSMiddleware 中间件，适用于前端页面与 API 接口域名不一致的场景，风险边界在于允许凭据时不能将源设置为通配符。

先说结论：FastAPI 通过添加 CORSMiddleware 中间件处理跨域，配置时需明确指定允许的来源域名，避免安全漏洞。

适合：前端与后端部署在不同域名或端口，浏览器发起 AJAX/Fetch 请求的场景
先准备：确认前端请求携带的 Header 和 Method，以便在白名单中放行
验收：通过浏览器开发者工具 Network 面板检查响应头是否包含 Access-Control-Allow-Origin

命令速用版

直接在 main.py 中导入中间件并添加到 app，以下代码片段可直接复用：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # 前端地址
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

为什么会这样

浏览器出于安全策略默认禁止跨域请求，FastAPI 需要显式声明允许哪些外部源访问接口。

RAG 接口通常被 Web 前端调用，当前端域名（如 example.com）与 API 域名（如 api.example.com）不同时，浏览器会触发同源策略限制。FastAPI 基于 Starlette 构建，内置了 CORS 中间件来处理预检请求（OPTIONS）和添加必要的响应头，无需手动编写每个接口的跨域逻辑。

分步处理

按顺序执行以下配置步骤，确保中间件在路由注册前加载：

导入中间件：在创建 FastAPI 实例的文件中，从 fastapi.middleware.cors 导入 CORSMiddleware。
配置允许源：设置 allow_origins 参数为前端域名的列表，若需支持多环境可读取环境变量。
设置凭据策略：若前端请求需要携带 Cookie 或 Authorization 头，将 allow_credentials 设为 True。
放行方法与头：根据实际业务设置 allow_methods 和 allow_headers，开发环境可用通配符，生产环境建议限定具体值。

怎么验证是否生效

通过浏览器开发者工具或 curl 命令检查响应头：

打开浏览器开发者工具，切换到 Network 标签页。
刷新页面触发 RAG 接口请求，查看该请求的 Response Headers。
确认存在 Access-Control-Allow-Origin 且值为当前前端域名。
若允许凭据，确认存在 Access-Control-Allow-Credentials: true。

常见坑

通配符与凭据冲突：allow_origins 设置为 ["*"] 时，allow_credentials 必须为 False，否则启动报错。
中间件顺序：CORSMiddleware 应添加在其他可能处理请求的中间件之前，确保优先拦截跨域检查。
localhost 端口差异：http://localhost:3000 与 http://localhost:8000 视为不同源，需分别配置。

常见问题

允许所有域名怎么配置？

将 allow_origins 设置为 ["*"]，但此时 allow_credentials 必须为 False，否则无法通过验证。

为什么 OPTIONS 请求返回 405？

CORS 中间件会自动处理 OPTIONS 预检请求，若被其他路由拦截需检查路由顺序或中间件加载位置。

生产环境可以直接用通配符吗？

不建议，生产环境应明确列出受信任的前端域名，防止恶意站点利用接口权限。

参考来源

FastAPI 官方文档，CORS 配置教程，https://fastapi.tiangolo.com/tutorial/cors/