---
title: "HTTP CORS 跨域配置"
date: 2026-03-12
lastmod: 2026-03-12
description: "控制 HTTP CORS 跨域支持的配置说明"
tags: ["HTTP", "CORS", "跨域", "安全配置"]
summary: "配置项作用 #  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."
---


## 配置项作用

`http.cors.enabled` 配置项控制是否启用跨域资源共享 (CORS) 支持，允许 Web 应用程序从不同域名访问 Easysearch HTTP API。

## 是否可选

是

## 默认值

```
false (禁用 CORS)
```

## 配置项类型

**静态配置** - 需要重启节点才能生效

## 配置格式

```yaml
# 启用 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 并允许所有源（不推荐用于生产）：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "*"
```

**启用 CORS 并允许特定源（推荐）：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com,https://admin.example.com"
```

**启用 CORS 并使用正则表达式：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "https://.*\.example\.com"
```

**启用 CORS 并允许凭证：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"
http.cors.allow-credentials: true
```

**开发环境配置：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "*"
http.cors.allow-credentials: false
```

## 安全建议

**生产环境最佳实践：**

1. **指定明确的允许源**
```yaml
# 好的做法
http.cors.enabled: true
http.cors.allow-origin: "https://app.example.com"

# 不推荐
http.cors.enabled: true
http.cors.allow-origin: "*"
```

2. **避免与凭证同时使用通配符**
```yaml
# 危险组合
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
```

3. **限制允许的方法和头**
```yaml
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"
```

## 配置验证

```bash
# 查看当前配置
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
```

**解决方案：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "https://your-app.com"
```

**问题 2：凭证未发送**

**解决方案：**

```yaml
http.cors.enabled: true
http.cors.allow-origin: "https://your-app.com"  # 不能是 *
http.cors.allow-credentials: true
```

**问题 3：自定义头未通过**

**解决方案：**

```yaml
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 客户端）

## 注意事项

1. **静态配置**：修改 CORS 设置需要重启节点
2. **安全考虑**：生产环境应限制允许的源
3. **通配符风险**：`allow-origin: "*"` 不应与 `allow-credentials: true` 同时使用
4. **预检请求**：首次跨域请求会发送 OPTIONS 预检请求
5. **缓存时间**：合理设置 `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 配置示例

```yaml
# 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
```