20. 网关请求、会话与根因定位

返回概览 · 完整版目录 · 下载完整 PDF

本章说明如何在管理控制台中查询单次网关请求、按会话查看多轮调用、处理会话诊断给出的问题、核对路由策略命中，以及平台管理员如何查看平台运行状态和出口网络。入口与权限见 19.1。

20.1 查询网关请求

入口：「管理控制台 → 概览」，选择「网关请求」页签。

页签顶部是时间范围与请求量分布条，在分布条上拖选可缩小时间窗；下方是请求列表。工具栏提供：

• 搜索框「搜索 Trace / 请求 ID / 用户 / 资源」；
• 顶栏实体筛选：「客户端」「目标模型」「接入凭据」，以及部门和成员范围；
• 列表筛选：「结果」「调用类型」「命中策略」「HTTP 状态码」「耗时区间（毫秒）」「供应商」「请求 ID」「MCP 工具」等；
• 「导出 CSV」：导出当前筛选范围内的请求。

列表默认显示调用记录，主要列包括「Trace ID」「发起人 · 客户端」「部门」「上游端点」「全周期耗时」「结果」「失败阶段」「请求造型」「耗时构成」「模型」「输入 / 输出 Token」「费用」和「时间」。「结果」取值为「已完成」「已拦截」「失败」「已取消」。

选择「结果归因」「错误类型」「责任方」「渠道」「网关模型」「发出模型」或「上游模型一致性」任一筛选后，列表切换为交付记录，按上游交付的结果展示「渠道」「网关模型」「网关 / 上游状态码」「发出模型」「上游自报模型」「一致性」「重试次数」「责任方」「交付结论」等列。「操作」列对「平台配置」类失败给出「配置路由策略」，对「上游故障」类失败给出「查看上游健康」。点击交付记录打开「交付详情」，其中「终止原因」列出「结果归因」「终止原因码」「失败阶段」「截断预算」和「供应商」，点击「查看该请求」进入请求详情。

「上游模型一致性」用于发现上游替换模型：取值「一致」「不一致」「上游未声明」。「不一致」表示上游响应中自报的模型与网关发出的模型不同。

限制：

• 「运营」角色只看到本人发起的请求，页面显示「仅显示你本人发起的请求。查看全公司的请求需要管理员、财务或只读审计权限。」
• 具备「财务」角色、但不是租户管理员或「只读审计」的账号可以浏览列表，不能打开请求详情。
• 「处理节点」筛选仅平台管理员可用。

20.2 阅读请求详情

点击调用记录进入请求详情。页头显示 Trace ID、发起人、请求造型和结果，提供「看该模型流水」「看该会话」（有会话读取权限时显示）和「刷新」；会话尚在整理时，会话位置显示「会话整理中」并自动重试，超过 1 分钟显示「会话整理较慢，请稍后刷新」，并可用上一条、下一条在当前列表中切换（「第 N / M 条」）。详情分为五个页签：

「路由与改写」页签按请求经过网关的顺序展示：

• 「请求去向」：「客户端声明的模型」、接管请求的「规则链」（「第 N 条规则」，最后一条标注「终局规则」）、「最终执行」的供应商与模型、「路由结论」（「已改路由」「未改路由」「已拦截」）及「原因」。本次请求未触发规则时显示「本次请求没有触发任何路由规则」。
• 「上游尝试」：每一次尝试的「序号」「档位」「供应商 / 模型」「账号 · 选号理由」「结果」「原因」「状态码」「耗时」「首字时间」。结果包括「成功」「响应被拒」「超时」「客户端中止」「流中断」等；故障转移与重试在这里逐次可见。
• 「请求改动」：「模型名」的改写（「原名 → 新名」）和命中规则对「请求头与请求体」的改写位置；「原始报文」一行提供「对比原始请求与上游请求」。
• 「命中记录」：该请求命中的全部策略，列出「时间」「规则」「处置」「结果」和「故障转移」，覆盖路由策略、流量限额、内容护栏（含工具调用防护）和站点防护。

命中语义缓存的请求不访问上游，「请求」页签中上游各段显示「命中语义缓存，未请求上游」。

对比客户端请求与上游请求

需要确认网关实际改写了什么时，在「请求」页签查看原始报文：

