用户手册
21. 问题诊断与处理
完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。
本章按现象列出排查入口，并说明如何从一次失败的网关请求定位到原因。主要使用的页面是「管理控制台 → 概览」中的「网关请求」「对话」「路由策略命中」页签、「会话诊断」和「操作审计」；平台级问题使用平台管理员的「系统运行监控」与「出口网络」。各页面的完整说明见第 19 章和第 20 章。
| 现象 | 优先核对 | 进一步核对 |
|---|---|---|
| 看不到管理控制台或目标入口 | 当前账号是否为管理员或具备对应职责角色；许可是否包含该页面所属模块 | 是否登录了正确的租户；「系统运行监控」「出口网络」只在平台管理员的管理控制台中显示 |
| 登录后首页与预期不同 | Zentrix 登录后进入个人首页的「使用情况」 | 管理员从右上角账号菜单进入「管理控制台」 |
| 供应商验证失败 | 地址、API 密钥、供应商类型和网络 | 供应商侧的模型权限；「出口网络」中该供应商目标的时延与丢包 |
| 模型服务已启用但不能用 | 服务中是否有已启用的模型 | 「网关请求」中该模型请求的「责任方」；「平台配置」表示渠道凭据没有该模型的访问权，或该模型没有可用渠道 |
| 请求被额度或速率拒绝 | 「网关请求」的「结果归因」是否为「策略 · 配额 / 预算」或「策略 · 限流 / 排队超时」 | 模型服务配额、API 密钥配额和全局限额；「会话诊断」中的「被额度或限流拒绝」问题 |
| 用量页面一直为 0 | 所选时间范围是否包含实际调用 | 调用是否发生在其他模型服务、接入凭据或成员下 |
| 成员看不到 MCP 服务 | MCP 是否已发布，成员是否在可用范围内 | 授权有效期和组织归属 |
| MCP Tools 为空或调用失败 | 端点是否可达、Tools 是否解析成功 | 在「网关请求」中按「调用类型」筛选「MCP 调用」，查看失败记录；排查材料中不得记录密钥 |
| 敏感数据误报或漏报 | 流量规则选中的检测类型、正则表达式和命中处置 | 用「敏感数据试运行」和脱敏样本复测（13.3 节） |
| 护栏未按预期拦截 | 流量规则中是否有启用的「内容检测」动作覆盖该调用 | 请求详情「路由与改写」页签的「命中记录」中是否有该次请求的命中 |
| 模型调用慢或失败 | 「网关请求」中按时间和「结果」筛选 | 打开请求详情，查看「时延与成败」和「路由与改写」页签 |
| 多轮会话反复失败或费用异常 | 「对话」页签中的会话详情 | 「会话诊断」中的问题清单 |
| 配置被意外修改 | 「操作审计」中选择时间范围和操作 | 在搜索框中查询操作人、动作或资源 |
21.1 网关请求：定位失败调用
「网关请求」记录经过网关的每一次模型、MCP、A2A 和 API 服务调用，包括结果、失败阶段、耗时、命中规则和每次上游尝试。排查运行期失败时，先在这里找到目标请求，再按详情中的线索进入对应的配置页面。
前提：
- 租户管理员、「运营」「财务」「只读审计」角色可以打开该页签。
- 「运营」角色只看到本人发起的请求；查看全租户的请求需要租户管理员、「财务」或「只读审计」权限。具备「财务」角色、但不是租户管理员或「只读审计」的账号不能打开请求详情。
操作步骤：
- 进入「管理控制台 → 概览」，选择「网关请求」页签。
- 在工具栏选择覆盖问题发生时间的时间范围。
- 使用筛选器缩小范围：「结果」选择「失败」或「已拦截」；需要按失败原因查看时，选择「结果归因」「错误类型」或「责任方」，列表切换为交付记录，「操作」列给出对应的处理入口。
- 已知请求 ID、Trace ID 或成员时，在搜索框「搜索 Trace / 请求 ID / 用户 / 资源」中直接输入。
- 点击目标行打开请求详情；交付记录中先打开「交付详情」，查看「终止原因」后点击「查看该请求」。按下表判断原因类型。
| 详情中的线索 | 原因类型 | 处理入口 |
|---|---|---|
| 「时延与成败」中「拦截原因」有值，「命中记录」中有内容护栏的命中 | 护栏 | 「护栏」中对应的敏感数据、词库或问答规则 |
| 「结果归因」为「策略 · 限流 / 排队超时」或「策略 · 配额 / 预算」，「失败阶段」为「限流」或「配额」 | 限流与配额 | 「流量规则」中的全局限额、模型服务配额、API 密钥配额 |
| 「路由与改写」中「路由结论」为「已拦截」，或「失败阶段」为「路由选择」 | 路由 | 「流量规则」中「规则链」所列的规则 |
| 「失败阶段」为「认证」或「鉴权」 | 调用身份 | API 密钥、调用规则与可用范围 |
| 「责任方」为「上游故障」，「上游尝试」中出现「超时」「流中断」等结果 | 上游 | 「操作」列的「查看上游健康」进入「模型供应商」；平台管理员查看「出口网络」 |
| 「责任方」为「平台配置」 | 渠道配置 | 「操作」列的「配置路由策略」进入「流量规则」；同时核对模型服务的渠道凭据 |
| 「责任方」为「调用方」 | 请求本身不合法，或指名了不存在的模型 | 通知调用方修正请求 |
| 「责任方」为「传输中断」 | 已开始返回，中途断开 | 客户端网络与平台出口网络 |
- 修正配置后，由同一调用方重新发起一次请求，在列表中确认新记录的「结果」为「已完成」。
已购 FinOps 模块时，也可以从「网关总览」页签的「请求结果归因」图表进入：点击某一类结果，页面切换到「网关请求」并带上相应的「结果归因」筛选。
21.2 操作审计：定位配置变更
配置变更后出现资源不可用或行为变化时，进入「管理控制台 → 审计与合规 → 操作审计」。该页面需要全链路审计模块，租户管理员和「审计员」可以使用。
工具栏提供时间范围、搜索框「搜索操作人、动作或资源...」和筛选器；筛选项包括「按操作筛选」「按结果筛选」「数据等级」「策略来源」「策略动作」「模型」等。「操作人员」和「资源」没有独立筛选项，需要在搜索框中查询。
- 选择覆盖问题发生时间的范围，并设置「按操作筛选」与「按结果筛选」。
- 在搜索框中输入操作人员、动作或资源名称；需要时继续选择「数据等级」「策略来源」或「策略动作」。
- 打开目标记录，核对操作人员、对象、变更时间、结果和页面提供的前后状态。
- 将记录时间与「网关请求」中异常开始出现的时间对齐。
- 确认误操作后回到对应管理页面恢复配置，再执行一次正常请求和一次无权限请求。
- 在「操作审计」中确认恢复操作已有记录，资源状态与预期一致。
追溯 AI 调用与合规决策
需要说明一次 AI 请求被放行、拦截、改写或路由到某个模型的原因时，按同一请求 ID 和时间把以下记录串联起来：
- 在「网关请求」中定位目标请求，记录请求 ID、Trace ID、发起人、模型、结果和发生时间。
- 打开请求详情的「路由与改写」页签：「请求去向」给出客户端声明的模型、接管请求的规则链和最终执行的供应商与模型；「命中记录」列出该请求命中的全部策略及动作；「上游尝试」列出每次尝试的结果与原因。
- 需要核对网关实际发出的内容时，在「请求」页签对比客户端请求与发往上游的请求。每次读取报文正文都会写入一条审计记录。
- 涉及敏感数据时，进入「操作审计」，在「按操作筛选」中选择「敏感数据」，按相同时间范围查找检测记录。
- 请求属于多轮会话时，点击详情页头部的「看该会话」，在会话详情的「网关调用」和「诊断」页签中查看同一会话内的其他失败与诊断结论。
- 配置近期有调整时，在「操作审计」中查询模型、路由规则、配额、MCP 或护栏的变更记录。
- 将请求、策略命中、会话和配置变更按时间顺序整理到同一事件记录中，区分请求失败、策略拒绝和上游失败。
- 修正配置后，用相同入口发送一条不含真实敏感信息的验证请求，确认「网关请求」中出现新的记录且结果符合预期。
审计记录用于说明平台实际执行了什么，不替代业务系统中的结果核对。报文已按租户日志策略清理或未留存时，应以页面可见的证据完成判断，不通过其他渠道索取或传播敏感原文。