Version: 3.10

Consumer

描述#

Consumer 是某类服务的消费者，需要与用户认证配合才可以使用。当不同的消费者请求同一个 API 时，APISIX 会根据当前请求的用户信息，对应不同的 Plugin 或 Upstream 配置。如果 Route、Service、Consumer 和 Plugin Config 都绑定了相同的插件，只有消费者的插件配置会生效。插件配置的优先级由高到低的顺序是：Consumer > Route > Plugin Config > Service。

对于 API 网关而言，一般情况可以通过请求域名、客户端 IP 地址等字段识别到某类请求方，然后进行插件过滤并转发请求到指定上游。但有时候该方式达不到用户需求，因此 APISIX 支持了 Consumer 对象。

如上图所示，作为 API 网关，需要知道 API Consumer（消费方）具体是谁，这样就可以对不同 API Consumer 配置不同规则。

配置选项#

定义 Consumer 的字段如下：

名称	必选项	描述
username	是	Consumer 名称。
plugins	否	Consumer 对应的插件配置。详细信息，请参考 Plugins。

识别消费者#

在 APISIX 中，识别 Consumer 的过程如下图：

授权认证：比如有 key-auth、JWT 等；
获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识；
获取 Consumer 上绑定的 Plugin 或 Upstream 信息：完成对不同 Consumer 做不同配置的效果。

当有不同的使用者请求相同的 API，并且需要根据使用者执行不同的插件和上游配置时，使用 Consumer 是非常合适的。需要与用户身份验证系统结合使用。

目前，可以与 Consumer 配置的身份验证插件包括 basic-auth 、hmac-auth、jwt-auth、key-auth、ldap-auth 和 wolf-rbac。

你可以参考 key-auth 认证授权插件的调用逻辑，进一步理解 Consumer 概念和使用。

注意

如需了解更多关于 Consumer 对象的信息，你可以参考 Admin API Consumer 资源介绍。

使用示例#

以下示例介绍了如何对某个 Consumer 开启指定插件：

note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

创建 Consumer，指定认证插件 key-auth，并开启特定插件 limit-count。

curl http://127.0.0.1:9180/apisix/admin/consumers \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        },
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    }
}'

创建路由，设置路由规则和启用插件配置。

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "key-auth": {}
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试插件。
连续发送三次测试请求，前两次返回正常，没达到限速阈值。
```
curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
```
第三次测试返回 503，请求被限制：
```
HTTP/1.1 503 Service Temporarily Unavailable
...
```

通过 consumer-restriction 插件，限制用户 jack 对该 Route 的访问。

设置黑名单，禁止 jack 访问该 API。

curl http://127.0.0.1:9180/apisix/admin/routes/1  \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "key-auth": {},
        "consumer-restriction": {
            "blacklist": [
                "jack"
            ]
        }
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

通过以下命令访问该路由，均返回 403，jack 被禁止访问。
```
curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
```
返回结果：
```
HTTP/1.1 403
...
```