Kong 3.9.0 版本更新全解：kong drain 排水命令、Hugging Face LLM 驱动、Hybrid RPC 框架与 Admin API YAML 支持

Kong 3.9.0 是一次围绕运维可用性、AI 网关能力与 Hybrid 集群架构的版本：本文基于仓库中的 3.9.0 变更日志 完整梳理该版本的弃用项、新增特性、依赖升级与缺陷修复，并逐一结合 kong/cmd/drain.lua、kong/status/ready.lua、kong/plugins/redirect/handler.lua、kong/llm/drivers/huggingface.lua 等源码实现，帮助读者在升级前准确评估影响面、并掌握每项新能力的落地用法。

一、版本概览

3.9.0 的核心变化可以归纳为五条主线：

主线	代表变更	源码佐证
运维可用性	新增 kong drain 命令，使 /status/ready 返回 503	kong/cmd/drain.lua
AI 网关	新增 Hugging Face 推理 API 的 LLM 驱动；修复 ai-proxy 多个 function calling 问题	kong/llm/drivers/huggingface.lua
Hybrid 模式	为数据面/控制面新增 RPC 框架	kong/clustering/rpc/
Admin API	/config 端点支持 application/yaml 官方媒体类型	kong/api/api_helpers.lua
可观测性	request debugger 时间分辨率提升到微秒；新增 total_time_without_upstream 字段	changelog/3.9.0/3.9.0.md

二、弃用项（Deprecations）

• Core：配置项 node_id 已弃用（deprecated）。仍在使用 node_id 的部署应在下个版本前移除该配置，升级后请检查 kong.conf 中是否残留该键。

三、新增特性（Features）

3.1 CLI：新增 kong drain 命令

变更日志条目：新增 kong drain CLI 命令，使 /status/ready 端点返回 503 Service Unavailable。

从源码看，这条命令非常适合 K8s/容器环境下的优雅停机（preStop 钩子）：先排水、再等 LB 摘流量、最后停进程。其实现位于 kong/cmd/drain.lua，关键流程为：

1. 通过 conf_loader 加载配置，优先读取 <PREFIX>/kong_env 中运行中节点的实际配置；
2. 取第一个 status listener 的地址，构造 http(s)://<ip>:<port>/status/ready URL；
3. 以 POST 方式发送 JSON 请求体 {"status": "draining"}，期望得到 204 响应；
4. 成功后打印 Kong's status successfully changed to 'draining'。

命令用法与可选参数（摘自该文件中的 lapp 帮助文本）：

Usage: kong drain [OPTIONS]

Make status listeners(`/status/ready`) return 503 Service Unavailable.

Example usage:
 kong drain

Options:
 -c,--conf    (optional string)  configuration file
 -p,--prefix  (optional string)  override prefix directory

服务端的响应逻辑在 kong/status/ready.lua：POST 处理器在请求参数 status == "draining" 时，把共享字典键 kong:status:ready 置为 false 并返回 204；此后 GET /status/ready 只要检测到该标志为 false，就立刻返回 503 {"message": "draining"}，不再执行数据库连通性与 router/plugins iterator 重建计数检查。也就是说，排水状态一经设置就持续有效，直到该 Kong 节点重启（共享字典随进程生命周期）为止。

3.2 Core：Hugging Face LLM 驱动

变更日志条目：新增对接 Hugging Face 推理 API 的 LLM 驱动，同时支持 Hugging Face 托管的 Serverless 与专属（dedicated）LLM 实例，覆盖 conversational（对话）与 text generation（文本生成）两类任务。

驱动实现位于 kong/llm/drivers/huggingface.lua（与 kong/llm/drivers/ 下已有的 openai、anthropic、bedrock、gemini、cohere、azure、mistral、llama2 等驱动并列）。从源码结构看，该驱动的核心工作是把 OpenAI 风格请求转换为 Hugging Face 推理 API 格式，再反向转换响应：

