智能体身份和权限管理平台
智能体身份和权限管理平台
文档指南
请输入
- 文档首页
智能体身份和权限管理平台用户指南权限管控权限网关综合用户指南
复制全文
下载 pdf权限网关综合用户指南
文档反馈
问问助手Overview
权限网关底层依赖 APIG 网关和数据面 WASM 插件生效。它的职责是在请求进入后端服务之前匹配路由，提取资源标识和动作，调用权限管理完成鉴权；在需要时，还可以对响应中的列表或单对象做权限过滤。
权限网关适合在不大幅改造后端服务的情况下，为已有 API 接入统一权限控制。用户可以基于内置模板快速创建服务，也可以接入自定义后端；接口数量较多时，还可以通过 Swagger、OpenAPI 或自然语言文档解析生成路由草稿。
- 如果您使用 VikingDB、MCP 等标准后端，优先选择内置服务模板。
- 如果您接入已有业务 API，先验证后端连通性，再创建服务和路由。
- 如果您需要列表级过滤，重点检查 APISpec 中的资源提取器和响应过滤器。
核心概念与对应 API
Gateway
Gateway 是底层 APIG 网关实例，通常由运维人员维护。它可以是共享网关，也可以是专属网关；发布后会同步 APIG 网关 ID、上游源、默认上游服务和插件配置等信息。
模块能力
- 管理共享或专属 APIG 网关资源。
- 维护网关容量、VPC、子网、节点规格、WASM 插件镜像和默认上游配置。
- 通过发布动作将本地网关配置同步到 APIG。
API
后端服务模板
后端服务模板由平台运维维护，用于封装常见后端服务的域名、端口、协议、超时、预置路由和 APISpec。用户创建内置服务时，选择模板即可生成服务和路由。
模块能力
- 维护 VikingDB、MCP 等标准后端服务的模板。
- 为模板绑定多个路由模板，每个路由模板可包含默认权限池、资源类型和 APISpec。
- 提供创建服务时的下拉选项和路由模板选项。
API
权限网关服务 Service
Service 是用户侧核心实体，代表一个接入权限网关的后端服务实例。它绑定后端连接信息、权限空间、项目、标签和可访问域名。创建后需要发布，配置才会同步到 APIG 并对流量生效。
模块能力
- 绑定后端服务配置，包括域名、端口、协议、TLS 和超时。
- 绑定 PermissionSpaceId 和可读的权限空间名称。
- 承载服务下的多条路由，并通过发布动作同步到 APIG。
- 支持内置模板创建和自定义后端创建两种方式。
API
路由 Route
Route 定义请求如何匹配、如何路由、如何映射到权限管理。它包含 HTTP 方法、路径、匹配类型、优先级、权限池、资源类型、鉴权资源类型和可选 APISpec。
模块能力
- 在服务内维护 API 路由，路由名称在服务内唯一。
- 配置 Method、Path、PathMatchType 和 Priority。
- 通过 PermissionPool、ResourceType 和 AuthResourceType 对接权限管理语义。
- 支持从路由模板创建、单条创建、批量创建、发布和禁用。
API
典型规则
- Priority 当前语义为数值越小越优先，默认值为 100。
- Path 应保持稳定，避免用会频繁变化的路径片段作为权限标识。
- PermissionPool、ResourceType 和 ActionValue 应与权限管理侧资源动作模型保持一致。
APISpec、Extractors 与 ResponseFilters
APISpec 决定数据面插件如何从请求和响应中识别权限语义。它包含资源标识符、操作类型、操作值、属性提取器和响应过滤器。
模块能力
- 通过 IdentifierType 和 IdentifierValue 定位资源标识。
- 通过 ActionType 和 ActionValue 映射权限管理动作。
- 通过 Extractors 从 Header、Body、Query 或 Path 中提取资源属性。
- 通过 ResponseFilters 对数组或单对象响应做权限过滤。
典型字段
响应过滤模式
文档解析
文档解析用于从 Swagger、OpenAPI 或自然语言文档中生成路由草稿。解析接口返回 DocumentId，调用方再通过状态接口查询解析结果。
API
处理顺序
- 上传文档并传入 DocType。
- 获取 DocumentId。
- 轮询 GetDocumentStatus，直到状态为 completed 或 failed。
- 人工检查解析出的 ParsedRoute，补齐权限池、资源类型和 APISpec。
- 通过 BatchCreateRoutes 或单条创建接口保存到服务。
数据面路由规范
数据面接口供 WASM 插件调用。插件根据 APIG 路由 ID 获取权限规范，再按路由配置执行资源提取、鉴权和响应过滤。
API
标签与配额
标签用于服务治理、资源筛选和运营管理；配额用于创建或发布前确认容量边界。
API
模块关系与职责边界
使用流程
流程一：基于内置模板创建服务
- 准备权限空间。
在权限管理中创建或选择权限空间，确认资源类型、动作和基础策略已准备好。
- 选择模板。
调用 DescribeTemplateOptions 获取模板列表，按后端类型或关键词选择模板。
- 选择路由模板。
调用 DescribeRouteTemplateOptions 查看模板下路由，确认默认权限池、资源类型和 APISpec。
- 创建服务。
调用 CreateServiceFromTemplate，填写服务名、权限空间和需要创建的路由模板 ID。
- 检查服务。
调用 GetService 和 ListRoutes 确认服务与路由已生成。
- 发布服务。
调用 PublishService 将配置同步到 APIG，获取公网或内网域名。
流程二：自定义后端服务接入
- 验证后端。
填写 BackendConfig，调用 ValidateBackend 检查域名、端口、协议和 TLS 配置。
- 检查名称。
调用 CheckServiceName，确保服务名在账号内可用。
- 创建服务。
调用 CreateService，绑定权限空间、项目、标签和后端配置。
- 创建路由。
通过 CreateRoute 或 BatchCreateRoutes 添加路由，并配置权限池、资源类型和 APISpec。
- 发布变更。
调用 PublishService 或 PublishRoute，将服务和路由同步到 APIG。
- 联调鉴权。
用真实请求验证路由匹配、资源提取、权限管理策略命中和后端转发。
流程三：从 API 文档解析路由
- 上传文档。
调用 ParseDocument，选择 Swagger、OpenAPI 或 NaturalLanguage 文档类型。
- 等待解析完成。
使用 GetDocumentStatus 查询状态，完成后获取路由草稿。
- 人工校正。
检查路径、方法、权限池、资源类型、动作值和资源标识符，修正自动解析不确定的部分。
- 保存路由。
调用 BatchCreateRoutes 保存，按需要选择 SKIP、UPSERT、STRICT 或 SYNC 模式。
- 发布验证。
发布后使用真实请求验证鉴权和响应过滤效果。
流程四：启用响应过滤
- 确认列表结构。
确定后端响应中资源数组或单对象所在的 JSON Pointer。
- 配置过滤器。
在 ResponseFilters 中设置资源类型、过滤模式、数组路径、资源路径、ID 字段和属性映射。
- 确认权限策略。
在权限管理中为这些资源和动作创建策略，确保对象权限查询或单项鉴权能返回正确结果。
- 发布路由。
调用 PublishRoute 同步 APIG。
- 对比响应。
使用不同权限主体请求同一接口，确认无权限资源项被过滤且分页行为符合预期。
场景选择指南
与权限管理的关系
权限网关不直接维护业务授权策略。它负责把 HTTP 请求映射为权限管理能够识别的主体、动作、资源和上下文；最终 allow/deny 由权限管理策略决定。
常见问题
服务创建后为什么没有生效？
服务和路由创建后只是管理面记录。需要调用 PublishService 或 PublishRoute 同步到 APIG，状态变为 active 后才会对流量生效。
路由优先级是越大越优先吗？
当前接口定义中 Priority 的语义是数值越小越优先，默认值为 100。如果历史设计文档与接口注释不一致，以当前接口定义和 API 参考为准。
路由能匹配请求，为什么仍然全部无权限？
通常是权限网关和权限管理的语义没有对齐。请检查 PermissionSpaceId、ResourceType、ActionValue、资源 key 提取结果，以及权限管理中是否存在启用状态的匹配策略。
什么时候选择模板，什么时候选择自定义服务？
标准后端服务优先选择模板，模板已经封装后端配置、路由和部分 APISpec。已有业务 API、私有后端或路径语义差异较大的服务，使用自定义服务更合适。
批量创建路由的模式怎么选？
SKIP 适合只补充新增路由；UPSERT 适合重复执行导入；STRICT 适合任何冲突都应失败的发布流程；SYNC 适合全量同步，但会删除请求列表之外的已有路由。
响应过滤会替代请求前鉴权吗？
不会。请求前鉴权决定请求是否可以访问当前 API；响应过滤用于列表或详情结果中的资源项裁剪。涉及敏感写操作时，应优先确保请求前鉴权准确。
文档解析结果可以直接发布吗？
不建议。解析结果是路由草稿，路径和方法通常较准确，但权限池、资源类型、动作值和响应过滤规则仍需要人工确认后再保存和发布。
最近更新时间：2026.08.24 15:15:46
这个页面对您有帮助吗？
有用
有用
无用
无用