02 · Runtime Architecture – TEVER Core (v0.5)

v0.4 运行时以 "Ingest Gateway → EventBus → RuleEngine / Projection / Audit" 为主线。
v0.5 在其基础上，新增 LLM Gateway + Prompt Registry + AI Actions，使 LLM 成为 Core 的受控工具。

0. 总览：v0.5 关键链路

(Edge / On-Prem)
Collector Agent
  └─ push EventEnvelopeV1 (HTTP/mTLS)
          ↓
(Core)
Ingest Gateway → Validate/Normalize → EventBus → Consumers
                                   ↘ Event Store (hot) ↘ Cold Store/Archive (later)
Consumers:
  - RuleEngine (filter/aggregate/trigger)
  - Projection Engine (把部分外部事件投影为实体状态，可选)
  - Audit Service (证据链、工具调用、审批留痕)
  - LLM Gateway (v0.5 新增：统一 LLM 接入)
  - Analytics/Reporting (可选)

1. 组件拆分（v0.5）

1.1 Ingest Gateway（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

提供 POST /ingest/events（批量/单条）
认证：token 或 mTLS（由 EventSource 配置决定）
处理：解析 EventEnvelopeV1、校验 schemaRef、去重、脱敏、写入 Event Store & 发布到 EventBus

1.2 Schema Registry（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

存储 schema（按 appId/type/version）
供 ingest 校验、UI 字段提示、Rule 编辑器引用

1.3 EventBus（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

v0.4 已提出可用 Kafka/RabbitMQ/Redis Streams/NATS
MVP 推荐两种落地：
- 轻量：Postgres events 表 + Redis Stream（或仅 Redis Stream）
- 进阶：Kafka（topic = tenant + source/type 分区）

1.4 RuleEngine（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI Actions。

支持两类规则：
- on_event（流式）：对 event stream 实时处理
- on_schedule（扫描）：定时聚合、报表、合规核查
v0.5 新增：支持 AI Actions（invoke_llm_summary、invoke_llm_report、invoke_llm_generate_doc）

1.5 Window Aggregator（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

负责对事件流做时间窗口聚合（count/avg/max…），并将聚合结果写入 Aggregates Store
状态存储：
- 轻量：Redis（窗口 state）+ Postgres（聚合结果）
- 进阶：Kafka Streams / Flink（可后续演进）

1.6 Alert Service（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI 洞察关联。

负责把 RuleEngine/聚合触发结果"落为告警对象"（Alert）
提供：去重合并（fingerprint）、状态流转（open/acked/closed/muted）、SLA & 升级
v0.5 新增：支持关联 AI 洞察（ai_insight_id）

1.7 Action Executor（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI Actions。

所有动作（邮件、Webhook、工单、审批、封禁、归档、AI）统一入口
动作执行必须：
- 先写 action_requested 审计记录
- 执行后写 action_succeeded/action_failed
- 关联 traceId 与 ruleId
v0.5 新增：支持 AI Actions（只读），禁止直接改实体

1.8 Query Service & View Renderer（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI 洞察查询。

对外提供统一 Query API：events/alerts/aggregates/audits/search
v0.5 新增：支持查询 AI 洞察（GET /api/v1/query/ai_insights）
v0.5 新增：支持查询文档草稿（GET /api/v1/query/document_drafts）
View Renderer 负责：统一鉴权、渲染通用组件（EventStream/Alert/Audit/Search/AIInsight）

1.9 Audit Service（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展 tool_call 记录。

目标：支持"事后追责/合规审计/对外审计"
记录：
- rule 命中证据（输入事件/聚合窗口）
- 动作执行证据（参数/响应/失败原因）
- tool_call（如果有大模型/外部工具）
v0.5 扩展：tool_call 记录增强（prompt 版本、模型版本、输出 hash、tokens、校验结果）
可导出：按时间范围导出不可篡改包

1.10 Prompt Registry（v0.5 新增）

位置: backend/app/core/prompts/

功能：

存储 Prompt 模板（按 appId/name/version）
支持版本化、回滚、启用状态
每个 prompt 绑定 output_schema（结构化输出，JSON Schema）
支持 PromptPack 安装（类似 RulePack）

API：

