模块概述

无服务器日志归档与检索模块用于在 Serverless 架构下接收应用日志、进行对象存储归档、异步构建查询索引，并提供关键字与时间范围查询能力。模块支持多租户隔离，集成鉴权与计费，具备保留策略、压缩与清理、告警通知及审计追踪能力。对外暴露入库接口 /logs/ingest 与查询接口 /logs/search。

核心功能

• 日志入库与归档

  • 通过事件触发或 HTTP 入库接口接收应用日志。
  • 按服务名与日期进行分桶/分区写入对象存储，支持多租户隔离。
  • 支持配置的日志压缩策略（如按文件或批次压缩）。
  • 记录必要的元数据（租户、服务、时间戳、来源）以便后续索引与查询。

• 异步索引构建

  • 基于新增日志对象的事件异步构建索引。
  • 支持关键字与时间范围查询所需的索引结构（倒排索引与时间区间索引）。
  • 索引构建采用最终一致性模型，不阻塞入库。

• 日志检索

  • 提供按关键字与时间范围的查询接口。
  • 返回匹配日志的定位信息（对象存储键、偏移范围或记录标识），以及基础元数据。

• 保留策略、压缩与清理

  • 支持租户或服务级别的保留策略（按天数或日期阈值）。
  • 在保留期内可进行压缩以降低存储成本。
  • 到期对象与索引通过清理流程删除或归档。

• 多租户隔离

  • 按租户进行命名空间隔离（前缀/分桶），鉴权控制访问范围。
  • 支持租户级配额与用量统计（与计费模块交互）。

• 监控告警与审计追踪

  • 异常事件（入库失败、索引构建错误、查询超限）触发告警通知。
  • 所有管理与访问操作产生日志，纳入审计追踪。

• 鉴权与计费集成

  • 入库与查询接口在 API 网关处进行鉴权与租户识别。
  • 将入库量、存储占用、查询次数等用量指标上报计费模块。

技术架构

• 组件与职责

  • API 网关
    • 暴露 /logs/ingest 与 /logs/search。
    • 集成鉴权模块进行请求鉴权与租户解析。
  • 入库函数（Serverless Function）
    • 接收事件触发或 HTTP 请求中的日志数据。
    • 进行元数据校验（租户、服务、时间戳）。
    • 将日志按服务名与日期写入对象存储，并按租户进行前缀隔离。
  • 对象存储（日志与索引）
    • 日志桶/前缀存放原始日志数据与压缩归档。
    • 索引桶/前缀存放构建后的索引分片与时间索引。
  • 索引构建函数（异步）
    • 由对象存储新增事件触发。
    • 解析新增日志对象，生成或更新关键字倒排索引与时间范围索引。
    • 将索引分片持久化到索引前缀。
  • 查询函数（Serverless Function）
    • 解析查询条件（租户、服务、时间范围、关键字）。
    • 读取索引分片，进行筛选与合并。
    • 返回匹配日志的定位信息及元数据。
  • 清理函数（计划/定时触发）
    • 根据保留策略执行对象与索引清理。
    • 在清理前可执行压缩或归档操作（按策略）。
  • 告警与审计
    • 告警：接收模块异常事件并发送通知。
    • 审计：记录接口调用与管理操作，供审计查询。

• 数据组织与命名规范（示例）

  • 日志对象键前缀
    • {tenant_id}/{service_name}/logs/YYYY/MM/DD/HH/{uuid_or_batch_id}.log[.compressed]
  • 索引对象键前缀
    • {tenant_id}/{service_name}/index/YYYY/MM/DD/{index_shard_id}.idx
  • 元数据（对象标签或伴随清单）
    • tenant_id, service_name, ts_range, compression, ingestion_id

• 索引模型（抽象）

  • 关键字倒排索引：token -> [object_key, offset/record_id, ts]
  • 时间索引：时间片 -> [object_key, offset_range]
  • 注：索引构建为异步，查询对最新入库日志的可见性可能有短暂延迟。

