API7 网关 AI Agent Skill：consumer-restriction 插件

概述

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

优先级：2400

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

前置条件

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

适用场景

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

插件配置参考

字段	类型	是否必填	默认值	描述
type	string	否	consumer_name	限制类型：consumer_name、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（最高优先级）> whitelist > allowed_by_methods（最低优先级）

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

限制类型的配置位置

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

分步示例

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

仅允许 jack1 访问该路由：

# 创建带身份认证配置的消费者
a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "jack1",
  "plugins": {
    "key-auth": {"key": "jack1-key"}
  }
}
EOF

a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "jack2",
  "plugins": {
    "key-auth": {"key": "jack2-key"}
  }
}
EOF

# 创建带限制规则的路由
a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["jack1"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 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，同时允许其他消费者访问：

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

3. 限制指定消费者

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

a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "acme-corp",
  "plugins": {
    "key-auth": {"key": "acme-key"}
  }
}
EOF

# 创建仅允许指定消费者访问的路由
a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "enterprise-only",
  "uri": "/premium/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_name",
      "whitelist": ["acme-corp"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

4. 按方法限制

仅允许 jack1 发起 POST 请求：

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

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

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

a7 consumer create --gateway-group default -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：

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

配置同步示例

version: "1"
gateway_group: default
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:
      type: roundrobin
      nodes:
        - host: admin-backend
          port: 8080
          weight: 1

  - 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:
      type: roundrobin
      nodes:
        - host: api-backend
          port: 8080
          weight: 1

常见模式

分级访问控制

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_name",
      "whitelist": ["enterprise-user", "pro-user"],
      "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/a7 仓库中的 a7-plugin-consumer-restriction/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。