4. 接口调用基础：Loki HTTP API 概览，Push API 与 Query API 的端点与认证方式

在变更门禁场景中，Loki 的 HTTP API 是日志平台与门禁系统之间的通信桥梁。门禁系统通过 Push API 写入日志，通过 Query API 检索日志。理解这两类 API 的端点、数据格式与认证方式，是后续实现联动调试的前提。

4.1 Loki HTTP API 整体架构

Loki 对外暴露统一的 HTTP 服务端口（默认 3100），所有 API 均基于 RESTful 风格。下图展示了 Push API 与 Query API 在整体架构中的位置与数据流向：

4.2 Push API：日志写入端点

Push API 是门禁系统向 Loki 写入日志的唯一入口。变更事件、审批记录、执行结果等日志数据均通过此接口发送。

4.2.1 端点与请求方式

4.2.2 请求体结构详解

每个 Push 请求包含一个或多个 streams，每个 stream 由标签（labels）和日志条目（values）组成：

{
  "streams": [
    {
      "stream": {
        "job": "change-gate",
        "environment": "production",
        "change_id": "CHG-20250321-001"
      },
      "values": [
        ["1711000000000000000", "{\"level\":\"info\",\"msg\":\"变更审批通过\",\"user\":\"admin\"}"],
        ["1711000001000000000", "{\"level\":\"info\",\"msg\":\"变更开始执行\",\"user\":\"admin\"}"]
      ]
    }
  ]
}

4.3 Query API：日志查询端点

Query API 用于从 Loki 中检索日志数据。在变更门禁场景中，日志平台通过此接口查询变更事件、执行状态和异常信息。

4.3.1 端点与请求方式

4.3.2 两种查询模式对比

4.4 认证方式

Loki 支持多种认证机制，在变更门禁场景中，推荐使用以下两种方式：

4.4.1 Basic Auth（基础认证）

通过 HTTP Header 传递用户名和密码（Base64 编码）：

# Push API 请求示例（带 Basic Auth）
curl -X POST "http://loki.example.com:3100/loki/api/v1/push" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password123' | base64)" \
  -d '{"streams":[{"stream":{"job":"change-gate"},"values":[["1711000000000000000","test log"]]}]}'

4.4.2 X-Scope-OrgID（多租户认证）

Loki 的多租户模式通过 X-Scope-OrgID 头标识租户。门禁系统可为不同环境（生产、预发、测试）分配独立 OrgID：

# 带租户标识的 Push 请求
curl -X POST "http://loki.example.com:3100/loki/api/v1/push" \
  -H "Content-Type: application/json" \
  -H "X-Scope-OrgID: production" \
  -d '{"streams":[{"stream":{"job":"change-gate"},"values":[["1711000000000000000","test log"]]}]}'

4.5 Push API 与 Query API 认证方式对比

4.6 接口调用流程示例

以下是一个完整的变更门禁日志写入与查询的调用流程：

4.7 常见错误与排查