• 交互流程（简化）

  1. 应用产生日志 → 事件触发/HTTP 调用 → 入库函数写入对象存储。
  2. 对象存储新增事件 → 索引构建函数生成/更新索引分片。
  3. 用户发起 /logs/search → 查询函数读取索引分片，返回命中记录。
  4. 定时任务 → 清理函数依据保留策略执行压缩与删除。
  5. 鉴权与计费模块分别在 API 网关与用量上报流程中参与。
  6. 异常或阈值事件 → 告警模块通知；接口操作 → 审计模块记录。

接口说明

• 公共约定

  • 鉴权：Authorization 头（具体鉴权方式由鉴权模块负责）。成功鉴权后解析出 tenant_id。
  • 请求与响应格式：application/json。
  • 时间格式：RFC 3339（例如 2024-09-01T12:00:00Z）。
  • 错误编码：标准 HTTP 状态码，响应体包含 code 与 message。

• 日志入库接口

  • Path: /logs/ingest
  • Method: POST
  • 用途：接收应用日志并持久化至对象存储，触发异步索引构建。
  • 请求头
    • Authorization: Bearer
    • Content-Type: application/json
  • 请求体（示例 schema）
    • tenant_id: 可选；如未提供，从鉴权上下文解析
    • service_name: 字符串
    • logs: 数组，元素为日志记录对象
      • timestamp: 字符串（RFC 3339）
      • level: 字符串（可选）
      • message: 字符串
      • fields: 对象（可选，键值对扩展属性）
  • 响应
    • 202 Accepted（异步处理）
      • ingestion_id: 字符串
      • stored_objects: 数组（对象键或批次标识）
      • note: "indexing is asynchronous"
    • 4xx/5xx 错误
      • code: 字符串
      • message: 字符串

• 日志查询接口

  • Path: /logs/search
  • Method: POST
  • 用途：基于关键字与时间范围进行日志检索。
  • 请求头
    • Authorization: Bearer
    • Content-Type: application/json
  • 请求体（示例 schema）
    • tenant_id: 可选；如未提供，从鉴权上下文解析
    • service_name: 字符串
    • query:
      • keywords: 数组（字符串，匹配关键字）
      • time_range:
        • from: 字符串（RFC 3339）
        • to: 字符串（RFC 3339）
    • pagination: 可选
      • limit: 整数（默认值由服务端配置）
      • cursor: 字符串（可选，用于翻页）
  • 响应
    • 200 OK
      • hits: 数组
        • object_key: 字符串（对象存储键）
        • record_id_or_offset: 字符串或整数（记录定位）
        • timestamp: 字符串
        • service_name: 字符串
        • tenant_id: 字符串
      • next_cursor: 字符串（可选）
      • note: "results based on asynchronous index; latest logs may be delayed"
    • 4xx/5xx 错误
      • code: 字符串
      • message: 字符串

使用示例

• 使用 cURL 写入日志

  curl -X POST https://api.example.com/logs/ingest \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "service_name": "order-service",
      "logs": [
        {
          "timestamp": "2024-09-01T12:00:00Z",
          "level": "INFO",
          "message": "order created",
          "fields": {"orderId": "A123"}
        },
        {
          "timestamp": "2024-09-01T12:00:01Z",
          "level": "ERROR",
          "message": "payment failed",
          "fields": {"orderId": "A123", "reason": "timeout"}
        }
      ]
    }'
  

• 使用 cURL 按关键字与时间范围查询

  curl -X POST https://api.example.com/logs/search \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "service_name": "order-service",
      "query": {
        "keywords": ["payment", "failed"],
        "time_range": {
          "from": "2024-09-01T12:00:00Z",
          "to": "2024-09-01T13:00:00Z"
        }
      },
      "pagination": {"limit": 100}
    }'
  

