跳至主要內容

网关请求证据模型与选型：从一个状态码还原整条控制链

高谷深陵大约 17 分钟约 5201 字

一次订单查询返回 403，应用团队看到业务日志里没有请求，平台团队却在网关控制台看到路由“已发布”。双方都没有错，也都没有足够证据：控制台状态只能证明控制面接受了一次变更，业务日志为空只能证明请求没有进入该实例，谁在何处拒绝请求仍然未知。

网关排障容易陷入配置阅读，是因为团队把请求当成一个状态码，而不是一组连续决策。可靠模型必须保存调用者身份、入口、路由、策略、上游尝试和配置版本；随后才能把 401、403、404、429、502、503、504 与网络错误落到具体责任层。

网关请求证据模型与选型知识海报
用身份、路由、策略、上游和配置版本还原请求控制链高清原图

先定义网关正在处理的对象

消费者不是一个 IP，也不一定是人。它可能是浏览器会话、移动应用、合作伙伴系统、后台服务或批处理任务。消费者身份来自 API Key、证书、JWT、外部授权结论或网络边界；每种身份都有签发者、受众、有效期、撤销方式和缓存传播时间。

入口由地址、端口、协议、SNI/Host、证书和监听器共同定义。路由把 method、Host、Path、Header、query 或其他条件映射到规则；策略在特定阶段执行认证、授权、限流、变换、缓存或观测；上游则包含服务、端点、健康、负载均衡、超时和重试。控制面把这些对象变成数据面配置，配置版本决定一次请求实际使用哪套规则。

因此最小证据记录不是一条访问日志，而是请求级、尝试级和发布级三组可关联字段。请求级记录回答入口作出了什么决定，尝试级记录回答数据面实际连接过哪些上游，发布级记录回答当时哪一代配置已被哪些节点接收。

{
  "observed_at": "<RFC3339_TIMESTAMP>",
  "edge_request_id": "edge-01J2Y6G4",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "data_plane_id": "gateway-zone-a-03",
  "listener_id": "public-https-443",
  "route_id": "orders-v2",
  "route_revision": "sha256:7c8e...",
  "principal_ref": "partner:sha256:19ad...",
  "authn_result": "accepted",
  "authz_result": "allowed",
  "rate_limit_result": "allowed",
  "gateway_status": 200,
  "response_flags": [],
  "duration_ms": 38,
  "attempt_count": 1,
  "sampling_policy": "errors-and-0.1pct-success"
}

一次上游尝试独立记录 edge_request_id、attempt 序号、cluster、endpoint、连接阶段、开始时间、耗时、响应码或传输错误。重试两次后成功的请求，不能只留下最终 200；否则容量模型看不到三倍上游放大，故障分析也看不到前两次连接失败。发布记录则保存期望 revision、控制面对象代际、节点实际 revision、发布时间、发布身份和回退 revision。

示例字段只表达合同，不暗示某个产品原生输出同一 JSON。principal_ref 是稳定的受控引用或不可逆摘要，不是 JWT、API Key、邮箱和客户端证书全文。route_id 与 response_flags 应来自有界枚举，原始 Path、query、User-Agent 和错误消息不能直接成为指标标签。产品接入时建立字段映射和缺失语义，不能跨实现复制日志字段名。

先部署一条与产品解耦的证据合同

仓库先保存合同与产品映射，再由发布流水线注入 revision。一个可维护的接入目录可以这样组织：

gateway-evidence/
  contract/request-evidence.schema.json
  mappings/envoy.yaml
  mappings/kong.yaml
  policies/redaction.yaml
  samples/accepted.json
  samples/rejected-missing-revision.json
  scripts/check-evidence.mjs

合同中的 required 字段应尽量少而稳定，产品特有字段进入 attributes，但必须受大小、名称和敏感级别限制。下面的检查器用来阻止“状态码存在就算证据完整”的退化：

// gateway-evidence/scripts/check-evidence.mjs
import { readFile } from 'node:fs/promises'

const required = [
  'observed_at', 'edge_request_id', 'data_plane_id', 'listener_id',
  'route_id', 'route_revision', 'gateway_status', 'attempt_count'
]
const file = process.argv[2]
if (!file) throw new Error('usage: node check-evidence.mjs <record.json>')

