KrakenD：从声明式聚合到无状态网关治理
订单详情页原本由前端分别请求订单、库存和会员三个服务。一次移动端改版后，团队把三次调用合成一个网关接口，联调环境立刻变得清爽；上线压测时，其中一个上游偶发超时，聚合接口的延迟却整体被拖长，同名字段还悄悄覆盖了另一份结果。网关返回了 JSON，却没有人能回答它实际调用了哪些上游、等了多久，以及失败时为何仍得到 200。
这正是 KrakenD 擅长也最容易被误用的现场。它以声明式配置构造请求处理管线，能够并行调用多个 backend、合并结果、做变换和局部保护，但它不是分布式事务协调器，也不会替团队自动定义“部分成功”的业务语义。真正可靠的接入，需要把配置版本、聚合规则、超时、错误分类和节点本地状态一起变成可验证证据。
先看清请求经过了什么
KrakenD Community Edition 可以只带一份配置启动，不要求集中数据库。请求先匹配 endpoint，再由 endpoint 下的一个或多个 backend 构造上游请求；非 no-op 路径会解码响应、选择或重命名字段，最后合并为客户端响应。这里有三类容易混淆的对象：
endpoint 是客户端看到的契约，决定公开方法、路径、输出编码和总超时。backend 是一次上游调用，决定目标主机、URL 模式、上游编码、字段映射和局部保护。extra_config 把缓存、熔断、认证、插件等组件挂到相应阶段；挂错层级通常不会得到想象中的行为。
“无状态”描述的是节点不依赖中心配置数据库就能接流量，并不表示进程里没有状态。内存缓存、基础熔断器和无状态限流计数都活在实例内；重启会清空，多副本也不会天然共享。需要集中计数或其他全局状态时，要按目标版本和功能矩阵确认企业能力及其 Redis 等外部依赖，不能把单节点实验的精确额度承诺复制到集群。
在隔离网络里从零跑起来
下面用两个可区分的上游做教学环境。先固定目标 KrakenD 镜像的发行标签，再记录 digest；不要把示例占位符替换成浮动的 latest。镜像平台、配置 schema、插件 builder 和功能许可都应与同一目标制品核对。示例用 2.13 发行线展示固定 schema URL；若选择其他发行线，必须同时替换镜像标签和 $schema 中的主次版本，不能让编辑器按一套 schema 提示、运行时却加载另一套二进制。
# compose.yaml
services:
orders:
image: hashicorp/http-echo:1.0
command: ["-listen=:8080", "-text={\"source\":\"orders\",\"id\":\"A-100\",\"status\":\"paid\"}"]
networks: [gateway_lab]
profile:
image: hashicorp/http-echo:1.0
command: ["-listen=:8080", "-text={\"source\":\"profile\",\"name\":\"Ada\",\"status\":\"active\"}"]
networks: [gateway_lab]
krakend:
image: devopsfaith/krakend:${KRAKEND_TAG:?set KRAKEND_TAG}
command: ["run", "-c", "/etc/krakend/krakend.json"]
ports: ["127.0.0.1:8080:8080"]
volumes:
- ./krakend.json:/etc/krakend/krakend.json:ro
depends_on: [orders, profile]
networks: [gateway_lab]
networks:
gateway_lab: {}{
"$schema": "https://www.krakend.io/schema/v2.13/krakend.json",
"version": 3,
"name": "customer-api-lab",
"port": 8080,
"timeout": "2s",
"cache_ttl": "0s",
"endpoints": [
{
"endpoint": "/v1/customer/{id}",
"method": "GET",
"output_encoding": "json",
"backend": [
{
"host": ["http://orders:8080"],
"url_pattern": "/",
"encoding": "json",
"group": "order"
},
{
"host": ["http://profile:8080"],
"url_pattern": "/",
"encoding": "json",
"group": "profile"
}
]
}
]
}group 很关键：两个上游都有 source 和 status，如果直接平铺合并，就会产生字段碰撞。分组后，客户端契约明确为 order.status 与 profile.status，上游新增同名字段也不至于静默改变另一组数据。timeout 是 endpoint 的时间预算，不是可靠性装饰；它必须小于调用方超时，并为网络抖动、序列化和客户端收包保留余量。
先验证制品身份和配置，再启动：
docker compose pull
docker image inspect "devopsfaith/krakend:${KRAKEND_TAG}" --format '{{index .RepoDigests 0}}'
docker compose run --rm krakend version
docker compose run --rm krakend check --config /etc/krakend/krakend.json
docker compose run --rm krakend check --lint --test-gin-routes --config /etc/krakend/krakend.json
docker compose run --rm krakend check --lint-no-network --test-gin-routes --config /etc/krakend/krakend.json
docker compose up -d
curl -i http://127.0.0.1:8080/v1/customer/A-100这些命令需要在目标镜像上执行后再作为发布证据。第一条 check 只证明配置可解析；--lint 会从该发行线的在线 schema 识别未知字段和错误类型；--lint-no-network 改用二进制内置 schema；--test-gin-routes 会短暂建立真实路由以发现冲突。在线与内置 lint 都保留，是为了暴露 schema 修订节奏差异，而不是把任意一个成功结果当成另一个的替代。预期证据不是只出现一句 Syntax OK!，而是各检查退出码为零、在线与内置结果可解释、容器保持运行、响应体同时包含 order 与 profile，且访问日志中的请求能对应镜像 digest 与配置摘要。若当前发行线的 CLI 参数有变化，先查看该制品内的 krakend check --help，不应在流水线里静默删掉失败的门禁。
正向实验：证明并行聚合，而不只证明能访问
把两个 echo 上游换成能够记录调用时间并分别延迟的合成服务：orders 延迟约一个短窗口，profile 延迟约另一个短窗口。直接访问各上游，保存状态码、响应体和耗时基线；再访问聚合 endpoint。若调用为并行，网关总耗时应接近较慢上游加固定开销，而不是两段延迟之和。
curl -sS -o orders.json -w 'orders code=%{http_code} time=%{time_total}\n' http://127.0.0.1:18081/
curl -sS -o profile.json -w 'profile code=%{http_code} time=%{time_total}\n' http://127.0.0.1:18082/
curl -sS -o aggregate.json -w 'gateway code=%{http_code} time=%{time_total}\n' http://127.0.0.1:8080/v1/customer/A-100
jq . aggregate.json不要写死一个毫秒阈值。容器调度和机器负载会改变绝对时间，稳定的不变量是：两条上游都有同一个实验 request ID；聚合耗时没有随两段延迟简单相加；响应结构与 endpoint 契约一致。连续执行多轮，若结果偶尔退化为相加，要检查连接复用、上游并发限制和实验服务自身是否串行。
需要前一步结果才能构造后一步请求时，可以选择 Sequential Proxy，但代价也随之改变：总延迟趋近各步骤相加，第一步失败会取消后续链路，而且它没有事务提交或补偿语义。订单创建、扣款这类有副作用的流程不应仅靠 sequential 包装成“可靠工作流”。
反向实验：让错误稳定暴露
先把 profile 的 host 改成不存在的 http://profile-missing:8080，保持 orders 正常。重新执行配置检查，再启动隔离实例并请求相同 endpoint。这里要保存四类证据：客户端状态码和 body、KrakenD 日志中的 backend 错误、orders 实际调用次数、profile 的连接或解析错误。
预期现象必须由目标版本实测确认，因为输出编码、错误细节和是否返回部分数据会受配置影响。判断标准不是“网关没崩”，而是团队事先定义的部分失败契约得到兑现：若客户端不得消费残缺对象，就应通过响应完成度、错误映射或业务端校验拒绝它；若允许部分结果，必须有明确字段表明哪一组缺失，不能让字段缺席冒充真实空值。
再做两个只改变一个变量的反例：
删除两个 backend 的 group，观察同名 status 的碰撞结果，并把它纳入契约回归。将某条 backend 设为 no-op，让上游返回 500，比较客户端看到的状态码和基础熔断器计数。no-op 追求透明传递，也绕开依赖解码和状态码解释的部分能力，不能同时承诺完全透传与完整聚合变换。
反例结束后恢复已知良好配置，重新运行 check，并用同一组请求证明两条上游都恢复。配置文件恢复成功不等于数据面恢复，真实请求证据才完成回滚闭环。
JWT 认证先锁定签名者，再决定把什么交给上游
KrakenD Community Edition 可以在 endpoint 的 extra_config 中使用 auth/validator 校验由外部 IdP 签发的 JWS。KrakenD 不负责用户登录，也不会对每个请求调用 IdP 做 token introspection；它从本地文件或远端 JWKS 选择公钥，核对 token header 中的 kid 与 alg，验证签名、过期时间，并按配置检查 issuer、audience、role 或 scope。认证放在 endpoint 层，失败请求不会进入 backend 聚合链。
下面的配置把签名算法、签发者、受众和 scope 同时锁定。只配置 jwk_url 与 alg 只能证明“某个受信签名者签过”，不能证明 token 是发给这个 API、来自目标租户或拥有读取权限。
{
"endpoint": "/v1/customer/{id}",
"method": "GET",
"extra_config": {
"auth/validator": {
"alg": "RS256",
"jwk_url": "https://id.example.invalid/.well-known/jwks.json",
"issuer": "https://id.example.invalid/",
"audience": ["customer-api"],
"scopes_key": "scope",
"scopes_matcher": "all",
"scopes": ["customer:read"],
"cache": true,
"cache_duration": 300,
"failed_jwk_key_cooldown": "10s"
}
}
}alg 必须与 endpoint 允许的算法精确匹配，不能接受 token 自报任意算法；audience 中声明的值要求全部存在；scopes_matcher: all 表示所列 scope 缺一不可；cache_duration 决定每个副本内 JWK 的复用窗口；failed_jwk_key_cooldown 避免攻击者持续发送未知 kid 时反复冲击 IdP。生产 JWKS 必须使用可验证的 HTTPS，disable_jwk_security 不能为了联调方便进入正式配置。若使用 jwk_local_path，公钥文件就成为随镜像发布的安全制品，轮换速度、只读挂载和回滚必须纳入发布链。
正向实验由隔离 IdP 签发一枚短时 token，固定 kid、issuer、audience 与 customer:read，请求聚合 endpoint 并证明两个上游各调用一次。再做四个单变量反例：错误签名、未知 kid、错误 audience、缺少 scope；四者都应在 backend 调用数保持不变时被拒绝。保存状态码、KrakenD 认证错误分类、JWKS 请求次数和脱敏 token 摘要，不保存完整 token。operation_debug 可能暴露 claim，只能在合成流量的隔离环境短时开启。
密钥轮换采用重叠窗口：IdP 先发布新旧两个 JWK，等待所有副本能够看到新 kid，再签发新 token；观察旧 token 使用归零且最长 token 生命周期与 JWK 缓存窗口都过去后，才移除旧公钥。反向轮换实验在一个副本缓存旧 JWKS、另一个副本冷启动时发送新 token，可以暴露节点间接受结果不一致；负载均衡器上的偶发 401 往往不是“JWT 随机失效”，而是 JWK 代际不同。需要即时撤销时，单靠离线 JWT 验签和有限 TTL 不够，应缩短 token 生命周期或引入产品支持的撤销/在线授权机制，并核算其新依赖和故障策略。
向上游传播 claim 会把认证结果变成新的信任边界。只传播业务确需的稳定标识，并在入口删除客户端伪造的同名 header；上游只信任来自网关网络身份的 header。完整 token、角色全集和个人数据不应为调试便利扩散到每个 backend，访问日志、Trace 与错误响应也要对这些字段脱敏。
把缓存与熔断放回正确的状态边界
qos/http-cache 缓存的是 backend 的 GET/HEAD 响应，不是最终 endpoint 的聚合结果。最终 backend URL 与 Vary 会参与缓存键，响应中的有效 Cache-Control 决定可缓存时长；没有有效缓存指令时，不应假定“配置了 cache 就一定命中”。缓存位于实例内存，没有主动 purge API，过期、LRU 替换或重启才会移除。使用自定义 HTTP client、客户端凭证、Lambda、AMQP 等链路时可能绕过这套缓存能力，不能只看配置中出现了 qos/http-cache 就宣称命中。
这会直接改变设计：用户权限、余额和库存等高敏感或强时效数据，不能因为“减少上游调用”就随意缓存。测试时至少覆盖 GET 与 POST、Cache-Control、Vary 高基数、过期、重启、大对象、并发 miss 和两个副本。生产容量不能只看条目数，还要测平均与高分位响应大小、键开销、并发装载和 Go GC。2.13 schema 中 max_items 与 max_size 必须同时配置，任缺一个就不能把缓存视为已封顶；shared: true 只允许同一进程内符合相同键的 backend 定义共用 bucket，不会在不同副本间共享。
"extra_config": {
"qos/http-cache": {
"shared": false,
"max_items": 1000,
"max_size": 134217728
}
}缓存正向实验让上游返回 Cache-Control: max-age=30 和递增计数，连续请求应表现为后续请求不上游、延迟显著下降；KrakenD 没有直接的 hit/miss 管理接口，因此必须同时看 Trace、上游日志和调用计数。反向实验把响应改为 no-store 或 max-age=0，确认每次都到达上游；再让两个副本轮流接流量，证明首次 miss 会分别发生。若业务要求跨副本预热、精确 purge 或共享一致缓存，应在架构中引入专用缓存层，而不是把进程内 bucket 解释成分布式缓存。
基础 qos/circuit-breaker 维护 CLOSED、OPEN、HALF-OPEN 状态。max_errors 表示窗口内连续错误门槛，而非总体错误率；进入 OPEN 后等待 timeout，再允许探测请求决定是否闭合。每个副本独立维护状态，因此负载均衡后的客户端可能在短窗口内看到不同结果。
熔断实验要区分连接错误、超时、解码错误和 HTTP 500，并分别比较普通 JSON 路径与 no-op。同时记录每个副本日志和实际上游调用数，才能判断是 breaker 拒绝、网关超时，还是上游自己返回错误。HALF-OPEN 下的精确并发、节点间命中差异和重启行为不能凭状态图推断，必须锁定版本压测。
配置发布是一次制品发布
单文件适合入门，真实项目常需要按环境组合 host、凭证引用和功能片段。Flexible Config 能渲染模板，但它也会把变量展开为最终配置；一旦把真实 secret 写入 FC_OUT、CI artifact 或调试日志，模板化反而扩大了泄露面。
一条稳健发布链应当保留：源模板与非敏感默认值、目标镜像 digest、渲染器输入摘要、渲染后配置摘要、严格 check/audit 退出码、隔离实例烟测和生产数据面的配置标识。krakend check 的 -n 内置 schema 与在线 schema用途不同；网络不可用时可用内置 schema，但升级门禁要比较目标 schema，发现差异就停止发布，而不是自动放宽未知字段。
项目仓库可以采用这样的责任分层：
gateway/
config/
krakend.tmpl
partials/
environments/
dev.env.example
staging.env.example
tests/
smoke.sh
aggregation.sh
release/
image-digest.txt
config.sha256环境文件只提交变量名和合成值，真实凭证由 secret manager 在运行时注入。每次变更只改一个可解释的策略面，先直接调用两个上游保存基线，再走网关验证路由、输出字段、错误语义和 request ID。配置摘要应进入访问日志或部署标签，使排障者能从一次请求反查实际版本，而不是只看 Git 主分支当前内容。
插件不是普通配置项
Lua 适合较小的请求或响应变换，不需要重编译 KrakenD；Go 插件能承载更复杂、性能敏感的逻辑，却与宿主 ABI 紧密耦合。Go 版本、架构、操作系统、glibc/musl 和共享依赖任何一项不匹配，都可能在加载阶段失败，甚至把 panic 带进网关进程。
使用目标 KrakenD 版本对应的官方 builder 构建，并保存源码提交、builder digest、插件摘要和依赖清单。krakend version 用来记录宿主 Go/libc 信息，krakend check-plugin -s ./plugin/go.sum 用来发现依赖冲突；检查通过仍不代表生产安全，还要在一次性隔离容器中验证加载、并发、panic、超时、内存和卸载回滚。
插件以网关进程权限执行，没有隔离沙箱。第三方 .so、Lua 脚本、Martian 配置和它们的依赖都属于供应链执行面：必须有 owner、代码审查、摘要固定和禁用开关。升级 KrakenD 时，先重建并验证全部插件，再升级一小组数据面；不要让旧插件成为无法退出旧网关版本的锁链。
排障先按失败层分型
客户端只提供 502 或空字段时，先用 request ID 把证据按层对齐，而不是立即调大超时：
| 失败层 | 第一证据 | 常见原因 |
|---|---|---|
| 配置生成 | 渲染配置摘要、check 退出码 | 未知字段、类型错误、变量未展开、schema 漂移 |
| 路由匹配 | endpoint、方法、路径参数、配置版本 | 路径不一致、旧副本仍接流量、方法未发布 |
| backend 构造 | 实际 host、URL pattern、query/header 转发 | 内部 DNS、路径拼接、头过滤或参数映射错误 |
| 上游执行 | 上游状态码、耗时、调用次数 | 连接失败、超时、容量不足、重试放大 |
| 解码与合并 | encoding、group、字段映射、body 摘要 | 非 JSON、空 body、字段碰撞、类型变化 |
| 局部保护 | 副本、cache 命中、breaker 状态 | 节点状态不一致、陈旧缓存、OPEN 拒绝 |
日志至少携带 request ID、endpoint、backend、上游耗时、上游状态、网关状态、配置摘要和副本身份，但不能记录真实授权头或完整客户 body。若只有客户端状态码而没有上游状态，便无法区分“网关生成错误”与“透明传递上游错误”；若只有控制面配置而没有副本身份，也无法定位滚动发布中的旧节点。
从容量和成本反推是否该选 KrakenD
KrakenD 特别适合配置驱动、读多写少、需要聚合与变换、希望数据面少依赖中心数据库的团队。它的代价是：配置发布需要工程化；部分失败语义必须由 API 设计明确；节点内缓存、熔断与限流不是集群强一致；复杂业务编排和插件会把轻量数据面重新变重。
容量模型从 fan-out 开始。一条入口请求并行调用三个 backend，上游请求量基线就是入口量的三倍；超时、重试、缓存 miss 和 HALF-OPEN 探测会继续放大。压测应同时观察入口 RPS、每个 backend RPS、连接池等待、各阶段延迟、响应大小、进程 RSS、GC、错误分类和上游取消是否及时。不能用官网的通用吞吐数字替代目标 TLS、日志、插件和聚合结构下的测量。
如果主要需求是消费者生命周期、开发者门户、细粒度控制面 RBAC、集中分析和产品套餐，纯 KrakenD 数据面通常需要外部系统配合，选型时要把这些集成与自建成本算进去。如果核心是高性能声明式聚合、简单横向扩展和 Git 驱动配置，它会更贴合。比较 CE 与 EE 时，以目标制品的功能矩阵、实际 license、支持和退出条款为准，不写死价格、节点数或“免费无限”。
权限、数据和长期治理
网关容器使用只读配置和非特权运行身份，只开放数据面端口；调试、指标和管理入口放在受控网络。上游凭证按环境与用途拆分，禁止把一个高权限 token 共享给所有 backend。轮换时先让上游并存新旧凭证，发布新配置并观察旧凭证命中归零，再撤销旧凭证；节点本地缓存可能延迟失效的场景必须单独验证。
访问日志、Trace 和错误 body 都可能含路径参数、消费者标识和业务数据。先定义允许记录的字段，再设置采样、脱敏、保留期和删除责任。缓存会复制上游数据到每个实例内存，插件可能看到完整请求，这两处也属于数据处理边界，不能只治理中心日志平台。
团队至少明确配置 owner、插件 owner、运行平台 owner 和上游 owner。发布门禁验证 schema、配置摘要、双上游正向实验、错误上游反例、敏感信息扫描和回滚；升级门禁再增加镜像 digest、插件 ABI、配置兼容、双跑响应差异和容量趋势。例外必须带到期时间，不能靠永久关闭 lint 或放宽未知字段维持发布。
清理、回滚与退出
实验结束先撤销合成凭证和测试路由，再停止容器；确认没有其他项目引用后删除容器网络。若配置渲染生成了含 secret 的文件，应先按敏感制品处理并从 CI artifact、临时目录和 shell history 中清除，而不只是删工作树文件。
docker compose down --remove-orphans
docker compose ps -a
docker network ls --filter name=gateway_lab不要默认加 -v：只有确认 volume 全部属于本实验且没有需要保留的证据时才删除。回滚顺序是恢复上一份已验证配置与镜像 digest、重建小组实例、执行双上游烟测、逐步恢复流量，再撤下失败版本。若插件或功能让网关无法迁移，应提前维护无插件基线、标准 OpenAPI 契约、上游直连验证和 DNS/入口切换方案，让退出不依赖事故当天临时逆向配置。
至此，一个可交付的 KrakenD 方案不再只是“容器启动且返回 JSON”，而是能回答：每个字段来自哪里，失败在哪一层被解释，状态保存在什么地方，多副本会出现什么差异，配置与插件如何发布，以及如何在不泄露凭证、不遗留状态的前提下回到上一版本。