• 事件触发与索引构建（流程示例）
  1. 对象存储接收到 {tenant_id}/{service_name}/logs/2024/09/01/12/batch-001.log。
  2. 触发索引构建函数，解析日志，更新：
     • 关键字倒排索引：如 "payment" → [batch-001.log, offset=123, ts=...]
     • 时间索引：2024-09-01T12:00 → [batch-001.log, offset_range=...]
  3. 将索引分片写入 {tenant_id}/{service_name}/index/2024/09/01/shard-XYZ.idx。

注意事项

• 索引最终一致性

  • 索引构建为异步，入库后到可检索存在短暂延迟。对于严格实时场景需考虑该一致性特性。

• 多租户隔离

  • 依赖鉴权解析的租户上下文进行对象命名空间隔离。客户端不应跨租户访问或查询。

• 压缩与读取

  • 压缩策略影响查询时的读取性能与范围定位。查询函数需根据对象压缩状态选择合适的读取与解压策略。

• 保留策略与清理

  • 超出保留期的日志与索引会被删除或归档。请在策略配置中明确时间阈值与例外（如审计保留要求）。

• 关键字匹配

  • 关键字查询基于索引的精确匹配或配置的分词规则。避免依赖未声明的模糊、通配或正则能力。

• 接口限流与计费

  • 入库与查询可能受限流与配额控制；计费依据用量指标进行统计。请确保客户端遵守接口使用规范。

• 安全与合规

  • 日志中可能包含敏感信息。请在入库前进行脱敏/过滤，并遵循租户与审计的合规要求。

• 错误与告警

  • 入库失败、索引构建错误、清理异常等会产生告警通知。请配置接收渠道并及时处理。

以上文档基于 Serverless 目标架构和模块描述进行编写，涵盖模块定位、功能、架构、接口、示例与使用注意事项。

模块概述

分布式消息路由与重试模块用于将生产者提交的业务消息按业务标签路由到目标主题与分区，并向消费者提供拉取接口。模块实现去重键与幂等写入，支持指数退避重试、死信队列与延时队列，且暴露监控与告警指标。通过与权限、配置中心和存储协同，保障高可用与可运维性。

核心功能

• 消息路由

  • 基于业务标签将消息路由到目标主题与分区。
  • 路由规则由配置中心下发与管理。
  • 规则缺失时，拒绝写入并返回明确错误。

• 生产与消费接口

  • 生产者发布接口：/messages/publish。
  • 消费者拉取接口：/messages/poll。
  • 接口层做权限校验与限流控制。

• 幂等与去重

  • 支持去重键（dedupeKey），以实现幂等写入。
  • 在去重窗口内（由存储与配置策略决定），相同dedupeKey的重复发布不会产生重复消息。

• 重试机制（指数退避）

  • 失败消息按指数退避进行自动重试，重试次数与退避参数可通过配置中心设置。
  • 达到最大重试次数后进入死信队列（DLQ）。

• 死信队列（DLQ）

  • 存放多次重试仍失败或不可路由的消息，用于后续分析与人工/自动补偿。

• 延时队列

  • 支持按延时属性投递（如延时毫秒或定时投递时间），到期后转入正常投递流程。

• 监控与告警

  • 暴露关键指标：发布成功率、发布延迟、重试次数与失败率、死信数量、消费延迟等。
  • 支持阈值告警（如发布失败率、死信增长异常）。

• 高可用协同

  • 权限系统：鉴权与接口访问控制。
  • 配置中心：路由、重试、延时与阈值策略的集中配置与动态生效。
  • 存储层：消息持久化、去重索引与队列管理，支持多副本与故障切换（具体策略以存储实现为准）。

技术架构

• 组件划分

  • 接入层（API Gateway/Service）：提供/messages/publish与/messages/poll，进行鉴权、限流、参数校验。
  • 路由器：按业务标签查找路由规则，决定目标主题与分区。
  • 写入器：执行幂等写入（基于dedupeKey的去重索引与消息存储），返回投递结果。
  • 重试调度器：维护失败消息的指数退避计划，调度重试与转入DLQ。
  • 延时调度器：管理延时消息，到期后投递至目标主题与分区。
  • 监控与告警：采集指标，输出到监控系统与告警通道。
  • 权限与配置适配层：与权限系统、配置中心交互，确保策略生效与安全合规。

