Apache APISIX CORS 插件来处理跨域问题 ｜allow_credential: true配置约束

文章目录

• Apache APISIX CORS 插件深度排障：`allow_origins_by_regex` + `allow_credential` 的隐蔽陷阱
• • 一、背景
  • 二、问题复现
  • • 配置
    • 测试
    • 预期结果
    • 实际结果
  • 三、深入理解 `allow_credential` 参数
  • • 3.1 一句话定义
    • 3.2 它不控制什么
    • 3.3 工作机制：前后端的"双向握手"
    • 3.4 它具体保护了哪些"凭证"？
    • 3.5 设为 `true` 的 5 大连锁约束
    • 3.6 在 APISIX 中的具体表现
    • 3.7 实际应用场景
    • • 场景 1：传统 Web 应用（Session + Cookie）
      • 场景 2：SPA + Token 认证（不依赖 Cookie）
      • 场景 3：SSO / 第三方登录回调
      • 场景 4：纯公开 API
    • 3.8 `true` vs `false` 对照表
  • 四、什么时候应该用 `allow_credential: false`？
  • • 4.1 核心结论：绝大多数场景都应该用 `false`
    • 4.2 `false` 到底干了什么？
    • 4.3 应该用 `false` 的 6 个典型场景
    • • ① Token 认证（JWT / Bearer Token）—— 最常见
      • ② 公开 API / OpenAPI
      • ③ 服务间调用 / 微服务网关
      • ④ 移动端 App（原生 HTTP 请求）
      • ⑤ WebSocket 连接
      • ⑥ 前端 Token 存 localStorage / sessionStorage
    • 4.4 `false` 的 3 大优势（为什么推荐）
    • 4.5 常见误解澄清
    • 4.6 决策流程图
    • 4.7 经验法则：不确定就用 `false`
  • 五、根因分析：源码级拆解
  • • 5.1 陷阱一：`allow_credential: true` 与 `allow_origins` 默认值 `*` 冲突导致 Schema 校验失败
    • • 源码证据
      • 问题推演
      • 官方文档佐证
      • `allow_credential: true` 完整参数约束总结
      • 为什么 W3C/CORS 规范禁止 `credentials + *`？
      • 实际影响：哪些配置组合会失败？
    • 5.2 陷阱二：`allow_origins_by_regex` 存在时会完全接管 Origin 匹配，忽略 `allow_origins`
    • • 源码证据
      • 设计意图
    • 5.3 陷阱三：OPTIONS 请求在 `rewrite` 阶段直接返回 200，CORS 头在 `header_filter` 阶段设置
    • • 源码证据
  • 六、正确的配置方式
  • • 6.1 方案一：`allow_origins_by_regex` + 显式覆盖所有默认值
    • 6.2 方案二（推荐）：仅使用 `allow_origins` 字符串匹配（无需正则）
    • 6.3 方案三：不使用 `allow_credential`
  • 七、`allow_credential: false` 的影响与风险分析
  • • 7.1 什么是 "凭证"（Credentials）？
    • 7.2 `allow_credential: false` 时浏览器的行为
    • 7.3 什么场景可以安全地设为 `false`？
    • 7.4 关于 `Authorization` 头的特殊说明
    • 7.5 `allow_credential: false` 的连锁影响
    • 7.6 决策树：我该用 `true` 还是 `false`？
    • 7.7 从 `true` 改为 `false` 的迁移注意事项
  • 八、配置诊断 Checklist
  • • Step 1：确认插件是否被正确加载
    • Step 2：检查 `allow_credential` 与通配符的冲突
    • Step 3：确认 `allow_origins_by_regex` 的正则表达式语法
    • Step 4：检查是否有其他路由匹配了同一个请求
    • Step 5：确认 APISIX 的 error.log 中是否有插件报错
    • Step 6：使用 `_meta.disable` 确认插件状态
  • 九、常见错误配置速查表
  • 十、总结
  • • 黄金法则
  • 十一、参考链接