GET /api/v1/prompts/templates - 查询 Prompt 模板列表
GET /api/v1/prompts/templates/{id} - 查询 Prompt 模板详情
POST /api/v1/prompts/templates - 创建 Prompt 模板
PUT /api/v1/prompts/templates/{id} - 更新 Prompt 模板
DELETE /api/v1/prompts/templates/{id} - 删除 Prompt 模板（软删除）
POST /api/v1/prompts/render - 渲染 Prompt（变量替换）
POST /api/v1/prompts/validate - 验证输出是否符合 schema

1.11 LLM Gateway（v0.5 新增）

位置: backend/app/core/llm/

功能：

统一 LLM 接入（OpenAI/Dify/本地模型）
限流（按租户/App/用户）
缓存（相同输入缓存结果）
重试（指数退避）
结构化输出校验（JSON Schema）
关键：输入只用引用（eventIds/alertIds/entityIds/timeRange/viewPreset），由 Core Query API 组装 context pack

API：

POST /api/v1/llm/chat - 聊天接口
POST /api/v1/llm/chat/stream - 流式聊天接口（可选）

数据流：

Rule/Action
    ↓
LLM Gateway API
    ↓
Context Builder (组装上下文)
    ↓
Prompt Renderer (渲染 Prompt)
    ↓
Rate Limiter (限流检查)
    ↓
Cache (缓存检查)
    ↓
LLM Provider (调用 LLM)
    ↓
Retry (如果需要)
    ↓
Validator (输出校验)
    ↓
Audit Logger (记录审计)
    ↓
返回结果

2. 存储策略（v0.4 已有，v0.5 扩展）

2.1 MVP（先跑通）

Event Store：PostgreSQL（events 表）
Audit Store：PostgreSQL（audit_log / tool_calls）
v0.5 新增：Prompt Store：PostgreSQL（prompt_templates 表）
对象存储：MinIO/S3（存放导出包、原始附件）

2.2 进阶（高吞吐 & 长期沉淀）

EventBus：Kafka
Hot Store：ClickHouse/Timescale（可选）
Cold Store：对象存储（分区 parquet）+ 数仓（可选）
核心原则：Core 仍对外提供统一 Query API；底层存储可替换

3. Push vs Pull：采集策略决策（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

3.1 默认：Push（内网探针）

适用：外协系统在内网、不可被 TEVER 访问。

部署 tever-agent（Collector Agent）
Agent 通过 token/mTLS 向 Ingest 推送

3.2 补充：Pull（云端可达系统）

适用：SaaS、开放 API、外网系统。

由 Core 的 Connector Worker 定时拉取
拉取后也必须变成 EventEnvelopeV1 再进入同一链路

4. "外部事件 → 内部实体"的投影（v0.4 已有）

v0.4 已定义，v0.5 保持不变。

不是所有外部事件都要变成 Entity 状态。v0.4 给出可选策略：

只存事件：用于审计/告警/趋势（最轻）
投影为 Entity：当你希望在 UI 中以"对象状态"方式呈现

5. 多租户与隔离（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展 LLM 限流和隔离。

tenantId 是 EventEnvelope 的一级字段
EventSource 绑定 tenantId
Rule/Action 默认只能作用于本 tenant 的数据
导出/审计必须按 tenant 分区
v0.5 新增：LLM 限流按 tenant/App/用户隔离

6. Query API（v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展 AI 相关查询。

目标：View Renderer / App Views 只依赖这一层，不直连 ES/Kafka/DB。

v0.4 已有：

GET /query/events - 事件流查询
GET /query/alerts - 告警列表/详情
GET /query/aggregates - 聚合结果查询
GET /query/audits - 审计记录查询
GET /query/search - 统一检索入口

v0.5 新增：

GET /query/ai_insights - AI 洞察查询
GET /query/document_drafts - 文档草稿查询

约束：Query 层对"底层存储实现"保持可替换；迁移存储不影响 Views 与 Apps。

7. 平台可观测性（TEVER 监控 TEVER，v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展 AI 相关指标。

建议在 Core 内置 telemetry 指标，并事件化（见 01 文档）：

v0.4 已有指标：

ingest：QPS、校验失败率、拒绝率、延迟
rules：命中次数、执行时延、失败率
actions：成功率、重试次数、外部调用耗时
agents：在线率、心跳丢失、缓冲队列长度

v0.5 新增指标：

llm：调用次数、成功率、平均耗时、tokens 消耗、限流触发次数
prompts：模板使用次数、渲染失败率、输出校验失败率

这些指标既可输出 Prometheus，也可写入事件流，驱动哨兵规则与面板。

文档版本: v1.0
最后更新: 2025-12-17