• 数据流概览

  • 发布：客户端调用/messages/publish → 鉴权与校验 → 路由规则解析 → 幂等写入 → 返回结果；失败进入重试队列或DLQ。
  • 拉取：客户端调用/messages/poll → 鉴权与校验 → 从目标主题分区读取可用消息 → 返回消息批次。

• 状态与存储

  • 消息存储：主题/分区组织的持久化数据。
  • 去重索引：基于dedupeKey的索引结构，维护幂等窗口。
  • 调度存储：用于重试与延时的计划队列。

接口说明

• /messages/publish

  • 用途：生产者发布消息，按业务标签路由并写入目标主题与分区，支持幂等。
  • 建议协议与方法：HTTP POST（实际以部署配置为准）。
  • 请求字段（JSON）：
    • tag：string，业务标签（必填）。
    • payload：object|string，消息内容（必填）。
    • headers：object，消息头（选填）。
    • dedupeKey：string，去重键（选填，用于幂等）。
    • delayMs 或 deliverAt：number|string，延时毫秒或投递时间戳（选填）。
  • 响应字段（JSON）：
    • messageId：string，消息唯一标识。
    • routedTo：object，包含topic与partition。
    • status：string，"accepted" 或错误描述。
    • retryPlan：object（选填），若进入重试，返回当前重试状态摘要。

• /messages/poll

  • 用途：消费者按主题与分区拉取消息。
  • 建议协议与方法：HTTP GET/POST（实际以部署配置为准）。
  • 请求参数：
    • topic：string（必填）。
    • partition：number（必填）。
    • maxBatch：number（选填），最大返回条数。
    • timeoutMs：number（选填），服务端等待可用消息的最长时间（长轮询可选）。
  • 响应字段（JSON）：
    • messages：array，元素包含：
      • messageId：string
      • tag：string
      • payload：object|string
      • headers：object
      • attempt：number，当前重试次数（首投为0）
      • routedTo：object，topic与partition

注：具体协议、方法与鉴权头部由权限与网关层配置决定；若路由规则未配置或权限校验失败，接口返回明确错误码与信息（如"ROUTE_NOT_FOUND"、"UNAUTHORIZED"）。

使用示例

• 发布消息
  • curl 示例（HTTP POST）：

    curl -X POST https://api.example.com/messages/publish \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer <token>" \
      -d '{
        "tag": "order.created",
        "payload": {"orderId": "O123", "amount": 19900},
        "headers": {"traceId": "T-001"},
        "dedupeKey": "order-created-O123",
        "delayMs": 0
      }'
    

• 拉取消息
  • curl 示例（HTTP GET）：

    curl "https://api.example.com/messages/poll?topic=orders&partition=3&maxBatch=50&timeoutMs=3000" \
      -H "Authorization: Bearer <token>"
    

注意事项

• 路由配置
  • 发布前需确保对应业务标签已在配置中心完成路由规则配置，否则将被拒绝。
• 幂等与去重
  • dedupeKey需具备业务唯一性；去重窗口由存储策略与配置决定，超出窗口后重新发布可能产生新消息。
• 重试与DLQ
  • 指数退避参数与最大重试次数通过配置中心设置；重试耗尽的消息将进入DLQ，需要业务侧建立处理与告警机制。
• 延时投递
  • 延时队列不保证绝对精确的投递时间，存在合理误差范围。
• 权限与配额
  • 调用接口必须通过权限校验；可能存在每秒请求与消息大小限制，具体以权限与网关配置为准。
• 高可用与容错
  • 模块节点无状态，可水平扩展；存储层的副本与故障切换策略由具体实现提供，需结合运维监控与告警进行保障。
• 兼容与演进
  • 接口字段的扩展通过配置中心与版本化策略推进；依赖方应避免对未声明字段的强耦合。