• to_huggingface 负责请求方向：对 llm/v1/completions 任务把 prompt 改写为 inputs，并通过 set_default_parameters 把 OpenAI 风格的 top_k / top_p / temperature / max_tokens 映射进 Hugging Face 的 parameters 对象——对话模型使用 max_length、生成模型使用 max_new_tokens；
• 模型级选项支持 options.huggingface.use_cache 与 options.huggingface.wait_for_model 两个开关，分别控制是否允许缓存、以及模型冷启动时是否等待加载完成；
• from_huggingface 负责响应方向：把 Hugging Face 的 generated_text（生成任务）或 choices[].message.content（对话任务）统一包装成 Kong 标准的 choices/usage 结构，并对 error / message 字段做错误透传。

在 ai-proxy 插件中配置 provider: "huggingface" 的 model 即可使用该驱动，从而复用 ai-proxy 的负载均衡、重试与可观测能力。

3.3 Clustering：Hybrid 模式 RPC 框架

变更日志条目：为 Hybrid 模式部署新增远程过程调用（RPC）框架。

从源码结构看，框架实现位于 kong/clustering/rpc/ 目录，包含 json_rpc_v2.lua（JSON-RPC 2.0 协议层）、socket.lua（传输）、queue.lua / concentrator.lua（请求排队与聚合）、future.lua（异步结果）、callbacks.lua（回调分发）、manager.lua 与 utils.lua 等模块。这为控制面（CP）与数据面（DP）之间新增的跨节点调用能力打下基础——在此之前两者之间主要是基于 cluster_events 的异步事件同步。配套地，本版本还修复了 Hybrid 模式下 CP 连接错误日志级别过高/过低的问题（见 5.5 节）。

3.4 Admin API：/config 支持 application/yaml

变更日志条目：声明式配置的 /config 端点新增支持官方 YAML 媒体类型 application/yaml。此前客户端多以 text/yaml 提交 YAML 声明式配置，现在可以直接使用标准媒体类型。

实现证据在 kong/api/api_helpers.lua：请求体解析处判断 content_type 前缀为 application/yaml（或与 text/yaml 相同）时按 YAML 解码。典型用法：

curl -X POST http://localhost:8001/config \
  -H "Content-Type: application/yaml" \
  -d @kong.yml

3.5 Plugin：新增 Redirect 插件

变更日志条目：新增 redirect 插件，用于把请求重定向到另一地址。

该插件 schema 与 handler 分别位于 kong/plugins/redirect/schema.lua 与 kong/plugins/redirect/handler.lua。配置项共三个：

字段	类型	默认值	说明
status_code	integer	301	响应码，取值范围 100–599（必填）
location	url	无	重定向目标 URL（必填）
keep_incoming_path	boolean	false	为 true 时，用入站请求的 path 与原始 query string 覆盖 location 中的对应部分

handler 的行为细节：在 access 阶段直接调用 kong.response.exit(status_code, "redirecting", { Location = ... }) 终止请求；当 keep_incoming_path 开启时，使用仓库新引入的 resty.ada URL 解析器（见 3.6 节）对 location 做 set_pathname(入站 path) 与 set_search(原始 query) 后再拼回完整 URL。插件优先级为 779——从源码注释看，该值刻意选择在所有限流/校验类插件与转换类插件之后、在需要调用上游的 AI 插件之前执行，避免重定向请求先触发限流计数或上游调用。

3.6 Core 其他新特性

逐项继承变更日志内容并补充实现位置：

• Kong Manager 多域名支持：Kong Manager 新增多域名支持，使 Admin API 请求可以动态跨域访问（dynamic cross-origin access），适配 Manager 与 Admin API 部署在不同域名/子域的环境。
• ADA 依赖：仓库新增 ADA 依赖——一个 WHATWG 规范兼容、高性能的 URL 解析器（C 库 + Lua 绑定）。它同时是 3.9.0 多个特性的底座，例如上述 Redirect 插件即用 resty.ada 解析 URL；相关单元测试见 spec/01-unit/31-ada-url_spec.lua。
• correlation-id 优先级提升：correlation-id 插件的 PRIORITY 从 1 提升到 100001。由于插件按优先级顺序执行，该调整使其运行在绝大多数插件（尤其是自定义认证插件）之后，从而能拿到认证插件可能重写的请求头再关联日志 ID。
• tls.disable_http2_alpn() PDK 补丁：新增可在执行 TLS 握手时禁用 HTTP/2 ALPN 的函数。这为“上游不支持/不应协商 HTTP/2”的场景提供了控制手段，ai-proxy 正是利用它（见 3.7 节）。
• Request debugger 输出增强：
  • total_time 字段的分辨率提升到微秒级；
  • 新增 total_time_without_upstream 字段，仅反映 Kong 自身引入的延迟（不含上游耗时），便于区分网关开销与后端开销。