const record = JSON.parse(await readFile(file, 'utf8'))
const missing = required.filter((key) => record[key] === undefined || record[key] === '')
if (missing.length) {
  console.error(`missing evidence fields: ${missing.join(', ')}`)
  process.exit(2)
}
if (!Number.isInteger(record.attempt_count) || record.attempt_count < 0) {
  console.error('attempt_count must be a non-negative integer')
  process.exit(3)
}
if (record.principal_ref && /bearer|eyJ|BEGIN CERTIFICATE|api[_-]?key/i.test(record.principal_ref)) {
  console.error('principal_ref appears to contain credential material')
  process.exit(4)
}
console.log(`${record.edge_request_id} ${record.route_id}@${record.route_revision}`)

先用完整样本运行，预期退出码为 0，输出请求 ID 和 route revision；再复制一份样本并删除 route_revision，预期退出码为 2 且标准错误列出缺失字段。第三个反例把测试 JWT 放进 principal_ref，预期退出码为 4。这三个结果只能证明合同校验器按预期工作，不能证明网关已经产生正确字段。

node gateway-evidence/scripts/check-evidence.mjs gateway-evidence/samples/accepted.json
node gateway-evidence/scripts/check-evidence.mjs gateway-evidence/samples/rejected-missing-revision.json

接入具体产品时，先从隔离数据面导出一条成功和一条本地拒绝记录，转换为合同格式，再与控制面 revision 和上游日志关联。映射规则发生变化时先双写旧、新字段并比较缺失率；观察窗口结束后才删除旧映射。回滚是恢复上一版映射与采集配置，不是让解析器静默丢弃新字段。

把控制面成功和数据面成功拆开

控制面接收 YAML、Admin API 请求或云资源变更后，通常还要经过校验、持久化、转换、分发和数据面应用。任一阶段失败，都可能出现“提交成功但请求仍走旧配置”。Gateway API 规范把期望状态与 condition 形式的观察状态分开，其他产品虽然对象不同，也要建立等价的发布证据。

一次发布至少保留四个状态：期望配置版本、控制面接受状态、数据面实际版本、业务请求结果。Kubernetes 资源要读 status.conditions、关联父级和 observedGeneration；只有 condition 观察到当前 metadata.generation，状态才与眼前 spec 属于同一代。Accepted=True 只表示配置足以产生某些数据面效果，不代表全部规则有效；Programmed=True 表示配置已经发送给数据面，也不等于当前请求一定可达；ResolvedRefs=False 必须继续追到不存在或未获准的引用。独立网关要查配置 hash、revision 或节点同步状态；云 API 管理要区分草稿、deployment、stage/revision 与实际入口。没有统一版本字段时，团队应在发布流水线生成不可变 revision，并把它注入数据面元数据或诊断响应。

错误实验可以故意引用不存在的上游。理想结果不是“命令失败”，而是控制面指出无效引用，数据面不接收候选配置，旧请求仍由上一版本服务。若产品接受配置但运行时返回错误，则要记录这种延迟失败语义，并把 smoke test 纳入发布门禁。

用两个上游建立可判定实验

单个 hello world 上游无法证明路由和灰度。实验应启动两个响应不同版本标识的服务，直接访问后再经网关访问。下面只描述通用上游行为，实际端口由隔离环境分配：

GET /health -> 200 {"ready":true,"instance":"blue"}
GET /whoami -> 200 {"instance":"blue","path":"/whoami"}

GET /health -> 200 {"ready":true,"instance":"green"}
GET /whoami -> 200 {"instance":"green","path":"/whoami"}

先把所有流量指向 blue，验证 route ID、上游标识和配置版本；再切一小部分到 green，保存足够样本；随后停止 green，观察健康检查、重试和故障状态。写请求不得用于自动重试实验，除非上游实现幂等键并能证明没有重复副作用。

反向实验至少包括错误 Host、错误 Path、无效凭证、无健康上游和策略依赖不可达。每类失败要有独立状态码或错误细节；多个层级都返回 403 或 503 时，必须借助 response-code detail、route ID、策略指标和上游连接日志区分。

状态码只能缩小范围

401 通常表示缺少或无效认证，但业务应用也可能返回它；403 可能来自网关授权、WAF、外部授权服务或上游；404 可能是没有路由、Path 变换错误或业务资源不存在；429 需要指出网关、云平台、授权服务还是上游在限流。

502 常见于连接、协议或上游响应问题，503 可能是无健康端点、熔断、控制面保护或应用不可用，504 常见于网关等待上游超时。TCP reset、TLS alert、DNS 失败和客户端超时甚至没有 HTTP 状态码。排查顺序应从最早可证实的异常层开始，而不是见到 5xx 就增加超时。

响应应携带受控关联标识，网关日志保存 gateway status 与 upstream status，指标区分本地拒绝和上游响应，Trace 区分入口 server span 与上游 client span。OpenTelemetry HTTP 语义约定提供了跨实现字段基线，但字段稳定级别和版本迁移仍需随 instrumentation 校准。查询参数、凭证和请求体不因“排障需要”自动获得长期记录权限。

