HTTP 详细错误信息配置

配置项作用 #

http.detailed_errors.enabled 配置项控制是否在 HTTP 错误响应中包含详细的调试信息。

是否可选 #

是

默认值 #

true (启用详细错误信息)

配置项类型 #

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

配置格式 #

# 启用详细错误（默认）
http.detailed_errors.enabled: true

# 禁用详细错误
http.detailed_errors.enabled: false

错误响应对比 #

启用详细错误时：

{
  "error": {
    "root_cause": [
      {
        "type": "query_parsing_exception",
        "reason": "Failed to parse query",
        "stack_trace": "org.easysearch.common.ParsingException: Failed to parse query...",
        "caused_by": {
          "type": "illegal_argument_exception",
          "reason": "invalid query"
        }
      }
    ],
    "type": "search_phase_execution_exception",
    "reason": "all shards failed",
    "stack_trace": "..."
  },
  "status": 400
}

禁用详细错误时：

{
  "error": "No EasysearchException found",
  "status": 400
}

详细错误包含的信息 #

当启用时，错误响应包含：

root_cause - 根本原因数组
error.type - 异常类名
error.reason - 错误消息
error.stack_trace - 完整堆栈跟踪
error.caused_by - 链式异常
元数据字段 - 索引、分片等信息

环境	推荐值	说明
开发环境	true	便于调试问题
测试环境	true	帮助定位问题
生产环境	false	防止信息泄露
高安全环境	false	最小化信息暴露

安全影响 #

启用详细错误的风险：

暴露系统架构
- 堆栈跟踪显示代码结构
- 揭示内部组件依赖
泄露配置信息
- 文件路径
- 系统配置细节
辅助攻击
- 帮助攻击者了解系统
- 为漏洞利用提供线索

使用示例 #

开发环境配置：

http.detailed_errors.enabled: true

生产环境配置：

http.detailed_errors.enabled: false

配置验证 #

# 查看当前配置
GET /_nodes/settings?filter_path=nodes.*.http.detailed_errors.enabled

# 触发错误查看响应格式
GET /_nonexistent_index/_search

与 error_trace 参数的关系 #

即使启用了详细错误，error_trace 查询参数仍然控制堆栈跟踪的包含：

# 不包含堆栈跟踪（即使启用详细错误）
GET /_search?error_trace=false

# 包含堆栈跟踪
GET /_search?error_trace=true

注意事项 #

静态配置：修改设置需要重启节点
安全优先：生产环境建议禁用
调试便利：开发环境保持启用
信息泄露：详细错误可能暴露敏感信息
日志记录：即使禁用详细错误，错误仍会记录到日志

安全建议 #

生产环境最佳实践：

# 禁用详细错误
http.detailed_errors.enabled: false

# 配置适当的日志级别
logger.level: INFO

# 监控错误日志
# 通过日志文件查看详细信息

配置项	默认值	说明
`http.detailed_errors.enabled`	true	是否显示详细错误

完整配置示例 #

# easysearch.yml

# 开发环境
http.detailed_errors.enabled: true
logger.level: DEBUG

# 生产环境
http.detailed_errors.enabled: false
logger.level: INFO

标签

HTTP 错误处理安全配置