Nacos v3 HTTP API 鉴权规范鉴权元组、Filter 分流与公开端点治理【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos v3 HTTP API 将鉴权模型落地为「鉴权元组 注解声明 过滤器分流」三层结构每个受保护端点通过Secured注解声明apiType signType resource action tags五元组服务端由AuthAdminFilter与AuthFilter两个过滤器按 API 受众自动分流处理并以明确的规则区分公开端点、初始化端点与需鉴权端点。本文以 Nacos 仓库中的 HTTP API 鉴权规范 为主体结合 鉴权与权限规范、默认鉴权插件实现规范 以及core、auth、api模块的源码实现完整还原 v3 HTTP API 的鉴权设计帮助你理解端点注解的写法、过滤器分流的底层逻辑、公开端点的治理边界以及如何基于该模型为新增 API 正确声明鉴权元数据。1. 规范定位共享鉴权模型在 HTTP 传输层的落地点Nacos 的鉴权领域模型是跨协议共享的。鉴权与权限规范 定义了 HTTP API、gRPC API、插件 API 和服务端内部调用共用的认证与权限模型其核心链路为请求身份 - 已认证主体 - 角色 - 权限 - 资源/动作而 HTTP API 鉴权规范 是这一共享模型在 v3 HTTP API 上的传输层具体化它规定每个 HTTP 端点如何声明鉴权元数据、服务端如何通过过滤器按受众分流、哪些端点被明确豁免鉴权。插件契约则由 鉴权插件规范 和 可见性插件规范 定义三者共同构成「领域模型 → 传输层规范 → 插件契约」的完整链条。2. 鉴权元组一个端点的鉴权声明由五个维度构成V3 HTTP API 的有效鉴权元组为apiType signType resource action tags各维度含义如下维度取值示例说明apiTypeOPEN_API、ADMIN_API、CONSOLE_API、内部 API区分 API 受众决定适用的鉴权开关范围与分流过滤器signTypeCONFIG、NAMING、AI、CONSOLE标识资源领域用于选择资源解析器resource/v3/ns/instance/list等受保护路径或逻辑资源名标识受保护的资源路径或逻辑资源名actionREAD、WRITE请求操作类型tagsONLY_IDENTITY、ALLOW_ANONYMOUS附加特殊行为标记2.1apiTypeAPI 受众与鉴权范围apiType枚举定义于 ApiType.java包含四种取值其语义与 鉴权与权限规范 中的描述一致值含义ADMIN_API面向维护者、工具和网关的管理 APICONSOLE_APINacos 控制台使用的 APIOPEN_API面向应用或 SDK 的客户端 APIINNER_API服务端内部 API通常由服务端身份保护apiType不仅决定 API 受众还直接决定该请求走哪一个鉴权过滤器、受哪一组鉴权开关控制详见下文第 3、5 节。2.2signType资源领域标识signType标识用于解析和授权资源的领域常见取值包括值含义CONFIG配置资源NAMING服务发现和注册资源AIMCP、Prompt、Agent、Tool 等 AI 注册中心资源CONSOLE用户、角色、权限等控制台管理资源从源码看Secured.java 中signType的默认值为SignType.NAMING即未显式声明领域时默认按命名空间/服务发现资源处理。2.3action读与写action通常为READ或WRITE查询、列表、详情、订阅、监听等只读操作对应READ创建、更新、删除、发布、注册、注销、状态变更等操作对应WRITE。虽然实现可以存储rw这类组合动作但端点注解必须使用与 API 行为匹配的明确动作Secured.java 中action的默认值为ActionTypes.READ。2.4tags特殊行为标记tags增加特殊行为常见值包括ONLY_IDENTITY该端点只做身份校验跳过权限校验。在 AbstractWebAuthFilter.java 中过滤器遍历注解的tags一旦命中Constants.Tag.ONLY_IDENTITY便跳过validateAuthority直接放行。ALLOW_ANONYMOUS允许匿名访问详见第 6 节已实现例外。3. Filter 分流两个过滤器按apiType各司其职当前代码按apiType分发鉴权由两个过滤器完成过滤器处理范围源码位置AuthAdminFilterSecured.apiType()为ApiType.ADMIN_API的方法AuthAdminFilter.javaAuthFilterapiType()不是ADMIN_API的受保护 API包括OPEN_API、CONSOLE_API和内部 APIAuthFilter.java两个过滤器都继承自AbstractWebAuthFilter仅通过覆写isMatchFilter(Secured)决定自己接管哪些请求// AuthAdminFilter只处理 ADMIN_API Override protected boolean isMatchFilter(Secured secured) { return ApiType.ADMIN_API.equals(secured.apiType()); } // AuthFilter处理其余所有受保护 API Override protected boolean isMatchFilter(Secured secured) { return !ApiType.ADMIN_API.equals(secured.apiType()); }3.1 底层鉴权执行流程AbstractWebAuthFilter的 doFilter 方法 完整串联了鉴权执行链路可归纳为以下步骤通过ControllerMethodsCache定位请求对应的 Controller 方法方法不存在或未声明Secured时直接放行未受保护的端点。读取Secured注解将apiType写入请求上下文AuthContext。调用isMatchFilter判断当前过滤器是否接管不接管则放行给另一个过滤器。调用HttpProtocolAuthService.parseIdentity从 header、参数、token、证书或连接器元数据中构造IdentityContext。检查isAuthEnabled()是否开启鉴权未开启则放行。校验服务端身份checkServerIdentity失败返回 403匹配则标记SERVER_IDENTITY后放行服务端内部调用。调用protocolAuthService.enableAuth(secured)判断该动作与领域是否启用鉴权。解析Resource并写入上下文随后validateIdentity校验身份、validateAuthority针对Permission(resource, action)校验权限。任一环节抛出AccessException时通过writeAccessDeniedResponse返回 HTTP 403 的ACCESS_DENIED响应。此外AuthFilter还覆写了 checkServerIdentity对于INNER_API在旧版本集群升级期间InnerApiAuthEnabled未启用时沿用旧逻辑跳过服务端身份校验以兼容升级窗口。4. 必要注解Secured的声明要求与选择V3 HTTP API 应声明Secured除非该端点被明确设计为以下四类之一公开端点初始化端点健康检查端点已记录的兼容路径。Secured.java 中注解的完整字段如下字段默认值目的actionActionTypes.READ需要的动作通常为READ或WRITEresource空字符串显式资源名主要用于SPECIFIED或控制台资源signTypeSignType.NAMING用于资源解析和权限判断的领域parserDefaultResourceParser.class默认解析器不足时使用的自定义资源解析器tags{}复制到Resource.properties的附加元数据apiTypeApiType.OPEN_APIAPI 受众与鉴权范围apiType的选择有明确约定Admin API 应使用ApiType.ADMIN_APIConsole API 应使用ApiType.CONSOLE_APIOpen API 应使用ApiType.OPEN_API。资源解析遵循的优先级为resource非空时直接转换为SPECIFIED资源 → 方法级parser非默认时由其解析请求保留注解声明的signType和apiType→ 否则按signType选择协议对应的类型化 Parser → 找不到时由DefaultResourceParser返回空资源。需要特别注意的是显式指定的 Parser 构造或解析失败时不得静默降级为空资源因为继续使用更宽泛的资源可能削弱鉴权约束该失败应作为请求处理错误抛出。5. 公开端点与初始化端点豁免鉴权的边界端点只有在被明确设计为公开端点、初始化端点、健康检查端点或兼容端点时才可以不声明Secured。公开端点必须在文档中标记为公开并且不得暴露敏感运维细节。5.1 已实现的公开端点清单以下端点已实现并公开对应的 Admin API 和 Console API 文档已将其标记为公开接口无需身份信息端点归属GET /v3/admin/core/stateAdmin APIGET /v3/admin/core/state/livenessAdmin APIGET /v3/admin/core/state/readinessAdmin APIGET /v3/console/server/stateConsole APIGET /v3/console/server/announcementConsole APIGET /v3/console/server/guideConsole APIGET /v3/console/health/livenessConsole APIGET /v3/console/health/readinessConsole API可见公开端点的典型构成是两类服务状态/健康检查类state、liveness、readiness服务于未认证的探活探测控制台公告/指南类announcement、guide服务于未登录用户在登录页获取必要信息。这与 鉴权与权限规范 中「由服务端状态保护的一次性管理员初始化以及为未认证探测而设计的健康检查或状态端点」的公开原则一致。5.2 初始化端点行为初始化行为遵循「仅限首次」原则/v3/auth/user/admin可以在不存在全局管理员且鉴权系统为NACOS时创建第一个管理员用户一旦全局管理员已经存在该端点必须被拒绝。该端点属于 默认鉴权插件实现规范 中的默认鉴权 API 族是典型的一次性初始化端点它只在无管理员状态下有意暴露避免任意用户重复初始化管理员账户。5.3 兼容性公开的治理当某个端点因兼容性而公开、而不是当前设计要求公开时鉴权与权限规范 要求新文档化 API 应作为主 API旧端点只作为兼容面保留。这意味着公开端点不是一成不变的新增开发应以新规范为准旧端点仅为既有客户端保留。6. 插件提供的 Auth API/v3/auth/*的面归属/v3/auth/*API 面属于鉴权插件而不是 Open、Admin 或 Console API 的任一家族。其治理规则如下默认插件必须遵循规范随 Nacos 一起发布的 Nacos 默认鉴权插件 必须遵循 Nacos HTTP API 规范 对路径形态、响应形态、参数校验和错误行为的规范。第三方插件建议遵循第三方鉴权插件通过 Nacos 暴露 HTTP API 时也建议遵循同一套规则以保证 API 消费方尤其是 Java 客户端的兼容性。默认插件拥有的 v3 API 族包括详见 默认鉴权插件实现规范路径目的/v3/auth/user用户管理和密码更新/v3/auth/user/login登录和 token 签发/v3/auth/user/admin当不存在全局管理员时进行管理员初始化/v3/auth/role角色管理/v3/auth/permission权限管理/v3/auth/visibility显式资源可见性授权管理这些端点按路径不归属于 Open、Admin 或 Console API但仍必须遵守 Nacos v3 API 的响应、错误和鉴权约定。例如/v3/auth/user/login是有意公开的登录端点而管理端点console/users、console/roles、console/permissions等必须使用控制台域的Secured资源保护。7. 已实现例外AI 客户端端点的匿名访问以下已实现行为需要在端点级文档中说明部分 AI 客户端端点通过ALLOW_ANONYMOUS允许匿名访问。这是鉴权规范中明确记录的例外。结合 默认鉴权插件实现规范匿名 AI 访问只有在以下条件同时满足时才允许端点标记该请求允许匿名访问即携带ALLOW_ANONYMOUStagauth:nacos插件的anonymous.ai.enabled配置已启用默认false默认插件将请求接受为内置匿名身份。同时有一个重要的安全约束只有当请求没有显式提供任何默认鉴权凭据 key 时才允许降级为匿名身份。提供Authorization、accessToken、username或password都视为显式凭据存在——即使对应值为空白也一样如果这些凭据为空白或无效插件必须返回认证失败而不能降级为匿名身份。8. 鉴权开关与插件选择的配套配置虽然鉴权元组由注解声明但鉴权是否真正生效由一组开关控制按 API 受众划分配置细节见 鉴权与权限规范 与 默认鉴权插件实现规范配置范围nacos.core.auth.enabled启用 Open API 和通用鉴权系统nacos.core.auth.admin.enabled启用 Admin API 鉴权nacos.core.auth.console.enabled启用 Console API 和登录行为鉴权nacos.plugin.auth.type启动时选择鉴权插件默认nacosnacos.core.auth.system.type是历史 aliasnacos.core.auth.server.identity.key/nacos.core.auth.server.identity.value服务端之间调用的身份 key/value在 AbstractWebAuthFilter 中isAuthEnabled()返回false时直接放行因此这些开关构成了端点鉴权的总闸门即使端点声明了Secured对应受众的鉴权开关未开启时请求也不会被拦截。9. 从 HTTP 鉴权到授权与可见性请求准入不等于数据可见最后需要强调一个易混淆点通过Secured鉴权只代表请求级准入通过不代表所有匹配数据行都可见。Nacos 将请求级授权与数据级可见性分开处理层次主要问题典型 SPI鉴权插件该调用方是否可以针对解析出的资源/动作调用这个 APIAuthPluginService可见性插件该调用方是否可以看见或修改这个具体资源或范围查询应该返回哪些资源VisibilityService对于具备可见性语义的资源推荐请求流程为Secured AuthPlugin - VisibilityService - 业务操作单资源读在可见性拒绝时可以返回 not found 以隐藏资源存在性写操作在调用方能定位资源但不能修改时应返回 access denied列表和搜索 API 必须在产生分页数据和总数前应用可见性。这条链路完整落地于默认鉴权插件与默认可见性实现名称同为nacos当前用于 AI 资源具体行为见 默认鉴权插件实现规范 与 可见性插件规范。小结Nacos v3 HTTP API 的鉴权设计可以概括为三条主线元组声明apiType signType resource action tags五个维度完整描述一个端点的鉴权语义、过滤器分流AuthAdminFilter与AuthFilter按apiType精确分工底层共用AbstractWebAuthFilter的执行链路、边界治理公开端点、初始化端点、健康检查端点的豁免规则以及ALLOW_ANONYMOUS匿名访问的例外约束。为新增端点声明鉴权时应遵循默认声明Secured按受众选择apiType按操作类型选择action只有明确设计的公开/初始化/健康检查端点才可豁免且公开端点必须在文档中显式标记。深入理解可继续阅读仓库中的相关文档与源码HTTP API 鉴权规范、鉴权与权限规范、鉴权插件规范、可见性插件规范、默认鉴权插件实现规范以及核心实现 AbstractWebAuthFilter.java、AuthAdminFilter.java、AuthFilter.java、Secured.java 与 ApiType.java。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 7:43:24 · 阅读 1.2k Nacos v3 HTTP API 鉴权规范：鉴权元组、Filter 分流与公开端点治理
Nacos v3 HTTP API 鉴权规范鉴权元组、Filter 分流与公开端点治理【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos v3 HTTP API 将鉴权模型落地为「鉴权元组 注解声明 过滤器分流」三层结构每个受保护端点通过Secured注解声明apiType signType resource action tags五元组服务端由AuthAdminFilter与AuthFilter两个过滤器按 API 受众自动分流处理并以明确的规则区分公开端点、初始化端点与需鉴权端点。本文以 Nacos 仓库中的 HTTP API 鉴权规范 为主体结合 鉴权与权限规范、默认鉴权插件实现规范 以及core、auth、api模块的源码实现完整还原 v3 HTTP API 的鉴权设计帮助你理解端点注解的写法、过滤器分流的底层逻辑、公开端点的治理边界以及如何基于该模型为新增 API 正确声明鉴权元数据。1. 规范定位共享鉴权模型在 HTTP 传输层的落地点Nacos 的鉴权领域模型是跨协议共享的。鉴权与权限规范 定义了 HTTP API、gRPC API、插件 API 和服务端内部调用共用的认证与权限模型其核心链路为请求身份 - 已认证主体 - 角色 - 权限 - 资源/动作而 HTTP API 鉴权规范 是这一共享模型在 v3 HTTP API 上的传输层具体化它规定每个 HTTP 端点如何声明鉴权元数据、服务端如何通过过滤器按受众分流、哪些端点被明确豁免鉴权。插件契约则由 鉴权插件规范 和 可见性插件规范 定义三者共同构成「领域模型 → 传输层规范 → 插件契约」的完整链条。2. 鉴权元组一个端点的鉴权声明由五个维度构成V3 HTTP API 的有效鉴权元组为apiType signType resource action tags各维度含义如下维度取值示例说明apiTypeOPEN_API、ADMIN_API、CONSOLE_API、内部 API区分 API 受众决定适用的鉴权开关范围与分流过滤器signTypeCONFIG、NAMING、AI、CONSOLE标识资源领域用于选择资源解析器resource/v3/ns/instance/list等受保护路径或逻辑资源名标识受保护的资源路径或逻辑资源名actionREAD、WRITE请求操作类型tagsONLY_IDENTITY、ALLOW_ANONYMOUS附加特殊行为标记2.1apiTypeAPI 受众与鉴权范围apiType枚举定义于 ApiType.java包含四种取值其语义与 鉴权与权限规范 中的描述一致值含义ADMIN_API面向维护者、工具和网关的管理 APICONSOLE_APINacos 控制台使用的 APIOPEN_API面向应用或 SDK 的客户端 APIINNER_API服务端内部 API通常由服务端身份保护apiType不仅决定 API 受众还直接决定该请求走哪一个鉴权过滤器、受哪一组鉴权开关控制详见下文第 3、5 节。2.2signType资源领域标识signType标识用于解析和授权资源的领域常见取值包括值含义CONFIG配置资源NAMING服务发现和注册资源AIMCP、Prompt、Agent、Tool 等 AI 注册中心资源CONSOLE用户、角色、权限等控制台管理资源从源码看Secured.java 中signType的默认值为SignType.NAMING即未显式声明领域时默认按命名空间/服务发现资源处理。2.3action读与写action通常为READ或WRITE查询、列表、详情、订阅、监听等只读操作对应READ创建、更新、删除、发布、注册、注销、状态变更等操作对应WRITE。虽然实现可以存储rw这类组合动作但端点注解必须使用与 API 行为匹配的明确动作Secured.java 中action的默认值为ActionTypes.READ。2.4tags特殊行为标记tags增加特殊行为常见值包括ONLY_IDENTITY该端点只做身份校验跳过权限校验。在 AbstractWebAuthFilter.java 中过滤器遍历注解的tags一旦命中Constants.Tag.ONLY_IDENTITY便跳过validateAuthority直接放行。ALLOW_ANONYMOUS允许匿名访问详见第 6 节已实现例外。3. Filter 分流两个过滤器按apiType各司其职当前代码按apiType分发鉴权由两个过滤器完成过滤器处理范围源码位置AuthAdminFilterSecured.apiType()为ApiType.ADMIN_API的方法AuthAdminFilter.javaAuthFilterapiType()不是ADMIN_API的受保护 API包括OPEN_API、CONSOLE_API和内部 APIAuthFilter.java两个过滤器都继承自AbstractWebAuthFilter仅通过覆写isMatchFilter(Secured)决定自己接管哪些请求// AuthAdminFilter只处理 ADMIN_API Override protected boolean isMatchFilter(Secured secured) { return ApiType.ADMIN_API.equals(secured.apiType()); } // AuthFilter处理其余所有受保护 API Override protected boolean isMatchFilter(Secured secured) { return !ApiType.ADMIN_API.equals(secured.apiType()); }3.1 底层鉴权执行流程AbstractWebAuthFilter的 doFilter 方法 完整串联了鉴权执行链路可归纳为以下步骤通过ControllerMethodsCache定位请求对应的 Controller 方法方法不存在或未声明Secured时直接放行未受保护的端点。读取Secured注解将apiType写入请求上下文AuthContext。调用isMatchFilter判断当前过滤器是否接管不接管则放行给另一个过滤器。调用HttpProtocolAuthService.parseIdentity从 header、参数、token、证书或连接器元数据中构造IdentityContext。检查isAuthEnabled()是否开启鉴权未开启则放行。校验服务端身份checkServerIdentity失败返回 403匹配则标记SERVER_IDENTITY后放行服务端内部调用。调用protocolAuthService.enableAuth(secured)判断该动作与领域是否启用鉴权。解析Resource并写入上下文随后validateIdentity校验身份、validateAuthority针对Permission(resource, action)校验权限。任一环节抛出AccessException时通过writeAccessDeniedResponse返回 HTTP 403 的ACCESS_DENIED响应。此外AuthFilter还覆写了 checkServerIdentity对于INNER_API在旧版本集群升级期间InnerApiAuthEnabled未启用时沿用旧逻辑跳过服务端身份校验以兼容升级窗口。4. 必要注解Secured的声明要求与选择V3 HTTP API 应声明Secured除非该端点被明确设计为以下四类之一公开端点初始化端点健康检查端点已记录的兼容路径。Secured.java 中注解的完整字段如下字段默认值目的actionActionTypes.READ需要的动作通常为READ或WRITEresource空字符串显式资源名主要用于SPECIFIED或控制台资源signTypeSignType.NAMING用于资源解析和权限判断的领域parserDefaultResourceParser.class默认解析器不足时使用的自定义资源解析器tags{}复制到Resource.properties的附加元数据apiTypeApiType.OPEN_APIAPI 受众与鉴权范围apiType的选择有明确约定Admin API 应使用ApiType.ADMIN_APIConsole API 应使用ApiType.CONSOLE_APIOpen API 应使用ApiType.OPEN_API。资源解析遵循的优先级为resource非空时直接转换为SPECIFIED资源 → 方法级parser非默认时由其解析请求保留注解声明的signType和apiType→ 否则按signType选择协议对应的类型化 Parser → 找不到时由DefaultResourceParser返回空资源。需要特别注意的是显式指定的 Parser 构造或解析失败时不得静默降级为空资源因为继续使用更宽泛的资源可能削弱鉴权约束该失败应作为请求处理错误抛出。5. 公开端点与初始化端点豁免鉴权的边界端点只有在被明确设计为公开端点、初始化端点、健康检查端点或兼容端点时才可以不声明Secured。公开端点必须在文档中标记为公开并且不得暴露敏感运维细节。5.1 已实现的公开端点清单以下端点已实现并公开对应的 Admin API 和 Console API 文档已将其标记为公开接口无需身份信息端点归属GET /v3/admin/core/stateAdmin APIGET /v3/admin/core/state/livenessAdmin APIGET /v3/admin/core/state/readinessAdmin APIGET /v3/console/server/stateConsole APIGET /v3/console/server/announcementConsole APIGET /v3/console/server/guideConsole APIGET /v3/console/health/livenessConsole APIGET /v3/console/health/readinessConsole API可见公开端点的典型构成是两类服务状态/健康检查类state、liveness、readiness服务于未认证的探活探测控制台公告/指南类announcement、guide服务于未登录用户在登录页获取必要信息。这与 鉴权与权限规范 中「由服务端状态保护的一次性管理员初始化以及为未认证探测而设计的健康检查或状态端点」的公开原则一致。5.2 初始化端点行为初始化行为遵循「仅限首次」原则/v3/auth/user/admin可以在不存在全局管理员且鉴权系统为NACOS时创建第一个管理员用户一旦全局管理员已经存在该端点必须被拒绝。该端点属于 默认鉴权插件实现规范 中的默认鉴权 API 族是典型的一次性初始化端点它只在无管理员状态下有意暴露避免任意用户重复初始化管理员账户。5.3 兼容性公开的治理当某个端点因兼容性而公开、而不是当前设计要求公开时鉴权与权限规范 要求新文档化 API 应作为主 API旧端点只作为兼容面保留。这意味着公开端点不是一成不变的新增开发应以新规范为准旧端点仅为既有客户端保留。6. 插件提供的 Auth API/v3/auth/*的面归属/v3/auth/*API 面属于鉴权插件而不是 Open、Admin 或 Console API 的任一家族。其治理规则如下默认插件必须遵循规范随 Nacos 一起发布的 Nacos 默认鉴权插件 必须遵循 Nacos HTTP API 规范 对路径形态、响应形态、参数校验和错误行为的规范。第三方插件建议遵循第三方鉴权插件通过 Nacos 暴露 HTTP API 时也建议遵循同一套规则以保证 API 消费方尤其是 Java 客户端的兼容性。默认插件拥有的 v3 API 族包括详见 默认鉴权插件实现规范路径目的/v3/auth/user用户管理和密码更新/v3/auth/user/login登录和 token 签发/v3/auth/user/admin当不存在全局管理员时进行管理员初始化/v3/auth/role角色管理/v3/auth/permission权限管理/v3/auth/visibility显式资源可见性授权管理这些端点按路径不归属于 Open、Admin 或 Console API但仍必须遵守 Nacos v3 API 的响应、错误和鉴权约定。例如/v3/auth/user/login是有意公开的登录端点而管理端点console/users、console/roles、console/permissions等必须使用控制台域的Secured资源保护。7. 已实现例外AI 客户端端点的匿名访问以下已实现行为需要在端点级文档中说明部分 AI 客户端端点通过ALLOW_ANONYMOUS允许匿名访问。这是鉴权规范中明确记录的例外。结合 默认鉴权插件实现规范匿名 AI 访问只有在以下条件同时满足时才允许端点标记该请求允许匿名访问即携带ALLOW_ANONYMOUStagauth:nacos插件的anonymous.ai.enabled配置已启用默认false默认插件将请求接受为内置匿名身份。同时有一个重要的安全约束只有当请求没有显式提供任何默认鉴权凭据 key 时才允许降级为匿名身份。提供Authorization、accessToken、username或password都视为显式凭据存在——即使对应值为空白也一样如果这些凭据为空白或无效插件必须返回认证失败而不能降级为匿名身份。8. 鉴权开关与插件选择的配套配置虽然鉴权元组由注解声明但鉴权是否真正生效由一组开关控制按 API 受众划分配置细节见 鉴权与权限规范 与 默认鉴权插件实现规范配置范围nacos.core.auth.enabled启用 Open API 和通用鉴权系统nacos.core.auth.admin.enabled启用 Admin API 鉴权nacos.core.auth.console.enabled启用 Console API 和登录行为鉴权nacos.plugin.auth.type启动时选择鉴权插件默认nacosnacos.core.auth.system.type是历史 aliasnacos.core.auth.server.identity.key/nacos.core.auth.server.identity.value服务端之间调用的身份 key/value在 AbstractWebAuthFilter 中isAuthEnabled()返回false时直接放行因此这些开关构成了端点鉴权的总闸门即使端点声明了Secured对应受众的鉴权开关未开启时请求也不会被拦截。9. 从 HTTP 鉴权到授权与可见性请求准入不等于数据可见最后需要强调一个易混淆点通过Secured鉴权只代表请求级准入通过不代表所有匹配数据行都可见。Nacos 将请求级授权与数据级可见性分开处理层次主要问题典型 SPI鉴权插件该调用方是否可以针对解析出的资源/动作调用这个 APIAuthPluginService可见性插件该调用方是否可以看见或修改这个具体资源或范围查询应该返回哪些资源VisibilityService对于具备可见性语义的资源推荐请求流程为Secured AuthPlugin - VisibilityService - 业务操作单资源读在可见性拒绝时可以返回 not found 以隐藏资源存在性写操作在调用方能定位资源但不能修改时应返回 access denied列表和搜索 API 必须在产生分页数据和总数前应用可见性。这条链路完整落地于默认鉴权插件与默认可见性实现名称同为nacos当前用于 AI 资源具体行为见 默认鉴权插件实现规范 与 可见性插件规范。小结Nacos v3 HTTP API 的鉴权设计可以概括为三条主线元组声明apiType signType resource action tags五个维度完整描述一个端点的鉴权语义、过滤器分流AuthAdminFilter与AuthFilter按apiType精确分工底层共用AbstractWebAuthFilter的执行链路、边界治理公开端点、初始化端点、健康检查端点的豁免规则以及ALLOW_ANONYMOUS匿名访问的例外约束。为新增端点声明鉴权时应遵循默认声明Secured按受众选择apiType按操作类型选择action只有明确设计的公开/初始化/健康检查端点才可豁免且公开端点必须在文档中显式标记。深入理解可继续阅读仓库中的相关文档与源码HTTP API 鉴权规范、鉴权与权限规范、鉴权插件规范、可见性插件规范、默认鉴权插件实现规范以及核心实现 AbstractWebAuthFilter.java、AuthAdminFilter.java、AuthFilter.java、Secured.java 与 ApiType.java。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考