时钟也是证据合同的一部分。数据面、授权服务、上游和日志平台应监控时间偏差，并记录事件时间与接收时间。否则 token 刚过期、配置刚发布和重试刚发生的现场可能被错误排序。日志平台延迟不应被解释为网关没有处理请求；还要检查采集游标、丢弃计数和最近成功接收时间。

策略链顺序会改变安全结论

若路径变换发生在授权前，授权服务看到的是变换后的资源；发生在授权后，则必须证明后续变换不会把请求送到权限不同的路由。插件清除路由缓存、重新匹配或修改身份 Header 时，可能让前一个授权结论失效。Envoy 的 HTTP filter 顺序说明和 External Authorization 安全提示明确记录了 route cache 重新计算可能造成的授权绕过风险。

策略链应有显式阶段：规范化不可信输入、建立消费者身份、执行授权、应用容量策略、选择路由/上游、做受控变换、记录结果。不同产品的实际执行模型并不相同，团队需要用正反请求验证，而不是仅看插件列表顺序。

外部授权和全局限流都是运行时依赖。它们不可达时，fail-open 能维持可用性却扩大越权或超额风险，fail-close 能保护边界却可能让所有流量中断。选择必须按 API 数据级别、失败影响和补偿能力分层，不应使用一个全局默认值。

用部署形态而不是功能表做初选

本地反向代理适合少量团队、稳定路由和应用内身份；它的状态少、退出简单。Gateway API 适合 Kubernetes 原生声明式入口，需要接受“规范 + 控制器 + 数据面”三层兼容矩阵。独立开源网关提供插件、消费者和管理 API，但团队要运营数据库、配置分发、插件供应链和升级。

托管 API 管理减少控制面基础设施工作，却增加云身份、私网连接、区域、配额、计费和退出约束。混合控制/数据面适合数据驻留或多网络环境，但控制面断连、证书轮换、配置缓存和版本兼容必须演练。

可以用下面的决策字段做初筛：

决策维度要回答的问题
运行位置开发机、Kubernetes、虚机、边缘、单云还是多云
配置权威Git、Kubernetes API、产品数据库还是云资源 API
状态依赖数据面是否依赖数据库，控制面断开后能否继续
身份模型消费者、管理员和上游分别使用什么身份
扩展方式内置策略、声明式插件、代码插件或外部服务
故障预算哪些依赖失败可以放行，哪些必须阻断
迁移能力配置、消费者、凭证、日志和门户数据能否导出
总成本基础设施、流量、存储、席位、插件和维护人力

产品比较必须使用目标版本和目标部署模式。社区版演示、企业版文档和托管版能力不能混成一个“支持”结论。

证据可得性应成为否决项，而不是上线后的补充项。候选实现若不能导出节点实际 revision、区分本地响应与上游响应、记录每次重试，或不能证明管理写操作来自哪个身份，就无法满足高风险 API 的故障归因。托管服务若只能提供聚合指标，应确认原始访问记录、审计事件和配置历史能否导出，导出延迟与保留期是否覆盖事故调查窗口。

配置发布需要可回退证据

声明式配置进入 Git 后，至少经过 schema/语法校验、语义检查、隔离数据面加载、正反 smoke test、候选发布和观察窗口。Admin API 直接写入适合受控自动化，不适合个人在生产手工修改；所有写动作要关联变更单、调用身份和 revision。

回滚并不总是“重新提交旧文件”。数据库 schema 迁移、插件状态、消费者凭证、证书和云资源删除可能不可逆。升级前要区分配置回滚、二进制回滚、数据库恢复和流量回切，逐项验证支持边界。

双跑迁移时，先同步只读配置和安全策略，再比较无副作用请求。镜像写流量可能重复交易、发送通知或消耗配额，默认禁止。切流后保留旧入口只用于明确窗口内的回切，防止两个控制面同时修改同一域名和消费者状态。

容量模型从每个决策点开始

数据面容量不仅受请求率影响，还受 TLS 握手、Header 大小、请求体、长连接、策略调用、日志、Trace、压缩和重试放大影响。外部授权和全局限流服务也有独立延迟与并发预算。控制面容量则取决于配置对象数量、更新频率、分发扇出、数据库与分析写入。

本地限流在副本扩容后总额度可能随副本数增长；共享计数引入网络和状态存储故障。缓存减少上游流量，却可能扩大身份或版本串读。容量测试要同时看客户端结果、网关 CPU/内存/连接、策略依赖、上游尝试数和日志存储，不能只看每秒请求数。

