## Overview 权限网关底层依赖 APIG 网关和数据面 WASM 插件生效。它的职责是在请求进入后端服务之前匹配路由，提取资源标识和动作，调用权限管理完成鉴权；在需要时，还可以对响应中的列表或单对象做权限过滤。权限网关适合在不大幅改造后端服务的情况下，为已有 API 接入统一权限控制。用户可以基于内置模板快速创建服务，也可以接入自定义后端；接口数量较多时，还可以通过 Swagger、OpenAPI 或自然语言文档解析生成路由草稿。 * 如果您使用 VikingDB、MCP 等标准后端，优先选择内置服务模板。 * 如果您接入已有业务 API，先验证后端连通性，再创建服务和路由。 * 如果您需要列表级过滤，重点检查 APISpec 中的资源提取器和响应过滤器。 --- ## 核心概念与对应 API ### Gateway Gateway 是底层 APIG 网关实例，通常由运维人员维护。它可以是共享网关，也可以是专属网关；发布后会同步 APIG 网关 ID、上游源、默认上游服务和插件配置等信息。 #### 模块能力 * 管理共享或专属 APIG 网关资源。 * 维护网关容量、VPC、子网、节点规格、WASM 插件镜像和默认上游配置。 * 通过发布动作将本地网关配置同步到 APIG。 #### API |**API Action** |**用途** | |---|---| |ListGateways |查询可用网关列表。 | |CreateGateway |创建网关。 | |GetGateway |查询网关详情。 | |UpdateGateway |更新网关名称、容量、网络、规格或插件镜像。 | |DeleteGateway |删除网关。 | |PublishGateway |将网关配置同步到 APIG。 | ### 后端服务模板后端服务模板由平台运维维护，用于封装常见后端服务的域名、端口、协议、超时、预置路由和 APISpec。用户创建内置服务时，选择模板即可生成服务和路由。 #### 模块能力 * 维护 VikingDB、MCP 等标准后端服务的模板。 * 为模板绑定多个路由模板，每个路由模板可包含默认权限池、资源类型和 APISpec。 * 提供创建服务时的下拉选项和路由模板选项。 #### API |**API Action** |**用途** | |---|---| |ListTemplates、GetTemplate |运维面查询模板和模板详情。 | |CreateTemplate、UpdateTemplate、DeleteTemplate |运维面维护后端服务模板。 | |ListRouteTemplates、GetRouteTemplate |运维面查询模板下的路由模板。 | |CreateRouteTemplate、UpdateRouteTemplate、DeleteRouteTemplate |运维面维护路由模板。 | |DescribeTemplateOptions |控制面获取可选模板。 | |DescribeRouteTemplateOptions |控制面获取模板下可选路由。 | ### 权限网关服务 Service Service 是用户侧核心实体，代表一个接入权限网关的后端服务实例。它绑定后端连接信息、权限空间、项目、标签和可访问域名。创建后需要发布，配置才会同步到 APIG 并对流量生效。 #### 模块能力 * 绑定后端服务配置，包括域名、端口、协议、TLS 和超时。 * 绑定 PermissionSpaceId 和可读的权限空间名称。 * 承载服务下的多条路由，并通过发布动作同步到 APIG。 * 支持内置模板创建和自定义后端创建两种方式。 #### API |**API Action** |**用途** | |---|---| |CreateServiceFromTemplate |基于内置服务模板创建服务，可选择部分路由模板。 | |CreateService |创建自定义后端服务，可同时内嵌路由列表。 | |ListServices |按关键词、后端类型、状态、权限空间、项目、标签分页查询服务。 | |GetService |按服务 ID 或服务名称查询详情。 | |UpdateService |更新服务描述等元信息。 | |DeleteService |删除服务。 | |PublishService |将服务配置同步到 APIG。 | |CheckServiceName |检查服务名是否可用。 | |ValidateBackend |验证自定义后端是否可达。 | ### 路由 Route Route 定义请求如何匹配、如何路由、如何映射到权限管理。它包含 HTTP 方法、路径、匹配类型、优先级、权限池、资源类型、鉴权资源类型和可选 APISpec。 #### 模块能力 * 在服务内维护 API 路由，路由名称在服务内唯一。 * 配置 Method、Path、PathMatchType 和 Priority。 * 通过 PermissionPool、ResourceType 和 AuthResourceType 对接权限管理语义。 * 支持从路由模板创建、单条创建、批量创建、发布和禁用。 #### API |**API Action** |**用途** | |---|---| |CreateRoute |为服务创建单条路由。 | |CreateRouteFromTemplate |基于路由模板创建路由，可覆盖路由名和权限池。 | |BatchCreateRoutes |批量创建路由，最多 50 条，支持 SKIP、UPSERT、STRICT、SYNC 模式。 | |ListRoutes |按关键词、方法、状态、排序条件分页查询路由。 | |GetRoute |查询路由详情。 | |UpdateRoute |更新路由匹配、权限池、资源类型、描述或 APISpec。 | |DeleteRoute |删除路由。 | |DisableRoute |将路由状态设为 inactive 并在 APIG 上禁用。 | |PublishRoute |将单条路由配置同步到 APIG。 | #### 典型规则 * Priority 当前语义为数值越小越优先，默认值为 100。 * Path 应保持稳定，避免用会频繁变化的路径片段作为权限标识。 * PermissionPool、ResourceType 和 ActionValue 应与权限管理侧资源动作模型保持一致。 ### APISpec、Extractors 与 ResponseFilters APISpec 决定数据面插件如何从请求和响应中识别权限语义。它包含资源标识符、操作类型、操作值、属性提取器和响应过滤器。 #### 模块能力 * 通过 IdentifierType 和 IdentifierValue 定位资源标识。 * 通过 ActionType 和 ActionValue 映射权限管理动作。 * 通过 Extractors 从 Header、Body、Query 或 Path 中提取资源属性。 * 通过 ResponseFilters 对数组或单对象响应做权限过滤。 #### 典型字段 |**字段** |**含义** |**示例** | |---|---|---| |IdentifierType |资源标识符类型，支持路径、路径前缀或 Header。 |PATH、PATH_PREFIX、HEADER | |IdentifierValue |资源标识位置或值，常用 JSON Pointer 或路径变量。 |/collection_name | |ActionType |动作类型，用于归类读、写、删除等语义。 |read、write | |ActionValue |发送给权限管理的动作 key。 |search、create | |Extractors |从请求中提取资源属性，可标记是否用于鉴权。 |从 PATH 提取集合名。 | |ResponseFilters |从响应中识别资源并过滤无权限项。 |过滤 /data/items。 | #### 响应过滤模式 |**模式** |**含义** |**适用响应** | |---|---|---| |ARRAY |按数组路径遍历资源项，逐项做权限判断或过滤。 |列表、搜索结果 | |SINGLE |按单对象路径识别资源，判断当前对象是否可返回。 |详情接口 | ### 文档解析文档解析用于从 Swagger、OpenAPI 或自然语言文档中生成路由草稿。解析接口返回 DocumentId，调用方再通过状态接口查询解析结果。 #### API |**API Action** |**用途** | |---|---| |ParseDocument |上传接口文档并生成路由规则草稿。 | |GetDocumentStatus |查询文档解析状态和解析出的路由列表。 | #### 处理顺序 1. 上传文档并传入 DocType。 2. 获取 DocumentId。 3. 轮询 GetDocumentStatus，直到状态为 completed 或 failed。 4. 人工检查解析出的 ParsedRoute，补齐权限池、资源类型和 APISpec。 5. 通过 BatchCreateRoutes 或单条创建接口保存到服务。 ### 数据面路由规范数据面接口供 WASM 插件调用。插件根据 APIG 路由 ID 获取权限规范，再按路由配置执行资源提取、鉴权和响应过滤。 #### API |**API Action** |**用途** | |---|---| |GetRouteSpec |根据 APIG 路由 ID 获取单条路由规范。 | |BatchGetRouteSpecs |批量获取路由规范。 | ### 标签与配额标签用于服务治理、资源筛选和运营管理；配额用于创建或发布前确认容量边界。 #### API |**API Action** |**用途** | |---|---| |DescribeTagOptions |获取控制面可选标签。 | |TagResources |为服务或相关资源绑定标签。 | |UntagResources |解除资源标签。 | |ListTagsForResources |查询或按标签过滤资源。 | |GetQuotaConfirm |确认指定服务码、配额码和维度下的配额。 | --- ## 模块关系与职责边界 |**模块** |**负责什么** |**不负责什么** | |---|---|---| |Gateway |承载 APIG 网关资源、插件和默认上游。 |不表达用户业务路由。 | |模板 |沉淀标准后端服务和预置路由。 |不保存用户实例状态。 | |Service |绑定用户后端、权限空间、项目和标签。 |不直接决定单个 API 的资源提取规则。 | |Route |定义请求匹配、权限池、资源类型和 APISpec。 |不维护 Cedar policy。 | |APISpec |定义资源标识、动作和请求/响应提取规则。 |不替代权限管理中的资源、动作和策略。 | |数据面插件 |按路由规范执行鉴权和过滤。 |不在本地持久化业务授权关系。 | |权限管理 |返回最终 allow/deny 结果。 |不负责 HTTP 路由匹配和后端转发。 | --- ## 使用流程 ### 流程一：基于内置模板创建服务 1. **准备权限空间。** 在权限管理中创建或选择权限空间，确认资源类型、动作和基础策略已准备好。 2. **选择模板。** 调用 DescribeTemplateOptions 获取模板列表，按后端类型或关键词选择模板。 3. **选择路由模板。** 调用 DescribeRouteTemplateOptions 查看模板下路由，确认默认权限池、资源类型和 APISpec。 4. **创建服务。** 调用 CreateServiceFromTemplate，填写服务名、权限空间和需要创建的路由模板 ID。 5. **检查服务。** 调用 GetService 和 ListRoutes 确认服务与路由已生成。 6. **发布服务。** 调用 PublishService 将配置同步到 APIG，获取公网或内网域名。 ### 流程二：自定义后端服务接入 1. **验证后端。** 填写 BackendConfig，调用 ValidateBackend 检查域名、端口、协议和 TLS 配置。 2. **检查名称。** 调用 CheckServiceName，确保服务名在账号内可用。 3. **创建服务。** 调用 CreateService，绑定权限空间、项目、标签和后端配置。 4. **创建路由。** 通过 CreateRoute 或 BatchCreateRoutes 添加路由，并配置权限池、资源类型和 APISpec。 5. **发布变更。** 调用 PublishService 或 PublishRoute，将服务和路由同步到 APIG。 6. **联调鉴权。** 用真实请求验证路由匹配、资源提取、权限管理策略命中和后端转发。 ### 流程三：从 API 文档解析路由 1. **上传文档。** 调用 ParseDocument，选择 Swagger、OpenAPI 或 NaturalLanguage 文档类型。 2. **等待解析完成。** 使用 GetDocumentStatus 查询状态，完成后获取路由草稿。 3. **人工校正。** 检查路径、方法、权限池、资源类型、动作值和资源标识符，修正自动解析不确定的部分。 4. **保存路由。** 调用 BatchCreateRoutes 保存，按需要选择 SKIP、UPSERT、STRICT 或 SYNC 模式。 5. **发布验证。** 发布后使用真实请求验证鉴权和响应过滤效果。 ### 流程四：启用响应过滤 1. **确认列表结构。** 确定后端响应中资源数组或单对象所在的 JSON Pointer。 2. **配置过滤器。** 在 ResponseFilters 中设置资源类型、过滤模式、数组路径、资源路径、ID 字段和属性映射。 3. **确认权限策略。** 在权限管理中为这些资源和动作创建策略，确保对象权限查询或单项鉴权能返回正确结果。 4. **发布路由。** 调用 PublishRoute 同步 APIG。 5. **对比响应。** 使用不同权限主体请求同一接口，确认无权限资源项被过滤且分页行为符合预期。 --- ## 场景选择指南 |**场景** |**推荐能力** |**说明** | |---|---|---| |标准后端服务快速接入 |CreateServiceFromTemplate |模板已包含后端配置和预置路由，减少手动配置成本。 | |已有业务 API 接入 |ValidateBackend + CreateService |先确认后端可达，再配置服务和路由。 | |接口很多，需要批量生成 |ParseDocument + BatchCreateRoutes |先自动解析，再人工校正权限语义。 | |只需要新增一条 API |CreateRoute + PublishRoute |变更范围小，适合单接口灰度。 | |模板路由需要轻微定制 |CreateRouteFromTemplate |可覆盖路由名和权限池，其余配置复用模板。 | |全量同步路由配置 |BatchCreateRoutes 的 SYNC 模式 |会删除服务下不在请求列表中的路由，使用前需确认影响面。 | |列表接口按权限过滤 |APISpec ResponseFilters |适合搜索结果、资源列表和集合查询接口。 | |临时停止某条 API 鉴权网关流量 |DisableRoute |将路由置为 inactive 并在 APIG 上禁用。 | --- ## 与权限管理的关系权限网关不直接维护业务授权策略。它负责把 HTTP 请求映射为权限管理能够识别的主体、动作、资源和上下文；最终 allow/deny 由权限管理策略决定。 |**环节** |**权限网关** |**权限管理** | |---|---|---| |配置阶段 |服务绑定 PermissionSpaceId，路由配置资源类型、动作和 APISpec。 |创建权限空间、资源、动作和策略。 | |请求阶段 |匹配路由，从请求中提取资源标识和动作。 |根据主体、动作、资源和上下文返回鉴权结果。 | |响应阶段 |按响应过滤规则删除无权限资源项。 |提供权限反查或单项鉴权能力。 | |排障阶段 |检查路由、APISpec、发布状态和插件配置。 |检查策略状态、资源动作、引用关系和权限点模式。 | --- ## 常见问题 ### 服务创建后为什么没有生效？服务和路由创建后只是管理面记录。需要调用 PublishService 或 PublishRoute 同步到 APIG，状态变为 active 后才会对流量生效。 ### 路由优先级是越大越优先吗？当前接口定义中 Priority 的语义是数值越小越优先，默认值为 100。如果历史设计文档与接口注释不一致，以当前接口定义和 API 参考为准。 ### 路由能匹配请求，为什么仍然全部无权限？通常是权限网关和权限管理的语义没有对齐。请检查 PermissionSpaceId、ResourceType、ActionValue、资源 key 提取结果，以及权限管理中是否存在启用状态的匹配策略。 ### 什么时候选择模板，什么时候选择自定义服务？标准后端服务优先选择模板，模板已经封装后端配置、路由和部分 APISpec。已有业务 API、私有后端或路径语义差异较大的服务，使用自定义服务更合适。 ### 批量创建路由的模式怎么选？ SKIP 适合只补充新增路由；UPSERT 适合重复执行导入；STRICT 适合任何冲突都应失败的发布流程；SYNC 适合全量同步，但会删除请求列表之外的已有路由。 ### 响应过滤会替代请求前鉴权吗？不会。请求前鉴权决定请求是否可以访问当前 API；响应过滤用于列表或详情结果中的资源项裁剪。涉及敏感写操作时，应优先确保请求前鉴权准确。 ### 文档解析结果可以直接发布吗？不建议。解析结果是路由草稿，路径和方法通常较准确，但权限池、资源类型、动作值和响应过滤规则仍需要人工确认后再保存和发布。

智能体身份和权限管理平台