a6-plugin-consumer-restriction

概述

Apache APISIX 的 consumer-restriction 插件可根据已认证消费者的身份，限制其访问路由或服务。它支持三种限制类型和三种匹配模式：黑名单、白名单和按方法限制。

优先级：2400

该插件在认证插件之后的 access 阶段运行。

前提条件

必须与认证插件（如 key-auth、basic-auth、jwt-auth、hmac-auth、wolf-rbac）配合使用，以识别消费者。

适用场景

限制特定路由仅供指定消费者访问。
实现分级访问控制，例如免费消费者和高级消费者。
控制每个消费者可以使用的 HTTP 方法。
限制消费者只能访问指定服务或路由。

插件配置参考

字段	类型	是否必填	默认值	描述
`type`	string	否	`consumer_name`	限制类型：`consumer_name`、`consumer_group_id`、`service_id` 或 `route_id`
`whitelist`	字符串数组	三者之一*	—	允许的标识符
`blacklist`	字符串数组	三者之一*	—	拒绝的标识符
`allowed_by_methods`	对象数组	三者之一*	—	按消费者限制 HTTP 方法
`allowed_by_methods[].user`	string	否	—	消费者用户名
`allowed_by_methods[].methods`	字符串数组	否	—	允许的 HTTP 方法：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、CONNECT、TRACE、PURGE
`rejected_code`	integer	否	`403`	被拒绝请求的 HTTP 状态码（≥ 200）
`rejected_msg`	string	否	`"The {type} is forbidden."`	自定义拒绝消息

* 必须至少配置 whitelist、blacklist 或 allowed_by_methods 中的一项。

判定优先级

blacklist (highest) > whitelist > allowed_by_methods (lowest)

**黑名单：**消费者匹配时，立即返回 403。
**白名单：**消费者不在白名单中时会被拒绝，除非 allowed_by_methods 允许该请求。
**allowed_by_methods：**消费者使用的方法不在允许列表中时会被拒绝。

限制类型的配置位置

类型	配置位置	描述
`consumer_name`	路由/服务	限制可访问此路由的消费者
`consumer_group_id`	路由/服务	限制可访问此路由的消费者组
`service_id`	消费者	限制此消费者可访问的服务
`route_id`	消费者	限制此消费者可访问的路由

分步示例

1. 按消费者名称配置白名单

仅允许 jack1 访问该路由：

# Create consumers with auth
a6 consumer create -f - <<'EOF'
{
  "username": "jack1",
  "plugins": {
    "key-auth": {"key": "jack1-key"}
  }
}
EOF

a6 consumer create -f - <<'EOF'
{
  "username": "jack2",
  "plugins": {
    "key-auth": {"key": "jack2-key"}
  }
}
EOF

# Create route with restriction
a6 route create -f - <<'EOF'
{
  "id": "restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["jack1"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

curl -H 'apikey: jack1-key' /api/data → 200 OK
curl -H 'apikey: jack2-key' /api/data → 403 {"message":"The consumer_name is forbidden."}

2. 按消费者名称配置黑名单

阻止 bad-actor，同时允许其他消费者访问：

a6 route create -f - <<'EOF'
{
  "id": "blacklisted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "blacklist": ["bad-actor"],
      "rejected_code": 403,
      "rejected_msg": "Access denied"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

3. 限制指定消费者

当前 Apache APISIX不会通过 Admin API 提供消费者组管理功能。配置消费者限制时，请使用 consumer_name 白名单或拒绝名单。

# Create consumer group
a6 consumergroup create -f - <<'EOF'
{
  "id": "enterprise",
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 60,
      "group": "enterprise"
    }
  }
}
EOF

# Create consumer in the group
a6 consumer create -f - <<'EOF'
{
  "username": "acme-corp",
  "plugins": {
    "key-auth": {"key": "acme-key"}
  },
  "group_id": "enterprise"
}
EOF

# Route restricted to enterprise group
a6 route create -f - <<'EOF'
{
  "id": "enterprise-only",
  "uri": "/premium/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_group_id",
      "whitelist": ["enterprise"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

4. 按方法限制

仅允许 jack1 发起 POST 请求：

a6 route create -f - <<'EOF'
{
  "id": "method-restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "allowed_by_methods": [
        {
          "user": "jack1",
          "methods": ["POST"]
        },
        {
          "user": "admin",
          "methods": ["GET", "POST", "PUT", "DELETE"]
        }
      ]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

5. 限制消费者访问指定服务（消费者级配置）

消费者 api-user 只能访问服务 1：

a6 consumer create -f - <<'EOF'
{
  "username": "api-user",
  "plugins": {
    "key-auth": {"key": "api-user-key"},
    "consumer-restriction": {
      "type": "service_id",
      "whitelist": ["1"],
      "rejected_code": 403
    }
  }
}
EOF

6. 限制消费者访问指定路由（消费者级配置）

消费者 limited-user 只能访问路由 1：

a6 consumer create -f - <<'EOF'
{
  "username": "limited-user",
  "plugins": {
    "key-auth": {"key": "limited-key"},
    "consumer-restriction": {
      "type": "route_id",
      "whitelist": ["1"],
      "rejected_code": 401
    }
  }
}
EOF

配置同步示例

version: "1"
consumers:
  - username: admin
    plugins:
      key-auth:
        key: admin-key
  - username: readonly
    plugins:
      key-auth:
        key: readonly-key

routes:
  - id: admin-api
    uri: /admin/*
    plugins:
      key-auth: {}
      consumer-restriction:
        whitelist:
          - admin
        rejected_code: 403
        rejected_msg: "Admin access required"
    upstream_id: admin-backend

  - id: public-api
    uri: /api/*
    plugins:
      key-auth: {}
      consumer-restriction:
        allowed_by_methods:
          - user: readonly
            methods: ["GET"]
          - user: admin
            methods: ["GET", "POST", "PUT", "DELETE"]
    upstream_id: api-backend

常见模式

分级访问控制

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_group_id",
      "whitelist": ["enterprise", "pro"],
      "rejected_code": 402,
      "rejected_msg": "Upgrade required for this endpoint"
    }
  }
}

隐藏端点是否存在

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["admin"],
      "rejected_code": 404,
      "rejected_msg": "Resource not found"
    }
  }
}

故障排查

现象	原因	解决方法
返回 401 且提示 "please check the consumer_name"	未配置认证插件，或消费者未通过认证	在路由上添加 `key-auth` 或 `jwt-auth`
返回 403，但消费者应被允许	消费者不在白名单中，或位于黑名单中	确认消费者用户名与白名单条目完全一致
`allowed_by_methods` 未生效	同时配置了优先级更高的白名单	删除白名单，或仅使用一种模式
`service_id` 限制未生效	配置在路由上而非消费者上	将 `consumer-restriction` 配置移至消费者插件
`route_id` 限制未生效	配置在路由上而非消费者上	将 `consumer-restriction` 配置移至消费者插件

本文根据 api7/a6 仓库中的 a6-plugin-consumer-restriction/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概述​

适用场景​

插件配置参考​

判定优先级​

限制类型的配置位置​

分步示例​

1. 按消费者名称配置白名单​

2. 按消费者名称配置黑名单​

3. 限制指定消费者​

4. 按方法限制​

5. 限制消费者访问指定服务（消费者级配置）​

6. 限制消费者访问指定路由（消费者级配置）​

配置同步示例​

常见模式​

分级访问控制​

隐藏端点是否存在​

故障排查​

概述