1. 在报文区选择段落：「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」。发生重试或故障转移时，上游各段按「第 N 次」分开。模型与 MCP 调用显示这四段；A2A 与 API 服务调用只显示「客户端请求」与「返回客户端的响应」两段。
2. 在「正文」「请求头」或「响应头」之间切换查看；「复制全文」复制当前段。
3. 选择「差异」查看客户端请求与发往上游的请求之间的改动。差异按「模型」「系统提示词」「第 N 条消息」「工具」「请求头」等对象分组，已抹除的请求头只显示「已抹除」，不显示值，标注「新增」「删除」「改写」；跨协议转发时页面注明入站与上游的协议族。网关未改写时显示「网关未改写这次请求」。
4. 「返回客户端的响应」与上游响应完全相同时，页面显示「与上游响应完全一致（正文与响应头都相同）」。

报文不可读时，页面给出原因：「该请求发生在报文归档开启之前，没有留存报文」「报文归档中，稍后可查看」「按租户日志策略未留存报文」「报文已超过租户日志策略的留存时长，已清理」「归档存储尚未就绪，报文暂不可读」等。超过采集上限的段标注「已截断」，不能参与差异对比。每次读取正文或差异都会写入审计记录，见 19.4。

20.3 查看对话与会话详情

入口：「管理控制台 → 概览」，选择「对话」页签。该页签对租户管理员和「只读审计」角色可见。

列表按会话列出「标题」「客户端」「接入」「成员」「来源」「轮次」「费用」和「最近活动」，「客户端」显示客户端标识与图标，「接入」显示该会话所属的 Agent 观测接入名称；可按「客户端」「来源」和「诊断问题」（「有诊断问题」「无诊断问题」）筛选。点击会话进入会话详情，页头显示「会话信息」（调用方、密钥、最终用户、组织、活跃时段）和「安全策略：命中 N · 脱敏 N」。会话详情的页签按数据来源显示：

「网关调用」页签顶部给出结论，例如「故障影响 N 轮（其中 M 轮最终完成）· 网关兜住 K 次 · 根因：…」，并提供「定位到第 N 轮」。页面提示「覆盖不全」时，表示部分轮次没有网关记录；提示「本会话没有经过网关的请求」时，客户端可能直连上游，这部分的成本、失败与策略都看不到。

会话包含网关调用时，可使用「导出 JSONL」（「Hermes 训练格式」或「Turn 运维明细」）；「导出报告 PDF」生成该会话的报告。

20.4 处理会话诊断问题

入口：「管理控制台 → 概览 → 会话诊断」。该页面对租户管理员可见，页签依次为「总览」「成员」「任务场景」「最佳实践」「问题」，页签行右侧是「诊断设置」。尚未收到会话数据时，页面显示「还没有收到会话数据」。

平台对近期会话自动运行诊断规则，按「问题」汇总同类命中。当前规则包括：

其中「提示词缓存反复失效」「被额度或限流拒绝」「上游换了模型」等规则直接使用网关记录；使用方式类规则依赖客户端上报的操作轨迹，只有网关数据时这类规则的识别范围有限。

处理一个问题：

1. 选择「问题」页签。清单列出「严重度」「问题」「负责方」「影响」「费用」、近期每日次数和「状态」，可按「负责方」「严重度」和客户端筛选。「负责方」取值包括「员工」「运行框架」「技能」「平台配置」「模型」「环境」「客户端配置」「模型与外部服务」「待判定」。
2. 点击问题进入详情。「概况」给出「概要」（费用、影响会话、次数、最近出现）、「每日发生次数」「分布特征」「原因分析」和「修复建议」；「证据」列出命中的会话，可点击「打开会话」；「处理记录」列出发现、标记与复查的历史。
3. 按修复建议完成调整后，在「标记为」中选择「已处理，开始观察」，填写「做了什么」（必填，最多 500 字）。
4. 第 7 天系统自动复查：好转则显示「已改善，问题已解决。」；未好转则显示「未改善，问题已回到未处理。」；样本不足时继续观察。「已解决」只能由系统复查判定，不能手动标记。
5. 判定不成立或决定不修复时，选择「忽略」并选择原因：「判定错误」的问题不再提醒；「接受不修」的问题在发生率翻倍时再次提醒。已忽略或观察中的问题可以「恢复为未处理」。

问题状态为「未处理」「观察中」「已解决」「已忽略」。多人同时处理时，页面提示「已被 某人 改为…，已刷新」。

