Nacos 可见性授权升级指南permissions.resource 字段扩容至 512 字符的完整方案【免费下载链接】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导读本文聚焦 Nacos 默认认证插件default auth plugin中显式可见性授权explicit visibility grants落地时的一个关键前置升级将权限表permissions.resource列从 512 字符以下扩容至VARCHAR(512)以完整承载可见性插件写入的规范资源标识符visibility/{namespaceId}/{resourceType}/{resourceName}。读者将掌握 MySQL、Derby、PostgreSQL、Oracle 四种数据库的迁移脚本、MySQL InnoDB 索引长度前置检查方法以及只扩列、不建反向索引这一设计边界的源码依据与测试佐证。一、升级背景与适用范围1.1 什么时候需要执行本次升级根据 doc/visibility-permission-resource-upgrade.md 的说明本次升级适用于同时满足以下条件的部署从permissions.resource长度小于 512 字符的旧库结构升级而来在默认认证插件nacos-default-auth-plugin中使用了显式可见性授权explicit visibility grants。如果旧库中resource列已经是 512 字符例如全新安装时直接使用新 schema则无需执行本文的迁移语句只有从旧结构升级且要启用可见性授权时才需要。1.2 为什么要扩容可见性插件visibility plugin负责判定某个资源对调用方是否可见它与认证auth职责分离auth 决定你是谁、能对目标资源做什么visibility 决定目标资源或范围查询中的资源对你是否可见。当前 Nacos 将其应用于 AI 注册中心资源允许资源私有PRIVATE、公开PUBLIC或通过显式授权对指定用户可见。当用户通过授权接口为某用户授予某资源的可见性权限时默认实现会把**原始规范资源标识符canonical resource identifier**原样写入permissions.resource列形如visibility/{namespaceId}/{resourceType}/{resourceName}以plugin-default-impl/nacos-default-auth-plugin中的 DefaultVisibilityService.java 为例其资源标识符构造逻辑为private static final String RESOURCE_PREFIX visibility; private String buildResourceIdentifier(VisibilityResource res) { String ns StringUtils.isBlank(res.getNamespaceId()) ? Constants.DEFAULT_NAMESPACE_ID : res.getNamespaceId(); return RESOURCE_PREFIX / ns / res.getResourceType() / res.getResourceName(); }而 VisibilityGrantRoleHelper.java 中持久化键的构造与此一致private static final String RESOURCE_IDENTIFIER_PREFIX visibility/; static String buildResourceIdentifier(String namespaceId, String resourceType, String resourceName) { return RESOURCE_IDENTIFIER_PREFIX normalizeNamespaceId(namespaceId) / normalizeResourceType(resourceType) / resourceName; }其中normalizeNamespaceId将空命名空间规范化为默认命名空间publicnormalizeResourceType会将资源类型 trim 并转小写。可见真实写入的标识符长度会随命名空间 ID、资源类型、资源名称的长度线性增长旧结构下 255 字符或更短的resource列不足以容纳较长的资源标识符因此必须扩容。1.3 存储约定禁止改写与哈希升级文档明确强调了一条重要约束Do not translate, escape, hash, or normalize the stored value beyond the canonical resource construction rules.即不要对已存储的值做翻译、转义、哈希或超出规范资源构造规则之外的任何规范化。标识符必须原样存储在permissions.resource中因为后续查询如findAuthorizedResourceNames依赖tryParseResourceIdentifier通过前缀匹配与三段式拆分来还原namespaceId / resourceType / resourceName见 VisibilityGrantRoleHelper.javastatic ParsedGrantResource tryParseResourceIdentifier(String resourceIdentifier) { if (StringUtils.isBlank(resourceIdentifier) || !resourceIdentifier.startsWith(RESOURCE_IDENTIFIER_PREFIX)) { return null; } String body resourceIdentifier.substring(RESOURCE_IDENTIFIER_PREFIX.length()); String[] parts body.split(/, 3); ... return new ParsedGrantResource(parts[0], parts[1], parts[2]); }文档同时提示基于哈希的资源键hash-based resource key可能由未来的持久化设计引入但不属于本次升级范围。二、升级脚本清单升级脚本随最终发行包一起交付在conf/目录下。本仓库源码中各数据库插件对应的脚本位于各自src/main/resources/META-INF/下数据库发行包中的脚本本仓库源码位置MySQLconf/mysql-upgrade-visibility-permission-resource.sqlmysql-upgrade-visibility-permission-resource.sqlDerbyconf/derby-upgrade-visibility-permission-resource.sqlderby-upgrade-visibility-permission-resource.sqlPostgreSQLconf/pg-upgrade-visibility-permission-resource.sqlpg-upgrade-visibility-permission-resource.sqlOracleconf/oracle-upgrade-visibility-permission-resource.sqloracle-upgrade-visibility-permission-resource.sql从源码看每个脚本的注释都保留了与文档一致的说明可见性插件在默认 RBAC permissions 表中存储规范资源标识符格式为visibility/{namespaceId}/{resourceType}/{resourceName}。三、MySQL 升级InnoDB 前置检查与 ALTER3.1 为什么 MySQL 需要特殊处理MySQL 的 permissions 表在(role, resource, action)上保持唯一权限键unique key。当resource扩容为VARCHAR(512)且使用utf8mb4字符集时该唯一索引的长度会显著增大。InnoDB 对索引键长度有限制与innodb_page_size及行格式相关旧版默认COMPACT/REDUNDANT行格式可能无法容纳变长列的大索引前缀。因此扩容前必须先确认当前 InnoDB 配置能否支持扩大的唯一索引。3.2 前置检查命令执行迁移前先运行以下检查对应 mysql-upgrade-visibility-permission-resource.sql 中建议的 pre-checksSELECT VERSION(); SHOW VARIABLES LIKE innodb_page_size; SHOW VARIABLES LIKE innodb_default_row_format; SHOW CREATE TABLE permissions;SELECT VERSION();确认 MySQL 版本评估版本对utf8mb4长索引的支持能力innodb_page_size默认 1638416KB较小的页大小会降低索引键长度上限innodb_default_row_format确认当前默认行格式新版默认为DYNAMICSHOW CREATE TABLE permissions;确认表当前引擎、字符集与行格式评估实际迁移影响面。若检查发现当前存储模式不兼容例如行格式为COMPACT或REDUNDANT需在应用迁移前配置兼容的存储模式。3.3 迁移语句与设计要点提供的脚本设置ROW_FORMATDYNAMIC并使用utf8mb4_bin排序规则保证可见性资源的匹配精确且大小写敏感ALTER TABLE permissions ROW_FORMATDYNAMIC, MODIFY COLUMN resource VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;要点解读ROW_FORMATDYNAMIC允许 InnoDB 将长VARCHAR索引前缀按动态行格式存储是支持utf8mb4长唯一索引的兼容模式utf8mb4字符集完整支持资源标识符中可能出现的各类字符包括 emoji 等四字节字符utf8mb4_bin排序规则按二进制字节比较保证visibility/...标识符的匹配精确且大小写敏感——这是可见性资源匹配正确性的关键避免_ci大小写不敏感排序规则导致的误匹配NOT NULL保持resource列仍为非空与既有权限模型保持一致。该测试 MySqlVisibilityPermissionSchemaResourceTest.java 从侧面印证了这些设计它断言新 schema 必须包含resource varchar(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL与ENGINEInnoDB ... ROW_FORMATDYNAMIC同时断言升级脚本中保留了全部四条前置检查命令与ROW_FORMATDYNAMIC配置。四、Derby / PostgreSQL / Oracle 升级与 MySQL 相比另外三种数据库只需扩展列类型无需处理行格式与索引长度问题4.1 DerbyALTER TABLE permissions ALTER COLUMN resource SET DATA TYPE VARCHAR(512);脚本见 derby-upgrade-visibility-permission-resource.sql。Derby 为 Nacos 单机/内嵌模式默认使用的数据库升级时注意在 Nacos 停止写入的情况下执行。4.2 PostgreSQLALTER TABLE permissions ALTER COLUMN resource TYPE VARCHAR(512);脚本见 pg-upgrade-visibility-permission-resource.sql。4.3 OracleALTER TABLE permissions MODIFY (resource VARCHAR2(512 CHAR) NOT NULL);脚本见 oracle-upgrade-visibility-permission-resource.sql。注意 Oracle 使用了VARCHAR2(512 CHAR)按字符而非字节计数且保留了NOT NULL约束。五、升级边界只扩列不建反向索引文档最后明确指出本次升级的刻意边界The upgrade only expands the raw canonical resource column. Grant-list-only reverse indexes such aspermissions(resource, action, role)androles(role, username)are intentionally not added.即本次升级只扩展现有resource原始列不会新增仅服务于授权列表查询的反向索引例如permissions(resource, action, role)按资源反查授权角色的索引roles(role, username)按角色反查用户的索引。这一设计意图在测试中同样被固化MySQL 的 schema 测试断言新 schema 中不包含idx_permission_resource和idx_role_user索引见 MySqlVisibilityPermissionSchemaResourceTest.java。可以推断这是为了避免在扩容迁移中引入与授权列表查询强耦合的索引结构保持迁移最小化、把索引策略留给后续持久化设计决策。六、扩容完成后的行为佐证升级完成后显式可见性授权即可正常工作。以下实现细节有助于验证迁移是否成功6.1 授权动作的持久化规范化VisibilityGrantRoleHelper.normalizeStoredAction会将写入动作规范化r存为rw与rw统一存为rw。这意味着写授权隐式包含读可见性——写授权持久化为rw后读/列表查询同样能命中该资源。6.2 内部角色名的哈希压缩为避免暴露用户名并适配roles.role varchar(50)的长度限制内部可见性授权角色名使用前缀u. SHA-256 摘要前 32 位十六进制的确定性构造见 VisibilityGrantRoleHelper.java。因此升级后观察 roles 表时会看到形如visibility_*_u.32位hex的角色名这是正常现象不要将其当作数据异常。6.3 授权管理权限规则DefaultVisibilityGrantService.checkManageGrantAuthority允许三类主体管理某资源的可见性授权未开启认证、全局管理员、资源所有者见 DefaultVisibilityGrantService.java。6.4 查询时的可见性判定DefaultVisibilityService.adviseQuery在列表/搜索场景下返回BaseVisibilityPredicate匿名用户为PUBLIC登录用户为PUBLIC_AND_OWNER并结合显式授权资源列表单资源校验validateVisibility则依次放行认证关闭、全局管理员、所有者、公开读、显式授权。更完整的查询组合规则F AND (B OR G)可参考 visibility-plugin-spec.md 与 默认认证插件规范。七、升级操作建议备份先行无论使用哪种数据库执行ALTER TABLE前先备份permissions表含唯一索引与约束定义先检查后执行MySQL严格按第三节的前置检查命令确认 InnoDB 配置兼容再执行迁移脚本停机窗口ALTER TABLE属于 DDL建议在 Nacos 服务停止写入或低峰期执行避免与运行时写请求竞争验证迁移后执行SHOW CREATE TABLE permissions;确认resource列为VARCHAR(512)MySQL 需同时确认ROW_FORMATDYNAMIC与utf8mb4_bin再启动 Nacos 进行授权/可见性验证。参考资源升级说明原文doc/visibility-permission-resource-upgrade.md可见性插件规范specs/zh-cn/auth/visibility-plugin-spec.md / specs/en/auth/visibility-plugin-spec.md默认可见性实现DefaultVisibilityService.java授权持久化实现DefaultVisibilityGrantService.java 与 VisibilityGrantRoleHelper.java四种数据库的升级脚本与测试plugin-default-impl/nacos-default-datasource-plugin/下各nacos-datasource-plugin-*模块的META-INF/*-upgrade-visibility-permission-resource.sql及对应*VisibilityPermissionSchemaResourceTest.java/output文章【免费下载链接】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），仅供参考
