3. 准入门禁日志特点分析
准入门禁系统产生的日志是索引生命周期管理与存储优化的直接作用对象。在构建 ELK 管道之前，必须深入理解其日志格式、字段语义、数据量级与写入吞吐特征。本章从这三个维度展开分析，为后续的索引模板设计、分片策略与冷热迁移提供数据基础。
3.1 日志格式：JSON / CSV / 多行
不同厂商的门禁控制器与平台输出的日志格式差异较大，但主流格式可归纳为以下三种：
| 格式类型 | 典型场景 | 优点 | 缺点 |
|---|---|---|---|
| JSON | 智能门禁平台、云门禁 API | 结构清晰，可直接被 Logstash / Filebeat 解析，支持嵌套字段 | 日志体积较大，占用更多存储与网络带宽 |
| CSV | 传统门禁控制器、嵌入式设备 | 体积小，解析效率高，适合高吞吐写入 | 字段顺序依赖强，缺少自描述能力，扩展性差 |
| 多行日志 | 老旧门禁系统、串口转网络输出 | 兼容性强，无需改造设备 | 需要 Logstash 配置多行编解码器，处理复杂度高 |
实战建议：优先推动门禁厂商输出 JSON 格式。如果无法改造，使用 Filebeat 的
multiline 配置或 Logstash 的 multiline codec 处理多行日志，并建议在边缘节点（如网关）完成格式归一化。
以下是一个典型的门禁 JSON 日志示例：
{
"@timestamp": "2025-03-21T14:32:10.123+08:00",
"user_id": "U20250321001",
"door_id": "D-A-03-12",
"event_type": "ACCESS_GRANTED",
"result": "SUCCESS",
"card_uid": "A1B2C3D4",
"device_ip": "192.168.10.45",
"duration_ms": 320
}3.2 字段定义：核心字段与扩展字段
准入门禁日志的字段设计直接影响索引映射（Mapping）的精度与查询性能。我们将字段分为必选核心字段与可选扩展字段两类。
3.2.1 核心字段
| 字段名 | 类型 | 说明 | 示例值 |
|---|---|---|---|
@timestamp |
date | 事件发生时间，建议使用 UTC+8 时区 | 2025-03-21T14:32:10.123+08:00 |
user_id |
keyword | 用户唯一标识，用于人员轨迹查询 | U20250321001 |
door_id |
keyword | 门禁点唯一编码，包含区域与楼层信息 | D-A-03-12 |
event_type |
keyword | 事件类型：ACCESS_GRANTED / ACCESS_DENIED / DOOR_OPEN / DOOR_CLOSE / ALARM | ACCESS_GRANTED |
result |
keyword | 认证结果：SUCCESS / FAILURE / TIMEOUT / ERROR | SUCCESS |
3.2.2 扩展字段
- card_uid（keyword）：卡片物理序列号，用于卡片生命周期追踪。
- device_ip（ip）：门禁控制器 IP 地址，用于设备级故障定位。
- duration_ms（long）：认证耗时（毫秒），用于性能监控。
- auth_method（keyword）：认证方式，如 CARD / FINGERPRINT / FACE / QRCODE。
- error_code（keyword）：失败时的错误码，如 ERR_001（卡片过期）、ERR_002（权限不足）。
索引映射优化要点：所有标识类字段（user_id、door_id、event_type、result）必须使用
keyword 类型，避免被 text 分词器拆分。时间字段统一使用 date 类型并指定格式。扩展字段建议使用 dynamic: false 或 dynamic: strict 控制映射，防止字段爆炸。
3.3 数据量级与写入吞吐预估
数据量级估算是索引分片数与生命周期策略设计的核心输入。以下基于一个中型园区（50 个门禁点、5000 名员工）的典型场景进行测算。
3.3.1 单条日志大小
| 格式 | 平均大小（压缩前） | 平均大小（压缩后，gzip） |
|---|---|---|
| JSON（含扩展字段） | ~350 字节 | ~120 字节 |
| CSV（仅核心字段） | ~120 字节 | ~45 字节 |
| 多行日志（原始格式） | ~500 字节 | ~180 字节 |
3.3.2 日吞吐量估算
假设每个门禁点日均通行 2000 次，每次通行产生 1 条日志（开门 + 关门可能产生 2 条，按 1.5 倍系数计算）：
- 单点日均日志量： 2000 次 × 1.5 = 3000 条
- 全园日均日志量： 50 点 × 3000 条 = 150,000 条
- 峰值吞吐（早高峰 8:00-9:00）： 假设高峰占全天 30%，即 45,000 条/小时 ≈ 12.5 条/秒
- 日均存储增量（JSON 格式）： 150,000 条 × 350 字节 ≈ 52.5 MB/天
- 月均存储增量： 52.5 MB × 30 ≈ 1.54 GB/月
注意：以上为保守估算。实际场景中，如果包含告警日志、系统心跳日志、图片抓拍元数据，数据量可能放大 3-5 倍。建议按峰值吞吐的 2 倍预留写入能力，并启用 Logstash 或 Kafka 做削峰填谷。
3.4 日志特点总结与架构映射
下图展示了准入门禁日志从产生到写入 Elasticsearch 的完整链路，以及各环节对应的特点与优化点：
3.5 关键结论
- 格式归一化是第一步：无论源端是 CSV 还是多行日志，必须在边缘网关或 Logstash 中统一转换为 JSON，降低后续解析复杂度。
- 字段设计决定查询效率：核心字段使用 keyword 类型，时间字段严格使用 date 类型，扩展字段使用 dynamic: false 防止映射膨胀。
- 数据量级决定分片策略：中型园区月增量约 1.5 GB，建议按日建索引，每个索引 1-2 个主分片，预留 30-60 天热数据存储。
- 写入吞吐决定架构选型：峰值 12.5 条/秒的写入压力较小，可直接使用 Filebeat → Elasticsearch；如果峰值超过 100 条/秒，建议引入 Kafka 或 Logstash 做缓冲。
下一阶段预告：基于本章的日志特点分析，第 4 章将设计准入门禁索引的 Mapping 模板与 Settings 参数，包括分片数、副本数、刷新间隔与分词器选择。