This is an automated email from the ASF dual-hosted git repository. kayx23 pushed a commit to branch codex/release-notes-3.18.0 in repository https://gitbox.apache.org/repos/asf/apisix-website.git
commit ec522491ff655fa62b22cd56bab24b1ef8133008 Author: kayx23 <[email protected]> AuthorDate: Wed Aug 19 13:19:35 2026 +0800 docs: add APISIX 3.18.0 release notes --- .../2026/08/24/release-apache-apisix-3.18.0.md | 568 +++++++++++++++++++++ .../2026/08/24/release-apache-apisix-3.18.0.md | 568 +++++++++++++++++++++ 2 files changed, 1136 insertions(+) diff --git a/blog/en/blog/2026/08/24/release-apache-apisix-3.18.0.md b/blog/en/blog/2026/08/24/release-apache-apisix-3.18.0.md new file mode 100644 index 00000000000..241cce11735 --- /dev/null +++ b/blog/en/blog/2026/08/24/release-apache-apisix-3.18.0.md @@ -0,0 +1,568 @@ +--- +title: "Release Apache APISIX 3.18.0" +authors: + - name: "Abhishek Choudhary" + title: "Author" + url: "https://github.com/shreemaan-abhishek"; + image_url: "https://github.com/shreemaan-abhishek.png"; + - name: "Traky Deng" + title: "Technical Writer" + url: "https://github.com/kayx23"; + image_url: "https://github.com/kayx23.png"; +keywords: + - Apache APISIX + - API Gateway + - API Management Platform + - New Release + - Cloud Native +description: Apache APISIX 3.18.0 is released on Aug 24, 2026. This release introduces AI response caching, semantic model routing, new security plugins, L4 enhancements, observability improvements, and important upgrade considerations. +tags: [Community] +--- + +<!-- TODO: Replace Aug 24, 2026 with the final release date. --> + +We are glad to present Apache APISIX 3.18.0 with new AI Gateway capabilities, stronger security defaults, L4 proxy enhancements, observability improvements, and reliability fixes across the gateway. + +<!--truncate--> + +This release introduces exact, semantic, and streaming response caching for LLM traffic; semantic model routing; Lakera Guard integration; an advanced LDAP authentication plugin; richer Prometheus metrics; and several improvements to stream proxying, health checks, logging, and encryption. + +The release also contains backward-incompatible changes. Review the following migration notes before upgrading. + +## Breaking Changes + +The following changes affect existing behavior, defaults, configuration, or observability contracts. Use the upgrade plan under each item to identify affected deployments and prepare the necessary changes before rollout. + +### Debug plugin reporting includes phases and execution order + +The `Apisix-Plugins` response header now reports ordered `plugin-name#phase` entries instead of a de-duplicated list of plugin names. Update tools that parse this header. + +**Upgrade plan:** Search dashboards, tests, and debugging tools for `Apisix-Plugins`. Update parsers to accept repeated plugin names in different phases and to preserve the reported order. + +For more information, see [PR #13710](https://github.com/apache/apisix/pull/13710). + +### Request and response buffering is limited by default + +Plugins that buffer request or response bodies now default to a 64 MiB limit. Oversized request bodies can be rejected, while oversized responses can be truncated or passed through without caching, depending on the plugin. Configure `max_req_body_size` or `max_resp_body_size` where larger payloads are expected. + +**Upgrade plan:** Identify routes that legitimately process bodies above 64 MiB. Set explicit limits on the affected plugins before upgrading, then test both oversized request rejection and response truncation behavior. + +For more information, see [PR #13705](https://github.com/apache/apisix/pull/13705). + +### Logger backlogs drop excess entries by default + +Batch-processor-based loggers now default `max_pending_entries` to `8192`. When a logging backend cannot keep up, new entries above the limit are discarded to protect worker memory. Increase the limit only after accounting for log body sizes and available memory. + +**Upgrade plan:** Review logger throughput, `batch_max_size`, and whether request or response bodies are included. Add alerts for discard messages and size `max_pending_entries` from the memory budget of each worker. + +For more information, see [PR #13826](https://github.com/apache/apisix/pull/13826). + +### AWS content moderation uses decoded AI content + +`ai-aws-content-moderation` now runs after `ai-proxy` or `ai-proxy-multi`, moderates protocol-decoded prompt content, and returns provider-compatible deny responses. The plugin requires AI proxy context, its priority changes from `1050` to `1031`, and the default deny status is now `200`. + +**Upgrade plan:** Ensure every route using the plugin also enables `ai-proxy` or `ai-proxy-multi`. Review clients that expect a 400 deny status and set `deny_code` explicitly if they should continue receiving an HTTP error. + +For more information, see [PR #13647](https://github.com/apache/apisix/pull/13647). + +### Aliyun request moderation defaults to the latest user turn + +`ai-aliyun-content-moderation` now defaults to moderating the latest user turn rather than the complete conversation across all roles. Set `request_check_mode: all` and configure `request_check_roles` if the previous scope is required. + +**Upgrade plan:** Decide whether moderation should cover only the newest user turn or the full conversation. Pin `request_check_mode` and `request_check_roles` explicitly instead of relying on defaults. + +For more information, see [PR #13598](https://github.com/apache/apisix/pull/13598). + +### SLS logger verifies TLS certificates by default + +`sls-logger` now defaults `ssl_verify` to `true` and sends SNI. Custom or self-signed logging endpoints must use a trusted certificate or explicitly set `ssl_verify: false`. + +**Upgrade plan:** Test the TLS handshake to every SLS endpoint with the APISIX trust store. Install the correct CA and hostname-valid certificate; use `ssl_verify: false` only as a deliberate temporary exception. + +For more information, see [PR #13785](https://github.com/apache/apisix/pull/13785). + +### OpenID Connect validation fails closed + +The `openid-connect` plugin now rejects tokens when the trusted issuer cannot be determined, treats `claim_validator.audience.match_with_client_id` as requiring an audience claim, and enforces `required_scopes` in authorization-code sessions. Review providers that issue opaque access tokens or omit scope claims. + +**Upgrade plan:** Test bearer and browser-session flows against the real identity provider. Configure `claim_validator.issuer.valid_issuers` when discovery may be unavailable, and confirm the provider exposes every configured required scope in a readable claim. + +For more information, see [PR #13829](https://github.com/apache/apisix/pull/13829). + +### Duplicate consumer authentication keys are rejected + +The Admin API now rejects duplicate lookup keys across Consumers and credentials for `key-auth`, `basic-auth`, `jwt-auth`, `hmac-auth`, and LDAP authentication. Existing ambiguous configurations should be made unique before they are updated. + +**Upgrade plan:** Audit existing Consumers and credentials for duplicate authentication keys before rollout. Resolve collisions first so later Admin API updates are not rejected. + +For more information, see [PR #13529](https://github.com/apache/apisix/pull/13529). + +### Forwarded-header handling changes + +`$var_x_forwarded_proto` is removed, while `$var_x_forwarded_host` and `$var_x_forwarded_port` are no longer writable from Lua. Plugins should use `core.request.set_header` to change upstream forwarding headers. Trusted peers that omit `X-Forwarded-Host` or `X-Forwarded-Port` now receive APISIX-observed values, and logger payloads include sanitized forwarded headers. + +**Upgrade plan:** Search custom plugins, NGINX snippets, and log formats for the three `$var_x_forwarded_*` variables. Replace Lua assignments with `core.request.set_header`, and update fixed-schema log consumers for the additional sanitized headers. + +For more information, see [PR #13803](https://github.com/apache/apisix/pull/13803). + +### AI proxy defaults to the FFI HTTP client + +`ai-proxy`, `ai-proxy-multi`, and `ai-request-rewrite` now default to `ngx_http_ffi_client`. The APISIX Runtime pinned by this release includes the module. Operators using an older or custom runtime without it must upgrade the runtime or set `plugin_attr.ai-proxy.http_client: lua-resty-http`. + +**Upgrade plan:** Run `nginx -V` on the target image and confirm `ngx_http_ffi_client` is present. Upgrade the runtime with APISIX, or opt out in `config.yaml` before sending AI traffic. + +For more information, see [PR #13778](https://github.com/apache/apisix/pull/13778). + +### Large `post_arg.*` route matches are bounded + +JSON and multipart bodies read for `post_arg.*` route predicates now default to a 64 MiB cap. A larger body no longer matches the predicate and can result in a 404. Raise `apisix.max_post_args_readable_size` or set it to `0` to retain unlimited reads. + +**Upgrade plan:** Locate routes that match on `post_arg.*`, determine their maximum expected body size, and set `apisix.max_post_args_readable_size` explicitly. Include an over-limit request in upgrade testing. + +For more information, see [PR #13601](https://github.com/apache/apisix/pull/13601). + +### Existing LDAP TLS verification is now effective + +The LDAP client dependency upgrade makes `ldap-auth.tls_verify: true` perform certificate verification instead of acting as a no-op. Deployments with self-signed or hostname-mismatched LDAP certificates must install a trusted matching certificate or explicitly disable verification where appropriate. + +**Upgrade plan:** Validate the LDAP certificate chain and SAN against `ldap_uri`. Configure the trusted CA before deployment and test both LDAPS and StartTLS paths that are in use. + +For more information, see [PR #13762](https://github.com/apache/apisix/pull/13762). + +### LDAP Consumer DNs use RFC 4514 escaping + +`ldap-auth` now looks up Consumers using the escaped bind DN returned by the LDAP client. Consumers for usernames containing characters such as commas or plus signs must use the RFC 4514-escaped `user_dn` form. + +**Upgrade plan:** Find LDAP usernames containing DN-special characters and rewrite their Consumer `user_dn` values with RFC 4514 escaping before upgrading. + +For more information, see [PR #13805](https://github.com/apache/apisix/pull/13805). + +### Prometheus LLM latency gains a `type` label + +`apisix_llm_latency` now distinguishes `type="total"` from `type="ttft"`, and streaming requests emit both observations. Update dashboards, alerts, and recording rules to select `type="total"` when they need the previous total-latency meaning. + +**Upgrade plan:** Update PromQL queries and recording rules before the new metric shape is scraped. Check expected series counts because each streaming request now contributes both total-latency and TTFT observations. + +For more information, see [PR #13487](https://github.com/apache/apisix/pull/13487). + +### Consumer-bound AI plugins default to skipping unrecognized traffic + +The new `fail_mode` option defaults to `skip`. Non-AI traffic that previously returned 500 in Aliyun moderation, or was moderated as a raw body by AWS moderation, now passes through unchecked. Set `fail_mode: error` when every request must be recognized and moderated. + +**Upgrade plan:** Classify routes as mixed traffic or AI-only. Set `fail_mode: error` explicitly on routes where unrecognized traffic must never bypass moderation, and test non-JSON and non-AI requests. + +For more information, see [PR #13489](https://github.com/apache/apisix/pull/13489). + +## New Features + +APISIX 3.18.0 expands AI Gateway, authentication, L4 proxying, observability, rate limiting, logging, and traffic-management capabilities. The following sections explain the use cases, behavior, and key configuration choices for each major addition. + +### Cache LLM responses with `ai-cache` + +The new `ai-cache` plugin reduces latency and upstream token cost for repetitive LLM workloads such as support assistants, document Q&A, translation, and prompt-based automation. It supports three complementary capabilities: + +- An exact Redis-backed L1 cache for byte-equivalent request semantics. +- An optional semantic L2 cache that embeds prompts with OpenAI or Azure OpenAI and searches RediSearch by cosine similarity. +- Complete SSE capture and replay for supported streaming providers, with JSON and SSE entries stored separately. + +Cache keys include the client protocol, effective model and provider, response-determining parameters, and the selected AI instance. They can also isolate by Route, Consumer, or selected NGINX variables. Redis and embedding failures fail open as a normal miss, so the cache does not become an availability dependency. + +The following example enables exact and semantic caching. The first request populates both layers; a later paraphrase can be served from L2 when its similarity clears the configured threshold. + +```json +{ + "ai-cache": { + "redis_host": "127.0.0.1", + "redis_port": 6379, + "layers": ["exact", "semantic"], + "semantic": { + "similarity_threshold": 0.9, + "embedding": { + "openai": { + "model": "text-embedding-3-small", + "api_key": "$env://OPENAI_API_KEY" + } + }, + "vector_search": { + "redis": {} + } + } + } +} +``` + +For more information, see [PR #13578](https://github.com/apache/apisix/pull/13578), [PR #13632](https://github.com/apache/apisix/pull/13632), and [PR #13644](https://github.com/apache/apisix/pull/13644). + +### Route prompts to models by meaning + +`ai-proxy-multi` adds a `semantic` balancing algorithm for deployments where the available models are not interchangeable. A single endpoint can route coding prompts to a capable model, translation to a lower-cost model, and unmatched traffic to a general fallback without exposing provider topology to clients. + +APISIX embeds each instance's natural-language examples once and caches the resulting reference vectors by configuration version. Each request requires one prompt-embedding call, followed by in-process cosine comparison. No vector database is needed. If embedding fails or no score clears the threshold, the request goes to the configured fallback instance. + +```json +{ + "ai-proxy-multi": { + "balancer": { + "algorithm": "semantic", + "threshold": 0.6 + }, + "semantic_opts": { + "fallback": "general", + "embeddings": { + "provider": "openai", + "model": "text-embedding-3-small", + "auth": { + "header": { + "Authorization": "Bearer $env://EMBEDDING_API_KEY" + } + } + } + }, + "instances": [ + { + "name": "code", + "provider": "openai", + "weight": 1, + "auth": {"header": {"Authorization": "Bearer $env://OPENAI_API_KEY"}}, + "options": {"model": "gpt-4o"}, + "override": {"endpoint": "https://api.openai.com/v1/chat/completions"}, + "examples": ["debug this stack trace", "write a Python function"] + }, + { + "name": "general", + "provider": "openai", + "weight": 1, + "auth": {"header": {"Authorization": "Bearer $env://OPENAI_API_KEY"}}, + "options": {"model": "gpt-4o-mini"}, + "override": {"endpoint": "https://api.openai.com/v1/chat/completions"}, + "examples": ["answer a general question"] + } + ] + } +} +``` + +Semantic selection is best-effort routing, not a content-security control, and does not yet provide health-aware retry after an instance is selected. + +For more information, see [PR #13676](https://github.com/apache/apisix/pull/13676). + +### Protect LLM requests and responses with Lakera Guard + +The new `ai-lakera-guard` plugin integrates with the Lakera Guard v2 API to detect prompt injection, sensitive information, policy violations, and malicious links at the gateway. It can scan requests, responses, or both, so applications do not need to implement the same guardrail integration independently. + +In `block` mode, flagged traffic is replaced with a provider-compatible refusal body. Streaming output is buffered before release so flagged tokens do not reach the client. In `alert` mode, operators can observe verdicts before enforcing them. Lakera API failures are controlled separately through `fail_open`, making the availability-versus-enforcement decision explicit. + +```json +{ + "ai-lakera-guard": { + "api_key": "$env://LAKERA_API_KEY", + "direction": "both", + "action": "alert", + "fail_open": true, + "reveal_failure_categories": false + } +} +``` + +A practical rollout is to begin with `action: alert` and `fail_open: true`, inspect detector results and false positives, then move selected Routes to `block`. For strict output enforcement, use `fail_open: false`; streaming responses are then buffered so an unavailable scanner cannot leak unchecked output. + +For more information, see [PR #13570](https://github.com/apache/apisix/pull/13570) and [PR #13606](https://github.com/apache/apisix/pull/13606). + +### Moderate more AI traffic with AWS and Aliyun + +AWS moderation can now inspect non-streaming and streaming responses in addition to requests. Realtime mode checks batches while a response is streaming and can replace the remainder immediately; final-packet mode scores the assembled output and records a risk level. Long content is split at UTF-8 boundaries and batched within AWS Comprehend's segment limits. + +Both AWS and Aliyun plugins can select which request roles are in scope. `user`, `tool`, and `assistant` content can follow latest-turn or all-history behavior, while selected system content is checked on every request. OpenAI's `developer` role is treated as system-level content. + +```json +{ + "ai-aws-content-moderation": { + "comprehend": { + "access_key_id": "$env://AWS_ACCESS_KEY_ID", + "secret_access_key": "$env://AWS_SECRET_ACCESS_KEY", + "region": "us-east-1" + }, + "request_check_roles": ["user", "tool", "system"], + "request_check_mode": "last", + "check_response": true, + "stream_check_mode": "realtime" + } +} +``` + +These controls help Agent and MCP workloads moderate tool output and potentially poisoned system instructions without repeatedly sending the entire conversation history to the moderation provider. + +For more information, see [PR #13735](https://github.com/apache/apisix/pull/13735), [PR #13773](https://github.com/apache/apisix/pull/13773), [PR #13767](https://github.com/apache/apisix/pull/13767), [PR #13646](https://github.com/apache/apisix/pull/13646), and [PR #13780](https://github.com/apache/apisix/pull/13780). + +### Add advanced LDAP authentication + +The new `ldap-auth-advanced` plugin supports directories where a username cannot be converted directly into a bind DN. It first searches for the user and then binds as the resolved DN, covering common Active Directory deployments that authenticate with attributes such as `sAMAccountName`. + +Search can use a service account or anonymous bind. The plugin supports LDAPS, StartTLS, certificate verification, connection pooling, LDAP filter escaping, bounded searches, and Consumer association by `user_dn`. Authentication failures return 401, while directory transport and configuration failures remain distinguishable as server errors. + +```json +{ + "ldap-auth-advanced": { + "ldap_uri": "ldap.example.com:636", + "use_ldaps": true, + "ssl_verify": true, + "base_dn": "ou=users,dc=example,dc=org", + "attribute": "sAMAccountName", + "bind_dn": "cn=apisix,ou=services,dc=example,dc=org", + "ldap_password": "$env://LDAP_BIND_PASSWORD" + } +} +``` + +By default, successful authentication must map to an APISIX Consumer. Set `consumer_required` deliberately if the directory identity should be authenticated without Consumer-based policies. + +For more information, see [PR #13762](https://github.com/apache/apisix/pull/13762). + +### Improve stream and L4 proxying + +Stream listeners can now enable or disable inbound and outbound PROXY protocol independently per TCP port. This removes the previous all-or-nothing global behavior and lets one APISIX instance serve clients and upstreams with different protocol requirements. + +When APISIX is behind a trusted load balancer, `nginx_config.stream.real_ip_from` adopts the client address from the inbound PROXY header. That address is then available to Stream plugins and can be rebuilt into the header sent upstream. L4 TLS upstreams can also receive a client certificate from inline configuration or `tls.client_cert_id`. + +```yaml +apisix: + proxy_mode: http&stream + stream_proxy: + tcp: + - addr: 9100 + proxy_protocol: true + proxy_protocol_to_upstream: true +nginx_config: + stream: + real_ip_from: + - 10.0.0.0/8 +``` + +Prometheus complements these controls with live active-connection gauges, termination status, and downstream/upstream ingress and egress bandwidth per listening address. The metrics require the APISIX Runtime included with this release and degrade gracefully on older runtimes. + +For more information, see [PR #13561](https://github.com/apache/apisix/pull/13561), [PR #13700](https://github.com/apache/apisix/pull/13700), [PR #13596](https://github.com/apache/apisix/pull/13596), and [PR #13796](https://github.com/apache/apisix/pull/13796). + +### Expand Prometheus controls and AI metrics + +Prometheus adds AI cache hit, miss, and bypass counters, an embedding-latency histogram, LLM prompt and completion token distributions, and separate total-latency and TTFT observations. These metrics make it possible to measure cache effectiveness, embedding overhead, prompt-size percentiles, and streaming responsiveness directly from the gateway. + +High-cardinality deployments can collapse selected built-in label values through plugin metadata without removing labels from the metric schema. Client-supplied model label values are also capped at 128 bytes. Library upgrades fix duplicate series, a 100% CPU loop when the metric dictionary fills, and failure to reclaim expired entries. + +```json +{ + "disabled_labels": { + "http_status": ["node", "consumer"], + "http_latency": ["node"], + "llm_prompt_tokens": ["request_llm_model"] + } +} +``` + +Apply `disabled_labels` through `/apisix/admin/plugin_metadata/prometheus`. Structural labels such as HTTP status code and latency type cannot be disabled because collapsing them would merge measurements with different meanings. + +For more information, see [PR #13659](https://github.com/apache/apisix/pull/13659), [PR #13202](https://github.com/apache/apisix/pull/13202), [PR #13637](https://github.com/apache/apisix/pull/13637), [PR #13602](https://github.com/apache/apisix/pull/13602), [PR #13708](https://github.com/apache/apisix/pull/13708), and [PR #13754](https://github.com/apache/apisix/pull/13754). + +### Share rate limits through Redis + +`ai-rate-limiting` can now store token counters in Redis, Redis Cluster, or Redis Sentinel, allowing multiple APISIX nodes to enforce one quota. The existing `local` policy remains the default and continues to maintain a separate counter per gateway node. + +`limit-count` adds three independent controls: a Sentinel backend for high availability, sliding-window counters that smooth boundary bursts, and delayed synchronization that batches Redis updates for high-throughput workloads. Delayed sync trades short-lived global accuracy for fewer network round trips; omit `sync_interval` when exact per-request Redis accounting is required. + +```json +{ + "limit-count": { + "count": 5000, + "time_window": 60, + "key": "consumer_name", + "key_type": "var", + "window_type": "sliding", + "policy": "redis-sentinel", + "redis_sentinels": [ + {"host": "10.0.0.1", "port": 26379}, + {"host": "10.0.0.2", "port": 26379} + ], + "redis_master_name": "mymaster", + "sync_interval": 1 + } +} +``` + +The sliding-window and delayed-sync implementations also receive atomicity and quota-calculation fixes in this release, so the new modes should be adopted together with the full 3.18.0 patch set. + +For more information, see [PR #13670](https://github.com/apache/apisix/pull/13670) and [PR #13443](https://github.com/apache/apisix/pull/13443). + +### Enhance OpenID Connect client flows + +The `openid-connect` plugin adds Pushed Authorization Requests (PAR), DPoP proof generation for token and userinfo calls, and client assertion algorithm and audience controls. PAR and DPoP are opt-in and use nested configuration objects; DPoP private keys are encrypted at rest. + +Applications that need the original signed ID token can enable `set_raw_id_token_header`, which forwards it as `X-Raw-ID-Token` in the authorization-code session flow. This differs from `X-ID-Token`, which contains encoded decoded claims rather than the provider's signed JWT. + +```json +{ + "openid-connect": { + "client_id": "apisix", + "client_secret": "$env://OIDC_CLIENT_SECRET", + "discovery": "https://idp.example.com/.well-known/openid-configuration";, + "redirect_uri": "https://gateway.example.com/callback";, + "par": { + "enabled": true + }, + "set_raw_id_token_header": true, + "session": { + "secret": "$env://OIDC_SESSION_SECRET" + } + } +} +``` + +The plugin also recovers more gracefully from browser-flow failures. A stale callback or `temporarily_unavailable` response can restart authentication from the original URL, with a bounded retry counter to prevent redirect loops. Deliberate outcomes such as `access_denied` are not retried. + +For more information, see [PR #13649](https://github.com/apache/apisix/pull/13649), [PR #13616](https://github.com/apache/apisix/pull/13616), [PR #13712](https://github.com/apache/apisix/pull/13712), and [PR #13825](https://github.com/apache/apisix/pull/13825). + +### Enrich logging and protect stored credentials + +Logger plugins support `log_format_extra`, which overlays selected fields onto the default structured log instead of replacing it. This is useful when adding tenant, upstream, or business context while retaining request headers, response data, latency fields, APISIX version, and resource identifiers. + +```json +{ + "log_format_extra": { + "upstream_host": "$upstream_unresolved_host", + "tenant": "$http_x_tenant_id" + } +} +``` + +Kafka logging can connect to TLS-enabled brokers, and Produce API version `2` can be selected when broker-side message timestamps are required. The Kafka output of `error-log-logger` receives the same TLS capability. + +Credential storage is also hardened: custom Elasticsearch and Loki headers, Redis passwords in rate-limiting plugins, Sentinel passwords, and inline Stream upstream client keys are encrypted at rest when data encryption is enabled. Debug logging paths that exposed serialized logger payloads or Kafka SASL credentials have been removed. + +For more information, see [PR #13568](https://github.com/apache/apisix/pull/13568), [PR #13607](https://github.com/apache/apisix/pull/13607), [PR #13521](https://github.com/apache/apisix/pull/13521), [PR #13612](https://github.com/apache/apisix/pull/13612), [PR #13784](https://github.com/apache/apisix/pull/13784), and [PR #13624](https://github.com/apache/apisix/pull/13624). + +### Add routing, health-check, and encryption options + +APISIX can keep `%2F` encoded while matching parameterized Routes, allowing a value such as `cat%2Fdog` to remain one path parameter rather than becoming two segments. The option is global, disabled by default, and only affects matching and captured parameters; downstream phases continue to see the normalized URI. + +Active health checks can send a custom HTTP method and request body. This is useful for upstreams that cannot be meaningfully checked with a bodyless GET, including LLM endpoints that require a minimal chat-completion POST. + +```json +{ + "checks": { + "active": { + "type": "https", + "http_method": "POST", + "http_path": "/v1/chat/completions", + "http_req_body": "{\"model\":\"health-check\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}" + } + } +} +``` + +The data-encryption keyring now accepts 16-byte AES-128 and 32-byte AES-256 keys in the same rotation set. Operators can place a new AES-256 key first while retaining older AES-128 keys for decryption. Default shared dictionaries are also larger for Prometheus, discovery, and tracing data that cannot safely evict entries when full. + +For more information, see [PR #13626](https://github.com/apache/apisix/pull/13626), [PR #13726](https://github.com/apache/apisix/pull/13726), [PR #13756](https://github.com/apache/apisix/pull/13756), and [PR #13688](https://github.com/apache/apisix/pull/13688). + +## Bug Fixes + +This release also resolves correctness, security, and reliability issues across major gateway subsystems. The fixes are grouped by affected area so operators can quickly identify the changes relevant to their deployments. + +### AI Gateway correctness and protocol compatibility + +AI proxying now preserves more of the upstream provider's intent and keeps retries isolated from earlier attempts. Clients receive the original 429/5xx error body and content type when a request is not retried; when fallback does occur, each instance rebuilds its request from the untouched client body so model options do not leak between instances. AI latency variables also use milliseconds consistently on successful and error responses. See [PR #13565](https://github.com/apache/apisix/p [...] + +Protocol conversion is more resilient and faithful: + +- Anthropic clients no longer hang when an upstream stream ends before opening a content block, and invalid `tool_call` arguments no longer discard an otherwise usable response. See [PR #13583](https://github.com/apache/apisix/pull/13583) and [PR #13599](https://github.com/apache/apisix/pull/13599). +- Anthropic tool-result ordering, tool-name mapping, reasoning effort, structured output, and message shaping now align more closely with OpenAI-compatible upstream expectations. See [PR #13674](https://github.com/apache/apisix/pull/13674). +- Structured and multimodal message content is flattened consistently for text consumers while remaining distinct in exact cache keys; semantic caching bypasses prompts containing non-text state. See [PR #13634](https://github.com/apache/apisix/pull/13634) and [PR #13654](https://github.com/apache/apisix/pull/13654). +- Realtime moderation no longer counts one upstream chunk multiple times when protocol conversion fans it out into several client events. See [PR #13765](https://github.com/apache/apisix/pull/13765). + +Internal requests from `ai-request-rewrite` no longer forward the downstream client's `Authorization` or `Cookie` headers to the configured LLM endpoint. The transparent `ai-proxy` path still forwards client headers as documented. See [PR #13699](https://github.com/apache/apisix/pull/13699). + +### Authentication and identity security + +Authentication plugins now reject malformed input cleanly and prevent client-controlled identity data from reaching upstream services: + +- Malformed JWT signatures return 401 rather than triggering a 500, while `jwe-decrypt` correctly allows a missing token when `strict` is disabled. See [PR #13518](https://github.com/apache/apisix/pull/13518) and [PR #13822](https://github.com/apache/apisix/pull/13822). +- `wolf-rbac` and `attach-consumer-label` always remove client-supplied identity headers before applying trusted identity data. See [PR #13696](https://github.com/apache/apisix/pull/13696) and [PR #13590](https://github.com/apache/apisix/pull/13590). +- `key-auth` reports its real failure reason through `multi-auth`, `basic-auth` validates `anonymous_consumer`, and `hmac-auth` reliably removes credentials when requested. See [PR #13693](https://github.com/apache/apisix/pull/13693), [PR #13682](https://github.com/apache/apisix/pull/13682), and [PR #13820](https://github.com/apache/apisix/pull/13820). + +CAS single-logout callbacks now stop at the plugin instead of being proxied upstream, and Casdoor sessions expire with their access tokens. Request IDs generated with the `nanoid` algorithm now use a CSPRNG and no longer suffer duplicate IDs, malformed output, or file-descriptor leaks. See [PR #13610](https://github.com/apache/apisix/pull/13610), [PR #13500](https://github.com/apache/apisix/pull/13500), and [PR #13508](https://github.com/apache/apisix/pull/13508). + +### Health checks and load balancing + +Consistent-hash rings now remain tied to configured nodes and weights while unhealthy targets are skipped at selection time, preventing healthy keys from moving unnecessarily. Least-connection balancing retains live load across scaling events and releases Stream connections correctly, so a newly added empty node is preferred over already-loaded nodes. See [PR #13532](https://github.com/apache/apisix/pull/13532) and [PR #13666](https://github.com/apache/apisix/pull/13666). + +Active health checks receive several reliability fixes: + +- Node-only upstream changes reconcile targets in place instead of destroying the checker, retaining health state and avoiding a window where unhealthy nodes receive traffic. See [PR #13629](https://github.com/apache/apisix/pull/13629). +- Domain nodes are probed with the configured domain as Host and TLS SNI rather than the resolved IP. See [PR #13743](https://github.com/apache/apisix/pull/13743). +- Stale targets are purged across all checkers, the periodic lock is released correctly, and failed AI upstream construction no longer aborts the timer for unrelated resources. See [PR #13627](https://github.com/apache/apisix/pull/13627) and [PR #13592](https://github.com/apache/apisix/pull/13592). +- `ai-proxy-multi` refreshes a picker after asynchronous health checkers appear and preserves existing query parameters in health-check paths. See [PR #13505](https://github.com/apache/apisix/pull/13505) and [PR #13506](https://github.com/apache/apisix/pull/13506). + +HTTPS upstreams using different referenced client certificates no longer share one keepalive pool. See [PR #13587](https://github.com/apache/apisix/pull/13587). + +### Rate limiting + +Sliding-window enforcement now performs the accept-or-reject decision and counter increment atomically on Redis backends. Delayed synchronization reports the previous window's weighted contribution correctly, preventing a fresh quota from appearing at every window boundary. See [PR #13574](https://github.com/apache/apisix/pull/13574) and [PR #13704](https://github.com/apache/apisix/pull/13704). + +Variable-resolved `count` and `time_window` values must now be positive safe integers. A malformed client-controlled value is rejected instead of crashing the limiter or silently skipping a rule. See [PR #13573](https://github.com/apache/apisix/pull/13573). + +Counter and connection isolation is corrected across workflows, Consumers, and Redis backends: + +- Each `limit-conn` workflow action receives its own counter, while Consumer-level counters are shared across that Consumer's Routes rather than being fragmented per Route. See [PR #13591](https://github.com/apache/apisix/pull/13591) and [PR #13600](https://github.com/apache/apisix/pull/13600). +- Redis and Sentinel keepalive pools are separated by database, credentials, and TLS settings, preventing counters from landing in another configuration's connection context. See [PR #13516](https://github.com/apache/apisix/pull/13516) and [PR #13553](https://github.com/apache/apisix/pull/13553). +- Redis policy schemas are copied before extension, and Redis Cluster script cache misses no longer trigger unnecessary topology refreshes. See [PR #13555](https://github.com/apache/apisix/pull/13555) and [PR #13579](https://github.com/apache/apisix/pull/13579). + +### Caching and request processing + +The in-memory `proxy-cache` strategy now uses an injective storage-key layout so a crafted request cannot read or overwrite another request's Vary variant. The layout version is bumped, making pre-upgrade memory-cache entries cold until they expire. `graphql-proxy-cache` PURGE also removes every indexed Vary variant instead of only the legacy base entry. See [PR #13831](https://github.com/apache/apisix/pull/13831) and [PR #13523](https://github.com/apache/apisix/pull/13523). + +Buffered request bodies are now reframed correctly before internal HTTP calls. `forward-auth`, AWS Lambda, Azure Functions, and OpenFunction remove stale client `Transfer-Encoding` and `Content-Length` values and let the HTTP client generate framing for the actual buffered body. See [PR #13642](https://github.com/apache/apisix/pull/13642) and [PR #13798](https://github.com/apache/apisix/pull/13798). + +Additional data-processing fixes include: + +- GraphQL fragment depth calculation is linear rather than exponential, and fragment cycles are rejected explicitly. See [PR #13809](https://github.com/apache/apisix/pull/13809). +- XML namespace removal no longer mutates a table during traversal, preserving namespaced keys and repeated elements reliably. See [PR #13522](https://github.com/apache/apisix/pull/13522). +- AWS Lambda SigV4 signs the same canonical, encoded, multi-value query string that is sent on the wire. See [PR #13520](https://github.com/apache/apisix/pull/13520). +- Empty repeated protobuf fields encode as JSON arrays, and JSON array element removal compacts the array instead of leaving holes. See [PR #13678](https://github.com/apache/apisix/pull/13678) and [PR #13818](https://github.com/apache/apisix/pull/13818). +- Duplicated `Content-Type` headers are rejected cleanly, control characters are escaped out of `$upstream_uri`, and unsafe URI rewriting retains the client query string. See [PR #13691](https://github.com/apache/apisix/pull/13691), [PR #13787](https://github.com/apache/apisix/pull/13787), and [PR #12843](https://github.com/apache/apisix/pull/12843). + +### Logging and observability + +Logger payloads and credentials are less likely to leak or cross configuration boundaries: + +- Elasticsearch, Kafka, RocketMQ, SLS, and Syslog no longer write serialized log payloads into the error log; Kafka SASL credentials are redacted from error paths. See [PR #13502](https://github.com/apache/apisix/pull/13502) and [PR #13786](https://github.com/apache/apisix/pull/13786). +- Loki resolves dynamic labels per request and groups each batch by the resolved label set, preventing one service's labels from leaking to another. See [PR #13562](https://github.com/apache/apisix/pull/13562). +- Loggly binds each batch processor to its own configuration, preventing one Route's token or tags from being used for another Route's batch. See [PR #13648](https://github.com/apache/apisix/pull/13648). +- Datadog falls back to per-metric datagrams when a coalesced DogStatsD packet would exceed the agent's default receive buffer. See [PR #13665](https://github.com/apache/apisix/pull/13665). +- Partial log rotation still sends the reopen signal when at least one file was rotated successfully. See [PR #13375](https://github.com/apache/apisix/pull/13375). + +OpenTelemetry tracers are rebuilt after metadata changes, and core-span injection uses an independent cache entry so it retains its always-on sampling behavior. Invalid, duplicated, or non-hex `X-Request-Id` values fall back to a generated trace ID rather than crashing export, and metadata value types are validated correctly. See [PR #13618](https://github.com/apache/apisix/pull/13618), [PR #13633](https://github.com/apache/apisix/pull/13633), [PR #12990](https://github.com/apache/apisix [...] + +### Configuration, discovery, and secrets + +Configuration updates and discovery now recover more predictably: + +- A transient DNS failure no longer leaves an upstream returning 503 after the same address becomes resolvable again. Consul skips one malformed node without discarding the remaining service nodes, and Stream Nacos discovery receives its required shared dictionary. See [PR #13137](https://github.com/apache/apisix/pull/13137), [PR #13513](https://github.com/apache/apisix/pull/13513), and [PR #13541](https://github.com/apache/apisix/pull/13541). +- Service hosts are normalized case-insensitively, xRPC schemas initialize when Stream routing needs them, and PROXY protocol listeners can bind IPv6 when IPv6 is enabled. See [PR #13781](https://github.com/apache/apisix/pull/13781), [PR #13515](https://github.com/apache/apisix/pull/13515), and [PR #12859](https://github.com/apache/apisix/pull/12859). +- Full etcd reloads retain the previous valid value when new data is invalid, watch timeouts no longer skip revisions, and unchanged items are reused to avoid unnecessary router rebuilds. See [PR #13717](https://github.com/apache/apisix/pull/13717) and [PR #13721](https://github.com/apache/apisix/pull/13721). + +Environment and secret handling also receives several corrections: + +- Exact-key environment lookup prevents prefix collisions, config-key substitution removes the unresolved key, and `nginx_config.envs` safely quotes values containing spaces. See [PR #13595](https://github.com/apache/apisix/pull/13595), [PR #12885](https://github.com/apache/apisix/pull/12885), and [PR #13713](https://github.com/apache/apisix/pull/13713). +- Secret cache entries invalidate when `/secrets` changes, and unresolved references now produce a field-specific error instead of failing silently. See [PR #13668](https://github.com/apache/apisix/pull/13668) and [PR #13737](https://github.com/apache/apisix/pull/13737). +- Consumer authentication fails closed when a secret reference remains unresolved. Stream TLS and referenced upstream SSL objects now initialize and resolve environment- or secret-backed certificate material correctly. See [PR #13667](https://github.com/apache/apisix/pull/13667), [PR #12935](https://github.com/apache/apisix/pull/12935), and [PR #13062](https://github.com/apache/apisix/pull/13062). + +Plugin state survives Consumer Route merges, and parent lookup now supports every plugin-bearing resource type. See [PR #13757](https://github.com/apache/apisix/pull/13757) and [PR #13663](https://github.com/apache/apisix/pull/13663). + +## Other Updates + +The following performance, refactoring, and maintenance changes reduce runtime overhead and simplify internal behavior without introducing new user-facing capabilities. + +- Reduce hot-path work by caching the filtered global-rule plugin set across phases, skipping Zipkin tag construction for unsampled requests, and reusing one Datadog UDP socket per batch. See [PR #13779](https://github.com/apache/apisix/pull/13779), [PR #13656](https://github.com/apache/apisix/pull/13656), and [PR #13653](https://github.com/apache/apisix/pull/13653). +- Remove the unused `clean_handlers` mechanism, separate generic data encryption from SSL-specific code, and remove the redundant CAS raw-cookie fallback. See [PR #13761](https://github.com/apache/apisix/pull/13761), [PR #13564](https://github.com/apache/apisix/pull/13564), and [PR #13635](https://github.com/apache/apisix/pull/13635). +- Silence expected metadata warnings for disabled or cross-subsystem plugins and standardize field-level schema documentation on `description`. See [PR #13514](https://github.com/apache/apisix/pull/13514) and [PR #13547](https://github.com/apache/apisix/pull/13547). + +## Changelog + +For the complete list of changes in this release, see the [3.18.0 changelog](https://github.com/apache/apisix/blob/master/CHANGELOG.md#3180). diff --git a/blog/zh/blog/2026/08/24/release-apache-apisix-3.18.0.md b/blog/zh/blog/2026/08/24/release-apache-apisix-3.18.0.md new file mode 100644 index 00000000000..a70670c704b --- /dev/null +++ b/blog/zh/blog/2026/08/24/release-apache-apisix-3.18.0.md @@ -0,0 +1,568 @@ +--- +title: "Apache APISIX 3.18.0 正式发布" +authors: + - name: "Abhishek Choudhary" + title: "Author" + url: "https://github.com/shreemaan-abhishek"; + image_url: "https://github.com/shreemaan-abhishek.png"; + - name: "Traky Deng" + title: "Technical Writer" + url: "https://github.com/kayx23"; + image_url: "https://github.com/kayx23.png"; +keywords: + - Apache APISIX + - API Gateway + - API Management Platform + - New Release + - Cloud Native +description: Apache APISIX 3.18.0 版本于 2026 年 8 月 24 日发布。该版本新增 AI 响应缓存、语义模型路由、安全插件、L4 增强与可观测性能力，并包含需要注意的升级变更。 +tags: [Community] +--- + +<!-- TODO: 正式发布后替换 2026 年 8 月 24 日这一占位日期。 --> + +我们很高兴地宣布 Apache APISIX 3.18.0 正式发布。该版本带来了新的 AI Gateway 能力、更严格的安全默认值、L4 代理增强、可观测性改进，以及覆盖网关各模块的可靠性修复。 + +<!--truncate--> + +本版本新增了 LLM 精确、语义与流式响应缓存、语义模型路由、Lakera Guard 集成、高级 LDAP 身份验证插件、更丰富的 Prometheus 指标，以及多项流代理、健康检查、日志和加密能力。 + +该版本也包含不向后兼容的变更。升级前请阅读以下迁移说明。 + +## 重大变更 + +以下变更会影响现有行为、默认值、配置或可观测性约定。请根据每项变更下的升级计划确认部署是否受影响，并在发布前完成必要调整。 + +### 调试插件报告包含阶段与执行顺序 + +`Apisix-Plugins` 响应头不再返回去重后的插件名称列表，而是按执行顺序返回 `plugin-name#phase`。依赖该响应头的解析工具需要相应更新。 + +**升级计划：** 搜索仪表盘、测试和调试工具中对 `Apisix-Plugins` 的使用。更新解析逻辑，使其接受同一插件出现在多个阶段，并保留返回的执行顺序。 + +更多信息，请参阅 [PR #13710](https://github.com/apache/apisix/pull/13710)。 + +### 默认限制请求与响应缓冲大小 + +需要缓冲请求体或响应体的插件现在默认使用 64 MiB 上限。超出限制的请求体可能被拒绝；超出限制的响应则会根据插件行为被截断或直接转发而不缓存。若业务需要更大的报文，请配置 `max_req_body_size` 或 `max_resp_body_size`。 + +**升级计划：** 找出确实需要处理 64 MiB 以上报文的路由，在升级前为相关插件设置明确上限，并分别验证超大请求的拒绝行为和响应截断行为。 + +更多信息，请参阅 [PR #13705](https://github.com/apache/apisix/pull/13705)。 + +### 日志积压默认丢弃超额条目 + +使用批处理器的日志插件现在默认将 `max_pending_entries` 设为 `8192`。当日志后端无法及时处理时，超出限制的新条目会被丢弃，以保护工作进程的内存。调高该值前应评估日志体大小与可用内存。 + +**升级计划：** 检查日志吞吐量、`batch_max_size`，以及是否记录请求体或响应体。为丢弃日志配置告警，并根据每个工作进程的内存预算设置 `max_pending_entries`。 + +更多信息，请参阅 [PR #13826](https://github.com/apache/apisix/pull/13826)。 + +### AWS 内容审核改为审核解码后的 AI 内容 + +`ai-aws-content-moderation` 现在运行在 `ai-proxy` 或 `ai-proxy-multi` 之后，审核协议解码后的提示词，并返回与提供商兼容的拒绝响应。该插件现在依赖 AI 代理上下文，优先级从 `1050` 调整为 `1031`，默认拒绝状态码改为 `200`。 + +**升级计划：** 确保使用该插件的每条路由同时启用了 `ai-proxy` 或 `ai-proxy-multi`。如果客户端仍应接收 HTTP 错误，请显式设置 `deny_code`，不要依赖新的默认值。 + +更多信息，请参阅 [PR #13647](https://github.com/apache/apisix/pull/13647)。 + +### 阿里云请求审核默认仅检查最新用户轮次 + +`ai-aliyun-content-moderation` 默认只审核最新用户轮次，不再审核整个对话历史中的所有角色。如需保留原有范围，请设置 `request_check_mode: all` 并配置 `request_check_roles`。 + +**升级计划：** 明确审核范围是最新用户轮次还是完整对话，并显式固定 `request_check_mode` 与 `request_check_roles`，不要继续依赖默认值。 + +更多信息，请参阅 [PR #13598](https://github.com/apache/apisix/pull/13598)。 + +### SLS 日志插件默认验证 TLS 证书 + +`sls-logger` 的 `ssl_verify` 现在默认为 `true`，并发送 SNI。自定义或自签名日志端点必须使用受信任证书，或显式设置 `ssl_verify: false`。 + +**升级计划：** 使用 APISIX 信任库测试所有 SLS 端点的 TLS 握手。安装正确的 CA 与主机名匹配证书；仅将 `ssl_verify: false` 作为明确且临时的例外。 + +更多信息，请参阅 [PR #13785](https://github.com/apache/apisix/pull/13785)。 + +### OpenID Connect 验证失败时拒绝请求 + +`openid-connect` 现在会在无法确定受信任签发者时拒绝令牌；`claim_validator.audience.match_with_client_id` 会隐式要求 audience 声明；授权码会话也会执行 `required_scopes`。请检查使用不透明访问令牌或缺少 scope 声明的身份提供商。 + +**升级计划：** 使用真实身份提供商测试 Bearer Token 与浏览器会话流程。若 Discovery 文档可能不可用，请配置 `claim_validator.issuer.valid_issuers`，并确认身份提供商会在可读取的声明中返回所有必需 scope。 + +更多信息，请参阅 [PR #13829](https://github.com/apache/apisix/pull/13829)。 + +### 拒绝重复的 Consumer 身份验证键 + +Admin API 现在会拒绝 `key-auth`、`basic-auth`、`jwt-auth`、`hmac-auth` 与 LDAP 身份验证中跨 Consumer 或凭证重复的查找键。更新现有歧义配置前，应先确保这些值唯一。 + +**升级计划：** 上线前审计现有 Consumer 与凭证中的重复身份验证键，并先解决冲突，避免后续 Admin API 更新被拒绝。 + +更多信息，请参阅 [PR #13529](https://github.com/apache/apisix/pull/13529)。 + +### 转发请求头处理行为变更 + +`$var_x_forwarded_proto` 已移除，`$var_x_forwarded_host` 与 `$var_x_forwarded_port` 不再可由 Lua 写入。插件应使用 `core.request.set_header` 修改发往上游的转发请求头。受信任对端未提供 `X-Forwarded-Host` 或 `X-Forwarded-Port` 时，现在会使用 APISIX 观测到的值；日志负载也会包含清洗后的转发请求头。 + +**升级计划：** 搜索自定义插件、NGINX 片段和日志格式中对三个 `$var_x_forwarded_*` 变量的使用。将 Lua 赋值改为 `core.request.set_header`，并更新采用固定字段结构的日志消费者。 + +更多信息，请参阅 [PR #13803](https://github.com/apache/apisix/pull/13803)。 + +### AI 代理默认使用 FFI HTTP 客户端 + +`ai-proxy`、`ai-proxy-multi` 与 `ai-request-rewrite` 现在默认使用 `ngx_http_ffi_client`。本版本固定的 APISIX Runtime 已包含该模块。使用不含此模块的旧版或自定义 Runtime 时，必须升级 Runtime，或设置 `plugin_attr.ai-proxy.http_client: lua-resty-http`。 + +**升级计划：** 在目标镜像中运行 `nginx -V`，确认包含 `ngx_http_ffi_client`。应随 APISIX 一起升级 Runtime；如果暂时无法升级，请在承载 AI 流量前通过 `config.yaml` 显式切换回 `lua-resty-http`。 + +更多信息，请参阅 [PR #13778](https://github.com/apache/apisix/pull/13778)。 + +### 限制大型 `post_arg.*` 路由匹配读取 + +用于 `post_arg.*` 路由条件的 JSON 和 multipart 请求体现在默认限制为 64 MiB。更大的请求体将无法命中该条件，并可能返回 404。如需保留无限制读取，请调高 `apisix.max_post_args_readable_size`，或将其设为 `0`。 + +**升级计划：** 找出使用 `post_arg.*` 的路由，确认预期最大请求体，并显式设置 `apisix.max_post_args_readable_size`。升级测试中应包含一个超出限制的请求。 + +更多信息，请参阅 [PR #13601](https://github.com/apache/apisix/pull/13601)。 + +### 现有 LDAP TLS 验证开始真正生效 + +LDAP 客户端依赖升级后，`ldap-auth.tls_verify: true` 会真正执行证书验证，而不再是无效配置。使用自签名证书或证书主机名不匹配的部署，需要安装受信任且匹配的证书，或在适当场景显式关闭验证。 + +**升级计划：** 根据 `ldap_uri` 验证 LDAP 证书链和 SAN，在部署前配置受信任 CA，并测试实际使用的 LDAPS 与 StartTLS 路径。 + +更多信息，请参阅 [PR #13762](https://github.com/apache/apisix/pull/13762)。 + +### LDAP Consumer DN 使用 RFC 4514 转义 + +`ldap-auth` 现在使用 LDAP 客户端返回的已转义 bind DN 查找 Consumer。用户名包含逗号、加号等特殊字符时，Consumer 的 `user_dn` 必须使用 RFC 4514 转义形式。 + +**升级计划：** 找出包含 DN 特殊字符的 LDAP 用户名，并在升级前将对应 Consumer 的 `user_dn` 改为 RFC 4514 转义形式。 + +更多信息，请参阅 [PR #13805](https://github.com/apache/apisix/pull/13805)。 + +### Prometheus LLM 延迟指标新增 `type` 标签 + +`apisix_llm_latency` 现在使用 `type="total"` 与 `type="ttft"` 区分总延迟和首个 Token 延迟（TTFT）；流式请求会同时记录两类样本。若需保持原有总延迟语义，请更新仪表盘、告警和记录规则，添加 `type="total"` 选择条件。 + +**升级计划：** 在抓取新指标前更新 PromQL 查询和记录规则。由于每个流式请求现在会产生总延迟与 TTFT 两类观测，还应检查预期的时间序列数量。 + +更多信息，请参阅 [PR #13487](https://github.com/apache/apisix/pull/13487)。 + +### Consumer 级 AI 插件默认跳过无法识别的流量 + +新增的 `fail_mode` 默认值为 `skip`。此前在阿里云审核中返回 500、或在 AWS 审核中按原始请求体处理的非 AI 流量，现在会未经审核直接放行。如果所有请求都必须可识别并接受审核，请设置 `fail_mode: error`。 + +**升级计划：** 将路由明确划分为混合流量或仅 AI 流量。对于无法识别的请求绝不能绕过审核的路由，显式设置 `fail_mode: error`，并测试非 JSON 与非 AI 请求。 + +更多信息，请参阅 [PR #13489](https://github.com/apache/apisix/pull/13489)。 + +## 新功能 + +APISIX 3.18.0 扩展了 AI Gateway、身份验证、L4 代理、可观测性、限流、日志和流量管理能力。以下内容将分别介绍各项主要功能的适用场景、工作方式和关键配置选择。 + +### 使用 `ai-cache` 缓存 LLM 响应 + +新的 `ai-cache` 插件可降低客服助手、文档问答、翻译和基于提示词的自动化等包含大量重复请求的 LLM 工作负载的延迟与上游 Token 成本。它提供三类互补能力： + +- 使用 Redis 存储的精确 L1 缓存，用于请求语义完全一致的场景。 +- 可选的语义 L2 缓存，使用 OpenAI 或 Azure OpenAI 生成嵌入向量，并通过 RediSearch 进行余弦相似度检索。 +- 对受支持流式提供商进行完整 SSE 捕获与重放，JSON 与 SSE 条目分别存储。 + +缓存键包含客户端协议、实际模型和提供商、决定响应的参数，以及最终选中的 AI 实例；还可以按路由、Consumer 或指定 NGINX 变量进行隔离。Redis 或嵌入向量生成失败时，请求会按普通 MISS 继续转发，因此缓存不会成为可用性依赖。 + +以下示例同时启用精确缓存和语义缓存。第一个请求会填充两层缓存；后续改写后的相似问题在超过阈值时可由 L2 直接返回。 + +```json +{ + "ai-cache": { + "redis_host": "127.0.0.1", + "redis_port": 6379, + "layers": ["exact", "semantic"], + "semantic": { + "similarity_threshold": 0.9, + "embedding": { + "openai": { + "model": "text-embedding-3-small", + "api_key": "$env://OPENAI_API_KEY" + } + }, + "vector_search": { + "redis": {} + } + } + } +} +``` + +更多信息，请参阅 [PR #13578](https://github.com/apache/apisix/pull/13578)、[PR #13632](https://github.com/apache/apisix/pull/13632) 和 [PR #13644](https://github.com/apache/apisix/pull/13644)。 + +### 根据语义将提示词路由到不同模型 + +`ai-proxy-multi` 新增 `semantic` 负载均衡算法，适用于多个模型能力、成本和延迟并不相同的部署。一个统一端点可以将编程问题路由到能力更强的模型，将翻译请求路由到低成本模型，并将无法归类的流量交给通用回退实例，而无需向客户端暴露提供商拓扑。 + +APISIX 会为每个实例的自然语言示例生成一次嵌入向量，并按配置版本缓存参考向量。每个请求只需生成一次提示词嵌入向量，随后在进程内完成余弦相似度比较，不需要向量数据库。如果嵌入向量生成失败或没有分数超过阈值，请求会交给配置的回退实例。 + +```json +{ + "ai-proxy-multi": { + "balancer": { + "algorithm": "semantic", + "threshold": 0.6 + }, + "semantic_opts": { + "fallback": "general", + "embeddings": { + "provider": "openai", + "model": "text-embedding-3-small", + "auth": { + "header": { + "Authorization": "Bearer $env://EMBEDDING_API_KEY" + } + } + } + }, + "instances": [ + { + "name": "code", + "provider": "openai", + "weight": 1, + "auth": {"header": {"Authorization": "Bearer $env://OPENAI_API_KEY"}}, + "options": {"model": "gpt-4o"}, + "override": {"endpoint": "https://api.openai.com/v1/chat/completions"}, + "examples": ["debug this stack trace", "write a Python function"] + }, + { + "name": "general", + "provider": "openai", + "weight": 1, + "auth": {"header": {"Authorization": "Bearer $env://OPENAI_API_KEY"}}, + "options": {"model": "gpt-4o-mini"}, + "override": {"endpoint": "https://api.openai.com/v1/chat/completions"}, + "examples": ["answer a general question"] + } + ] + } +} +``` + +语义选择是尽力而为的路由能力，并非内容安全控制；实例选定后目前也不提供基于健康状态的重试。 + +更多信息，请参阅 [PR #13676](https://github.com/apache/apisix/pull/13676)。 + +### 使用 Lakera Guard 保护 LLM 请求与响应 + +新的 `ai-lakera-guard` 插件在网关层与 Lakera Guard v2 API 集成，可检测提示词注入、敏感信息、策略违规和恶意链接。它可以扫描请求、响应或双向流量，应用无需分别实现同一套安全集成。 + +在 `block` 模式下，被标记的流量会被替换为与提供商兼容的拒绝响应。流式输出会先缓冲再释放，避免有风险的输出内容到达客户端。在 `alert` 模式下，运维人员可以先观察判定结果，再启用拦截。Lakera API 故障由独立的 `fail_open` 控制，使可用性与强制执行之间的选择保持明确。 + +```json +{ + "ai-lakera-guard": { + "api_key": "$env://LAKERA_API_KEY", + "direction": "both", + "action": "alert", + "fail_open": true, + "reveal_failure_categories": false + } +} +``` + +建议先使用 `action: alert` 和 `fail_open: true` 上线，观察检测结果与误报，再将选定路由切换为 `block`。若需要严格的响应侧强制执行，请使用 `fail_open: false`；此时流式响应会被缓冲，扫描服务不可用时也不会泄漏未经检查的输出。 + +更多信息，请参阅 [PR #13570](https://github.com/apache/apisix/pull/13570) 和 [PR #13606](https://github.com/apache/apisix/pull/13606)。 + +### 扩展 AWS 与阿里云 AI 内容审核能力 + +AWS 审核除了请求外，现在也可以检查非流式和流式响应。`realtime` 模式会在响应流动时分批检查，并可立即替换后续内容；`final_packet` 模式会对完整输出评分并记录风险等级。长内容会在 UTF-8 字符边界处拆分，并按 AWS Comprehend 的分段限制批量发送。 + +AWS 与阿里云插件都可以选择请求侧审核角色。`user`、`tool` 和 `assistant` 内容可以按最新轮次或完整历史处理；选中的 system 内容则会在每个请求中检查。OpenAI 的 `developer` 角色会作为 system 级内容处理。 + +```json +{ + "ai-aws-content-moderation": { + "comprehend": { + "access_key_id": "$env://AWS_ACCESS_KEY_ID", + "secret_access_key": "$env://AWS_SECRET_ACCESS_KEY", + "region": "us-east-1" + }, + "request_check_roles": ["user", "tool", "system"], + "request_check_mode": "last", + "check_response": true, + "stream_check_mode": "realtime" + } +} +``` + +这些配置可帮助 Agent 和 MCP 工作负载审核工具输出及可能被污染的系统指令，而无需在每个请求中把整个对话历史重复发送给审核提供商。 + +更多信息，请参阅 [PR #13735](https://github.com/apache/apisix/pull/13735)、[PR #13773](https://github.com/apache/apisix/pull/13773)、[PR #13767](https://github.com/apache/apisix/pull/13767)、[PR #13646](https://github.com/apache/apisix/pull/13646) 和 [PR #13780](https://github.com/apache/apisix/pull/13780)。 + +### 新增高级 LDAP 身份验证 + +新的 `ldap-auth-advanced` 插件适用于无法从用户名直接构造 bind DN 的目录。插件会先搜索用户，再使用解析出的 DN 进行绑定，覆盖通过 `sAMAccountName` 等属性进行身份验证的常见 Active Directory 部署。 + +搜索可以使用服务账号或匿名绑定。插件支持 LDAPS、StartTLS、证书验证、连接池、LDAP 过滤器转义、受限搜索，以及通过 `user_dn` 关联 Consumer。身份验证失败返回 401，而目录服务连接或配置故障仍会明确返回服务端错误。 + +```json +{ + "ldap-auth-advanced": { + "ldap_uri": "ldap.example.com:636", + "use_ldaps": true, + "ssl_verify": true, + "base_dn": "ou=users,dc=example,dc=org", + "attribute": "sAMAccountName", + "bind_dn": "cn=apisix,ou=services,dc=example,dc=org", + "ldap_password": "$env://LDAP_BIND_PASSWORD" + } +} +``` + +默认情况下，成功认证的身份必须映射到 APISIX Consumer。如果目录身份无需 Consumer 级策略即可通过认证，应明确配置 `consumer_required`。 + +更多信息，请参阅 [PR #13762](https://github.com/apache/apisix/pull/13762)。 + +### 增强 Stream 与 L4 代理 + +Stream 监听端口现在可以针对每个 TCP 端口分别启用或关闭入站和出站 PROXY 协议，不再受限于原有的全局开关。一个 APISIX 实例因此可以同时服务具有不同协议要求的客户端与上游。 + +当 APISIX 位于受信任的负载均衡器之后时，`nginx_config.stream.real_ip_from` 可以信任并使用入站 PROXY 头中的客户端地址。该地址随后可供 Stream 插件使用，并可重新写入发往上游的 PROXY 头。L4 TLS 上游也可以接收来自内联配置或 `tls.client_cert_id` 的客户端证书。 + +```yaml +apisix: + proxy_mode: http&stream + stream_proxy: + tcp: + - addr: 9100 + proxy_protocol: true + proxy_protocol_to_upstream: true +nginx_config: + stream: + real_ip_from: + - 10.0.0.0/8 +``` + +Prometheus 还提供活跃连接 Gauge 指标、终止状态，以及按监听地址统计的下游/上游入站与出站带宽。这些指标需要本版本包含的 APISIX Runtime；在旧版 Runtime 上会自动停用相关采集，不影响网关继续运行。 + +更多信息，请参阅 [PR #13561](https://github.com/apache/apisix/pull/13561)、[PR #13700](https://github.com/apache/apisix/pull/13700)、[PR #13596](https://github.com/apache/apisix/pull/13596) 和 [PR #13796](https://github.com/apache/apisix/pull/13796)。 + +### 扩展 Prometheus 控制与 AI 指标 + +Prometheus 新增 AI 缓存命中、未命中和绕过计数器、嵌入向量生成延迟直方图、LLM 提示词与补全 Token 分布，以及总延迟和 TTFT 的独立观测。借助这些指标，可以直接从网关衡量缓存效果、嵌入向量生成开销、提示词大小分位数和流式响应速度。 + +高基数部署可以通过插件元数据折叠指定内置标签的值，而不改变指标的标签结构。客户端提供的模型标签值也会限制为 128 字节。依赖升级修复了重复时间序列、指标字典满时的 100% CPU 忙循环，以及过期条目无法回收的问题。 + +```json +{ + "disabled_labels": { + "http_status": ["node", "consumer"], + "http_latency": ["node"], + "llm_prompt_tokens": ["request_llm_model"] + } +} +``` + +通过 `/apisix/admin/plugin_metadata/prometheus` 应用 `disabled_labels`。HTTP 状态码和延迟类型等结构性标签不能被禁用，因为折叠这些标签会合并语义不同的测量值。 + +更多信息，请参阅 [PR #13659](https://github.com/apache/apisix/pull/13659)、[PR #13202](https://github.com/apache/apisix/pull/13202)、[PR #13637](https://github.com/apache/apisix/pull/13637)、[PR #13602](https://github.com/apache/apisix/pull/13602)、[PR #13708](https://github.com/apache/apisix/pull/13708) 和 [PR #13754](https://github.com/apache/apisix/pull/13754)。 + +### 通过 Redis 共享限流计数器 + +`ai-rate-limiting` 现在可以将 Token 用量计数器存储在 Redis、Redis Cluster 或 Redis Sentinel 中，使多个 APISIX 节点共同执行一个配额。现有 `local` 策略仍是默认值，并继续为每个网关节点维护独立计数器。 + +`limit-count` 新增三项可独立使用的控制：用于高可用的 Sentinel 后端、平滑窗口边界突发的滑动窗口计数器，以及为高吞吐工作负载批量更新 Redis 的延迟同步。延迟同步以短时间内的全局精度换取更少的网络往返；如果需要每个请求精确写入 Redis，请不要配置 `sync_interval`。 + +```json +{ + "limit-count": { + "count": 5000, + "time_window": 60, + "key": "consumer_name", + "key_type": "var", + "window_type": "sliding", + "policy": "redis-sentinel", + "redis_sentinels": [ + {"host": "10.0.0.1", "port": 26379}, + {"host": "10.0.0.2", "port": 26379} + ], + "redis_master_name": "mymaster", + "sync_interval": 1 + } +} +``` + +本版本还修复了滑动窗口和延迟同步实现中的原子性与配额计算问题，因此采用新模式时应使用完整的 3.18.0 补丁集。 + +更多信息，请参阅 [PR #13670](https://github.com/apache/apisix/pull/13670) 和 [PR #13443](https://github.com/apache/apisix/pull/13443)。 + +### 增强 OpenID Connect 客户端流程 + +`openid-connect` 新增 Pushed Authorization Requests（PAR）、用于令牌端点和 UserInfo 请求的 DPoP 证明生成，以及客户端断言算法与 audience 控制。PAR 与 DPoP 均为可选能力，并使用嵌套配置对象；DPoP 私钥会加密存储。 + +需要原始签名 ID 令牌的应用可以启用 `set_raw_id_token_header`，在授权码会话流程中通过 `X-Raw-ID-Token` 转发。它不同于 `X-ID-Token`：后者包含编码后的已解码声明，而不是身份提供商签名的 JWT。 + +```json +{ + "openid-connect": { + "client_id": "apisix", + "client_secret": "$env://OIDC_CLIENT_SECRET", + "discovery": "https://idp.example.com/.well-known/openid-configuration";, + "redirect_uri": "https://gateway.example.com/callback";, + "par": { + "enabled": true + }, + "set_raw_id_token_header": true, + "session": { + "secret": "$env://OIDC_SESSION_SECRET" + } + } +} +``` + +浏览器流程故障也会得到更友好的恢复。过期回调或 `temporarily_unavailable` 响应可以从原始 URL 重新启动认证，并通过受限重试计数器避免重定向循环。`access_denied` 等明确拒绝结果不会重试。 + +更多信息，请参阅 [PR #13649](https://github.com/apache/apisix/pull/13649)、[PR #13616](https://github.com/apache/apisix/pull/13616)、[PR #13712](https://github.com/apache/apisix/pull/13712) 和 [PR #13825](https://github.com/apache/apisix/pull/13825)。 + +### 增强日志格式并保护存储的凭证 + +日志插件支持 `log_format_extra`，可以在默认结构化日志上覆盖或添加指定字段，而不是替换整条日志。这样可以添加租户、上游或业务上下文，同时保留请求头、响应数据、延迟字段、APISIX 版本与资源标识。 + +```json +{ + "log_format_extra": { + "upstream_host": "$upstream_unresolved_host", + "tenant": "$http_x_tenant_id" + } +} +``` + +Kafka 日志可以连接启用 TLS 的 Broker；当需要 Broker 端消息时间戳时，可以选择 Produce API 版本 `2`。`error-log-logger` 的 Kafka 输出也获得同样的 TLS 能力。 + +凭证存储也得到强化：启用数据加密后，Elasticsearch 与 Loki 自定义请求头、限流插件中的 Redis 密码、Sentinel 密码，以及内联 Stream 上游客户端私钥都会加密存储。可能暴露序列化日志内容或 Kafka SASL 凭证的调试日志已被移除。 + +更多信息，请参阅 [PR #13568](https://github.com/apache/apisix/pull/13568)、[PR #13607](https://github.com/apache/apisix/pull/13607)、[PR #13521](https://github.com/apache/apisix/pull/13521)、[PR #13612](https://github.com/apache/apisix/pull/13612)、[PR #13784](https://github.com/apache/apisix/pull/13784) 和 [PR #13624](https://github.com/apache/apisix/pull/13624)。 + +### 新增路由、健康检查和加密配置 + +APISIX 可以在匹配参数化路由时保留 `%2F` 编码，使 `cat%2Fdog` 等值继续作为一个路径参数，而不是被拆成两个路径段。该全局选项默认关闭，只影响匹配与捕获的参数；后续阶段仍会看到规范化后的 URI。 + +主动健康检查可以发送自定义 HTTP 方法和请求体，适用于无法通过无请求体 GET 进行有效检查的上游，例如要求最小 Chat Completion POST 的 LLM 端点。 + +```json +{ + "checks": { + "active": { + "type": "https", + "http_method": "POST", + "http_path": "/v1/chat/completions", + "http_req_body": "{\"model\":\"health-check\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}" + } + } +} +``` + +数据加密 keyring 现在可以在同一轮换集合中同时使用 16 字节 AES-128 与 32 字节 AES-256 密钥。运维人员可以将新的 AES-256 密钥放在首位，同时保留旧 AES-128 密钥用于解密。Prometheus、服务发现和链路追踪中无法安全淘汰的数据也使用了更大的默认共享字典。 + +更多信息，请参阅 [PR #13626](https://github.com/apache/apisix/pull/13626)、[PR #13726](https://github.com/apache/apisix/pull/13726)、[PR #13756](https://github.com/apache/apisix/pull/13756) 和 [PR #13688](https://github.com/apache/apisix/pull/13688)。 + +## Bug 修复 + +本版本还修复了网关多个核心子系统中的正确性、安全性与可靠性问题。以下内容按受影响的功能领域归类，便于运维人员快速找到与其部署相关的修复。 + +### AI Gateway 正确性与协议兼容性 + +AI 代理现在能够保留更多上游提供商的原始语义，并使重试与前一次尝试相互隔离。请求未重试时，客户端会收到原始 429/5xx 错误体和 Content-Type；发生回退时，每个实例都从未被修改的客户端请求体重新构造请求，避免模型选项在实例之间泄漏。AI 延迟变量在成功和错误响应上也统一使用毫秒。参阅 [PR #13565](https://github.com/apache/apisix/pull/13565)、[PR #13793](https://github.com/apache/apisix/pull/13793) 和 [PR #13711](https://github.com/apache/apisix/pull/13711)。 + +协议转换变得更加可靠和忠实： + +- 上游流在打开内容块前结束时，Anthropic 客户端不再挂起；无效的 `tool_call` 参数也不会丢弃原本可用的响应。参阅 [PR #13583](https://github.com/apache/apisix/pull/13583) 和 [PR #13599](https://github.com/apache/apisix/pull/13599)。 +- Anthropic 工具结果顺序、工具名称映射、推理强度、结构化输出和消息形态现在更符合 OpenAI 兼容上游的预期。参阅 [PR #13674](https://github.com/apache/apisix/pull/13674)。 +- 结构化与多模态消息内容会为文本消费者进行一致展开，同时在精确缓存键中保持区别；包含非文本状态的提示词会绕过语义缓存。参阅 [PR #13634](https://github.com/apache/apisix/pull/13634) 和 [PR #13654](https://github.com/apache/apisix/pull/13654)。 +- 协议转换将一个上游数据块展开为多个客户端事件时，实时审核不再重复计算同一数据块。参阅 [PR #13765](https://github.com/apache/apisix/pull/13765)。 + +`ai-request-rewrite` 的内部请求不再把下游客户端的 `Authorization` 或 `Cookie` 请求头转发到配置的 LLM 端点；透明代理的 `ai-proxy` 路径仍会按文档转发客户端请求头。参阅 [PR #13699](https://github.com/apache/apisix/pull/13699)。 + +### 身份验证与身份安全 + +身份验证插件现在可以干净地拒绝异常输入，并防止客户端控制的身份数据到达上游服务： + +- 异常 JWT 签名返回 401，而不再触发 500；`jwe-decrypt` 在关闭 `strict` 时也会正确允许缺少令牌的请求。参阅 [PR #13518](https://github.com/apache/apisix/pull/13518) 和 [PR #13822](https://github.com/apache/apisix/pull/13822)。 +- `wolf-rbac` 与 `attach-consumer-label` 会在应用受信任身份数据前始终删除客户端传入的身份请求头。参阅 [PR #13696](https://github.com/apache/apisix/pull/13696) 和 [PR #13590](https://github.com/apache/apisix/pull/13590)。 +- `key-auth` 会通过 `multi-auth` 报告真实失败原因，`basic-auth` 会验证 `anonymous_consumer`，`hmac-auth` 也能在要求时可靠移除凭证。参阅 [PR #13693](https://github.com/apache/apisix/pull/13693)、[PR #13682](https://github.com/apache/apisix/pull/13682) 和 [PR #13820](https://github.com/apache/apisix/pull/13820)。 + +CAS 单点登出回调现在会在插件处终止，不再转发到上游；Casdoor 会话会随访问令牌一起过期。`request-id` 的 `nanoid` 算法现在使用 CSPRNG，不再出现重复 ID、异常输出或文件描述符泄漏。参阅 [PR #13610](https://github.com/apache/apisix/pull/13610)、[PR #13500](https://github.com/apache/apisix/pull/13500) 和 [PR #13508](https://github.com/apache/apisix/pull/13508)。 + +### 健康检查与负载均衡 + +一致性哈希环现在与配置的节点和权重保持绑定，并在选择时跳过不健康目标，避免原本落到健康节点的哈希键发生不必要迁移。最少连接负载均衡会在扩缩容时保留实时负载，并正确释放 Stream 连接，因此新加入的空闲节点会优先于已有负载的节点。参阅 [PR #13532](https://github.com/apache/apisix/pull/13532) 和 [PR #13666](https://github.com/apache/apisix/pull/13666)。 + +主动健康检查获得多项可靠性修复： + +- 仅节点变化的上游会原地协调目标，而不是销毁检查器，从而保留健康状态，并避免不健康节点重新接收流量的窗口。参阅 [PR #13629](https://github.com/apache/apisix/pull/13629)。 +- 域名节点使用配置的域名作为 Host 与 TLS SNI，而不是使用解析后的 IP 进行探测。参阅 [PR #13743](https://github.com/apache/apisix/pull/13743)。 +- 所有检查器都会清除过期目标，周期锁会正确释放，AI 上游构造失败也不会中断其他资源的定时任务。参阅 [PR #13627](https://github.com/apache/apisix/pull/13627) 和 [PR #13592](https://github.com/apache/apisix/pull/13592)。 +- `ai-proxy-multi` 会在异步健康检查器建立后刷新服务选择器，并保留健康检查路径已有的查询参数。参阅 [PR #13505](https://github.com/apache/apisix/pull/13505) 和 [PR #13506](https://github.com/apache/apisix/pull/13506)。 + +使用不同引用客户端证书的 HTTPS 上游不再共享同一个 keepalive 连接池。参阅 [PR #13587](https://github.com/apache/apisix/pull/13587)。 + +### 限流 + +滑动窗口现在会在 Redis 后端原子地完成允许/拒绝判断和计数器递增。延迟同步会正确计算上一窗口的加权贡献，避免每个窗口边界都出现一份新的完整配额。参阅 [PR #13574](https://github.com/apache/apisix/pull/13574) 和 [PR #13704](https://github.com/apache/apisix/pull/13704)。 + +通过变量解析出的 `count` 与 `time_window` 现在必须是正的安全整数。客户端控制的异常值会被拒绝，而不再使限流器崩溃或静默跳过规则。参阅 [PR #13573](https://github.com/apache/apisix/pull/13573)。 + +`workflow`、Consumer 和 Redis 后端之间的计数器与连接隔离得到修复： + +- 每个 `limit-conn` `workflow` 动作使用独立计数器；Consumer 级计数器会在该 Consumer 的所有路由之间共享，而不再按路由拆分。参阅 [PR #13591](https://github.com/apache/apisix/pull/13591) 和 [PR #13600](https://github.com/apache/apisix/pull/13600)。 +- Redis 与 Sentinel keepalive 连接池会按数据库、凭证和 TLS 设置隔离，避免计数器落入另一份配置的连接上下文。参阅 [PR #13516](https://github.com/apache/apisix/pull/13516) 和 [PR #13553](https://github.com/apache/apisix/pull/13553)。 +- Redis 策略 schema 会先复制再扩展；Redis Cluster 脚本缓存未命中也不会再触发不必要的拓扑刷新。参阅 [PR #13555](https://github.com/apache/apisix/pull/13555) 和 [PR #13579](https://github.com/apache/apisix/pull/13579)。 + +### 缓存与请求处理 + +内存 `proxy-cache` 策略现在使用具有唯一映射关系的存储键格式，使构造请求无法读取或覆盖其他请求的 Vary 变体。布局版本也已升级，因此升级前的内存缓存条目在过期前将无法命中。`graphql-proxy-cache` 的 PURGE 也会删除索引中的所有 Vary 变体，而不再只删除旧的基础条目。参阅 [PR #13831](https://github.com/apache/apisix/pull/13831) 和 [PR #13523](https://github.com/apache/apisix/pull/13523)。 + +缓冲后的请求体现在会在内部 HTTP 调用前重新生成正确的消息边界信息。`forward-auth`、AWS Lambda、Azure Functions 与 OpenFunction 会移除已经不再适用的客户端 `Transfer-Encoding` 和 `Content-Length`，由 HTTP 客户端根据实际缓冲请求体重新生成 `Content-Length`。参阅 [PR #13642](https://github.com/apache/apisix/pull/13642) 和 [PR #13798](https://github.com/apache/apisix/pull/13798)。 + +其他数据处理修复包括： + +- GraphQL 片段深度计算从指数复杂度降为线性复杂度，并会显式拒绝片段循环。参阅 [PR #13809](https://github.com/apache/apisix/pull/13809)。 +- XML 命名空间移除不再在遍历期间修改同一张表，从而可靠保留命名空间键与重复元素。参阅 [PR #13522](https://github.com/apache/apisix/pull/13522)。 +- AWS Lambda SigV4 会对实际发送的同一份规范化、编码、多值查询字符串进行签名。参阅 [PR #13520](https://github.com/apache/apisix/pull/13520)。 +- 空的 repeated protobuf 字段会编码为 JSON 数组；移除 JSON 数组元素后也会压紧数组，不再留下空洞。参阅 [PR #13678](https://github.com/apache/apisix/pull/13678) 和 [PR #13818](https://github.com/apache/apisix/pull/13818)。 +- 重复的 `Content-Type` 请求头会被干净拒绝，`$upstream_uri` 中的控制字符会被转义，不安全 URI 重写也会保留客户端查询字符串。参阅 [PR #13691](https://github.com/apache/apisix/pull/13691)、[PR #13787](https://github.com/apache/apisix/pull/13787) 和 [PR #12843](https://github.com/apache/apisix/pull/12843)。 + +### 日志与可观测性 + +日志负载和凭证更不容易泄漏或跨配置串用： + +- Elasticsearch、Kafka、RocketMQ、SLS 与 Syslog 不再把序列化日志负载写入错误日志；Kafka SASL 凭证也会在错误路径中脱敏。参阅 [PR #13502](https://github.com/apache/apisix/pull/13502) 和 [PR #13786](https://github.com/apache/apisix/pull/13786)。 +- Loki 会按请求解析动态标签，并按解析后的标签集合对批次中的条目分组，避免一个服务的标签泄漏到另一个服务。参阅 [PR #13562](https://github.com/apache/apisix/pull/13562)。 +- Loggly 会将每个批处理器绑定到自己的配置，避免一条路由的令牌或标签被另一条路由的日志批次使用。参阅 [PR #13648](https://github.com/apache/apisix/pull/13648)。 +- 合并后的 DogStatsD 数据包超过 Agent 默认接收缓冲区时，Datadog 会回退为逐指标数据报。参阅 [PR #13665](https://github.com/apache/apisix/pull/13665)。 +- 部分日志文件轮转成功时仍会发送 reopen 信号。参阅 [PR #13375](https://github.com/apache/apisix/pull/13375)。 + +OpenTelemetry Tracer 会在元数据变更后重建，核心 Span 注入也会使用独立缓存条目，从而保留 always-on 采样行为。无效、重复或非十六进制的 `X-Request-Id` 会回退到自动生成的 Trace ID，而不再导致导出崩溃；元数据值类型也会被正确验证。参阅 [PR #13618](https://github.com/apache/apisix/pull/13618)、[PR #13633](https://github.com/apache/apisix/pull/13633)、[PR #12990](https://github.com/apache/apisix/pull/12990) 和 [PR #13690](https://github.com/apache/apisix/pull/13690)。 + +### 配置、服务发现与 Secret + +配置更新与服务发现现在能够更可预测地恢复： + +- 短暂 DNS 故障后，相同地址恢复可解析时，上游不再持续返回 503。Consul 会跳过单个异常节点，而不丢弃服务中的其他节点；Stream 子系统中的 Nacos 服务发现也获得所需的共享字典。参阅 [PR #13137](https://github.com/apache/apisix/pull/13137)、[PR #13513](https://github.com/apache/apisix/pull/13513) 和 [PR #13541](https://github.com/apache/apisix/pull/13541)。 +- Service 中的 Host 会按大小写不敏感方式规范化；Stream 路由需要 xRPC schema 时会正确初始化；启用 IPv6 后，PROXY 协议监听器也可以绑定 IPv6。参阅 [PR #13781](https://github.com/apache/apisix/pull/13781)、[PR #13515](https://github.com/apache/apisix/pull/13515) 和 [PR #12859](https://github.com/apache/apisix/pull/12859)。 +- etcd 全量重载遇到新数据无效时会保留之前的有效值；Watch 超时不再跳过 Revision；未变化条目会被复用以避免不必要的路由器重建。参阅 [PR #13717](https://github.com/apache/apisix/pull/13717) 和 [PR #13721](https://github.com/apache/apisix/pull/13721)。 + +环境变量与 Secret 处理也获得多项修复： + +- 精确键环境变量查找可避免前缀冲突；配置键替换会移除未解析旧键；`nginx_config.envs` 也会安全引用包含空格的值。参阅 [PR #13595](https://github.com/apache/apisix/pull/13595)、[PR #12885](https://github.com/apache/apisix/pull/12885) 和 [PR #13713](https://github.com/apache/apisix/pull/13713)。 +- `/secrets` 变化时 Secret 缓存会失效；未解析引用会生成包含字段信息的错误，而不再静默失败。参阅 [PR #13668](https://github.com/apache/apisix/pull/13668) 和 [PR #13737](https://github.com/apache/apisix/pull/13737)。 +- Secret 引用仍未解析时，Consumer 身份验证会拒绝请求，而不再使用引用字符串继续认证。Stream TLS 与引用的上游 SSL 对象也会正确初始化和解析由环境变量或 Secret 提供的证书材料。参阅 [PR #13667](https://github.com/apache/apisix/pull/13667)、[PR #12935](https://github.com/apache/apisix/pull/12935) 和 [PR #13062](https://github.com/apache/apisix/pull/13062)。 + +合并 Consumer 与 Route 配置后，插件状态会被保留；父资源查找也支持所有可携带插件的资源类型。参阅 [PR #13757](https://github.com/apache/apisix/pull/13757) 和 [PR #13663](https://github.com/apache/apisix/pull/13663)。 + +## 其他更新 + +以下性能优化、代码重构与维护性变更减少了运行时开销，并简化了内部行为，但不会引入新的用户功能。 + +- 通过跨阶段缓存全局规则插件集合、跳过未采样请求的 Zipkin 标签构建，以及在一个 Datadog 批次内复用 UDP 套接字，减少热路径工作。参阅 [PR #13779](https://github.com/apache/apisix/pull/13779)、[PR #13656](https://github.com/apache/apisix/pull/13656) 和 [PR #13653](https://github.com/apache/apisix/pull/13653)。 +- 移除未使用的 `clean_handlers` 机制，将通用数据加密与 SSL 专用代码分离，并移除多余的 CAS 原始 Cookie 回退。参阅 [PR #13761](https://github.com/apache/apisix/pull/13761)、[PR #13564](https://github.com/apache/apisix/pull/13564) 和 [PR #13635](https://github.com/apache/apisix/pull/13635)。 +- 对已禁用或跨子系统插件的元数据不再输出预期警告，并统一使用 `description` 记录字段级 schema 文档。参阅 [PR #13514](https://github.com/apache/apisix/pull/13514) 和 [PR #13547](https://github.com/apache/apisix/pull/13547)。 + +## 更新日志 + +此版本的完整更新列表，请参阅 [3.18.0 CHANGELOG](https://github.com/apache/apisix/blob/master/CHANGELOG.md#3180)。
![https://github.com/shreemaan-abhishek.png"](https://github.com/shreemaan-abhishek.png"){kind=link}
![https://github.com/kayx23.png"](https://github.com/kayx23.png"){kind=link}