配置项作用 #
http.cors.enabled 配置项控制是否启用跨域资源共享 (CORS) 支持，允许 Web 应用程序从不同域名访问 Easysearch HTTP API。
是否可选 #
是
默认值 #
false (禁用 CORS)
配置项类型 #
静态配置 - 需要重启节点才能生效
配置格式 #
# 启用 CORS
http.cors.enabled: true
# 禁用 CORS（默认）
http.cors.enabled: false
什么是 CORS #
CORS (Cross-Origin Resource Sharing) 是一种 HTTP 机制，允许服务器指示浏览器是否应该允许来自其他源的请求。
┌─────────────────────────────────────────────────────────┐
│ CORS 请求流程 │
└─────────────────────────────────────────────────────────┘
浏览器 (https://app.example.com)
│
│ 1. 发送请求
▼
Easysearch (https://api.example.com)
│
│ 2. 检查 CORS 配置
├── http.cors.enabled: false → 拒绝请求
└── http.cors.enabled: true
│
│ 3. 检查允许的源
├── origin 在允许列表 → 返回数据 + CORS 头
└── origin 不在列表 → 拒绝请求
相关 CORS 配置 #
http.cors.enabled 需要配合其他 CORS 配置使用：
| 配置项 | 默认值 | 说明 |
|---|---|---|
http.cors.allow-origin | "" | 允许的源 |
http.cors.allow-methods | “OPTIONS,HEAD,GET,POST,PUT,DELETE” | 允许的 HTTP 方法 |
http.cors.allow-headers | “X-Requested-With,Content-Type,Content-Length” | 允许的请求头 |
http.cors.allow-credentials | false | 是否允许携带凭证 |
http.cors.max-age | 1728000 | 预检请求缓存时间（秒） |
推荐设置 #
| 场景 | 推荐值 | 说明 |
|---|---|---|
| 默认配置 | false | 禁用 CORS |
| Web 前端直接访问 | true | 启用并配置允许的源 |
| 通过后端代理 | false | 禁用 CORS |
| 开发环境 | true | 允许本地开发 |
使用示例 #
启用 CORS 并允许所有源（不推荐用于生产）：
http.cors.enabled: true
http.cors.allow-origin: "*"
启用 CORS 并允许特定源（推荐）：
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com,https://admin.example.com"
启用 CORS 并使用正则表达式：
http.cors.enabled: true
http.cors.allow-origin: "https://.*\.example\.com"
启用 CORS 并允许凭证：
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"
http.cors.allow-credentials: true
开发环境配置：
http.cors.enabled: true
http.cors.allow-origin: "*"
http.cors.allow-credentials: false
安全建议 #
生产环境最佳实践：
- 指定明确的允许源
# 好的做法
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"
# 不推荐
http.cors.enabled: true
http.cors.allow-origin: "*"
- 避免与凭证同时使用通配符
# 危险组合
http.cors.enabled: true
http.cors.allow-origin: "*"
http.cors.allow-credentials: true # 不安全
# 正确做法
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"
http.cors.allow-credentials: true
- 限制允许的方法和头
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"
http.cors.allow-methods: "GET,POST"
http.cors.allow-headers: "Content-Type,Authorization"
配置验证 #
# 查看当前配置
GET /_nodes/settings?filter_path=nodes.*.http.cors.*
# 测试 CORS 预检请求
curl -X OPTIONS http://localhost:9200/ \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: GET" \
-v
# 检查响应头
curl -X GET http://localhost:9200/ \
-H "Origin: https://app.example.com" \
-v 2>&1 | grep -i "access-control"
常见问题 #
问题 1：CORS 错误
错误信息：
Access to XMLHttpRequest has been blocked by CORS policy
解决方案：
http.cors.enabled: true
http.cors.allow-origin: "https://your-app.com"
问题 2：凭证未发送
解决方案：
http.cors.enabled: true
http.cors.allow-origin: "https://your-app.com" # 不能是 *
http.cors.allow-credentials: true
问题 3：自定义头未通过
解决方案：
http.cors.enabled: true
http.cors.allow-origin: "https://your-app.com"
http.cors.allow-headers: "X-Requested-With,Content-Type,Authorization,X-Custom-Header"
何时需要启用 CORS #
需要启用 CORS 的情况：
- Web 前端直接从浏览器访问 Easysearch API
- 前端和 Easysearch 部署在不同域名
- 开发环境下本地调试
不需要启用 CORS 的情况：
- 通过后端服务器代理访问
- 前端和 API 在同一域名下
- 使用官方客户端（如 Python、Java 客户端）
注意事项 #
- 静态配置：修改 CORS 设置需要重启节点
- 安全考虑：生产环境应限制允许的源
- 通配符风险：
allow-origin: "*"不应与allow-credentials: true同时使用 - 预检请求：首次跨域请求会发送 OPTIONS 预检请求
- 缓存时间：合理设置
max-age以减少预检请求频率
相关配置项 #
| 配置项 | 默认值 | 说明 |
|---|---|---|
http.cors.allow-origin | "" | 允许的源列表 |
http.cors.allow-methods | OPTIONS,HEAD,GET,POST,PUT,DELETE | 允许的 HTTP 方法 |
http.cors.allow-headers | X-Requested-With,Content-Type,Content-Length | 允许的请求头 |
http.cors.allow-credentials | false | 是否允许携带凭证 |
http.cors.max-age | 1728000 | 预检请求缓存时间（秒） |
完整 CORS 配置示例 #
# easysearch.yml
# 启用 CORS
http.cors.enabled: true
# 允许的源
http.cors.allow-origin: "https://app.example.com,https://admin.example.com"
# 允许的 HTTP 方法
http.cors.allow-methods: "OPTIONS,HEAD,GET,POST,PUT,DELETE"
# 允许的请求头
http.cors.allow-headers: "X-Requested-With,Content-Type,Content-Length,Authorization"
# 允许携带凭证
http.cors.allow-credentials: true
# 预检请求缓存时间
http.cors.max-age: 1728000
