CORS 预检请求缓存时间配置

配置项作用 #

http.cors.max-age 配置项用于控制CORS 预检请求（Preflight Request）的结果在浏览器中的缓存时间。

当浏览器发送跨域请求前，对于非简单请求（如 PUT、DELETE 或带有自定义头的请求），浏览器会先发送一个 OPTIONS 预检请求。max-age 指定了这个预检响应可以被缓存多长时间。

配置项属性 #

配置路径: http.cors.max-age
数据类型: Integer（整数，单位：秒）
默认值: 1728000（20天）
最小值: 0（不缓存）
是否可选: 是
作用域: NodeScope（节点级别）

配置项详解 #

工作机制 #

CORS 预检请求缓存流程

首次发送 PUT 请求
    │
    ↓
浏览器发送 OPTIONS 预检请求
    │
    ↓
服务器返回响应
Access-Control-Max-Age: 1728000
    │
    ↓
浏览器缓存预检结果
    │
    ↓
在 20 天内再次发送 PUT 请求
    │
    ↓
直接发送实际请求（跳过预检）✅

    │
    ↓
20 天后再次发送 PUT 请求
    │
    ↓
重新发送 OPTIONS 预检请求

缓存效果对比 #

无缓存（max-age = 0）:

每次请求:
PUT /index/_doc/1
    ↓
OPTIONS 预检（网络往返）
    ↓
PUT 实际请求（网络往返）

总耗时: 2 × 网络延迟


有缓存（max-age = 1728000）:

首次请求:
PUT /index/_doc/1
    ↓
OPTIONS 预检（网络往返）
    ↓
PUT 实际请求（网络往返）

后续 20 天内的请求:
PUT /index/_doc/1
    ↓
PUT 实际请求（网络往返）

总耗时: 1 × 网络延迟（节省 50%）

预检请求响应头 #

预检请求响应示例:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true

关键响应头:

Access-Control-Max-Age: 1728000
    ↓
浏览器缓存此预检结果 1728000 秒（20 天）

配置建议 #

生产环境（默认） #

http:
  cors:
    enabled: true
    allow-origin: "*"
    max-age: 1728000  # 默认值（20 天）

建议: 保持默认值。适用于大多数生产环境，有效减少预检请求。

高频访问场景 #

http:
  cors:
    enabled: true
    allow-origin: "https://app.example.com"
    max-age: 604800  # 7 天

建议: 设置为 7-30 天。当应用需要频繁调用跨域 API 时使用。

开发调试环境 #

http:
  cors:
    enabled: true
    allow-origin: "http://localhost:3000"
    max-age: 3600  # 1 小时

建议: 设置为较短时间（1-24 小时）。开发时配置可能经常变化。

高安全要求 #

http:
  cors:
    enabled: true
    allow-origin: "https://app.example.com"
    max-age: 600  # 10 分钟

建议: 设置为较短时间（5-30 分钟）。当需要快速响应配置变化时使用。

代码示例 #

easysearch.yml 基础配置 #

http:
  cors:
    enabled: true
    allow-origin: "*"
    max-age: 1728000

完整 CORS 配置 #

http:
  cors:
    enabled: true
    allow-origin: "https://app.example.com"
    allow-methods: "OPTIONS,HEAD,GET,POST,PUT,DELETE"
    allow-headers: "Content-Type,Authorization"
    allow-credentials: true
    max-age: 86400  # 1 天

开发环境配置 #

http:
  cors:
    enabled: true
    allow-origin: "http://localhost:3000,http://localhost:8080"
    allow-methods: "GET,POST,PUT,DELETE"
    allow-headers: "Content-Type"
    max-age: 3600  # 1 小时

配置项	作用	默认值
`http.cors.enabled`	是否启用 CORS	false
`http.cors.allow-origin`	允许的来源域名	-
`http.cors.allow-methods`	允许的 HTTP 方法	OPTIONS,HEAD,GET,POST,PUT,DELETE
`http.cors.allow-headers`	允许的请求头	X-Requested-With,Content-Type,Content-Length
`http.cors.max-age`	预检请求缓存时间	1728000

缓存时间参考 #

不同场景的推荐时间 #

静态应用（配置很少变化）:
max-age: 604800  # 7 天
优点: 最大限度减少预检请求

动态应用（配置可能变化）:
max-age: 86400  # 1 天
优点: 平衡性能和灵活性

开发环境（配置经常变化）:
max-age: 3600  # 1 小时
优点: 快速反映配置变化

高安全要求（需要严格控制）:
max-age: 600  # 10 分钟
优点: 配置变化快速生效

浏览器限制 #

不同浏览器的最大缓存时间限制:

Chrome/Chromium:
- 最大值: 600 秒（10 分钟）
- 超过限制的值会被截断

Firefox:
- 最大值: 86400 秒（24 小时）
- 超过限制的值会被截断

Safari:
- 最大值: 600 秒（10 分钟）
- 超过限制的值会被截断

实际生效时间:
取服务器配置值和浏览器限制值的较小值

性能影响分析 #

请求次数对比 #

假设应用每 10 秒发送一次 PUT 请求

max-age = 0（无缓存）:

1 小时内 = 360 次请求
= 360 次预检 + 360 次实际请求
= 720 次网络往返


max-age = 3600（1 小时）:

1 小时内 = 360 次请求
= 1 次预检 + 360 次实际请求
= 361 次网络往返

节省: 359 次预检请求（49.9%）


max-age = 1728000（20 天）:

假设应用运行 1 天 = 8640 次请求
= 1 次预检 + 8640 次实际请求
= 8641 次网络往返

节省: 8639 次预检请求（99.9%）

使用场景 #

缓存失效 #

预检缓存失效的情况

1. 缓存时间到期
   max-age 的时间到了
   ↓
   下次请求重新预检

2. 浏览器关闭
   某些浏览器在关闭时清除缓存
   ↓
   重新打开后重新预检

3. 清除浏览器数据
   用户手动清除缓存
   ↓
   下次请求重新预检

4. 配置变化
   服务器 CORS 配置变化
   ↓
   等待缓存到期后生效

注意事项 #

浏览器限制: 浏览器对 max-age 有内部上限，超过上限的值会被截断。
配置变化延迟: 增加缓存时间会导致配置变更延迟生效。
与安全性的平衡: 缓存时间越长，性能越好，但配置变化的响应越慢。
动态更新: 此配置支持动态更新，修改后立即生效（但已有缓存不会立即清除）。
清除缓存: 无法主动清除浏览器中的预检缓存。
不同浏览器: 不同浏览器对 max-age 的处理可能不同。
调试建议: 调试时可以设置较小的值，方便观察预检请求。
与 CDN 配合: 如果使用 CDN，需要确保 CORS 头部正确传递。
监控建议: 监控预检请求的频率，评估缓存效果。
性能测试: 在生产环境部署前，测试不同缓存时间对性能的影响。

标签

HTTP CORS 跨域性能优化