用户手册
19. 可观测入口、数据来源与权限边界
完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。
Zentrix 的可观测数据保存在客户环境内，在管理控制台中查看。经过网关的调用由网关自动记录，客户端无需改造。本章说明各入口的位置与可见角色、数据从哪里来、依赖哪些组件，以及数据安全边界。具体操作见第 20 章。
19.1 选择入口
| 入口 | 路径 | 可见角色与前提 | 用途 |
|---|---|---|---|
| 「网关总览」页签 | 管理控制台 → 概览 | 租户管理员与「系统管理员」「运营」「安全管理员」「审计员」，「财务」只看到费用类面板（见 17.2 节）；用量分析面板需要 FinOps 模块 | 整体请求量、成功率、耗时与失败归因 |
| 「网关请求」页签 | 管理控制台 → 概览 | 租户管理员、「运营」「财务」「只读审计」；「运营」只看到本人发起的请求 | 检索单次调用，查看结果、路由、改写、上游尝试和报文 |
| 「对话」页签 | 管理控制台 → 概览 | 租户管理员、「只读审计」 | 按会话查看多轮调用、耗时、Token、费用与诊断 |
| 「路由策略命中」页签 | 管理控制台 → 概览 | 租户管理员。页签对「安全管理员」也显示，但命中数据接口只对租户管理员与「系统管理员」放行，安全管理员无法加载数据；页签属于基础功能，汇总的规则来自「流量规则」 | 按规则查看路由策略的命中次数、放行与拦截 |
| 「会话诊断」 | 管理控制台 → 概览 → 会话诊断 | 租户管理员 | 自动识别会话中的问题，给出原因、证据与修复建议，处理后复查 |
| 「操作审计」 | 管理控制台 → 审计与合规 → 操作审计 | 租户管理员、「审计员」；需要全链路审计模块 | 配置变更、敏感数据检测与访问记录 |
| 「报表导出」 | 管理控制台 → 审计与合规 → 报表导出 | 租户管理员、「系统管理员」 | 下载调用与用量数据、配置定时导出 |
| 「系统运行监控」 | 管理控制台 → 运行与排障 → 系统运行监控 | 平台管理员 | 网关节点、控制面服务与平台依赖的运行状态 |
| 「出口网络」 | 管理控制台 → 运行与排障 → 出口网络 | 平台管理员 | 平台访问公网的分层时延、丢包与逐跳诊断 |
| Prometheus 指标抓取 | 无界面 | 具备运行查看权限的账号身份；见 19.3 | 把按租户过滤的技术指标接入客户自有监控 |
「网关告警」页签与告警规则的配置见第 22 章。上述页面只显示当前账号权限与租户范围内的数据；角色由「管理控制台 → 组织与权限 → 角色管理」分配。
19.2 数据来源与依赖
| 数据 | 来源 | 依赖与限制 |
|---|---|---|
| 网关请求 | 网关自动记录每次模型、MCP、A2A 和 API 服务调用 | 无需客户端改造。请求列表、请求详情、「网关总览」的用量面板、用量分析与调用日志读取分析存储（ClickHouse），报文正文读取对象存储；分析存储是必装组件。分析存储暂时不可用时，这些页面提示「分析数据库读取超时，请稍后重试」，恢复后可查；网关节点在此期间把调用明细保留在本地，恢复后自动补齐，页头的「数据截至」时间停留在分析存储最后一次写入的时刻。模型调用本身不受影响 |
| 请求与响应报文 | 网关按「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」四段采集 | 需要平台对象存储：单机裸机部署可使用自带对象存储、本机目录或现有的 S3 兼容存储，多机与 Helm 部署只能使用现有的 S3 兼容存储。报文先在网关节点暂存，再补传到中心存储；留存规则见 22.5。单段超过 32 MiB 时截断 |
| 策略命中 | 网关在每次请求中记录命中的路由、流量限额、内容护栏（含工具调用防护）和站点防护等策略 | 存放在分析存储中。分析存储未就绪时，「路由策略命中」显示「策略命中数据暂不可用（观测存储未就绪），下方为空。」，请求详情显示「命中记录暂不可用（ClickHouse 未配置或查询失败）」 |
| 会话 | 网关把同一会话的多轮调用串联 | 会话列表的「来源」列显示「网关」「客户端上报」或「网关与客户端上报」。只有网关数据时，看不到客户端本地执行的命令与工具步骤 |
| 会话诊断结论 | 平台按会话数据定期运行规则检查；开启模型评审后，再由所选模型评审会话 | 模型评审按所选模型计费，可设置月预算，见 20.4 |
| 平台运行状态 | 各服务实例与网关节点定期上报运行状态 | 实例的处理器与内存历史依赖分析存储；不可用时显示「历史数据暂不可用」。网关节点详情的本机负载、过载保护与入库状态来自节点自报，不依赖分析存储 |
19.3 Prometheus 指标抓取
平台在 /ops/metrics/{service} 路径上提供按租户过滤的 Prometheus 文本格式指标，供客户自有的 Prometheus 抓取。{service} 取值为 zenova-control-plane、zenova-edge、zenova-worker 和 zenova-runtime-store；模型路由的指标随 zenova-edge 一并返回。未部署的服务返回 404。
返回内容只包含两类序列：
- 带租户标签且属于当前租户的序列；
- 不带租户维度的技术指标，包括
process_*、lobsterpool_http_server_request_duration_seconds、db_pool_*、lobsterpool_db_pool_*和gen_ai_server_*。
限制：抓取请求必须以具备运行查看权限的账号身份认证，租户管理员、「运营」「系统管理员」「安全管理员」「审计员」具备该权限。机器调用使用「访问密钥」，每个请求单独签名。采用该接口前，请与支持团队确认采集方式；客户需要自备 Prometheus 与看板。
19.4 数据安全
观测数据可能包含用户输入、模型输出、工具参数和请求头。平台对报文采取以下控制：
- 每次读取报文正文或差异都写入一条审计记录；审计写入失败时不返回正文，页面显示「报文访问审计写入失败，未返回报文」。
- 请求头中的凭据在采集时抹除，页面显示「已抹除·长度 N」或「平台凭据」，不显示原值。
- 请求详情的「请求改动」只记录改写的位置与方式，不记录请求内容与请求头的值。
- 留存策略为不留存内容时，正文在网关节点上即不产出，页面显示「按租户日志策略未留存报文」；超过留存时长的报文被清理，页面显示「报文已超过租户日志策略的留存时长，已清理」。
- 会话诊断证据的原文超过保留期后显示「原文已过保留期」。
接入前应约定：哪些输入输出允许留存原文、敏感数据与内部地址如何脱敏、各角色可查看的范围、导出与归档的保留期限。「已脱敏」必须由实际报文样本证明，不能只根据配置开关的状态判断。