会话详情「诊断」页签中的诊断卡显示单场会话的结论：「命中 N 个问题」「这场会话没有命中任何判定。」；诊断尚未完成时显示「这场会话尚未完成诊断，请稍后再查看。」；诊断无法完成时显示「无法完成诊断：」及原因（「诊断结果未通过数据校验」「分析库多次拒收诊断结果」「多次读取会话数据失败」）。会话有新数据时，诊断重新排队。

使用总览、成员、任务场景与最佳实践

「总览」「成员」「任务场景」「最佳实践」四个页签依赖模型评审。模型评审在「诊断设置」中开启：

点击「保存设置」后，下一轮诊断起生效，已评审的会话不重评。评审调用所选模型并按其单价产生费用，「本月已用」显示当月已用金额。

开启评审后：

• 「总览」：按「统计周期」（近 7 / 15 / 30 / 90 天）、部门和客户端显示「采用」「效果」「效率」「用法」「支撑」五张指标卡，以及「需要关注」「趋势」「未达成原因」「任务类型构成」「部门对比」。
• 「成员」：按「用得最好（相对效果）」「需要帮助」「尚未用起来」分组列出成员，点击成员查看画像；「导出表格」导出成员名单，导出操作写入审计。
• 「任务场景」：按任务类型和复杂度查看「达成组与未达成组的做法差异」、按部门对比和「会话示例」。
• 「最佳实践」：由模型根据评审样本自动生成并自动发布，不需要手动创建。每条实践随机保留一部分成员暂不推送，经 14 天验证期对比两组达成率，结论为「判定生效」「未达到预期，系统自动撤下」「样本不足，系统自动撤下」等；生效满 90 天后到期。管理员可在实践详情中「撤下」，撤下后 60 天内不再生成同一做法的实践。

限制：未开启评审时，上述页签显示「未开启评审」，「问题」页签照常可用。成员侧查看最佳实践与本人诊断的页面位于观测工作台，当前不在 Zentrix 的菜单中。

20.5 查看路由策略命中

入口：「管理控制台 → 概览」，选择「路由策略命中」页签。该页签对租户管理员和「安全管理员」显示，但命中数据接口只对租户管理员与「系统管理员」放行，安全管理员打开后无法加载数据；页签属于基础功能；汇总的规则来自「流量规则」，未开通动态路由时没有可汇总的规则。

列表按规则汇总当前时间窗内的路由策略命中，列出「策略规则」「匹配判定条件」「网关执行动作」「命中次数」「7 天走势」「最近命中」，可按「处置」（「放行」「拒绝」「改路由」「改写」「降级」「限速」）和「命中情况」（「命中」「未命中」「未求值」「错误」）筛选，搜索框为「搜索规则名称 / ID」。时间范围可选「最近 24 小时」「最近 7 天」「最近 30 天」或自定义区间，自定义区间不超过 31 天。

• 点击规则行打开详情，查看「规则身份」「匹配判定条件」「网关执行动作」和「命中事实（当前时间窗）」（命中次数、放行次数、拦截次数、去重来源数、「P95 决策时延」），点击「打开策略规则」进入编辑。
• 点击「下钻命中请求 ➔」，切换到「网关请求」页签并按该规则筛选。
• 规则已删除但仍有历史命中时，显示「规则已删除，以下为历史命中」。

本页签只汇总路由策略。流量限额、内容护栏等其他策略的命中，在单次请求详情的「命中记录」中查看。

追踪请求中的治理动作

请求被拦截、改写、降级或改路由时，按以下顺序判断策略是否在预期位置生效：

1. 在「网关请求」中定位目标请求，记录时间、发起人、接入凭据和请求 ID。
2. 打开详情的「路由与改写」页签，在「命中记录」中按时间核对各策略的「处置」与「结果」先后顺序；在「请求去向」中核对「路由结论」与「原因」。
3. 涉及改写时，在「请求改动」中核对改写位置，并在「请求」页签用「差异」核对实际发出的内容。
4. 对照「上游尝试」，区分「策略按预期阻止」与「上游自身失败」。
5. 调整规则后，用正例、反例和边界样例分别发起请求，确认目标请求的结果改变、非目标请求保持不变；规则的命中次数在「路由策略命中」中同步变化。
6. 在「操作审计」中核对规则变更记录，并在事件记录中写明验证结果与负责人。

20.6 平台运行状态与出口网络

以下两个页面只在平台管理员的管理控制台中显示，位于「运行与排障」分组。

