1. 裸奔的 ZooKeeper 节点一次事故让我决定认真对待 ACL1.1 默认权限位全开数据就像挂在公网ZooKeeper 在分布式系统里通常承担配置下发、服务注册、分布式锁状态这类关键数据。很多教程为了演示方便创建节点时直接使用开放权限这对应的是world:anyone——任何一台能连上服务端的客户端都能对这个节点做读、写、删、改权限等各种操作。这里要先说清楚ZooKeeper 本身不是安全网关它只做访问控制不做网络传输加密ACL 生效的前提是客户端已经能连到服务端。我维护的一个模拟项目 X 里开发阶段为了图省事所有配置节点都用了默认开放权限。后来某天一个数据清理任务把前缀匹配写宽了一个字符把/x-service/下面的全部配置路径当成过期数据删了。过程不到三秒根路径底下干干净净。事后排查发现脚本确实跑错了范围但更关键的是 ZooKeeper 这边没有任何权限校验脚本连认证都不需要因为每个节点都是开放 ACL。那次事故之后我意识到ACL 不是锦上添花的高级特性它是 ZooKeeper 数据安全的第一道闸门。尤其是多团队共用一个集群、或者 ZooKeeper 暴露在公司内网时默认开放等于把业务配置放在公网上裸奔只是暂时没有人恶意来删而已。1.2 ACL 管得住哪些操作管不住哪些操作ZooKeeper 的 ACL 控制范围需要先界定清楚。它管的是客户端对某个 znode路径节点执行操作的能力具体包括在该节点下创建子节点、读取节点数据、修改节点数据、删除节点子节点、修改节点 ACL 列表。这些操作分别对应后面要讲的 CREATE、READ、WRITE、DELETE、ADMIN 五个权限位。不管的是传输层面的安全比如网络抓包、TLS 配置也不管客户端是否伪造身份因为 digest 身份本质上是由客户端上送的用户名和密码片段决定的服务端只做摘要匹配后挂到会话上。打个比方ACL 像写字楼的门禁卡它能决定谁有权限进哪些楼层但它管不了访客拿着一张伪造的门禁卡敲门也管不了大楼之间的通信线路是否被人搭线监听。要解决传输安全和身份真实性问题得靠 TLS 和内网隔离等手段。理解这条边界很重要——不少同事问配了 ACL 是不是就安全了我的回答通常是它是第一道防线但不是最后一道。2. ACL 权限模型四个构成元素Scheme、Id、Permission、认证状态2.1 五个权限位是独立的开关不是角色等级ZooKeeper 给每个 znode 设置一个 ACL 列表列表里每一项由三部分组成scheme、id、permissions。permissions 是一个整型位掩码官方定义如下权限位值允许的操作典型场景READ1读取节点数据、子节点列表、ACL配置读取WRITE2修改节点数据更新配置、开关CREATE4在该节点下创建子节点服务注册、动态建目录DELETE8删除该节点下的子节点清理过期节点ADMIN16修改该节点的 ACL 列表权限管理员ALL31上面全部五种操作不推荐随便给业务方这里最容易搞错的一点是权限位不是等级。WRITE 不包含 READDELETE 不包含 WRITEADMIN 也不代表你自动拥有读写权限。比如我给某个账号配了READ | WRITE他能读能写但不能在这个节点下面创建子节点也不能删除这个节点下的子节点。还有一个非常关键的细节CREATE 和 DELETE 权限是配置在父节点上的。创建/a/b时服务端检查的是/a节点的 CREATE 权限删除/a/b时服务端检查的是/a节点的 DELETE 权限而不是/a/b自己的权限。很多人在这里栽过跟头给子节点配了 ALL但父节点只给了 READ结果一直删不掉子节点。组合权限时用位或运算就行代码里是ZooDefs.Perms.READ | ZooDefs.Perms.WRITE或者直接用ZooDefs.Perms.ALL。2.2 从 world 到 super四种常用 Scheme 的适用边界ZooKeeper 的 scheme 决定了id 字段按什么规则解释。world:anyone不区分身份任意客户端。这就是默认开放权限除非是刻意全员可读否则不要用。digest:username:base64(sha1(username:password))最常用的账号口令方式。注意冒号后面是摘要串不是明文密码。auth:特殊占位。创建节点时用new Id(auth, )服务端会用当前会话里已经通过addAuthInfo注册的 digest 身份自动填进去相当于创建者拥有该节点的 ACL。ip:1.2.3.4按客户端来源 IP 匹配适合固定出口 IP 的物理机场景。网络代理、NAT 场景下很容易失效后面单独展开。super:不是写在节点 ACL 里的 scheme而是在服务端 JVM 启动参数里配置的超级管理员身份无视任何节点 ACL。其中 digest 摘要必须通过 ZooKeeper 自带的DigestAuthenticationProvider工具类生成以username:password作为输入输出username:base64串。很多教程喜欢手写 SHA1 再 Base64容易在编码细节上出错直接用官方工具类最稳。2.3 addAuthInfo 与 ACL 列表如何对应到同一条身份客户端连接建立后要调用addAuthInfo(digest, username:password.getBytes())把账号口令注册到当前会话。这个调用不会立即触发权限校验它只是向服务端声明这个会话拥有哪些身份。服务端会在会话上挂一份已认证身份列表后续请求带着这些身份去和节点 ACL 逐项比对。一个会话可以多次调用addAuthInfo服务端保留的是多份身份不是覆盖关系。例如一个运维进程既要读配置又要做权限管理可以同时注册 reader 和 admin 两个账号。这也会带来一个风险所有注册过的身份权限会叠加如果同一个客户端既注册了普通账号又注册了管理员账号那权限隔离就形同虚设。我的习惯是一个 ZooKeeper 客户端只注册一个最小必要账号不同权限的账号分开建连接。3. 客户端实操用 Java 客户端从建节点到鉴权跑通全流程3.1 创建带 ACL 的节点构造列表时最容易写错的一行下面这段代码是模拟项目 X 里配置节点初始化的标准做法。我把/x-service/config的读权限给 reader 账号所有权限给 admin 账号import org.apache.zookeeper.*; import org.apache.zookeeper.data.ACL; import org.apache.zookeeper.data.Id; import org.apache.zookeeper.server.auth.DigestAuthenticationProvider; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; public class ZkAclInit { public static void main(String[] args) throws Exception { ZooKeeper zk new ZooKeeper(127.0.0.1:2181, 5000, event - {}); ListACL acls new ArrayList(); acls.add(new ACL(ZooDefs.Perms.READ, new Id(digest, DigestAuthenticationProvider.generateDigest(reader01:readPass123)))); acls.add(new ACL(ZooDefs.Perms.ALL, new Id(digest, DigestAuthenticationProvider.generateDigest(admin01:adminPass456)))); zk.create(/x-service, new byte[0], acls, CreateMode.PERSISTENT); zk.create(/x-service/config, version1.getBytes(StandardCharsets.UTF_8), acls, CreateMode.PERSISTENT); zk.close(); } }这里最容易写错的是 digest id 这一行。常见错误有两种把 ACL 里的 id 写成明文密码比如new Id(digest, reader01:readPass123)。服务端保存的是摘要串客户端认证后生成的摘要和明文串永远对不上结果不管怎么调addAuthInfo都是 NoAuth。对DigestAuthenticationProvider.generateDigest(reader01:readPass123)的返回值再做一次用户名拼接搞出reader01:reader01:base64串。这个方法返回的字符串已经包含了用户名直接拿来用就行不要再拼。3.2 认证信息 addAuthInfo 必须在任何业务操作之前初始化节点的进程只负责建节点不负责访问。接下来模拟真实客户端访问ZooKeeper reader new ZooKeeper(127.0.0.1:2181, 5000, event - {}); reader.addAuthInfo(digest, reader01:readPass123.getBytes());addAuthInfo一定要在所有可能触发权限校验的调用之前执行。不少人 new 完 ZooKeeper 之后先做了一次exists或getData发现没权限回头再补addAuthInfo虽然后续操作正常了但第一个请求的异常已经被记录排查时很容易误导人。一个容易忽略的细节是ZooKeeper 构造函数的 Watcher 参数和连接状态没有必然关系它只是用来接收会话状态事件。很多示例代码直接传event - {}实际项目里应该在这里处理SyncConnected、Expired等状态尤其是会话过期后需要重建客户端。我在几个版本上实测addAuthInfo注册后立刻发起业务请求服务端都能正确识别身份没有遇到过需要额外等待的时序问题所以顺序对了就行不用过度设计。3.3 三种身份访问同一个节点现象完全不同我写了一个验证 Demo用三个客户端分别访问刚才建的/x-service/configpublic class ZkAclCheck { static void inspect(String name, ZooKeeper zk, String path) throws Exception { try { byte[] data zk.getData(path, false, null); System.out.println(name getData success: new String(data)); } catch (KeeperException.NoAuthException e) { System.out.println(name getData NoAuthException); } try { zk.setData(path, version2.getBytes(), -1); System.out.println(name setData success); } catch (KeeperException.NoAuthException e) { System.out.println(name setData NoAuthException); } try { zk.delete(path, -1); System.out.println(name delete success); } catch (KeeperException.NoAuthException e) { System.out.println(name delete NoAuthException); } catch (KeeperException.NotEmptyException e) { System.out.println(name delete NotEmptyException); } } public static void main(String[] args) throws Exception { ZooKeeper anonymous new ZooKeeper(127.0.0.1:2181, 5000, event - {}); inspect(anonymous, anonymous, /x-service/config); ZooKeeper reader new ZooKeeper(127.0.0.1:2181, 5000, event - {}); reader.addAuthInfo(digest, reader01:readPass123.getBytes()); inspect(reader01, reader, /x-service/config); ZooKeeper admin new ZooKeeper(127.0.0.1:2181, 5000, event - {}); admin.addAuthInfo(digest, admin01:adminPass456.getBytes()); inspect(admin01, admin, /x-service/config); } }运行结果基本如下客户端身份getDatasetDatadeleteanonymousNoAuthExceptionNoAuthExceptionNoAuthExceptionreader01成功NoAuthExceptionNoAuthExceptionadmin01成功成功成功注意观察 delete 这一列删除/x-service/config时服务端检查的是父节点/x-service的 DELETE 权限。初始化时/x-service的 ACL 和/x-service/config一样admin 有 ALL所以能删reader 只有 READ所以不能删。如果你把父节点权限配成了只读哪怕子节点是 ALL同样删不掉这是 ZooKeeper 权限模型里特别容易踩的地方。4. 服务端校验流程与NoAuth疑难杂症的排查思路4.1 一次带 ACL 的读取请求在服务端经历什么不妨把服务端对一次 getData 的处理拆开看请求到达服务端后系统先通过 session id 找到当前会话持有的所有认证信息然后取出目标 znode 的 ACL 列表接着做两层校验。第一层是身份匹配把 ACL 项里的 scheme 和 id 与会话认证信息比对第二层是权限匹配看该项的 permissions 是否包含请求需要的操作位getData 需要 READ。只要 ACL 列表里有任何一项同时满足两层请求就通过如果全部不满足返回权限错误客户端侧表现为KeeperException.NoAuthException。这个流程解释了为什么有权限却 NoAuth很多时候不是 ZooKeeper 出 bug而是会话身份、节点 ACL、请求所需权限三个条件没有在同一个点上对上。我排查过一个案例某人说我加了 addAuthInfo 还是 NoAuth结果一看初始化节点时用的 digest id 是明文密码服务端存进 ACL 的是错误字符串客户端认证后算出的摘要和 ACL 里存的那串不一致永远匹配不上。另一个值得提的点是ACL 列表的匹配是或关系。只要列表里有一条匹配请求就放行。这个特性后面做密码轮换时很有用可以在 ACL 里同时保留新旧两个账号等客户端都迁移完再移除旧账号。4.2 常见的权限误判明文密码、继承、客户端IP、重连列几个我实际遇到过的误判场景排查时可以对照把明文密码当成 digest id 写在 ACL 里正确写法是DigestAuthenticationProvider.generateDigest(user:pass)。以为子节点会继承父节点 ACL。ZooKeeper 的 ACL 是每个 znode 独立配置创建子节点时如果不显式传 ACL子节点可能变成全员开放。以为有 READ 权限就一定能看子节点列表。getChildren 需要的是目标节点自身的 READ 权限如果目标节点没有授权返回的就是 NoAuth 而不是空列表。把exists的异常当成节点不存在。exists(/path)在无 READ 权限时同样抛 NoAuthException很多脚本在这里直接 catch 了普通不存在导致把权限问题当数据问题处理。连接断开重连后同一个 ZooKeeper 实例会在新会话里重放之前注册过的addAuthInfo所以认证信息看起来还在但如果你重新 new 了一个 ZooKeeper 对象必须重新调addAuthInfo否则必然 NoAuth。某些封装库默认以OPEN_ACL_UNSAFE创建节点业务方以为用了库就等于加了权限实际反而把 ACL 覆盖成了全员开放。每个场景最终都要回到身份 节点 ACL 请求所需权限位三点检查基本都能定位。排查时我会开启服务端的 DEBUG 日志观察权限错误发生前会话上到底带了哪些 authInfo比在客户端干猜快很多。4.3 super 超级管理员只在应急时打开super 是 ZooKeeper 留给运维的后门。启用方式是在服务端启动脚本里加一个 JVM 参数-Dzookeeper.DigestAuthenticationProvider.superDigestsuper:生成的摘要其中生成的摘要同样用DigestAuthenticationProvider.generateDigest(admin:adminPass456)得到。设置之后任何客户端只要addAuthInfo(digest, admin:adminPass456)这个会话就会被标记为 super可以无视所有节点的 ACL包括直接 setACL。这个能力是双刃剑。密码一旦泄漏整个 ZooKeeper 集群的数据都等于交给对方。我的建议是平时不配只在这类极端场景打开——所有节点权限全部配错、业务数据无法恢复、需要紧急介入时。用完立刻从启动参数里移除并重启。另外super 的摘要字符串相当于一把万能钥匙明文密码应该通过独立的密钥管理通道保存不要写死在启动脚本里。5. 生产环境把 ACL 用稳的几条实操纪律5.1 容器化场景下 ip ACL 为什么经常失灵之前一个服务的 ZooKeeper 节点 ACL 写的是ip:10.0.0.5以为只允许这台机器访问。结果服务在容器里怎么调都 NoAuth。查下来原因很直接服务端看到的 TCP 源 IP 不是容器内网 IP而是宿主机做 NAT 之后的 IP在某些环境里会变成 docker 网关地址。现在的经验法则是如果客户端跑在容器、被容器编排平台调度或者经过负载均衡转发千万不要依赖 ip ACL。这类场景要保证稳定可预期的源地址通常只有在物理机直连内网时才能做到。改用 digest 按业务账号授权才是顺路做法账号跟着客户端配置走不受网络路径改变影响。5.2 创建子节点时把父节点的 ACL 传下去这是我最想强调的一条纪律。ZooKeeper 创建节点时必须显式传 ACL 列表常用常量有ZooDefs.Ids.OPEN_ACL_UNSAFE全员开放和ZooDefs.Ids.CREATOR_ALL_ACL创建者所有权限。很多封装层偷懒总是用OPEN_ACL_UNSAFE结果父节点配了 digest子节点照样裸奔。我们的做法是在公共工具类里强制要求调用者传 ACL不提供默认开放版本。创建子节点时可以先把父节点的 ACL 取出来再传给子节点创建方法如果子节点有更细的隔离需求再单独覆盖。用getACL检查节点当前权限配置也是一个很有效的巡检手段能快速找到哪些节点还是全员开放状态。5.3 重建客户端后认证信息丢失运维脚本最容易踩这个坑脚本里封装了一个getClient()方法内部 new ZooKeeper 并统一完成addAuthInfo某次改造后有一部分调用路径没有走getClient()而是自己 new 了一个 ZooKeeper 实例没调addAuthInfo结果批量任务大面积 NoAuth。排查时看起来脚本逻辑没问题因为主路径有认证但旁路没有。我的建议是把所有创建 ZooKeeper 客户端的地方收敛成一个工厂方法工厂方法内部统一完成addAuthInfo业务代码禁止直接 new ZooKeeper。对 Java 项目来说这几乎是零成本的事却能避免大量漏认证问题。如果项目里已经有多个直接 new 的地方花半小时全部替换掉比事后排查快得多。5.4 密码轮换时用双 digest 项过渡digest 密码一旦变化ACL 里的摘要也要跟着变而更新 ACL 需要目标节点有 ADMIN 权限这一步经常被忽略。更稳的切换方式是在 ACL 列表里同时保留旧账号、新账号两个 digest 项先让客户端分批切到新密码等确认线上没有请求再用旧密码再通过 setACL 移除旧项。因为 ACL 列表是或关系双账号共存完全没问题。如果直接一把梭把摘要改成新的客户端侧还没切换完瞬间所有业务都会报 NoAuth。我在这上面吃过亏所以现在所有涉及权限变更的操作都放在低峰期并且分两步走先加后删而不是先删后加。ZooKeeper ACL 本身不复杂但坑都集中在基础细节上digest 摘要怎么生成、addAuthInfo 什么时候调用、子节点 ACL 是否显式传递、容器环境下的 IP 判断。我在模拟项目 X 上把这些规则固化成工具之后后面几轮线上变更几乎再没遇到权限问题。如果你也打算在团队里推开 ACL建议先花半小时拉一遍现有 znode 的 ACL 状态把全员开放的节点找出来从最核心的配置路径开始收敛不要指望一口吃成胖子。权限这件事早一天做风险就少一天。
1. 裸奔的 ZooKeeper 节点一次事故让我决定认真对待 ACL1.1 默认权限位全开数据就像挂在公网ZooKeeper 在分布式系统里通常承担配置下发、服务注册、分布式锁状态这类关键数据。很多教程为了演示方便创建节点时直接使用开放权限这对应的是world:anyone——任何一台能连上服务端的客户端都能对这个节点做读、写、删、改权限等各种操作。这里要先说清楚ZooKeeper 本身不是安全网关它只做访问控制不做网络传输加密ACL 生效的前提是客户端已经能连到服务端。我维护的一个模拟项目 X 里开发阶段为了图省事所有配置节点都用了默认开放权限。后来某天一个数据清理任务把前缀匹配写宽了一个字符把/x-service/下面的全部配置路径当成过期数据删了。过程不到三秒根路径底下干干净净。事后排查发现脚本确实跑错了范围但更关键的是 ZooKeeper 这边没有任何权限校验脚本连认证都不需要因为每个节点都是开放 ACL。那次事故之后我意识到ACL 不是锦上添花的高级特性它是 ZooKeeper 数据安全的第一道闸门。尤其是多团队共用一个集群、或者 ZooKeeper 暴露在公司内网时默认开放等于把业务配置放在公网上裸奔只是暂时没有人恶意来删而已。1.2 ACL 管得住哪些操作管不住哪些操作ZooKeeper 的 ACL 控制范围需要先界定清楚。它管的是客户端对某个 znode路径节点执行操作的能力具体包括在该节点下创建子节点、读取节点数据、修改节点数据、删除节点子节点、修改节点 ACL 列表。这些操作分别对应后面要讲的 CREATE、READ、WRITE、DELETE、ADMIN 五个权限位。不管的是传输层面的安全比如网络抓包、TLS 配置也不管客户端是否伪造身份因为 digest 身份本质上是由客户端上送的用户名和密码片段决定的服务端只做摘要匹配后挂到会话上。打个比方ACL 像写字楼的门禁卡它能决定谁有权限进哪些楼层但它管不了访客拿着一张伪造的门禁卡敲门也管不了大楼之间的通信线路是否被人搭线监听。要解决传输安全和身份真实性问题得靠 TLS 和内网隔离等手段。理解这条边界很重要——不少同事问配了 ACL 是不是就安全了我的回答通常是它是第一道防线但不是最后一道。2. ACL 权限模型四个构成元素Scheme、Id、Permission、认证状态2.1 五个权限位是独立的开关不是角色等级ZooKeeper 给每个 znode 设置一个 ACL 列表列表里每一项由三部分组成scheme、id、permissions。permissions 是一个整型位掩码官方定义如下权限位值允许的操作典型场景READ1读取节点数据、子节点列表、ACL配置读取WRITE2修改节点数据更新配置、开关CREATE4在该节点下创建子节点服务注册、动态建目录DELETE8删除该节点下的子节点清理过期节点ADMIN16修改该节点的 ACL 列表权限管理员ALL31上面全部五种操作不推荐随便给业务方这里最容易搞错的一点是权限位不是等级。WRITE 不包含 READDELETE 不包含 WRITEADMIN 也不代表你自动拥有读写权限。比如我给某个账号配了READ | WRITE他能读能写但不能在这个节点下面创建子节点也不能删除这个节点下的子节点。还有一个非常关键的细节CREATE 和 DELETE 权限是配置在父节点上的。创建/a/b时服务端检查的是/a节点的 CREATE 权限删除/a/b时服务端检查的是/a节点的 DELETE 权限而不是/a/b自己的权限。很多人在这里栽过跟头给子节点配了 ALL但父节点只给了 READ结果一直删不掉子节点。组合权限时用位或运算就行代码里是ZooDefs.Perms.READ | ZooDefs.Perms.WRITE或者直接用ZooDefs.Perms.ALL。2.2 从 world 到 super四种常用 Scheme 的适用边界ZooKeeper 的 scheme 决定了id 字段按什么规则解释。world:anyone不区分身份任意客户端。这就是默认开放权限除非是刻意全员可读否则不要用。digest:username:base64(sha1(username:password))最常用的账号口令方式。注意冒号后面是摘要串不是明文密码。auth:特殊占位。创建节点时用new Id(auth, )服务端会用当前会话里已经通过addAuthInfo注册的 digest 身份自动填进去相当于创建者拥有该节点的 ACL。ip:1.2.3.4按客户端来源 IP 匹配适合固定出口 IP 的物理机场景。网络代理、NAT 场景下很容易失效后面单独展开。super:不是写在节点 ACL 里的 scheme而是在服务端 JVM 启动参数里配置的超级管理员身份无视任何节点 ACL。其中 digest 摘要必须通过 ZooKeeper 自带的DigestAuthenticationProvider工具类生成以username:password作为输入输出username:base64串。很多教程喜欢手写 SHA1 再 Base64容易在编码细节上出错直接用官方工具类最稳。2.3 addAuthInfo 与 ACL 列表如何对应到同一条身份客户端连接建立后要调用addAuthInfo(digest, username:password.getBytes())把账号口令注册到当前会话。这个调用不会立即触发权限校验它只是向服务端声明这个会话拥有哪些身份。服务端会在会话上挂一份已认证身份列表后续请求带着这些身份去和节点 ACL 逐项比对。一个会话可以多次调用addAuthInfo服务端保留的是多份身份不是覆盖关系。例如一个运维进程既要读配置又要做权限管理可以同时注册 reader 和 admin 两个账号。这也会带来一个风险所有注册过的身份权限会叠加如果同一个客户端既注册了普通账号又注册了管理员账号那权限隔离就形同虚设。我的习惯是一个 ZooKeeper 客户端只注册一个最小必要账号不同权限的账号分开建连接。3. 客户端实操用 Java 客户端从建节点到鉴权跑通全流程3.1 创建带 ACL 的节点构造列表时最容易写错的一行下面这段代码是模拟项目 X 里配置节点初始化的标准做法。我把/x-service/config的读权限给 reader 账号所有权限给 admin 账号import org.apache.zookeeper.*; import org.apache.zookeeper.data.ACL; import org.apache.zookeeper.data.Id; import org.apache.zookeeper.server.auth.DigestAuthenticationProvider; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; public class ZkAclInit { public static void main(String[] args) throws Exception { ZooKeeper zk new ZooKeeper(127.0.0.1:2181, 5000, event - {}); ListACL acls new ArrayList(); acls.add(new ACL(ZooDefs.Perms.READ, new Id(digest, DigestAuthenticationProvider.generateDigest(reader01:readPass123)))); acls.add(new ACL(ZooDefs.Perms.ALL, new Id(digest, DigestAuthenticationProvider.generateDigest(admin01:adminPass456)))); zk.create(/x-service, new byte[0], acls, CreateMode.PERSISTENT); zk.create(/x-service/config, version1.getBytes(StandardCharsets.UTF_8), acls, CreateMode.PERSISTENT); zk.close(); } }这里最容易写错的是 digest id 这一行。常见错误有两种把 ACL 里的 id 写成明文密码比如new Id(digest, reader01:readPass123)。服务端保存的是摘要串客户端认证后生成的摘要和明文串永远对不上结果不管怎么调addAuthInfo都是 NoAuth。对DigestAuthenticationProvider.generateDigest(reader01:readPass123)的返回值再做一次用户名拼接搞出reader01:reader01:base64串。这个方法返回的字符串已经包含了用户名直接拿来用就行不要再拼。3.2 认证信息 addAuthInfo 必须在任何业务操作之前初始化节点的进程只负责建节点不负责访问。接下来模拟真实客户端访问ZooKeeper reader new ZooKeeper(127.0.0.1:2181, 5000, event - {}); reader.addAuthInfo(digest, reader01:readPass123.getBytes());addAuthInfo一定要在所有可能触发权限校验的调用之前执行。不少人 new 完 ZooKeeper 之后先做了一次exists或getData发现没权限回头再补addAuthInfo虽然后续操作正常了但第一个请求的异常已经被记录排查时很容易误导人。一个容易忽略的细节是ZooKeeper 构造函数的 Watcher 参数和连接状态没有必然关系它只是用来接收会话状态事件。很多示例代码直接传event - {}实际项目里应该在这里处理SyncConnected、Expired等状态尤其是会话过期后需要重建客户端。我在几个版本上实测addAuthInfo注册后立刻发起业务请求服务端都能正确识别身份没有遇到过需要额外等待的时序问题所以顺序对了就行不用过度设计。3.3 三种身份访问同一个节点现象完全不同我写了一个验证 Demo用三个客户端分别访问刚才建的/x-service/configpublic class ZkAclCheck { static void inspect(String name, ZooKeeper zk, String path) throws Exception { try { byte[] data zk.getData(path, false, null); System.out.println(name getData success: new String(data)); } catch (KeeperException.NoAuthException e) { System.out.println(name getData NoAuthException); } try { zk.setData(path, version2.getBytes(), -1); System.out.println(name setData success); } catch (KeeperException.NoAuthException e) { System.out.println(name setData NoAuthException); } try { zk.delete(path, -1); System.out.println(name delete success); } catch (KeeperException.NoAuthException e) { System.out.println(name delete NoAuthException); } catch (KeeperException.NotEmptyException e) { System.out.println(name delete NotEmptyException); } } public static void main(String[] args) throws Exception { ZooKeeper anonymous new ZooKeeper(127.0.0.1:2181, 5000, event - {}); inspect(anonymous, anonymous, /x-service/config); ZooKeeper reader new ZooKeeper(127.0.0.1:2181, 5000, event - {}); reader.addAuthInfo(digest, reader01:readPass123.getBytes()); inspect(reader01, reader, /x-service/config); ZooKeeper admin new ZooKeeper(127.0.0.1:2181, 5000, event - {}); admin.addAuthInfo(digest, admin01:adminPass456.getBytes()); inspect(admin01, admin, /x-service/config); } }运行结果基本如下客户端身份getDatasetDatadeleteanonymousNoAuthExceptionNoAuthExceptionNoAuthExceptionreader01成功NoAuthExceptionNoAuthExceptionadmin01成功成功成功注意观察 delete 这一列删除/x-service/config时服务端检查的是父节点/x-service的 DELETE 权限。初始化时/x-service的 ACL 和/x-service/config一样admin 有 ALL所以能删reader 只有 READ所以不能删。如果你把父节点权限配成了只读哪怕子节点是 ALL同样删不掉这是 ZooKeeper 权限模型里特别容易踩的地方。4. 服务端校验流程与NoAuth疑难杂症的排查思路4.1 一次带 ACL 的读取请求在服务端经历什么不妨把服务端对一次 getData 的处理拆开看请求到达服务端后系统先通过 session id 找到当前会话持有的所有认证信息然后取出目标 znode 的 ACL 列表接着做两层校验。第一层是身份匹配把 ACL 项里的 scheme 和 id 与会话认证信息比对第二层是权限匹配看该项的 permissions 是否包含请求需要的操作位getData 需要 READ。只要 ACL 列表里有任何一项同时满足两层请求就通过如果全部不满足返回权限错误客户端侧表现为KeeperException.NoAuthException。这个流程解释了为什么有权限却 NoAuth很多时候不是 ZooKeeper 出 bug而是会话身份、节点 ACL、请求所需权限三个条件没有在同一个点上对上。我排查过一个案例某人说我加了 addAuthInfo 还是 NoAuth结果一看初始化节点时用的 digest id 是明文密码服务端存进 ACL 的是错误字符串客户端认证后算出的摘要和 ACL 里存的那串不一致永远匹配不上。另一个值得提的点是ACL 列表的匹配是或关系。只要列表里有一条匹配请求就放行。这个特性后面做密码轮换时很有用可以在 ACL 里同时保留新旧两个账号等客户端都迁移完再移除旧账号。4.2 常见的权限误判明文密码、继承、客户端IP、重连列几个我实际遇到过的误判场景排查时可以对照把明文密码当成 digest id 写在 ACL 里正确写法是DigestAuthenticationProvider.generateDigest(user:pass)。以为子节点会继承父节点 ACL。ZooKeeper 的 ACL 是每个 znode 独立配置创建子节点时如果不显式传 ACL子节点可能变成全员开放。以为有 READ 权限就一定能看子节点列表。getChildren 需要的是目标节点自身的 READ 权限如果目标节点没有授权返回的就是 NoAuth 而不是空列表。把exists的异常当成节点不存在。exists(/path)在无 READ 权限时同样抛 NoAuthException很多脚本在这里直接 catch 了普通不存在导致把权限问题当数据问题处理。连接断开重连后同一个 ZooKeeper 实例会在新会话里重放之前注册过的addAuthInfo所以认证信息看起来还在但如果你重新 new 了一个 ZooKeeper 对象必须重新调addAuthInfo否则必然 NoAuth。某些封装库默认以OPEN_ACL_UNSAFE创建节点业务方以为用了库就等于加了权限实际反而把 ACL 覆盖成了全员开放。每个场景最终都要回到身份 节点 ACL 请求所需权限位三点检查基本都能定位。排查时我会开启服务端的 DEBUG 日志观察权限错误发生前会话上到底带了哪些 authInfo比在客户端干猜快很多。4.3 super 超级管理员只在应急时打开super 是 ZooKeeper 留给运维的后门。启用方式是在服务端启动脚本里加一个 JVM 参数-Dzookeeper.DigestAuthenticationProvider.superDigestsuper:生成的摘要其中生成的摘要同样用DigestAuthenticationProvider.generateDigest(admin:adminPass456)得到。设置之后任何客户端只要addAuthInfo(digest, admin:adminPass456)这个会话就会被标记为 super可以无视所有节点的 ACL包括直接 setACL。这个能力是双刃剑。密码一旦泄漏整个 ZooKeeper 集群的数据都等于交给对方。我的建议是平时不配只在这类极端场景打开——所有节点权限全部配错、业务数据无法恢复、需要紧急介入时。用完立刻从启动参数里移除并重启。另外super 的摘要字符串相当于一把万能钥匙明文密码应该通过独立的密钥管理通道保存不要写死在启动脚本里。5. 生产环境把 ACL 用稳的几条实操纪律5.1 容器化场景下 ip ACL 为什么经常失灵之前一个服务的 ZooKeeper 节点 ACL 写的是ip:10.0.0.5以为只允许这台机器访问。结果服务在容器里怎么调都 NoAuth。查下来原因很直接服务端看到的 TCP 源 IP 不是容器内网 IP而是宿主机做 NAT 之后的 IP在某些环境里会变成 docker 网关地址。现在的经验法则是如果客户端跑在容器、被容器编排平台调度或者经过负载均衡转发千万不要依赖 ip ACL。这类场景要保证稳定可预期的源地址通常只有在物理机直连内网时才能做到。改用 digest 按业务账号授权才是顺路做法账号跟着客户端配置走不受网络路径改变影响。5.2 创建子节点时把父节点的 ACL 传下去这是我最想强调的一条纪律。ZooKeeper 创建节点时必须显式传 ACL 列表常用常量有ZooDefs.Ids.OPEN_ACL_UNSAFE全员开放和ZooDefs.Ids.CREATOR_ALL_ACL创建者所有权限。很多封装层偷懒总是用OPEN_ACL_UNSAFE结果父节点配了 digest子节点照样裸奔。我们的做法是在公共工具类里强制要求调用者传 ACL不提供默认开放版本。创建子节点时可以先把父节点的 ACL 取出来再传给子节点创建方法如果子节点有更细的隔离需求再单独覆盖。用getACL检查节点当前权限配置也是一个很有效的巡检手段能快速找到哪些节点还是全员开放状态。5.3 重建客户端后认证信息丢失运维脚本最容易踩这个坑脚本里封装了一个getClient()方法内部 new ZooKeeper 并统一完成addAuthInfo某次改造后有一部分调用路径没有走getClient()而是自己 new 了一个 ZooKeeper 实例没调addAuthInfo结果批量任务大面积 NoAuth。排查时看起来脚本逻辑没问题因为主路径有认证但旁路没有。我的建议是把所有创建 ZooKeeper 客户端的地方收敛成一个工厂方法工厂方法内部统一完成addAuthInfo业务代码禁止直接 new ZooKeeper。对 Java 项目来说这几乎是零成本的事却能避免大量漏认证问题。如果项目里已经有多个直接 new 的地方花半小时全部替换掉比事后排查快得多。5.4 密码轮换时用双 digest 项过渡digest 密码一旦变化ACL 里的摘要也要跟着变而更新 ACL 需要目标节点有 ADMIN 权限这一步经常被忽略。更稳的切换方式是在 ACL 列表里同时保留旧账号、新账号两个 digest 项先让客户端分批切到新密码等确认线上没有请求再用旧密码再通过 setACL 移除旧项。因为 ACL 列表是或关系双账号共存完全没问题。如果直接一把梭把摘要改成新的客户端侧还没切换完瞬间所有业务都会报 NoAuth。我在这上面吃过亏所以现在所有涉及权限变更的操作都放在低峰期并且分两步走先加后删而不是先删后加。ZooKeeper ACL 本身不复杂但坑都集中在基础细节上digest 摘要怎么生成、addAuthInfo 什么时候调用、子节点 ACL 是否显式传递、容器环境下的 IP 判断。我在模拟项目 X 上把这些规则固化成工具之后后面几轮线上变更几乎再没遇到权限问题。如果你也打算在团队里推开 ACL建议先花半小时拉一遍现有 znode 的 ACL 状态把全员开放的节点找出来从最核心的配置路径开始收敛不要指望一口吃成胖子。权限这件事早一天做风险就少一天。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