3.7 PDK 新特性

• kong.service.request.clear_query_arg(name)：PDK 新增该 API，用于在转发前从上游请求的 query string 中移除指定参数（典型用途：转发给上游前抹掉用于认证的 key 参数）。实现位于 kong/pdk/service/request.lua。同批变更还修复了 key-auth 插件在隐藏凭据时 query 参数顺序丢失的问题（见 5.3 节）。
• Tracing PDK 支持 Array/Map 类型 span 属性：kong.tracing 的 span 属性不再局限于标量，可写入数组与 map，方便为 OpenTelemetry/Zipkin 等 exporter 上报更结构化的属性。

3.8 Plugin 其他新特性

• Prometheus：KONG_LATENCY_BUCKETS 的上限从 3000 提升到 6000，提高高延迟长尾的延迟统计精度。内置桶定义见 kong/plugins/prometheus/exporter.lua：{ 1, 2, 5, 7, 10, 15, 20, 30, 50, 75, 100, 200, 500, 750, 1000, 3000, 6000 }（单位为毫秒）。
• ai-proxy：对配置了 ai-proxy 的 route，其到上游的连接将禁用 HTTP/2 ALPN 握手。结合 3.6 节新增的 kong.service.request/tls 补丁能力，从源码结构看这是为了让 AI 上游（多为流式 SSE）稳定走 HTTP/1.1，规避部分 LLM API 在 h2 上的兼容问题。
• Prometheus：新增 Proxy-Wasm 指标（Proxy-Wasm metrics）支持，与 3.9.0 引入的“Wasm filter 可通过 /plugins Admin API 配置”能力（见下条）配套，使 Wasm 层产生的指标可被 Prometheus 插件采集。
• proxy-wasm：Wasm filter 现在支持通过 /plugins Admin API 进行配置，即 Wasm filter 以插件形态进入声明式/动态配置体系，而非只能写死在 proxy_wasm_filters 静态配置中。

四、依赖升级（Dependencies）

变更日志“Dependencies”部分全部条目如下，升级 3.9.0 时这些依赖会随之更新：

Core 依赖：

• lua-kong-nginx-module 从 0.11.0 升至 0.11.1：修复上游证书链未正确设置的问题。
• lua-resty-events 升至 0.3.1：优化内存占用。
• lua-resty-lmdb 升至 1.6.0：允许 page_size 为 1。
• lua-resty-lmdb 升至 1.5.0：新增 page_size 参数，允许调用方覆盖 LMDB 页面大小。

Default（默认打包依赖）：

• 支持 Ubuntu 24.04（Noble Numbat）：开源包与 Enterprise 包均支持。
• RPM Dockerfile 默认基础镜像 UBI 8 升至 UBI 9。
• lua-resty-aws 升至 1.5.4：修复 region 前缀生成中的 bug（影响 AWS 系插件签名）。
• lua-resty-ljsonschema 升至 1.2.0：enum 类型支持 null 作为合法选项；UTF-8 字符串长度按字符数而非字节数计算（影响 schema 校验中含多字节字符的 max/minLength 场景）。
• ngx_wasm_module 升级至 commit 9136e463a6f1d80755ce66c88c3ddecd0eb5e25d。
• Wasmtime 升至 26.0.0。
• OpenSSL 升至 3.2.3：修复 TLSv1.3 会话处理中无界内存增长等安全漏洞（CVE）。
• Wasm：移除了实验性的 datakit Wasm filter（使用 proxy_wasm_filters 中 datakit 条目的部署需相应清理）。

五、缺陷修复（Fixes）

5.1 Core

