ZooKeeper入门指南

ZooKeeper Getting Started Guide

ZooKeeper入门指南

• Getting Started: Coordinating Distributed Applications with ZooKeeper
• 入门：使用ZooKeeper协调分布式应用程序
  • Pre-requisites
  • 先决条件
  • Download
  • 下载
  • Standalone Operation
  • 独立运行
  • Managing ZooKeeper Storage
  • 管理ZooKeeper存储
  • Connecting to ZooKeeper
  • 连接到ZooKeeper
  • Programming to ZooKeeper
  • ZooKeeper编程
  • Running Replicated ZooKeeper
  • 运行ZooKeeper集群
  • Other Optimizations
  • 其他优化

Getting Started: Coordinating Distributed Applications with ZooKeeper

入门指南：使用ZooKeeper协调分布式应用程序

This document contains information to get you started quickly with ZooKeeper. It is aimed primarily at developers hoping to try it out, and contains simple installation instructions for a single ZooKeeper server, a few commands to verify that it is running, and a simple programming example. Finally, as a convenience, there are a few sections regarding more complicated installations, for example running replicated deployments, and optimizing the transaction log. However for the complete instructions for commercial deployments, please refer to the ZooKeeper Administrator's Guide.

本文档包含使您快速开始使用ZooKeeper的信息。它主要针对希望尝试使用它的开发人员，并包含单个ZooKeeper服务器的简单安装说明，一些验证其正在运行的命令以及一个简单的编程示例。最后，为方便起见，有几节涉及更复杂的安装，例如，集群运行的部署以及优化事务日志。但是，有关商业部署的完整说明，请参阅《ZooKeeper管理员指南》。

Pre-requisites

See System Requirements in the Admin guide.

先决条件

请参阅管理指南中的系统要求。

Download

To get a ZooKeeper distribution, download a recent stable release from one of the Apache Download Mirrors.

下载

要获得ZooKeeper发行版，请从Apache下载镜像之一下载最新的稳定版本。

Standalone Operation

Setting up a ZooKeeper server in standalone mode is straightforward. The server is contained in a single JAR file, so installation consists of creating a configuration.

Once you've downloaded a stable ZooKeeper release unpack it and cd to the root

To start ZooKeeper you need a configuration file. Here is a sample, create it in conf/zoo.cfg:

独立运行

在独立模式下设置ZooKeeper服务器非常简单。该服务器包含在单个JAR文件中，因此安装包括创建配置。

下载稳定的ZooKeeper版本后，将其解压缩并CD到根目录

要启动ZooKeeper，您需要在conf / zoo.cfg中创建一个配置文件。下面这个是一个示例：

tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181

This file can be called anything, but for the sake of this discussion call it conf/zoo.cfg. Change the value of dataDir to specify an existing (empty to start with) directory. Here are the meanings for each of the fields:

• tickTime : the basic time unit in milliseconds used by ZooKeeper. It is used to do heartbeats and the minimum session timeout will be twice the tickTime.

• dataDir : the location to store the in-memory database snapshots and, unless specified otherwise, the transaction log of updates to the database.

• clientPort : the port to listen for client connections

Now that you created the configuration file, you can start ZooKeeper:

该文件可以被命名为任何文件，但是为了便于讨论，将其命名为conf / zoo.cfg。更改dataDir的值指定以现有（一开始是空文件）目录。以下是每个字段的含义：

• tickTime：ZooKeeper使用的基本时间单位（毫秒）。它用于做心跳，并且最小会话超时将是tickTime的两倍。

• dataDir：存储内存数据库快照的位置，除非另有说明，否则存储数据库更新的事务日志。

• clientPort：用于侦听客户端连接的端口

现在，您已经创建了配置文件，您可以启动ZooKeeper：

bin/zkServer.sh start

ZooKeeper logs messages using log4j -- more detail available in the Logging section of the Programmer's Guide. You will see log messages coming to the console (default) and/or a log file depending on the log4j configuration.