系统运行监控

入口：「管理控制台 → 运行与排障 → 系统运行监控」。页面每 30 秒自动刷新，也可点击刷新按钮。页面顶部汇总异常与需要关注的数量，下方分为三组：

• 「数据面 · N 个节点」：每个网关节点一张卡片，点击进入该节点的实例页。尚无节点时显示「还没有网关节点」和「前往网关节点」。
• 「控制面」：控制面服务与「后台任务」等服务的状态、实例数与版本是否一致。点击服务查看实例列表：「落点」「版本」「运行态」（「备用」「接流」「已排空」）「主」「已运行」「最后上报」「状态」；「查看资源占用」显示该实例的处理器与内存趋势，可选 15 分钟、1 小时、6 小时。
• 「依赖」：「系统数据库」「权限服务」「身份提供方」「ClickHouse」「对象存储」「密钥服务」「语义缓存」。点击依赖查看「提供方式」（「平台托管」「外部提供」）、「接入地址」「连通情况」「延迟」「最近探测」「影响范围」和「处理建议」。

状态取值为「正常」「需要关注」「异常」「未启用」，原因包括「没有实例在运行」「有实例未就绪」「有实例停止上报」「实例版本不一致」「没有主实例」「无法连接」「部分实例无法连接」「响应偏慢」。实例未就绪时列出具体原因，如「配置尚未装载」「与控制面失联」「路由策略尚未装载」。

依赖异常的影响以页面「影响范围」为准，例如控制面不可用时管理后台与配置下发不可用，已下发到网关节点的配置继续生效；「ClickHouse」一项的「影响范围」写明调用明细、用量统计与日志的写入和查询不可用：「网关请求」列表与详情、「网关总览」的用量面板、策略命中、模型服务运行指标和实例历史样本都读取分析存储，期间这些页面不可查；模型调用不受影响，网关节点在本地保留调用明细，恢复后自动补齐。

出口网络

入口：「管理控制台 → 运行与排障 → 出口网络」。探测由控制面主节点发出，页面显示「探测节点」名称。

1. 打开右上角「启用出口网络探测」。约 1 分钟后出现第一批结果。关闭后停止发送探测包，历史数据保留，逐跳诊断仍可手动使用。
2. 查看分层结论。五层依次为「局域网网关」「运营商接入」「国内公网」「海外公网」「常用网站」，每层显示最近 24 小时的健康状态：「正常」「异常」「故障」「无数据」「不回应探测」。页面顶部给出结论，例如「出口网络正常」或「某层异常：丢包 X，从某时开始，已持续 N 分钟」。
3. 在「趋势」中选择目标与时间范围（1 小时、24 小时、7 天、30 天），查看延迟与丢包率。出网经过代理时，趋势同时显示「业务路径」与「直连对照」。
4. 在「探测目标」中查看各目标的「层级」「探测方式」「来源」「当前状态」「延迟」「丢包」。目标来源包括「自动识别」「内置」「模型供应商」和「自定义」；已启用的模型供应商的公网地址自动加入探测。
5. 需要探测其他站点时，点击「添加目标」，填写「名称」（1–32 个字）、「地址」（公网 IPv4 地址或域名）、「层级」（「国内公网」「海外公网」「常用网站」）和「探测方式」（「网站访问」「建连探测」「延迟探测」）；「建连探测」必须填写「端口」（1–65535），「网站访问」默认 443。最多添加 50 个自定义目标，只能添加公网地址。
6. 某个目标异常时，点击该行的「诊断」执行逐跳追踪，约需 10 秒。结果列出「跳数」「地址」「丢包」「平均延迟」，并给出「已到达目标，路径上没有持续丢包」或「从第 N 跳（地址）开始持续丢包」。历次结果保存在「诊断记录」中。

判定规则在页面「判定说明」中列出，当前版本为固定值：1 分钟内丢包不低于 5%，或延迟超过平时 3 倍且不低于 50 毫秒，记为异常；丢包不低于 50% 记为故障；连续 2 分钟成立才改变结论。同层只有一个目标出问题时，该层最多记为异常。

限制：本机不允许 ping 时，公网目标改用建连测量，「局域网网关」与「运营商接入」两层无法测量；部署不支持逐跳追踪时，「诊断」不可用。

20.7 根因定位顺序

---

上一章：19. 可观测入口、数据来源与权限边界 · 下一章：21. 问题诊断与处理