• 修复 ngx.balancer.recreate_request 在 balancer 阶段使用 ngx.req.set_body_data 后不会刷新 body buffer 的问题——影响 balancer 阶段改 body 后重试请求的正确性。
• 修复未把 ngx.ctx 传给 log_init_worker_errors 可能引发运行时崩溃的问题。
• 修复 plugins iterator 中插件配置缺失 workspace ID 的问题（同一问题在两个 PR 中先后修复）。
• 修复 schema 校验时未处理的 nil 字段触发 500 的问题。
• Vault 三项修复：
  • 数组型配置字段无法包含 vault 引用（$ kong-vault://...）的问题；
  • 在非默认 workspace 中更新 vault 实体不生效的问题；
  • 同时启用 http 与 stream 两个 subsystem 时，kong 配置中的 vault 引用无法解引用的问题。
• proxy-wasm：新增启动检查——当数据库中存在无效 Wasm filter 时阻止 Kong 启动，避免带病运行。
• 修复下游使用 HTTP/2 时 kong.request.enable_buffering 不可用的问题。

5.2 PDK

• kong.log.inspect 的日志级别对齐为文档所述的 notice 级别。
• 修复无效的 retries 变量产生的错误信息。

5.3 Plugin

ai-proxy / ai-transformers 是本版本修复最集中的插件：

• ai-proxy：修复向 Anthropic、Bedrock、Cohere、Gemini（含经 Vertex）发起 tools（function）调用返回空结果的问题；
• ai-proxy：修复 Bedrock Guardrail 配置被忽略的问题；
• ai-proxy：修复 Gemini provider 在内容安全（content safety）检查失败时报错异常的问题；
• ai-proxy：修复使用 "Google One" Gemini 订阅时 AI Transformer 插件总是返回 404 的问题；
• ai-transformers：修复正确的 LLM 错误信息未透传给调用方的问题；
• AI-Proxy：修复 Azure AI provider 上多模态（multi-modal）请求被拦截的问题；
• 修复 AI 语义缓存（semantic cache）不能使用请求方指定的 model 的问题；
• AWS-Lambda：修复 proxy 集成模式下 multiValueHeaders 为 null 导致内部 500 错误的问题；
• jwt：确保 rsa_public_key 不会被误做 base64 解码；
• key-auth：修复隐藏凭据时 query 参数顺序错乱的问题（与 PDK 新增 clear_query_arg 同批）；
• rate-limiting：修复 get_redis_connection() 返回值不正确的问题；
• rate-limiting：修复 hide_client_headers 为 true 且请求超限时返回 HTTP 500 的问题。

5.4 Admin API

• 修复使用空 tags 查询 Admin API 实体的问题。
• 修复 form-urlencoded 请求中嵌套参数无法正确解析的问题。

5.5 Clustering

• Clustering：调整控制面（CP）连接相关错误日志的级别，减少 Hybrid 场景下无意义的高级别告警噪音。

5.6 Default

• Loggly：修复容器等环境中 /bin/hostname 缺失导致启动时报错/警告的问题。

六、Kong Manager 修复

• 从其他实体创建/编辑 scoped plugin 时，隐藏 scope 变更字段（避免误操作改变作用域）。
• 修复并统一了一批 UI 体验问题（共 18 个关联 issue，见 changelog/3.9.0/kong-manager/ 下的条目文件）。
• 统一实体操作完成后的页面重定向逻辑，保证各实体页面的跳转行为一致。

七、升级建议

结合本仓库 3.9.0 变更日志，升级前建议关注四点：

1. 配置清理：移除已弃用的 node_id；若使用过 datakit Wasm filter，删除相关 proxy_wasm_filters 配置，否则新增强制检查会导致启动失败（这是 3.9.0 有意引入的 fail-fast 行为）。
2. Hybrid 部署：关注 CP 连接日志级别调整对现有告警规则（如基于 error 日志关键字）的影响。
3. OpenSSL 3.2.3：TLS 相关依赖升级，建议回归验证证书链与 TLS 握手行为（lua-kong-nginx-module 0.11.1 同时修复了上游证书链设置问题，两者都与 mTLS/证书链场景相关）。
4. AI 网关：大量 function calling 相关修复使 ai-proxy 对 Anthropic/Bedrock/Cohere/Gemini 的工具调用链路更加可靠，依赖 tools 调用的生产流量建议在升级后回放验证。

各条目的原始 issue 编号与内部任务号，可对照 changelog/3.9.0/ 下的条目文件（如 feat-kong-drain-cmd.yml、cp-dp-rpc.yml、plugins-redirect.yml）逐条追溯。