4. 索引设计基础：Mapping 设计原则、字段类型选择与动态映射权衡

索引 Mapping 是 Elasticsearch 数据建模的核心，它定义了文档如何被索引、存储和检索。在日志场景下，Mapping 设计直接决定查询性能、存储效率和数据准确性。本章将系统讲解 Mapping 设计原则、字段类型选择、日期格式处理以及动态映射与显式映射的权衡策略。

4.1 Mapping 设计核心原则

日志索引的 Mapping 设计需遵循以下五项原则，以确保系统在高吞吐写入和复杂查询场景下的稳定性：

1. 字段最小化原则：只索引需要查询和聚合的字段，避免为所有字段建立索引。日志中大量调试信息、原始堆栈无需被索引，可通过 index: false 或 enabled: false 跳过。
2. 类型精确原则：为每个字段选择最精确的数据类型。例如，IP 地址使用 ip 类型，经纬度使用 geo_point，避免统一使用 keyword 或 text。
3. 禁用动态映射原则：生产环境必须关闭动态映射（dynamic: false 或 strict），防止字段爆炸导致集群元数据膨胀和性能下降。
4. 多字段（multi-fields）原则：对需要同时支持精确匹配和全文搜索的字段，使用 fields 参数定义多字段，例如 message 字段同时保留 text 和 keyword 子字段。
5. 禁用 _source 压缩原则：日志场景下保留 _source 便于排查，但可通过 _source.includes/excludes 过滤冗余字段，或使用 source_reuse 特性减少存储开销。

4.2 字段类型选择：keyword vs text

字段类型选择是 Mapping 设计中最常见的决策点。keyword 和 text 的核心差异如下：

选择策略：

• 日志中 结构化字段（如 IP、状态码、日志级别、服务名）一律使用 keyword。
• 非结构化文本（如日志正文、错误堆栈）使用 text，并配合 fields 添加 keyword 子字段用于聚合。
• 对于长度超过 32766 字节的 keyword 字段，Elasticsearch 会拒绝索引，此时应改用 text 或 keyword 配合 ignore_above 截断。

// 多字段定义示例
PUT _index_template/nginx_log_template
{
  "index_patterns": ["nginx-*"],
  "template": {
    "mappings": {
      "properties": {
        "message": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 512
            }
          }
        },
        "client_ip": { "type": "ip" },
        "status_code": { "type": "keyword" },
        "request_method": { "type": "keyword" }
      }
    }
  }
}

4.3 日期格式处理

日志中时间字段是索引分片路由和生命周期管理的核心依据。日期格式设计需注意以下要点：

• 统一格式：推荐使用 ISO 8601 标准格式（yyyy-MM-dd'T'HH:mm:ss.SSSZ），避免混合多种日期格式。
• 多格式兜底：使用 format 参数指定多个候选格式，用 || 分隔，提高数据兼容性。
• 时区处理：日志采集端统一转换为 UTC 时间，避免因时区差异导致查询偏移。
• 时间戳字段：使用 @timestamp 作为标准时间字段，配合 ILM 的 rollover 条件使用。

// 日期格式定义示例
"@timestamp": {
  "type": "date",
  "format": "yyyy-MM-dd'T'HH:mm:ss.SSSZ||yyyy-MM-dd HH:mm:ss||epoch_millis"
}

4.4 动态映射与显式映射的权衡

动态映射（Dynamic Mapping）允许 ES 自动推断字段类型，显式映射（Explicit Mapping）则由运维人员手动定义。两者对比如下：

推荐策略：

• 生产环境使用 显式映射 + 索引模板，在模板中定义所有已知字段。
• 对于未知字段，设置 dynamic: false（忽略新字段）或 dynamic: strict（拒绝新字段），避免字段爆炸。
• 如果必须使用动态映射，配合 dynamic_templates 定义匹配规则，例如将所有字符串映射为 keyword，将数字映射为 float。

// 动态模板示例：将所有字符串映射为 keyword，数字映射为 float
PUT _index_template/app_log_template
{
  "index_patterns": ["app-*"],
  "template": {
    "mappings": {
      "dynamic_templates": [
        {
          "strings_as_keyword": {
            "match_mapping_type": "string",
            "mapping": {
              "type": "keyword"
            }
          }
        },
        {
          "numbers_as_float": {
            "match_mapping_type": "long",
            "mapping": {
              "type": "float"
            }
          }
        }
      ]
    }
  }
}

4.5 Mapping 设计决策流程

下图展示了日志索引 Mapping 设计的完整决策流程，帮助你在实际项目中快速做出正确选择：

4.6 实战：日志索引 Mapping 模板示例

以下是一个完整的 Nginx 日志索引模板，综合运用了上述设计原则：

PUT _index_template/nginx_access_log
{
  "index_patterns": ["nginx-access-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1,
      "index.lifecycle.name": "nginx_ilm_policy",
      "index.lifecycle.rollover_alias": "nginx-access"
    },
    "mappings": {
      "dynamic": false,
      "properties": {
        "@timestamp": {
          "type": "date",
          "format": "yyyy-MM-dd'T'HH:mm:ss.SSSZ||epoch_millis"
        },
        "client_ip": { "type": "ip" },
        "method": { "type": "keyword" },
        "uri": {
          "type": "text",
          "fields": {
            "keyword": { "type": "keyword", "ignore_above": 2048 }
          }
        },
        "status_code": { "type": "keyword" },
        "body_bytes": { "type": "long" },
        "referer": {
          "type": "keyword",
          "ignore_above": 1024
        },
        "user_agent": {
          "type": "text",
          "fields": {
            "keyword": { "type": "keyword", "ignore_above": 512 }
          }
        },
        "response_time": { "type": "float" },
        "upstream_addr": { "type": "ip" }
      }
    }
  }
}