5.5 跨域配置（CORS）

概述

CORS 中间件位于链路最前段（trace 之后），保证包括错误响应在内的所有响应都带跨域头——浏览器才能读到 401/403 的业务码。开发期因 Vite 代理通常感知不到它，前后端分离直连时才生效。

行为

读取 cors.allowOrigin：
  空 或 "*"  → 回显请求 Origin + Vary: Origin（防中间层缓存串源）
  具体来源   → 显式回显 + Allow-Credentials: true

通用响应头：
  Allow-Headers: Origin,Authorization,Content-Type,Accept,Token,X-Requested-With,X-Request-Id
  Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
  Max-Age: 600（预检缓存 10 分钟）

OPTIONS 预检 → 直接 204 终止链

配置

cors:
  allowOrigin: "*"    # 生产环境应改为实际前端域名

为什么放在链路前端

若 CORS 在业务中间件之后，被限流/鉴权拒绝的响应与 panic 兜底响应都不会带 CORS 头，浏览器只能看到"被 CORS 拦截"而非真实的 401/403——排障困难。本项目把 CORS 排在 metrics 之前，所有出口统一过它。

开发与生产的差异

场景	跨域处理
本地开发	Vite 代理 /api → 8000，同源请求，CORS 不介入
生产（同域部署）	Nginx 同域反代，无跨域
生产（跨域部署）	cors.allowOrigin 配前端精确域名，前端凭证模式

生产建议

• 不要长期使用 *：与凭证模式互斥，且等于开放任意站点调用
• 配置具体域名后自动开启 Allow-Credentials（Cookie/Header 凭证可用）
• 多域名场景在网关层处理 CORS，应用层收敛为内网信任

下一步

→ 5.6 密码与加密服务