---
title: "HTTP 详细错误信息配置"
date: 2026-02-02
lastmod: 2026-02-02
description: "控制 HTTP 错误响应详细程度的配置说明"
tags: ["HTTP", "错误处理", "安全配置"]
summary: "配置项作用 #  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": "."
---


## 配置项作用

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

## 是否可选

是

## 默认值

```
true (启用详细错误信息)
```

## 配置项类型

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

## 配置格式

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

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

## 错误响应对比

**启用详细错误时：**

```json
{
  "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
}
```

**禁用详细错误时：**

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

## 详细错误包含的信息

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

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

## 推荐设置

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

## 安全影响

**启用详细错误的风险：**

1. **暴露系统架构**
   - 堆栈跟踪显示代码结构
   - 揭示内部组件依赖

2. **泄露配置信息**
   - 文件路径
   - 系统配置细节

3. **辅助攻击**
   - 帮助攻击者了解系统
   - 为漏洞利用提供线索

## 使用示例

**开发环境配置：**

```yaml
http.detailed_errors.enabled: true
```

**生产环境配置：**

```yaml
http.detailed_errors.enabled: false
```

## 配置验证

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

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

## 与 error_trace 参数的关系

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

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

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

## 注意事项

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

## 安全建议

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

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

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

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

## 相关配置项

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

## 完整配置示例

```yaml
# easysearch.yml

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

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