--- title: "CORS 允许的 HTTP 方法配置" date: 2026-03-29 lastmod: 2026-03-29 description: "http.cors.allow-methods 配置项用于指定在跨域请求中允许的 HTTP 方法列表。" tags: ["HTTP", "CORS", "跨域", "HTTP方法"] summary: "配置项作用 # http.cors.allow-methods 配置项用于指定在跨域资源共享（CORS）请求中允许浏览器使用的 HTTP 方法列表。 当浏览器发送跨域请求的预检（OPTIONS）请求时，服务器会在 Access-Control-Allow-Methods 响应头中返回允许的 HTTP 方法。 配置项属性 # 配置路径: http.cors.allow-methods 数据类型: String（逗号分隔的字符串列表） 默认值: "OPTIONS,HEAD,GET,POST,PUT,DELETE" 是否可选: 是 作用域: NodeScope（节点级别） 配置项详解 # 工作机制 # CORS 预检请求流程 浏览器准备发送 PUT 请求 │ ↓ 发送 OPTIONS 预检请求 │ ↓ 包含请求的方法信息 Access-Control-Request-Method: PUT │ ↓ 服务器检查 allow-methods 配置 │ ├──────── 方法在允许列表中 ✅ │ ↓ │ 返回成功响应 │ ↓ │ Access-Control-Allow-Methods: │ OPTIONS,HEAD,GET,POST,PUT,DELETE │ ↓ │ 浏览器发送实际 PUT 请求 │ └──────── 方法不在允许列表中 ❌ ↓ 返回错误响应 ↓ 浏览器阻止实际请求 HTTP 方法说明 # 默认允许的方法: OPTIONS: - 作用: 预检请求，用于探测服务器支持的 CORS 功能 - 必需: CORS 预检必须包含此方法 HEAD: - 作用: 获取资源的头部信息，不返回实际内容 - 用途: 检查资源是否存在或获取元数据 GET: - 作用: 获取资源 - 用途: 查询数据、搜索、获取集群状态 POST: - 作用: 创建资源或执行操作 - 用途: 创建索引、执行搜索、批量操作 PUT: - 作用: 更新或创建资源 - 用途: 创建索引、更新映射、更新文档 DELETE: - 作用: 删除资源 - 用途: 删除索引、删除文档 简单请求 vs 非简单请求 # 简单请求（无需预检）: - 方法: GET, HEAD, POST - 头部: 仅限安全头部 - 直接发送请求 非简单请求（需要预检）: - 方法: PUT, DELETE, PATCH 等 - 头部: 包含自定义头部 - Content-Type: application/json 1." --- ## 配置项作用 `http.cors.allow-methods` 配置项用于指定**在跨域资源共享（CORS）请求中允许浏览器使用的 HTTP 方法列表**。 当浏览器发送跨域请求的预检（OPTIONS）请求时，服务器会在 `Access-Control-Allow-Methods` 响应头中返回允许的 HTTP 方法。 ## 配置项属性 - **配置路径**: `http.cors.allow-methods` - **数据类型**: `String`（逗号分隔的字符串列表） - **默认值**: `"OPTIONS,HEAD,GET,POST,PUT,DELETE"` - **是否可选**: 是 - **作用域**: NodeScope（节点级别） ## 配置项详解 ## 工作机制 ``` CORS 预检请求流程 浏览器准备发送 PUT 请求 │ ↓ 发送 OPTIONS 预检请求 │ ↓ 包含请求的方法信息 Access-Control-Request-Method: PUT │ ↓ 服务器检查 allow-methods 配置 │ ├──────── 方法在允许列表中 ✅ │ ↓ │ 返回成功响应 │ ↓ │ Access-Control-Allow-Methods: │ OPTIONS,HEAD,GET,POST,PUT,DELETE │ ↓ │ 浏览器发送实际 PUT 请求 │ └──────── 方法不在允许列表中 ❌ ↓ 返回错误响应 ↓ 浏览器阻止实际请求 ``` ## HTTP 方法说明 ``` 默认允许的方法: OPTIONS: - 作用: 预检请求，用于探测服务器支持的 CORS 功能 - 必需: CORS 预检必须包含此方法 HEAD: - 作用: 获取资源的头部信息，不返回实际内容 - 用途: 检查资源是否存在或获取元数据 GET: - 作用: 获取资源 - 用途: 查询数据、搜索、获取集群状态 POST: - 作用: 创建资源或执行操作 - 用途: 创建索引、执行搜索、批量操作 PUT: - 作用: 更新或创建资源 - 用途: 创建索引、更新映射、更新文档 DELETE: - 作用: 删除资源 - 用途: 删除索引、删除文档 ``` ## 简单请求 vs 非简单请求 ``` 简单请求（无需预检）: - 方法: GET, HEAD, POST - 头部: 仅限安全头部 - 直接发送请求 非简单请求（需要预检）: - 方法: PUT, DELETE, PATCH 等 - 头部: 包含自定义头部 - Content-Type: application/json 1. 先发送 OPTIONS 预检 2. 检查 allow-methods 3. 再发送实际请求 ``` ## 配置建议 ## 默认配置（标准 CRUD） ```yaml http: cors: enabled: true allow-origin: "*" allow-methods: "OPTIONS,HEAD,GET,POST,PUT,DELETE" # 默认值 ``` **建议**: 保持默认值。适用于大多数 RESTful API 场景。 ## RESTful API 完整配置 ```yaml http: cors: enabled: true allow-origin: "*" allow-methods: "OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE" ``` **建议**: 添加 `PATCH` 方法。当需要支持部分更新操作时使用。 ## 只读访问配置 ```yaml http: cors: enabled: true allow-origin: "*" allow-methods: "OPTIONS,HEAD,GET" ``` **建议**: 只包含安全方法。当需要只读访问时使用。 ## 完整方法配置 ```yaml http: cors: enabled: true allow-origin: "https://example.com" allow-methods: "OPTIONS,GET,HEAD,POST,PUT,PATCH,DELETE" ``` **建议**: 包含所有常用方法。生产环境的完整配置。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml http: cors: enabled: true allow-origin: "*" allow-methods: "OPTIONS,HEAD,GET,POST,PUT,DELETE" ``` ## 开发环境配置 ```yaml http: cors: enabled: true allow-origin: "http://localhost:3000" allow-methods: "OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE" ``` ## 只读 API 配置 ```yaml http: cors: enabled: true allow-origin: "https://public.example.com" allow-methods: "OPTIONS,HEAD,GET" allow-credentials: false ``` ## 相关配置 | 配置项 | 作用 | 默认值 | |--------|------|--------| | `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.allow-credentials` | 是否允许凭证 | false | | `http.cors.max-age` | 预检请求缓存时间 | 1728000 | ## Easysearch API 方法使用 ## 常用 API 方法分类 ``` 集群管理 API: GET /_cluster/health GET /_cluster/state PUT /_cluster/settings POST /_cluster/reroute 索引管理 API: PUT /{index} DELETE /{index} GET /{index}/_mapping PUT /{index}/_mapping 文档操作 API: GET /{index}/_doc/{id} POST /{index}/_doc PUT /{index}/_doc/{id} DELETE /{index}/_doc/{id} POST /{index}/_update 搜索 API: GET /{index}/_search POST /{index}/_search ``` ## 方法与权限对应 ``` 安全方法（只读）: - GET: 查询数据 - HEAD: 检查资源存在 - OPTIONS: 预检请求 修改方法: - POST: 创建资源、执行操作 - PUT: 完整更新资源 - PATCH: 部分更新资源 - DELETE: 删除资源 ``` ## 使用场景 ## 推荐使用默认配置的场景 - **标准 CRUD 应用**: 需要完整的增删改查功能 - **RESTful API**: 使用标准的 REST 架构 - **数据管理**: 需要管理索引和文档 ## 推荐添加 PATCH 的场景 - **部分更新**: 需要支持部分文档更新 - **现代 API**: 遵循现代 REST API 最佳实践 - **前端框架**: 使用支持 PATCH 的前端库 ## 推荐限制为只读的场景 - **公开数据**: 只提供数据查询服务 - **报表系统**: 只需要读取数据生成报表 - **监控面板**: 只需要展示集群状态 ## 预检请求示例 ``` 浏览器准备发送 PUT 请求: OPTIONS /my_index/_doc/1 HTTP/1.1 Host: easysearch.example.com Origin: https://app.example.com Access-Control-Request-Method: PUT Access-Control-Request-Headers: Content-Type 服务器返回响应: HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: OPTIONS,HEAD,GET,POST,PUT,DELETE Access-Control-Allow-Headers: Content-Type Access-Control-Max-Age: 1728000 浏览器检查响应后发送实际请求: PUT /my_index/_doc/1 HTTP/1.1 Host: easysearch.example.com Origin: https://app.example.com Content-Type: application/json { "field": "value" } ``` ## 安全注意事项 ## 最小权限原则 ``` 只开放需要的方法 公开 API: http.cors.allow-methods: "OPTIONS,HEAD,GET" （只允许查询，不允许修改） 内部 API: http.cors.allow-methods: "OPTIONS,HEAD,GET,POST,PUT,DELETE" （允许完整的 CRUD 操作） ``` ## 方法安全建议 ``` 安全方法（可公开）: - GET: 不修改数据 - HEAD: 只获取元数据 - OPTIONS: 预检请求 不安全方法（需要认证）: - POST: 可能创建资源 - PUT: 可能修改资源 - DELETE: 可能删除资源 - PATCH: 可能修改资源 ``` ## 注意事项 1. **OPTIONS 必需**: 必须包含 `OPTIONS` 方法，否则 CORS 预检会失败。 2. **方法名大小写**: 方法名必须使用大写，用逗号分隔。 3. **与 allow-headers 配合**: 某些方法需要特定的请求头才能正常工作。 4. **预检请求**: 任何非简单方法都会触发 OPTIONS 预检请求。 5. **动态更新**: 此配置支持动态更新，修改后立即生效。 6. **与认证配合**: 修改操作建议配合认证使用，避免安全问题。 7. **日志监控**: 监控被拒绝的 CORS 预检请求，及时发现配置问题。 8. **浏览器限制**: 某些浏览器对允许的方法有额外的限制。 9. **与 HTTP 规范一致**: 建议遵循 HTTP 规范的方法语义。 10. **测试验证**: 配置变更后需要测试所有跨域请求是否正常工作。