Loki 基础回顾：架构核心组件与日志流模型

在深入调试门禁接口与日志平台联动方案之前，必须重新理解 Loki 的核心架构。Loki 的设计哲学与 Prometheus 一脉相承——不解析日志内容，只索引元数据（标签），这使得它在高吞吐场景下比 Elasticsearch 节省约 10 倍的存储与内存。本节将拆解三个核心组件的工作职责，并说明日志流（Log Stream）模型如何决定查询效率。

2.1 核心组件职责与交互流程

Loki 采用微服务架构，Distributor、Ingester、Querier 构成数据面主干。下表对比了各组件的核心职责与关键配置参数：

下图展示了日志从推送至可查询的完整路径，重点标注了门禁接口调用链中可能出现的瓶颈点：

2.2 日志流模型：从标签到 Chunk

Loki 的日志流模型是理解写入与查询性能的基础。一个日志流（Log Stream）由一组完全相同的标签组合唯一标识，所有属于该流的日志行按时间顺序追加。模型包含三个关键层次：

1. 标签（Labels）：键值对，如 job="api-gateway"、env="prod"。标签是索引的唯一入口，标签基数（cardinality）直接影响 Distributor 路由效率和 Ingester 内存占用。
2. Chunk：Ingester 将同一日志流的数据按时间或大小打包成 chunk，压缩后存储。默认 chunk 大小为 1.5 MB，压缩比通常为 5:1 ~ 10:1。
3. 索引（Index）：Loki 2.x 之后默认使用 BoltDB（单机）或 TSDB（集群）存储标签到 chunk 的映射关系，不再依赖外部索引组件。

下表对比了标签与日志行内容的适用场景，帮助你在门禁接口日志接入时做出正确设计：

下图展示了日志流从写入到存储的完整生命周期，重点说明标签如何决定流的分片与合并：

2.3 组件协作与门禁接口调试要点

在门禁接口调用与日志平台联动方案中，理解组件协作顺序能帮助快速定位故障。一次完整的日志推送与查询流程如下：

• 推送阶段：客户端通过 HTTP API POST /loki/api/v1/push 发送日志 → Distributor 验证标签格式与速率限制 → 一致性哈希选择 Ingester 副本 → Ingester 追加到内存流并定期刷 chunk 至对象存储。
• 查询阶段：用户通过 LogQL 查询 → Querier 并行请求 Ingester（热数据）和对象存储（冷数据） → 合并结果并去重 → 返回日志行。
• 门禁接口调试关注点：推送阶段的 distributor_bytes_received_total 和 ingester_chunks_flushed_total 指标能直接反映数据是否成功写入；查询阶段的 querier_query_duration_seconds 超过 3s 通常意味着标签过滤不足或冷数据查询未命中缓存。