Apache APISIX Consumer 对象详解基于身份识别的细粒度流量治理【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixApache APISIX 的 Consumer消费者对象用于标识调用 API 的请求方身份从而在认证通过后为不同用户执行差异化的插件与上游配置。本文基于官方术语文档结合源码实现讲解 Consumer 的核心概念、配置字段、识别流程与实战示例读完即可在真实网关场景中落地基于用户的限流、黑白名单等治理策略。为什么需要 Consumer对于 API 网关而言通常可以通过请求的域名、客户端 IP 等手段区分请求来源APISIX 可以据此借助 Plugin 过滤请求并转发到指定的 Upstream。但这在有些场景下并不够用。网关更关心的是到底是谁在调用这个 API。只有知道了调用方是谁才能为不同的调用方配置不同的规则例如同一个接口A 客户限流 100 次/分钟B 客户限流 1000 次/分钟。上图直观表达了这一诉求多个请求方访问 APISIX 时网关需要先回答who are you?你是谁再决定后续如何对待这个请求。这正是 APISIX 中Consumer构造要解决的问题。在 APISIX 的配置优先级中Consumer 拥有最高优先级Consumer Route Plugin Config Service。也就是说当同一个路由同时被多个消费者命中时挂在 Consumer 上的插件配置会优先生效。Consumer 的配置字段Consumer 对象的核心字段定义如下与 schema_def.lua 中的 consumer schema 一一对应字段必填描述username是Consumer 的名称也是其唯一标识格式要求匹配^[a-zA-Z0-9_]$字母、数字、下划线plugins否Consumer 级别的插件配置具体插件配置方式参考 Plugingroup_id否关联的 Consumer Group 的 id用于批量管理插件配置labels否标签用于资源分类与检索desc否描述信息从源码看schema_def.lua 的_M.consumer规定username为必填required {username}且不允许出现未定义的额外字段additionalProperties false。值得注意的是username同时就是 Consumer 的id。在 apisix/consumer.lua 的 filter 函数 中有明确处理-- We expect the id is the same as username. Fix up it here if it isnt. consumer.value.id consumer.value.username即无论请求中如何填写 id最终都会以username作为 Consumer 的唯一标识后续认证插件拿到的consumer_name也来自这里见 plugin_consumer 中的注释。Consumer 的识别流程APISIX 中识别一个 Consumer 的过程分为三步认证Authentication由认证类插件完成例如 key-auth、JWT获取 Consumer id认证通过后得到 Consumer 的id即username作为该 Consumer 的唯一标识执行绑定配置执行挂载在该 Consumer 上的 Plugin、Upstream 等配置。底层实现上apisix/consumer.lua 的plugin_consumer()会在初始化时遍历 etcd 中/consumers下的所有 Consumer筛选出其中配置了type auth插件的项将插件配置提取为auth_conf并缓存。认证插件如 key-auth通过_M.consumers_kv(plugin_name, consumer_conf, key_attr)consumer.lua L116-L121以认证键为索引建立 KV 缓存实现 O(1) 的消费者查找。认证通过后认证插件调用_M.attach_consumer(ctx, consumer, conf)consumer.lua L84-L89将 Consumer 挂到请求上下文上function _M.attach_consumer(ctx, consumer, conf) ctx.consumer consumer ctx.consumer_name consumer.consumer_name ctx.consumer_group_id consumer.group_id ctx.consumer_ver conf.conf_version end此后consumer-restriction、limit-count等插件即可通过ctx.consumer_name感知到当前请求的消费者身份从而执行差异化策略。Consumer 最适合的场景是多个不同的消费者访问同一个 API需要根据消费者身份执行不同的插件与上游配置。这类能力必须与用户认证体系配合使用。APISIX 中可与 Consumer 配合的认证插件包括basic-auth、hmac-auth、jwt-auth、key-auth、ldap-auth、wolf-rbac。更深入的概念可以结合 key-auth 认证插件文档理解Consumer 对象的 Admin API 资源说明参见 Admin API Consumer。实战示例为特定 Consumer 启用插件下面通过完整示例演示如何为指定 Consumer 启用插件。示例将使用key-auth做身份认证并用limit-count对该消费者做限流。首先从config.yaml中取出管理密钥并保存为环境变量Admin API 默认监听127.0.0.1:9180数据面默认监听127.0.0.1:9080admin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)1. 创建 Consumer创建一个名为jack的 Consumer指定认证插件key-auth并启用限流插件limit-count60 秒窗口内最多 2 次请求超出返回 503curl 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 } } }说明Admin API 对 Consumer 只支持PUT与DELETE不支持POST与PATCH见 apisix/admin/consumers.lua 的 unsupported_methods。PUT时 URI 中的 username 必须与请求体中的username一致否则会返回wrong username错误见 check_conf。同时Admin API 强制校验Consumer 的plugins中必须包含至少一个认证类type 为 auth插件否则返回require one auth pluginconsumers.lua L40-L50。这从管理面保证了Consumer 必须能被认证识别这一设计初衷。2. 创建路由并开启插件创建路由/hello在路由上启用key-auth网关先完成认证并将请求转发到上游127.0.0.1:1980curl 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 }3. 验证限流效果发送测试请求携带jack的认证密钥auth-onecurl http://127.0.0.1:9080/hello -H apikey: auth-one -I前两次请求正常返回未达到限流阈值第三次请求返回503请求被限流拦截HTTP/1.1 503 Service Temporarily Unavailable ...这正是 Consumer 级插件配置的典型效果限流规则只作用于jack这一个消费者不影响其他消费者访问同一路由。进阶用 consumer-restriction 做访问控制除了限流还可以用 consumer-restriction 插件按消费者身份做访问控制。下面把jack加入黑名单禁止其访问该 API。1. 在路由上配置黑名单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 }2. 验证拦截效果再次使用jack的密钥发起请求curl http://127.0.0.1:9080/hello -H apikey: auth-one -I反复测试均返回403jack已被禁止访问该 APIHTTP/1.1 403 ...补充说明与源码路径配置优先级Consumer Route Plugin Config Service意味着消费者维度的插件配置会覆盖路由维度的同名配置这也是实现同一接口不同客户不同策略的基础。Consumer 与 Consumer Group当多个 Consumer 需要共享同一组插件配置时可以通过group_id关联 Consumer Group 批量管理避免逐个重复配置。数据加载Consumer 配置在init_worker阶段通过core.config.new(/consumers, cfg)consumer.lua L139-L155从 etcd或独立部署下的配置文件加载并在 etcd 配置变更时自动热更新无需重启网关。相关资源Consumer 核心实现apisix/consumer.luaConsumer Admin API 实现apisix/admin/consumers.luaConsumer Schema 定义apisix/schema_def.lua认证插件参考key-auth、jwt-auth相关测试t/admin/consumers.t、t/node/consumer-plugin.t总而言之Consumer 是 APISIX 将请求与人关联起来的关键抽象。配合认证插件它让网关能够在同一路由上针对不同调用方执行限流、黑白名单、灰度等精细化策略是构建多租户、多客户 API 治理体系的基石能力。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考