This is an automated email from the ASF dual-hosted git repository.
kayx23 pushed a commit to branch release/3.19
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/release/3.19 by this push:
new c550234594 docs: port source-verified terminology corrections (#14104)
c550234594 is described below
commit c550234594cc29722c09b24cef8eb9d293956233
Author: Traky Deng <[email protected]>
AuthorDate: Wed Oct 28 22:50:23 2026 +0800
docs: port source-verified terminology corrections (#14104)
---
docs/en/latest/router-radixtree.md | 12 ++++++----
docs/en/latest/stream-proxy.md | 3 ++-
docs/en/latest/terminology/consumer.md | 33 ++++++++++++---------------
docs/en/latest/terminology/credential.md | 8 +++----
docs/en/latest/terminology/global-rule.md | 4 ++--
docs/en/latest/terminology/plugin-config.md | 8 +++----
docs/en/latest/terminology/plugin-metadata.md | 20 +++++++---------
docs/en/latest/terminology/plugin.md | 23 +++++++------------
docs/en/latest/terminology/secret.md | 2 +-
docs/zh/latest/terminology/consumer.md | 31 +++++++++++++------------
docs/zh/latest/terminology/credential.md | 8 +++----
docs/zh/latest/terminology/global-rule.md | 6 ++---
docs/zh/latest/terminology/plugin-config.md | 8 +++----
docs/zh/latest/terminology/plugin-metadata.md | 20 ++++++----------
docs/zh/latest/terminology/plugin.md | 23 +++++++------------
15 files changed, 90 insertions(+), 119 deletions(-)
diff --git a/docs/en/latest/router-radixtree.md
b/docs/en/latest/router-radixtree.md
index 8b68d9d5c9..98a86063e0 100644
--- 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,7 +194,7 @@ 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.
By default, an URL-encoded slash (`%2F`) inside a parameter is decoded by Nginx
into a real `/` before route matching, so a request like `/blog/cat%2Fdog` is
@@ -242,14 +242,16 @@ simply does not apply to such requests.
### 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"],
@@ -264,7 +266,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
index 7b1a2c9175..0e988f2695 100644
--- 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` or `snis`: One or more TLS Server Name Indication values. These fields
apply 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
index 17fc7d8f50..bce2eae9c8 100644
--- 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.
-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:
-
-
+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
index b0ed3bc2fd..594dc994c1 100644
--- 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
index 1007f4b05a..c4cba9a3b1 100644
--- a/docs/en/latest/terminology/global-rule.md
+++ b/docs/en/latest/terminology/global-rule.md
@@ -28,9 +28,9 @@ 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.
+Global Rule Plugins run before locally bound Plugins within the same phase.
The complete order is global `rewrite`, local `rewrite`, global `access`, then
local `access`. A global `access` handler therefore does not run before a local
`rewrite` handler. Priorities order Plugins within each phase and scope, and an
early response prevents later handlers from running. See [Plugins execution
order](./plugin.md#plugins-execution-order) for details.
## Example
diff --git a/docs/en/latest/terminology/plugin-config.md
b/docs/en/latest/terminology/plugin-config.md
index da2a1379af..12e20cf9f8 100644
--- a/docs/en/latest/terminology/plugin-config.md
+++ b/docs/en/latest/terminology/plugin-config.md
@@ -121,11 +121,11 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
"nodes": {
"127.0.0.1:1980": 1
}
- }
+ },
"plugins": {
"proxy-rewrite": {
"uri": "/test/add",
- "host": "apisix.iresty.com"
+ "host": "example.com"
},
"limit-count": {
"count": 20,
@@ -149,7 +149,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
"nodes": {
"127.0.0.1:1980": 1
}
- }
+ },
"plugins": {
"ip-restriction": {
"whitelist": [
@@ -159,7 +159,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
},
"proxy-rewrite": {
"uri": "/test/add",
- "host": "apisix.iresty.com"
+ "host": "example.com"
},
"limit-count": {
"count": 20,
diff --git a/docs/en/latest/terminology/plugin-metadata.md
b/docs/en/latest/terminology/plugin-metadata.md
index 93ece32a6c..783ffd7c9c 100644
--- 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.
-
+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/plugin.md
b/docs/en/latest/terminology/plugin.md
index 3fe7cd6038..6e6d7811db 100644
--- a/docs/en/latest/terminology/plugin.md
+++ b/docs/en/latest/terminology/plugin.md
@@ -89,25 +89,18 @@ When a request goes through APISIX, the plugin's
corresponding methods are execu
A route whose `upstream.scheme` is `ws` or `wss` still runs
`rewrite`/`access`/`before_proxy`/`log` normally, but replaces
`header_filter`/`body_filter`/`delayed_body_filter` with four
WebSocket-specific phases: `ws_handshake`, `ws_client_frame`,
`ws_upstream_frame`, and `ws_close`. See the ["extra phase" section of the
plugin development guide](../plugin-develop.md#extra-phase) for details.
-<br />
-<div style={{textAlign: 'center'}}>
-<img
src="https://static.apiseven.com/uploads/2023/03/09/ZsH5C8Og_plugins-phases.png";
alt="Routes Diagram" width="50%"/>
-</div>
-<br />
-
## Plugins execution order
-In general, plugins are executed in the following order:
+Global and locally bound plugins for a matched HTTP Route are interleaved by
phase:
-1. Plugins in [global rules](./global-rule.md)
- 1. plugins in rewrite phase
- 2. plugins in access phase
+1. global-rule plugins in the `rewrite` phase;
+2. locally bound plugins in the `rewrite` phase;
+3. global-rule plugins in the `access` phase; and
+4. locally bound plugins in the `access` phase.
-2. Plugins bound to other objects
- 1. plugins in rewrite phase
- 2. plugins in access phase
+A locally bound `rewrite` handler runs before every global-rule `access`
handler. If a `rewrite` handler terminates the request, the `access` handlers
scheduled after it do not run, but `log` handlers still run.
-Within each phase, you can optionally define a new priority number in the
`_meta.priority` field of the plugin, which takes precedence over the default
plugins priority during execution. Plugins with higher priority numbers are
executed first.
+Within each of these groups, you can optionally define a new priority number
in the `_meta.priority` field of the plugin, which takes precedence over the
default plugin priority during execution. Plugins with higher priority numbers
are executed first. A priority does not move a plugin across phase or
global/local groups.
For example, if you want to have `limit-count` (priority 1002) run before
`ip-restriction` (priority 3000) when requests hit a route, you can do so by
passing a higher priority number to `_meta.priority` field of `limit-count`:
@@ -146,7 +139,7 @@ Some common configurations can be applied to plugins
through the `_meta` configu
| disable | boolean | When set to `true`, the plugin is
disabled. |
| error_response | string/object | Custom error response. |
| priority | integer | Custom plugin priority. |
-| filter | array | Depending on the requested parameters, it
is decided at runtime whether the plugin should be executed. Something like
this: `{{var, operator, val}, {var, operator, val}, ...}}`. For example:
`{"arg_version", "==", "v2"}`, indicating that the current request parameter
`version` is `v2`. The variables here are consistent with NGINX internal
variables. For details on supported operators, please see
[lua-resty-expr](https://github.com/api7/lua-resty-expr#o [...]
+| filter | array | Depending on the requested parameters, it
is decided at runtime whether the plugin should be executed. Something like
this: `{{var, operator, val}, {var, operator, val}, ...}}`. For example:
`{"arg_version", "==", "v2"}`, indicating that the current request parameter
`version` is `v2`. The variables here are consistent with NGINX internal
variables. See [APISIX
expressions](../router-radixtree.md#how-to-filter-route-by-nginx-built-in-variable)
for the [...]
### Disable the plugin
diff --git a/docs/en/latest/terminology/secret.md
b/docs/en/latest/terminology/secret.md
index 347bcf7cb2..0ee4d913fa 100644
--- 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:
diff --git a/docs/zh/latest/terminology/consumer.md
b/docs/zh/latest/terminology/consumer.md
index 22f4a0fd42..7cee94fff0 100644
--- 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 地址等属性匹配请求，但这些属性不一定能识别发起请求的应用或用户。
-如上图所示，作为 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 的过程如下：
-
+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 概念和使用。
diff --git a/docs/zh/latest/terminology/credential.md
b/docs/zh/latest/terminology/credential.md
index e7b39ecd67..164f055286 100644
--- a/docs/zh/latest/terminology/credential.md
+++ b/docs/zh/latest/terminology/credential.md
@@ -29,11 +29,9 @@ description: 本文介绍了 Apache APISIX Credential 对象的作用以及如
## 描述
-Credential 是存放 [Consumer](./consumer.md) 凭证配置的对象。
-一个 Consumer 可以使用不同类型的多个凭证。
-当你需要为一个 Consumer 配置不同类型的多个凭证时，就会用到 Credential。
+Credential 存储与 [Consumer](./consumer.md) 关联的认证插件配置。每个 Credential
最多包含一个已启用的认证插件，例如 `basic-auth`、`hmac-auth`、`jwt-auth` 或 `key-auth`。
-目前，Credential 可以配置的身份认证插件包括 `basic-auth`、`hmac-auth`、`jwt-auth` 以及 `key-auth`。
+一个 Consumer 可以拥有不同认证插件的 Credential，也可以为同一认证插件配置多个具有不同识别值的
Credential。例如，可以先创建第二个 `key-auth` Credential，将客户端切换到新密钥，再删除旧
Credential，以完成密钥轮换。Credential 详情独立存储，获取 Consumer 资源时不会返回这些详情。
## 配置选项
@@ -43,7 +41,7 @@ Credential 是存放 [Consumer](./consumer.md) 凭证配置的对象。
|---------|-----|-----------------------------------------------------|
| desc | 否 | Credential 描述。 |
| labels | 否 | Credential 标签。 |
-| plugins | 否 | Credential 对应的插件配置。详细信息，请参考 [Plugins](./plugin.md)。 |
+| plugins | 否 | 最多包含一个认证插件配置。详细信息请参见 [Plugins](./plugin.md)。 |
:::note
diff --git a/docs/zh/latest/terminology/global-rule.md
b/docs/zh/latest/terminology/global-rule.md
index 8b3dc7ad48..6b0a8d7aeb 100644
--- a/docs/zh/latest/terminology/global-rule.md
+++ b/docs/zh/latest/terminology/global-rule.md
@@ -29,11 +29,9 @@ description: 本文介绍了全局规则的概念以及如何启用全局规则
## 描述
-[Plugin](plugin.md) 配置可直接绑定在 [Route](route.md) 上，也可以被绑定在 [Service](service.md)
或 [Consumer](consumer.md) 上。
+[Global Rule](../admin-api.md#global-rule) 为传入请求配置 [Plugin](plugin.md)，不依赖于绑定到
[Route](route.md)、[Service](service.md)、[Consumer](consumer.md) 或 [Plugin
Config](plugin-config.md) 的插件配置。限流和可观测性插件通常会全局启用，以便为所有 API 提供一致的行为。
-如果你需要一个能作用于所有请求的 Plugin，可以通过 Global Rules 启用一个全局的插件配置。
-
-全局规则相对于 Route、Service、Plugin Config、Consumer 中的插件配置，Global Rules 中的插件总是优先执行。
+同一阶段内的 Global Rule Plugin 会先于局部绑定的 Plugin 执行。完整顺序为：全局 `rewrite`、局部
`rewrite`、全局 `access`、局部 `access`。因此，全局 `access` 处理函数不会先于局部 `rewrite`
处理函数执行。优先级只对同一阶段和作用域内的 Plugin
进行排序；如果某个处理函数提前返回响应，后续处理函数将不会执行。详情请参见[插件执行顺序](./plugin.md#插件执行顺序)。
## 使用示例
diff --git a/docs/zh/latest/terminology/plugin-config.md
b/docs/zh/latest/terminology/plugin-config.md
index 7253890d9e..5e8ae8ac83 100644
--- a/docs/zh/latest/terminology/plugin-config.md
+++ b/docs/zh/latest/terminology/plugin-config.md
@@ -127,11 +127,11 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
"nodes": {
"127.0.0.1:1980": 1
}
- }
+ },
"plugins": {
"proxy-rewrite": {
"uri": "/test/add",
- "host": "apisix.iresty.com"
+ "host": "example.com"
},
"limit-count": {
"count": 20,
@@ -155,7 +155,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
"nodes": {
"127.0.0.1:1980": 1
}
- }
+ },
"plugins": {
"ip-restriction": {
"whitelist": [
@@ -165,7 +165,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
},
"proxy-rewrite": {
"uri": "/test/add",
- "host": "apisix.iresty.com"
+ "host": "example.com"
},
"limit-count": {
"count": 20,
diff --git a/docs/zh/latest/terminology/plugin-metadata.md
b/docs/zh/latest/terminology/plugin-metadata.md
index 3af77a0833..c705f69ef9 100644
--- a/docs/zh/latest/terminology/plugin-metadata.md
+++ b/docs/zh/latest/terminology/plugin-metadata.md
@@ -27,25 +27,19 @@ description: APISIX 的插件元数据
#
-->
-## 摘要
-
-在本文档中，您将了解到 APISIX 中，插件元数据的基本概念和您可能使用到的场景。
-
-浏览文档末尾的相关资源，获取与此相关的更多信息。
-
## 描述
-在 APISIX 中，配置通用的元数据属性，可以作用于包含该元数据插件的所有路由及服务中。例如为`rocketmq-logger`指定了
`log_format`，则所有绑定 rocketmq-logger 的路由或服务都将使用该日志格式。
+本文介绍 APISIX 插件元数据的基本概念和适用场景。
-下图说明了插件元数据的概念，使用两个不同路由上的
[syslog](https://apisix.apache.org/zh/docs/apisix/plugins/syslog/) 插件的实例，以及为
[syslog](https://apisix.apache.org/zh/docs/apisix/plugins/syslog/)
插件设置全局`log_format`的插件元数据对象：
+在 APISIX 中，插件元数据对象为同一插件的所有实例配置共享设置，适用于日志格式模板等通常需要保持一致的配置。
-
+APISIX 为每个插件名称保存一个插件元数据对象。只有定义了元数据 Schema
的插件才支持插件元数据。字段和行为取决于具体插件，因此配置前请查看对应插件的文档。
-如果没有另外指定，插件元数据对象上的`log_format`应将相同的日志格式统一应用于两个`syslog`插件。但是，由于`/orders`路由上的`syslog`插件具有不同的`log_format`，因此访问该路由的请求将按照路由中插件指定的`log_format`生成日志。
+例如，插件元数据可以为所有 `syslog` 插件实例定义共享的 `log_format`。未配置实例级 `log_format`
时，插件使用元数据中的值；配置实例级 `log_format` 后，该值优先。
-在插件级别设置的元数据属性更加精细，并且比`全局`元数据对象具有更高的优先级。
+对于支持共享 `log_format` 元数据的日志插件，此行为也适用于 `http-logger`、`kafka-logger` 和
`file-logger` 等插件。
-插件元数据对象只能用于具有元数据属性的插件。有关哪些插件具有元数据属性的更多详细信息，请查看插件配置属性及相关信息。
+插件元数据与插件实例配置之间不存在适用于所有插件的统一优先级规则。每个插件自行决定如何使用元数据，以及实例级字段是否覆盖元数据字段。
## 配置示例
@@ -82,4 +76,4 @@ curl
http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger \
## 相关资源
-核心概念 - [插件](https://apisix.apache.org/docs/apisix/terminology/plugin/)
+[插件](./plugin.md)
diff --git a/docs/zh/latest/terminology/plugin.md
b/docs/zh/latest/terminology/plugin.md
index 263998ff95..4ebd0c3da4 100644
--- a/docs/zh/latest/terminology/plugin.md
+++ b/docs/zh/latest/terminology/plugin.md
@@ -86,25 +86,18 @@ plugins:
当一个请求通过 APISIX 时，插件的相应方法会在以下一个或多个阶段中执行： `rewrite`, `access`, `before_proxy`,
`header_filter`, `body_filter`, and `log`。这些阶段在很大程度上受到[OpenResty
指令](https://openresty-reference.readthedocs.io/en/latest/Directives/)的影响。
-<br />
-<div style={{textAlign: 'center'}}>
-<img
src="https://static.apiseven.com/uploads/2023/03/09/ZsH5C8Og_plugins-phases.png";
alt="Routes Diagram" width="50%"/>
-</div>
-<br />
-
## 插件执行顺序
-通常情况下，插件按照以下顺序执行：
+对于匹配 HTTP Route 的请求，全局规则插件和局部绑定的插件会按阶段交错执行：
-1. [全局规则](./global-rule.md) 插件
- 1. rewrite 阶段的插件
- 2. access 阶段的插件
+1. 全局规则插件的 `rewrite` 阶段；
+2. 局部绑定插件的 `rewrite` 阶段；
+3. 全局规则插件的 `access` 阶段；
+4. 局部绑定插件的 `access` 阶段。
-2. 绑定到其他对象的插件
- 1. rewrite 阶段的插件
- 2. access 阶段的插件
+局部绑定插件的 `rewrite` 处理函数会先于所有全局规则插件的 `access` 处理函数执行。如果某个 `rewrite`
处理函数终止了请求，则排在它之后的 `access` 处理函数不会执行，但 `log` 处理函数仍会执行。
-在每个阶段内，你可以在插件的 `_meta.priority`
字段中可选地定义一个新的优先级数，该优先级数优先于默认插件优先级在执行期间。具有更高优先级数的插件首先执行。
+在上述每个分组内，你可以在插件的 `_meta.priority`
字段中定义新的优先级数，该优先级会在执行时覆盖插件的默认优先级。优先级数越高，插件越先执行。优先级不会使插件跨越阶段或全局、局部分组执行。
例如，如果你想在请求到达路由时，让 `limit-count`（优先级 1002）先于 `ip-restriction`（优先级
3000）运行，可以通过将更高的优先级数传递给 `limit-count` 的 `_meta.priority` 字段来实现：
@@ -143,7 +136,7 @@ plugins:
| disable | boolean | 当设置为 `true` 时，则禁用该插件。可选值为 `true` 和 `false`。
|
| error_response | string/object | 自定义错误响应。 |
| priority | integer | 自定义插件优先级。 |
-| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var,
operator, val} 元素组成列表，类似：`{{var, operator, val}, {var, operator, val},
...}}`。例如 `{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与
NGINX 内部自身变量命名是保持一致。操作符的使用方法，请参考
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)。|
+| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var,
operator, val} 元素组成列表，类似：`{{var, operator, val}, {var, operator, val},
...}}`。例如 `{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与
NGINX 内部自身变量命名保持一致。条件格式和支持的操作符请参考 [APISIX
表达式](../router-radixtree.md#如何通过-nginx-内置变量过滤路由)。|
### 禁用指定插件
![https://static.apiseven.com/uploads/2023/03/09/ZsH5C8Og_plugins-phases.png"](https://static.apiseven.com/uploads/2023/03/09/ZsH5C8Og_plugins-phases.png"){kind=link}