企业官网建设流程全解析

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

【免费下载链接】kong🦍 The API and AI Gateway项目地址: https://gitcode.com/GitHub_Trending/ko/kong

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 的核心变化可以归纳为五条主线：

二、弃用项（Deprecations）

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

三、新增特性（Features）

3.1 CLI：新增kong drain命令

变更日志条目：新增kong drainCLI 命令，使/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/readyURL；
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。配置项共三个：

handler 的行为细节：在access阶段直接调用kong.response.exit(status_code, "redirecting", { Location = ... })终止请求；当keep_incoming_path开启时，使用仓库新引入的resty.adaURL 解析器（见 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 可通过/pluginsAdmin API 配置”能力（见下条）配套，使 Wasm 层产生的指标可被 Prometheus 插件采集。
• proxy-wasm：Wasm filter 现在支持通过/pluginsAdmin 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升级至 commit9136e463a6f1d80755ce66c88c3ddecd0eb5e25d。
• 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）逐条追溯。

【免费下载链接】kong🦍 The API and AI Gateway项目地址: https://gitcode.com/GitHub_Trending/ko/kong