成本同样来自多层：实例与集群、跨区流量、日志与分析、控制面数据库、证书/HSM、开发者门户、商业插件、支持和迁移人力。托管产品价格与配额会变，预算应从真实账单和用量导出，不从文章静态数字推断。

证据链自身也需要容量预算。请求记录量近似为 请求率 × 平均记录字节 × 保留秒数 × 副本系数，attempt 记录还要乘以平均尝试次数。成功请求可按稳定规则采样，认证拒绝、策略错误、配置代际不一致、上游重试耗尽和管理写操作应保留更高比例。采样决策必须随记录保存；没有 sampling_policy 时，查询结果不能用于推断真实错误率。

高可用不是把每份日志同步到更多节点。数据面即使暂时失去日志后端也应继续按受控策略服务，但必须暴露缓冲区占用、丢弃数和最老未发送事件年龄。缓冲区写满时，低风险访问日志可以按明确优先级丢弃；审计事件和高风险授权拒绝需要独立通道或阻断升级策略。日志恢复后验证序列缺口，不能只看采集进程重新变绿。

凭证、请求数据与审计记录分级存放

访问日志、Trace、策略调试日志和控制面审计记录具有不同数据边界。访问日志保存受控身份引用与路由结果；Trace 保存阶段耗时和调用关系；临时策略调试只在指定实例、字段和时间窗启用；控制面审计保存谁在何时修改了哪个对象及前后 revision。四者不应共用一个无限制查询角色。

Authorization、Cookie、API Key、客户端证书私钥和完整请求体默认拒绝采集。URL query 也可能包含令牌或个人数据；启用 OpenTelemetry HTTP 属性前，应按参数名清洗并验证落库结果。脱敏规则要有反向样本：向测试请求放入唯一标记 SECRET_SHOULD_NOT_APPEAR_7F3A，随后查询访问日志、Trace 和错误索引，预期均无命中。若命中，先停用对应采集路径并删除污染数据，再修复规则，不能只在展示层隐藏。

读取原始证据、临时提高采样率和启用请求体捕获都属于高权限动作，应绑定工单、操作者、原因、对象范围和自动到期时间。清理时恢复采样策略，撤销临时角色，删除测试消费者与凭证，关闭调试字段，并用日志平台查询和身份系统状态分别证明数据与权限已经收回。

失败时沿证据链收敛

直接访问上游健康与业务基线，确认应用和网络是否已经失败。核对 DNS、TLS、监听器和 Host/SNI，确定请求是否到达目标数据面。查询命中 route、配置 revision 和控制器 condition，排除旧配置与冲突。

查询认证、授权、限流和变换的具体策略结论，不只看最终状态码。核对上游选择、端点健康、连接错误、尝试次数和超时层级。用 request ID 关联客户端、网关和应用证据，确认时间与采样窗口一致。

修复后重放原请求和对应反例，最后验证旧配置、临时凭证和调试日志已清理。

若某层没有证据，就先补观测，不要用修改下一层配置来碰运气。临时提高日志级别必须限定实例、字段和时间，结束后恢复并删除敏感输出。

团队治理以退出证明收尾

配置仓库、控制面管理员、消费者管理员、证书 owner、插件 owner、观测 owner 和成本 owner 应明确分开。管理 API 只开放给受控自动化和紧急通道，Dashboard/Portal 使用组织身份与最小权限，数据库和备份加密并限制下载。

供应链包括网关镜像、Helm Chart、控制器、插件、策略包和管理 UI。锁定版本与摘要，保存 SBOM/签名或官方校验信息，在升级前重放正反实验。代码插件拥有请求内容和凭证访问能力，评审等级不能低于业务代码。

退役时先冻结新发布，导出并校验配置与消费者清单，迁移凭证和证书，切换 DNS/入口，观察错误和旧入口流量，再撤销管理员与消费者身份。最后删除旧数据面、数据库、缓存、日志、Trace、备份、Portal 账号和云资源，并用资源 API、端口、存储与后续账单证明退出完成。

发布前检查

请求证据能绑定消费者、入口、路由、策略、上游和配置 revision。控制面接受、数据面应用和真实请求结果分别验证。两个上游与错误路由、错误身份、无健康上游反例可重复。

策略执行顺序、fail-open/fail-close 和日志敏感字段已经审查。部署形态、状态依赖、容量、费用、升级和迁移基于目标模式判断。回滚覆盖配置、二进制、数据库、插件、凭证和入口流量。

临时消费者、路由、端口、日志、存储和云资源均有精确清理证明。

跳到正文