kayx23 · Oct 29, 2026 · Oct 28, 2026
diff --git a/docs/en/latest/router-radixtree.md b/docs/en/latest/router-radixtree.md
@@ -23,7 +23,7 @@ Title: Router Radixtree
 
 ### What is Libradixtree?
 
-[Libradixtree](https://github.com/api7/lua-resty-radixtree) is an adaptive radix tree that is implemented in Lua for OpenResty and it is based on FFI for [rax](https://github.com/antirez/rax). APISIX uses libradixtree as a route dispatching library.
+Libradixtree is an adaptive radix tree implemented in Lua for OpenResty and based on FFI for [rax](https://github.com/antirez/rax). APISIX uses libradixtree as a route dispatching library.
 
 ### How to use Libradixtree in APISIX?
 
@@ -194,18 +194,20 @@ route like
 
 will match both `/blog/dog` and `/blog/cat`.
 
-For more details, see https://github.com/api7/lua-resty-radixtree/#parameters-in-path.
+Named parameters match one path segment. A trailing wildcard parameter matches the remaining path segments.
 
 ### How to filter route by Nginx built-in variable?
 
-Nginx provides a variety of built-in variables that can be used to filter routes based on certain criteria. Here is an example of how to filter routes by Nginx built-in variables:
+The Route `vars` field accepts APISIX expressions. Each basic condition uses the form `[variable, operator, value]`. Conditions in the outer array are combined with AND by default. Supported operators include equality and inequality comparisons, numeric comparisons, regular-expression matching, membership checks, array containment checks, and IP address matching.
+
+Nginx provides built-in variables that can be used in these expressions. The following example filters a route by request variables:
 
 ```shell
 $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
 {
     "uri": "/index.html",
     "vars": [
-        ["http_host", "==", "iresty.com"],
+        ["http_host", "==", "example.com"],
         ["cookie_device_id", "==", "a66f0cdc4ba2df8c096f74c9110163a9"],
         ["arg_name", "==", "json"],
         ["arg_age", ">", "18"],
@@ -220,7 +222,7 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
 }'
 ```
 
-This route will require the request header `host` equal `iresty.com`, request cookie key `_device_id` equal `a66f0cdc4ba2df8c096f74c9110163a9` etc. You can learn more at [radixtree-new](https://github.com/api7/lua-resty-radixtree#new).
+This route requires the request host to equal `example.com`, the `_device_id` cookie to equal `a66f0cdc4ba2df8c096f74c9110163a9`, and the remaining expressions to match.
 
 ### How to filter route by POST form attributes?
 

diff --git a/docs/en/latest/stream-proxy.md b/docs/en/latest/stream-proxy.md
@@ -81,11 +81,12 @@ More examples can be found in [test cases](https://github.com/apache/apisix/blob
 
 ## More stream route filtering options
 
-Currently there are three attributes in stream routes that can be used for filtering requests:
+Stream routes can filter connections with the following attributes:
 
 - `server_addr`: The address of the APISIX server that accepts the L4 stream connection.
 - `server_port`: The port of the APISIX server that accepts the L4 stream connection.
 - `remote_addr`: The address of client from which the request has been made.
+- `sni`: The TLS Server Name Indication value. This field applies to TLS-enabled stream listeners.
 
 Here is an example:
 

diff --git a/docs/en/latest/terminology/consumer.md b/docs/en/latest/terminology/consumer.md
@@ -29,38 +29,35 @@ description: This article describes the role of the Apache APISIX Consumer objec
 
 ## Description
 
-For an API gateway, it is usually possible to identify the type of the requester by using things like their request domain name and client IP address. A gateway like APISIX can then filter these requests using [Plugins](./plugin.md) and forward it to the specified [Upstream](./upstream.md).
-
-It has the highest priority: Consumer > Route > Plugin Config > Service.
-
-But this level of depth can be insufficient on some occasions.
+In APISIX, a **Consumer** represents a user, application, or host that sends requests through the gateway. Consumers are typically used with authentication plugins, which identify a Consumer from request credentials and make its plugin configuration available while APISIX processes the request.
 
 ![consumer-who](../../../assets/images/consumer-who.png)
 
-An API gateway should know who the consumer of the API is to configure different rules for different consumers. This is where the **Consumer** construct comes in APISIX.
+Consumers can carry plugin configuration and can reference a [Consumer Group](./consumer-group.md) for shared plugin configuration. When the same plugin is configured in more than one local object, APISIX merges those configurations according to the [plugin merging precedence](./plugin.md#plugins-merging-precedence).
 
 ### Configuration options
 
 The fields for defining a Consumer are defined as below.
 
-| Field      | Required | Description                                                                                                                                                                      |
-| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `username` | True      | Name of the consumer.                                                                                                                                                             |
-| `plugins`  | False       | Plugin configuration of the **Consumer**. For specific Plugin configurations, please refer the [Plugins](./plugin.md). |
+| Field | Required | Description |
+| ----- | -------- | ----------- |
+| `username` | True | Unique name of the Consumer. |
+| `desc` | False | Description of the Consumer. |
+| `labels` | False | Labels attached to the Consumer. |
+| `group_id` | False | ID of the Consumer Group whose plugins are merged with the Consumer's plugins. |
+| `plugins` | False | Plugin configuration for the Consumer. See [Plugins](./plugin.md). |
 
 ## Identifying a Consumer
 
-The process of identifying a Consumer in APISIX is described below:
-
-![consumer-internal](../../../assets/images/consumer-internal.png)
+The process of identifying a Consumer in APISIX works as follows:
 
-1. The first step is Authentication. This is achieved by Authentication Plugins like [key-auth](../plugins/key-auth.md) and [JWT](../plugins/jwt-auth.md).
-2. After authenticating, you can obtain the `id` of the Consumer. This `id` will be the unique identifier of a Consumer.
-3. The configurations like Plugins and Upstream bound to the Consumer are then executed.
+1. An authentication plugin, such as [key-auth](../plugins/key-auth.md) or [jwt-auth](../plugins/jwt-auth.md), validates the request credentials.
+2. The plugin identifies the Consumer by its unique `username`.
+3. APISIX merges the Consumer and Consumer Group plugin configuration with the plugin configuration from the matched Route, Plugin Config, and Service.
 
-Consumers are useful when you have different consumers requesting the same API and you need to execute different Plugin and Upstream configurations based on the consumer. These need to be used in conjunction with the user authentication system.
+Consumers are useful when different applications or users request the same API and require different plugin configuration, such as rate limits or access controls. A Consumer does not hold an Upstream configuration.
 
-Authentication plugins that can be configured with a Consumer include `basic-auth`, `hmac-auth`, `jwt-auth`, `key-auth`, `ldap-auth`, and `wolf-rbac`.
+Authentication plugins enabled in APISIX can be configured on a Consumer. Examples include `basic-auth`, `hmac-auth`, `jwt-auth`, `key-auth`, `ldap-auth`, and `wolf-rbac`.
 
 Refer to the documentation for the [key-auth](../plugins/key-auth.md) authentication Plugin to further understand the concept of a Consumer.
 

diff --git a/docs/en/latest/terminology/credential.md b/docs/en/latest/terminology/credential.md
@@ -29,11 +29,9 @@ description: This article describes what the Apache APISIX Credential object doe
 
 ## Description
 
-Credential is the object that holds the [Consumer](./consumer.md) credential configuration.
-A Consumer can use multiple credentials of different types.
-Credentials are used when you need to configure multiple credentials for a Consumer.
+A Credential stores authentication plugin configuration for a [Consumer](./consumer.md). Each Credential contains at most one enabled authentication plugin, such as `basic-auth`, `hmac-auth`, `jwt-auth`, or `key-auth`.
 
-Currently, Credential can be configured with the authentication plugins `basic-auth`, `hmac-auth`, `jwt-auth`, and `key-auth`.
+A Consumer can have Credentials for different authentication plugins. It can also have multiple Credentials for the same authentication plugin when their identifying values differ. For example, a Consumer can rotate a key by creating a second `key-auth` Credential, switching clients to the new key, and then deleting the old Credential. Credential details are stored separately and are not included when you retrieve the Consumer resource.
 
 ### Configuration options
 
@@ -43,7 +41,7 @@ The fields for defining a Credential are defined as below.
 |---------|----------|---------------------------------------------------------------------------------------------------------|
 | desc    | False    | Description of the Credential.                                                                          |
 | labels  | False    | Labels of the Credential.                                                                               |
-| plugins | False    | The plugin configuration corresponding to Credential. For more information, see [Plugins](./plugin.md). |
+| plugins | False    | At most one authentication plugin configuration. For more information, see [Plugins](./plugin.md). |
 
 :::note
 

diff --git a/docs/en/latest/terminology/global-rule.md b/docs/en/latest/terminology/global-rule.md
@@ -28,7 +28,7 @@ description: This article describes how to use global rules.
 
 ## Description
 
-A [Plugin](./plugin.md) configuration can be bound directly to a [Route](./route.md), a [Service](./service.md) or a [Consumer](./consumer.md). But what if we want a Plugin to work on all requests? This is where we register a global Plugin with Global Rule.
+A [Global Rule](../admin-api.md#global-rule) configures [Plugins](./plugin.md) for incoming requests independently of Plugins bound to a [Route](./route.md), [Service](./service.md), [Consumer](./consumer.md), or [Plugin Config](./plugin-config.md). Rate-limiting and observability Plugins are often enabled globally to apply consistent behavior across APIs.
 
 Compared with the plugin configuration in Route, Service, Plugin Config, and Consumer, the plugin in the Global Rules is always executed first.
 

diff --git a/docs/en/latest/terminology/plugin-metadata.md b/docs/en/latest/terminology/plugin-metadata.md
@@ -28,23 +28,19 @@ description: Plugin Metadata in Apache APISIX.
 
 ## Description
 
-In this document, you will learn the basic concept of plugin metadata in APISIX and why you may need them.
-
-Explore additional resources at the end of the document for more information on related topics.
+In this document, you will learn the basic concept of plugin metadata in APISIX and why you may need it.
 
 ## Overview
 
-In APISIX, a plugin metadata object is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name. It is useful when a plugin is enabled across multiple objects and requires a universal update to their metadata fields.
-
-The following diagram illustrates the concept of plugin metadata using two instances of [syslog](https://apisix.apache.org/docs/apisix/plugins/syslog/) plugins on two different routes, as well as a plugin metadata object setting a [global](https://apisix.apache.org/docs/apisix/plugins/syslog/) `log_format` for the syslog plugin:
+In APISIX, a plugin metadata object configures shared settings for all instances of the same plugin. It is useful for values, such as log-format templates, that should normally remain consistent wherever the plugin is enabled.
 
-![plugin_metadata](https://static.apiseven.com/uploads/2023/04/17/Z0OFRQhV_plugin%20metadata.svg)
+APISIX stores one plugin metadata object for each plugin name. Only plugins that define a metadata schema support plugin metadata. Fields and behavior depend on the plugin, so check the documentation for the specific plugin before configuring its metadata.
 
-Without otherwise specified, the `log_format` on plugin metadata object should apply the same log format uniformly to both `syslog` plugins. However, since the `syslog` plugin on the `/orders` route has a different `log_format`, requests visiting this route will generate logs in the `log_format` specified by the plugin in route.
+For example, plugin metadata can define a shared `log_format` for every instance of the `syslog` plugin. An instance without its own `log_format` uses the metadata value, while an instance-level `log_format` takes precedence when configured.
 
-Metadata properties set at the plugin level is more granular and has a higher priority over the "global" metadata object.
+For logger plugins that support shared `log_format` metadata, this behavior also applies to plugins such as `http-logger`, `kafka-logger`, and `file-logger`.
 
-Plugin metadata objects should only be used for plugins that have metadata fields. Check the specific plugin documentation to know more.
+Plugin metadata is not merged with every plugin configuration by a universal precedence rule. Each plugin determines how its instances consume metadata and whether an instance-level field overrides a metadata field.
 
 ## Example usage
 
@@ -78,6 +74,6 @@ With this configuration, your logs would be formatted as shown below:
 {"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
 ```
 
-## Additional Resource(s)
+## Additional resources
 
-Key Concepts - [Plugins](https://apisix.apache.org/docs/apisix/terminology/plugin/)
+[Plugins](./plugin.md)
diff --git a/docs/en/latest/terminology/secret.md b/docs/en/latest/terminology/secret.md
@@ -30,7 +30,7 @@ Secrets refer to any sensitive information required during the running process o
 - API key
 - Sensitive plugin configuration fields, typically used for authentication, hashing, signing, or encryption
 
-APISIX Secret allows users to store secrets through some secrets management services (Vault, etc.) in APISIX, and read them according to the key when using them to ensure that **Secrets do not exist in plain text throughout the platform**.
+APISIX Secret allows APISIX to retrieve values from external secret managers such as HashiCorp Vault instead of storing those values directly in resource configuration. Connection credentials can still be configured as literal values. Where supported, use environment-variable references; for GCP, use `auth_file` when the service-account key should not be embedded in resource configuration.
 
 Its working principle is shown in the figure:
 ![secret](../../../assets/images/secret.png)

diff --git a/docs/zh/latest/terminology/consumer.md b/docs/zh/latest/terminology/consumer.md
@@ -29,36 +29,37 @@ description: 本文介绍了 Apache APISIX Consumer 对象的作用以及如何
 
 ## 描述
 
-Consumer 是某类服务的消费者，需要与用户认证配合才可以使用。当不同的消费者请求同一个 API 时，APISIX 会根据当前请求的用户信息，对应不同的 Plugin 或 Upstream 配置。如果 [Route](./route.md)、[Service](./service.md)、[Consumer](./consumer.md) 和 [Plugin Config](./plugin-config.md) 都绑定了相同的插件，只有消费者的插件配置会生效。插件配置的优先级由高到低的顺序是：Consumer > Route > Plugin Config > Service。
+在 APISIX 中，Consumer 表示通过网关发送请求并使用后端服务的用户、应用或主机。Consumer 通常与认证插件配合使用。认证插件根据请求凭证识别 Consumer，并在 APISIX 处理请求时使其插件配置生效。
 
-对于 API 网关而言，一般情况可以通过请求域名、客户端 IP 地址等字段识别到某类请求方，然后进行插件过滤并转发请求到指定上游。但有时候该方式达不到用户需求，因此 APISIX 支持了 Consumer 对象。
+Route 可以根据请求域名、客户端 IP 地址等属性匹配请求，但这些属性不一定能识别发起请求的应用或用户。
 
 ![Consumer](../../../assets/images/consumer-who.png)
 
-如上图所示，作为 API 网关，需要知道 API Consumer（消费方）具体是谁，这样就可以对不同 API Consumer 配置不同规则。
+Consumer 可以配置插件，也可以引用 Consumer Group 以共享插件配置。当多个局部对象配置了同一插件时，APISIX 会按照[插件合并优先顺序](./plugin.md#插件合并优先顺序)合并这些配置。
 
 ## 配置选项
 
 定义 Consumer 的字段如下：
 
-| 名称     | 必选项 | 描述                                                                         |
-| -------- | ---- | ------------------------------------------------------------------------------|
-| username | 是   | Consumer 名称。                                                                |
-| plugins  | 否   | Consumer 对应的插件配置。详细信息，请参考 [Plugins](./plugin.md)。 |
+| 名称 | 必选项 | 描述 |
+| ---- | ------ | ---- |
+| `username` | 是 | Consumer 的唯一名称。 |
+| `desc` | 否 | Consumer 的描述。 |
+| `labels` | 否 | Consumer 的标签。 |
+| `group_id` | 否 | Consumer Group 的 ID，其插件配置会与 Consumer 的插件配置合并。 |
+| `plugins` | 否 | Consumer 的插件配置。详细信息请参见 [Plugins](./plugin.md)。 |
 
 ## 识别消费者
 
-在 APISIX 中，识别 Consumer 的过程如下图：
+在 APISIX 中，识别 Consumer 的过程如下：
 
-![Consumer Internal](../../../assets/images/consumer-internal.png)
+1. 认证插件（例如 [key-auth](../plugins/key-auth.md) 或 [jwt-auth](../plugins/jwt-auth.md)）验证请求凭证。
+2. 认证插件通过唯一的 `username` 识别 Consumer。
+3. APISIX 将 Consumer 和 Consumer Group 的插件配置与匹配到的 Route、Plugin Config 和 Service 的插件配置合并。
 
-1. 授权认证：比如有 [key-auth](../plugins/key-auth.md)、[JWT](../plugins/jwt-auth.md) 等；
-2. 获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识；
-3. 获取 Consumer 上绑定的 Plugin 或 Upstream 信息：完成对不同 Consumer 做不同配置的效果。
+当不同应用或用户请求同一 API，并且需要不同的限流或访问控制等插件配置时，可以使用 Consumer。Consumer 本身不包含 Upstream 配置。
 
-当有不同的使用者请求相同的 API，并且需要根据使用者执行不同的插件和上游配置时，使用 Consumer 是非常合适的。需要与用户身份验证系统结合使用。
-
-目前，可以与 Consumer 配置的身份验证插件包括 `basic-auth` 、`hmac-auth`、`jwt-auth`、`key-auth`、`ldap-auth` 和 `wolf-rbac`。
+在 APISIX 中启用的认证插件可以配置在 Consumer 上，例如 `basic-auth`、`hmac-auth`、`jwt-auth`、`key-auth`、`ldap-auth` 和 `wolf-rbac`。
 
 你可以参考 [key-auth](../plugins/key-auth.md) 认证授权插件的调用逻辑，进一步理解 Consumer 概念和使用。