title: ZooKeeper 帮助手册 date: 2014-10-14T00:00:00 description: "官方手册的个人翻译" tags: [zookeeper]
原文地址： http://zookeeper.apache.org/doc/r3.4.6/zookeeperProgrammers.html
本文假设你已经具有一定分布式计算的基础知识。你将在第一部分看到以下内容：
接下来的4小节讲述了程序开发的实际应用：
本文的附录中包含和ZooKeeper相关的有用信息。
ZooKeeper有一个类似分布式文件系统的命名体系。区别在于Zookeeper每个一个节点或子节点都可以拥有数据。节点路径是一个由斜线分开的绝对路径，注意没有相对路径。只要满足下面要求的unicode字符都可以作为节点路径：
ZooKeeper树结构中的节点被称为znode。各个znode维护着一组用来标记数据和访问权限发生变化的版本号。这些版本号组成的状态结构具有时间戳。Zookeeper使用版本号和时间戳来验证缓存状态，调整更新。 每次znode中的数据发生变化，znode的版本号增加。例如，每当一个客户端恢复数据时，它就接收这个版本的数据，而当一个客户端提交了更新或删除记录，它必须同时提供这个znode当前正在发生变化的数据的版本。如果这个版本和目前真实的版本不匹配，则提交无效。 __提示，在分布式程序中，一个字节点可以代表一个通用的主机，服务器，集群中的一员，客户端程序等。但是在Zookeeper中，znode代表数据节点，Servers代表组成了Zookeeper服务的机器; quorum peers refer to the servers that make up an ensemble; 客户端代表任何使用ZooKeeper服务的主机或程序。
znode作为对程序开发来说最重要的信息，有几个特性需要特别关注下：
Watches 客户端可以在znode上设置Watch。znode发生的变化会触发watch然后清除watch。当一个watch被触发，Zookeeper给客户端发送一个通知。更多关于watch的内容请查看ZooKeeper Watches一节。
数据存取 命名空间中每个znode中的数据读写是原子操作。读操作读取znode中的所有数据位，写操作则替换所有数据。每个节点都有一个访问权限控制表（ACL）来标记谁可以做什么。 zookeeper不是设计成普通的数据库或大型对象存储的。它是用来管理coordination data。coordination data包括配置文件、状态信息、rendezvous等。这些数据结构的一个共同特点就是相对较小——以千字节为准。Zookeeper的客户端和服务会检查确保每个znode上的数据小于1M，实际平均数据要远远小于1M。 大规模数据的操作会引发一些潜在的问题并且延长在网络和介质之间传输的时间。如果确实需要大型数据的存储，那么可以采用如NFS或HDFS之类的大型数据存储系统，亦或是在zookeeper中存储指向存储位置的指针。
临时节点（Ephemeral Nodes） zookeeper还有临时节点的概念，这些节点的生命周期依赖于创建它们的session是否活跃。session结束时节点即被销毁。也由于这种特性，临时节点不允许有子节点。
序列节点——命名不唯一
当你创建节点的时候，你会需要zookeeper提供一组单调递增的计数来作为路径结尾。这个计数对父znode是唯一的。用%010d的格式——用0来填充的10位数（计数如此命名是为了简单排序）。例如"<path>0000000001"，注意计数器是有符号整型，超过表示范围会溢出。
zookeeper有很多记录时间的方式：
存在于znode中的状态结构，由以下各个部分组成：
客户端通过创建一个handle和服务端建立session连接。一旦创建完成，handle就进入了CONNECTING状态，客户端库尝试连接一台构成zookeeper的server，届时进入CONNECTED状态。通常情况下操作会介于这两种状态之间。 一旦出现了不可恢复的错误：如session中止，鉴权失败或者应用直接结束handle，则handle会进入到CLOSED状态。下图是客户端的状态转换图：
<img>状态转换图</img>
应用在创建客户端session时必须提供一串逗号分隔的主机号:端口号，每对主机端口号对应一个ZooKeeper的server（如："127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"），客户端库会尝试连接任意一台服务器，如果连接失败或是客户端主动断开连接，客户端会自动继续与下一台服务器连接，直到连接成功。
3.2.0版本新增内容: 一个新的操作“chroot”可以添加在连接字符串的尾部，用来指明客户端命令运行的根目录地址。类似unix的chroot命令，例如： "127.0.0.1:4545/app/a" or "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a"，说明客户端会以"/app/a"为根目录，所有路径都相对于根目录来设置，如"/foo/bar"的操作会运行在"/app/a/foo/bar"。 这一特性在多用户环境下非常好用，每个使用zookeeper服务的用户可以设置不同的根目录。
当客户端获得和zookeeper服务连接的handle时，zookeeper会创建一个Zookeeper session分配给客户端，用一个64-bit数字表示。一旦客户端连接了其他服务器，客户端必须把这个session id也作为连接握手的一部分发送。出于安全目的，zookeeper给session id创建一个密码，任何zookeeper服务器都可以验证密码。 当客户端创建session时密码和session id一起发送到客户端来，当客户端重新连接其他服务器时，同时要发送密码和session id。
zookeeper客户端库里有一个创建zookeeper session的参数，叫做session timeout（超时），用毫秒表示。客户端发送请求超时，服务端在超时范围内响应客户端。session超时最小为2个ticktime，最大为20个ticktime。zookeeper客户端API可以协调超时时间。 当客户端和zookeeper服务器集群断开时，它会搜索session创建时的服务器列表。最后，当至少一个服务器和客户端重新建立连接，session或被重新置为"connected"状态（超时时间内重新连接），或被置为"expired（过期）"状态（超出超时时间）。不建议在断开连接后重新创建session。ZK客户端库会帮你重新连接。特别地，我们将启发式学习模式植入客户的库中来处理类似“羊群效应”等问题。只有当你的session过期时才重新创建（托管的）。 session过期的状态转换图示例同过期session的watcher：
另一个session建立时zookeeper需要的参数是默认watcher（监视者）。在客户端发生任何变化时，watcher都会发出通知。例如客户端失去和服务器的连接、客户端session到期等。watcher默认的初始状态是disconnected。（也就是说任何状态改变事件都由客户端库发送到watcher）。当新建一个连接时，第一个发送给watcher的事件通常就是session连接事件。
客户端发送请求会使session保持活动状态。客户端会发送ping包（译者注：心跳包）以保持session不会超时。Ping包不仅让服务端知道客户端仍然活动，而且让客户端也知道和服务端的连接没有中断。Ping包发送时间正好可以判断是否连接中断或是重新启动一个新的服务器连接。
和服务器的连接建立成功，当一个同步或异步操作执行后，有两种情况会让客户端库判断失去连接：
3.2.0版本新增内容 —— SessionMovedException 一个客户端无法查看的内部异常SessionMovedException。这个异常发生在服务端收到一个请求，这个请求的session已经在另一个服务器上重新连接。发生这种情况的原因通常是客户端发送完请求后，由于网络延时，客户端超时重新和其他服务器建立连接，当请求包到达第一台服务器时，服务器发现session已经移除并关闭了和客户端的连接。客户端一般不用理会这个问题，但是有一种情况值得注意，当两台客户端使用事先存储的session id和密码试图创建同一个连接时，第一台客户端重建连接，第二台则会被中断。
所有zookeeper的读操作——getData(), getChildren(), exists()——都可以设置一个watch。Zookeeper的watch的定义是：watch事件是一次性触发的，发送到客户端的。在监视的数据发生变化时产生watch事件。以下三点是watch(事件)定义的关键点：
getData("/znode1", true)然后节点/znode1发生数据变化或删除，这个客户端将收到/znode1的watch事件。如果/znode1继续发生改变，不会再有watch发送，除非客户端又做了其他读操作产生了新的watch。watch在客户端已连接上的服务器里维护，这样可以保证watch轻量便于设置，维护和分发。当客户端连接了一台新的服务器，watch会在任何session事件时触发。当断开和服务器的连接时，watch不会触发。当客户端重新连接上时，任何之前注册过的watch都会重新注册并在需要的时候被触发。一般来说这一切都是透明的。只有一种可能会丢失watch：当一个znode在断开和服务器连接时被创建或删除，那么判断这个znode存在的watch因未创建而找不到。
ZooKeeper如何保证watch可靠性
zookeeper有如下方式：
watch注意事项
zookeeper使用ACL来控制对znode（zookeeper的数据节点）的访问权限。ACL的实现方式和unix的文件权限类似：用不同位来代表不同的操作限制和组限制。与标准unix权限不同的是，zookeeper的节点没有三种域——用户，组，其他。zookeeper里没有节点的所有者的概念。取而代之的是，一个由ACL指定的id集合和其相关联的权限。
注意，一个ACL只从属于一个特定的znode。对这个znode子节点也是无效的。例如，如果/app只有被ip172.16.16.1的读权限，/app/status有被所有人读的权限，那么/app/status可以被所有人读，ACL权限不具有递归性。
zookeeper支持插件式认证方式，id使用scheme:id的形式。scheme是id对应的类型方式，例如ip:172.16.16.1就是一个地址为172.16.16.1的主机id。
当客户端连接zookeeper并且认证自己，zookeeper就在这个与客户端的连接中关联所有与客户端一致的id。当客户端访问某个znode时，znode的ACL会重新检查这些id。ACL的表达式为(scheme:expression,perms)。expression就是特殊的scheme，例如，(ip:19.22.0.0/16, READ)就是把任何以19.22开头的ip地址的客户端赋予读权限。
ZooKeeper支持下列权限：
CREATE和DELETE操作是更细的粒度上的WRITE操作。有一种特殊的情况：
zookeeper没有文件所有者的概念，但有ADMIN权限。在某种意义上说，ADMIN权限指定了所谓的所有者。zookeeper虽然不支持查找权限（在目录上的执行权限虽然不能列出目录内容，却可以查找），但每个客户端都隐含着拥有查找权限。这样你可以查看节点状态，但仅此而已。（这有个问题，如果你在不存在的节点上调用了zoo_exists()，你将无权查看）
ZooKeeper有下列内建模式：
username:pathasowrd的字符串来生成一个MD5哈希表作为ACL ID标识。在空文档中发送username:password来完成认证。现在的ACL表达式格式为username:base64, 用SHA1编码密码。addr/bits，addr中最有效的位匹配上主机ip最有效的位。zookeeper运行于复杂的环境下，有各种不同的认证方式。因此zookeeper拥有一套插件式的认证框架。内建认证scheme也是使用这套框架。
为了便于理解认证框架的工作方式，你首先要了解两种主要的认证操作。框架首先必须认证客户端。这步操作通常在客户端连接服务器的同时完成并且将从客户端发过来的（或从客户端收集来的）认证信息关联此次连接。认证框架的第二步操作是在ACL中寻找关联的客户端的条目。ACL条目是<idspec, permissions>格式。idspec可能是一个关联了连接的，和认证信息匹配的简单字符串，也可能是评估认证信息的表达式。这取决于认证插件如何实现匹配。下面是一个认证插件必须实现的接口：
public interface AuthenticationProvider {
String getScheme();
KeeperException.Code handleAuthentication(ServerCnxn cnxn, byte authData[]);
boolean isValid(String id);
boolean matches(String id, String aclExpr);
boolean isAuthenticated();
}
第一个方法getScheme返回一个标识该插件的字符串。由于我们支持多种认证方式，认证证书或者idspec必须一直加上scheme:作为前缀。zookeeper服务器使用认证插件返回的scheme判断哪个id适用于该scheme。
当客户端发送与连接关联的认证信息时，handleAuthentication被调用。客户端指定和认证信息相应的模式。zookeeper把信息传给认证插件，认证插件的getScheme匹配scheme。实现handleAuthentication的方法通常在判断信息错误后返回一个error，或者在确认连接后使用cnxn.getAuthInfo().add(new Id(getScheme(), data))
认证插件在设置和ACL中都有涉及。当对某个节点设置ACL时，zookeeper服务器会传那个条目的id给isValid(String id)方法。插件需要判断id的连接来源。例如，ip:172.16.0.0/16是有效id，ip:host.com是无效id。如果新的ACL包括一个"auth"条目，就用isAuthenticated判断该scheme的认证信息是否关联了连接，是否可以被添加到ACL中。一些scheme不会被包含到auth中。例如，如果auth已经指定，客户端的ip地址就不作为id添加到ACL中。
在检查ACL时zookeeper有一个matches(String id, String aclExpr)方法。ACL的条目需要和认证信息相匹配。为了找到和客户端对应的条目，zookeeper服务器寻找每个条目的scheme，如果对某个scheme有那个客户端的认证信息，matches(String id, String aclExpr)会被调用并传入两个值，分别是事先由handleAuthentication 加入连接信息中认证信息的id，和设置到ACL条目id的aclExpr。认证插件用自己的逻辑匹配scheme来判断id是否在aclExpr中。
有两个内置认证插件：ip和digest。附加插件可以使用系统属性添加。在zookeeper启动过程中，会扫描所有以"zookeeper.authProvider"开头的系统属性。并且把那些属性值解释为认证插件的类名。这些属性可以使用-Dzookeeeper.authProvider.X=com.f.MyAuth或在服务器设置文件中添加条目来创建：
authProvider.1=com.f.MyAuth
authProvider.2=com.f.MyAuth2
注意属性的后缀是唯一的。如果出现重复的情况-Dzookeeeper.authProvider.X=com.f.MyAuth -Dzookeeper.authProvider.X=com.f.MyAuth2，只有一个会被使用。同样，所有服务器都必须统一插件定义，否则客户端用插件提供的认证schemes连接服务器时会出错。
ZooKeeper是一个高性能，可扩展的服务。读和写操作都非常快速。之所以如此，全因为zookeeper有数据一致性的保证：
顺序一致性 客户端的更新会按照它们发送的次序排序。
原子性 更新的失败或成功，都不会出现半个结果。
单独系统镜像 不管客户端连哪个服务器，它看来都是同一个。
可靠性 一旦更新生效，它就会一直保存到下一次客户端更新。这就有两个推论：
时效性 客户端看到的系统状态在某个时间范围内是最新的（几十秒内），任何系统更改都会在该时间范围内被客户端发现。否则客户端会检测到断开服务。
用这些一致性保证可以在客户端中构造出更高级的程序如 leader election, barriers, queues, read/write revocable locks(无须在zookeeper中附加任何东西)。更多信息Recipes and Solutions
zookeeper不存在的一致性保证： 多客户端同一时刻看到的内容相同 zookeeper不可能保证两台客户端在同一时间看到的内容总是一样，由于网络延迟等原因。假设这样一个场景，A和B是两个客户端，A设置节点/a下的值从0变为1，然后让B读/a，B可能读到旧的数据0。如果想让A和B读到同样的内容，B必须在读之前调用zookeeper接口中的sync()方法。
下面是一些常见的陷阱：
其他资料链接请自行官网查看。