The steps outlined here run ZooKeeper in standalone mode. There is no replication, so if ZooKeeper process fails, the service will go down. This is fine for most development situations, but to run ZooKeeper in replicated mode, please see Running Replicated ZooKeeper.

ZooKeeper使用log4j记录消息-有关详细信息，请参阅《程序员指南》的“记录”部分。您将看到进入控制台的日志消息（默认）和/或一个日志文件，具体取决于log4j配置。

此处概述的步骤以独立模式运行ZooKeeper。没有集群，因此，如果ZooKeeper进程失败，该服务将关闭。这对于大多数开发情况都很好，但是要以集群方式运行ZooKeeper，请参阅“运行ZooKeeper集群”。

Managing ZooKeeper Storage

For long running production systems ZooKeeper storage must be managed externally (dataDir and logs). See the section on maintenance for more details.

Connecting to ZooKeeper

管理ZooKeeper存储

对于长时间运行的生产系统，必须从外部管理ZooKeeper存储（dataDir和日志）。有关更多详细信息，请参见维护部分。

连接到ZooKeeper

$ bin/zkCli.sh -server 127.0.0.1:2181

This lets you perform simple, file-like operations.

Once you have connected, you should see something like:

这使您可以执行简单的类似文件的操作。

连接后，您应该会看到类似以下内容的信息：

Connecting to localhost:2181
log4j:WARN No appenders could be found for logger (org.apache.zookeeper.ZooKeeper).
log4j:WARN Please initialize the log4j system properly.
Welcome to ZooKeeper!
JLine support is enabled
[zkshell: 0]

From the shell, type help to get a listing of commands that can be executed from the client, as in:

在shell中，键入help以获取可以在客户端执行的命令的列表，如下所示：

[zkshell: 0] help
ZooKeeper -server host:port cmd args
addauth scheme auth
close
config [-c] [-w] [-s]
connect host:port
create [-s] [-e] [-c] [-t ttl] path [data] [acl]
delete [-v version] path
deleteall path
delquota [-n|-b] path
get [-s] [-w] path
getAcl [-s] path
getAllChildrenNumber path
getEphemerals path
history
listquota path
ls [-s] [-w] [-R] path
ls2 path [watch]
printwatches on|off
quit
reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*]
redo cmdno
removewatches path [-c|-d|-a] [-l]
rmr path
set [-s] [-v version] path data
setAcl [-s] [-v version] [-R] path acl
setquota -n|-b val path
stat [-w] path
sync path

From here, you can try a few simple commands to get a feel for this simple command line interface. First, start by issuing the list command, as in ls, yielding:

从这里，您可以尝试一些简单的命令，以了解这种简单的命令行界面。首先，如中下所示ls 发出list命令，得到：

[zkshell: 8] ls /
[zookeeper]

Next, create a new znode by running create /zk_test my_data. This creates a new znode and associates the string "my_data" with the node. You should see:

接下来，通过运行创建一个新的znode create /zk_test my_data。这将创建一个新的znode并将字符串“ my_data”与该节点关联。您应该看到：

[zkshell: 9] create /zk_test my_data
Created /zk_test

Issue another ls / command to see what the directory looks like:

发出另一个ls /命令以查看目录的情况：

[zkshell: 11] ls /
[zookeeper, zk_test]

Notice that the zk_test directory has now been created.

Next, verify that the data was associated with the znode by running the get command, as in:

请注意，现在已创建zk_test目录。

接下来，通过运行get命令来验证数据是否与znode关联，如下所示：

[zkshell: 12] get /zk_test
my_data
cZxid = 5
ctime = Fri Jun 05 13:57:06 PDT 2009
mZxid = 5
mtime = Fri Jun 05 13:57:06 PDT 2009
pZxid = 5
cversion = 0
dataVersion = 0
aclVersion = 0
ephemeralOwner = 0
dataLength = 7
numChildren = 0

We can change the data associated with zk_test by issuing the set command, as in:

我们可以通过发出set命令来更改与zk_test相关的数据，如下所示：

[zkshell: 14] set /zk_test junk
cZxid = 5
ctime = Fri Jun 05 13:57:06 PDT 2009
mZxid = 6
mtime = Fri Jun 05 14:01:52 PDT 2009
pZxid = 5
cversion = 0
dataVersion = 1
aclVersion = 0
ephemeralOwner = 0
dataLength = 4
numChildren = 0
[zkshell: 15] get /zk_test
junk
cZxid = 5
ctime = Fri Jun 05 13:57:06 PDT 2009
mZxid = 6
mtime = Fri Jun 05 14:01:52 PDT 2009
pZxid = 5
cversion = 0
dataVersion = 1
aclVersion = 0
ephemeralOwner = 0
dataLength = 4
numChildren = 0

(Notice we did a get after setting the data and it did, indeed, change.

Finally, let's delete the node by issuing:

（请注意，我们在设置数据后做了一个改变，get确认确实发生了变化。

最后，通过发出以下命令delete来删除节点：

[zkshell: 16] delete /zk_test
[zkshell: 17] ls /
[zookeeper]
[zkshell: 18]

That's it for now. To explore more, see the Zookeeper CLI.

现在就这样。要了解更多信息，请参见Zookeeper CLI。

Programming to ZooKeeper

ZooKeeper has a Java bindings and C bindings. They are functionally equivalent. The C bindings exist in two variants: single threaded and multi-threaded. These differ only in how the messaging loop is done. For more information, see the Programming Examples in the ZooKeeper Programmer's Guide for sample code using the different APIs.

Running Replicated ZooKeeper

Running ZooKeeper in standalone mode is convenient for evaluation, some development, and testing. But in production, you should run ZooKeeper in replicated mode. A replicated group of servers in the same application is called a quorum, and in replicated mode, all servers in the quorum have copies of the same configuration file.

针对ZooKeeper编程

ZooKeeper具有Java绑定和C绑定。它们在功能上是等效的。C绑定存在两种变体：单线程和多线程。这些区别仅在于消息传递循环的完成方式。有关更多信息，请参见《ZooKeeper程序员指南》中的“编程示例”，以获取使用不同API的示例代码。

运行集群的ZooKeeper

以独立模式运行ZooKeeper便于评估，某些开发和测试。但是在生产中，您应该在集群模式下运行ZooKeeper。同一应用程序中的一组服务器的集群组称为（quorum）仲裁，并且在集群模式下，仲裁中的所有服务器都具有相同配置文件的副本。

Note

For replicated mode, a minimum of three servers are required, and it is strongly recommended that you have an odd number of servers. If you only have two servers, then you are in a situation where if one of them fails, there are not enough machines to form a majority quorum. Two servers are inherently less stable than a single server, because there are two single points of failure.

The required conf/zoo.cfg file for replicated mode is similar to the one used in standalone mode, but with a few differences. Here is an example:

注意

对于集群模式，至少需要三个服务器，并且强烈建议您使用奇数个服务器。如果只有两台服务器，那么您将处于一种情况，如果其中一台服务器发生故障，则没有足够的计算机构成多数仲裁。由于存在两个单点故障，因此两个服务器就不如单个服务器稳定。

集群模式所需的conf / zoo.cfg文件类似于独立模式下使用的文件，但有一些区别。这是一个例子：

tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
initLimit=5
syncLimit=2
server.1=zoo1:2888:3888
server.2=zoo2:2888:3888
server.3=zoo3:2888:3888

The new entry, initLimit is timeouts ZooKeeper uses to limit the length of time the ZooKeeper servers in quorum have to connect to a leader. The entry syncLimit limits how far out of date a server can be from a leader.

With both of these timeouts, you specify the unit of time using tickTime. In this example, the timeout for initLimit is 5 ticks at 2000 milliseconds a tick, or 10 seconds.

The entries of the form server.X list the servers that make up the ZooKeeper service. When the server starts up, it knows which server it is by looking for the file myid in the data directory. That file has the contains the server number, in ASCII.

Finally, note the two port numbers after each server name: " 2888" and "3888". Peers use the former port to connect to other peers. Such a connection is necessary so that peers can communicate, for example, to agree upon the order of updates. More specifically, a ZooKeeper server uses this port to connect followers to the leader. When a new leader arises, a follower opens a TCP connection to the leader using this port. Because the default leader election also uses TCP, we currently require another port for leader election. This is the second port in the server entry.

新条目initLimit是超时ZooKeeper用于限制仲裁中的ZooKeeper服务器必须连接到领导者的时间长度。条目syncLimit限制服务器与领导者之间过时的差距。

对于这两个超时，您都可以使用tickTime指定时间单位。在此示例中，initLimit的超时是5心跳数，即2000毫秒/心跳数，即10秒。

表格server.X的条目列出了组成ZooKeeper服务的服务器。服务器启动时，它通过在数据目录中查找文件myid来知道它是哪台服务器。该文件包含ASCII格式服务器号。

最后，记下每个服务器名称后的两个端口号：“ 2888”和“ 3888”。对等方使用前一个端口连接到其他对等方。这样的连接是必要的，以便对等方可以进行通信，例如，同意更新顺序。更具体地说，ZooKeeper服务器使用此端口将关注者连接到领导者。当出现新的领导者时，跟随者使用此端口打开与领导者的TCP连接。因为默认的领导者选举也使用TCP，所以我们当前需要另一个端口来进行领导者选举。这是服务器条目中的第二个端口。(第一个端口节点间通信，第二个端口用于leader选举)

If you want to test multiple servers on a single machine, specify the servername as localhost with unique quorum & leader election ports (i.e. 2888:3888, 2889:3889, 2890:3890 in the example above) for each server.X in that server's config file. Of course separate _dataDir_s and distinct _clientPort_s are also necessary (in the above replicated example, running on a single localhost, you would still have three config files).

Please be aware that setting up multiple servers on a single machine will not create any redundancy. If something were to happen which caused the machine to die, all of the zookeeper servers would be offline. Full redundancy requires that each server have its own machine. It must be a completely separate physical server. Multiple virtual machines on the same physical host are still vulnerable to the complete failure of that host.

If you have multiple network interfaces in your ZooKeeper machines, you can also instruct ZooKeeper to bind on all of your interfaces and automatically switch to a healthy interface in case of a network failure. For details, see the Configuration Parameters.

注意

如果要在一台计算机上测试多台服务器，请为每台服务器指定服务器名称为localhost，并具有唯一的仲裁和领导者选择端口（例如，在上面的示例中为2888：3888、2889：3889、2890：3890）。配置文件。当然，也需要单独的_dataDir_s和不同的_clientPort_s（在上面的复制示例中，在单个localhost上运行，您仍然会有三个配置文件）。

请注意，在一台计算机上设置多个服务器不会产生任何冗余。如果发生某些事情导致机器死机，则所有zookeeper服务器都将处于脱机状态。完全冗余要求每个服务器都有自己的计算机。它必须是完全独立的物理服务器。同一物理主机上的多个虚拟机仍然容易受到该主机完全故障的影响。

如果ZooKeeper机器中有多个网络接口，则还可以指示ZooKeeper绑定所有接口，并在网络出现故障时自动切换到正常接口。有关详细信息，请参阅“配置参数”。

Other Optimizations

There are a couple of other configuration parameters that can greatly increase performance:

• To get low latencies on updates it is important to have a dedicated transaction log directory. By default transaction logs are put in the same directory as the data snapshots and myid file. The dataLogDir parameters indicates a different directory to use for the transaction logs.

其他优化

还有几个其他配置参数可以大大提高性能：

• 为了获得较低的更新延迟，拥有专用的事务日志目录非常重要。默认情况下，事务日志与数据快照和myid文件放在同一目录中。dataLogDir参数指定一个不同的目录。用于存储事务日志