Twemproxy（Nutcracker）技术文档

本文档旨在帮助用户详细理解并使用Twemproxy（Nutcracker），这是一个为memcached和redis协议设计的快速轻量级代理。以下内容将包括安装指南、使用说明、项目API使用文档以及安装方式。

1. 安装指南

要构建Twemproxy 0.5.0+，请从发行版tarball开始：

$ ./configure
$ make
$ sudo make install

若要以调试模式构建Twemproxy 0.5.0+，请执行以下命令：

$ CFLAGS="-ggdb3 -O0" ./configure --enable-debug=full
$ make
$ sudo make install

若要从源代码构建Twemproxy并启用调试日志和断言，请按照以下步骤操作：

$ git clone [e-mail]:twitter/twemproxy.git
$ cd twemproxy
$ autoreconf -fvi
$ ./configure --enable-debug=full
$ make
$ src/nutcracker -h

注意事项：

• 使用较新版本的gcc（较旧版本的gcc存在问题）
• 使用CFLAGS="-O1" ./configure && make
• 使用CFLAGS="-O3 -fno-strict-aliasing" ./configure && make
• autoreconf -fvi && ./configure 需要安装 automake 和 libtool
• make check 会运行单元测试

2. 项目的使用说明

Twemproxy可以通过命令行参数进行配置，以下是一些基本的命令行选项：

Usage: nutcracker [-?hVdDt] [-v verbosity level] [-o output file]
                  [-c conf file] [-s stats port] [-a stats addr]
                  [-i stats interval] [-p pid file] [-m mbuf size]

• -h, --help：显示帮助信息
• -V, --version：显示版本信息并退出
• -t, --test-conf：测试配置文件语法错误并退出
• -d, --daemonize：作为守护进程运行
• -D, --describe-stats：打印统计信息描述并退出
• -v, --verbose=N：设置日志级别（默认：5，最小：0，最大：11）
• -o, --output=S：设置日志文件（默认：stderr）
• -c, --conf-file=S：设置配置文件（默认：conf/nutcracker.yml）
• -s, --stats-port=N：设置统计监控端口（默认：22222）
• -a, --stats-addr=S：设置统计监控IP（默认：0.0.0.0）
• -i, --stats-interval=N：设置统计聚合间隔，单位为毫秒（默认：30000毫秒）
• -p, --pid-file=S：设置pid文件（默认：不启用）
• -m, --mbuf-size=N：设置mbuf块大小，单位为字节（默认：16384字节）

3. 项目API使用文档

Twemproxy的API主要用于配置和管理代理服务器。配置文件通常为YAML格式，以下是一个配置文件的示例：

alpha:
  listen: 127.0.0.1:22121
  hash: fnv1a_64
  distribution: ketama
  auto_eject_hosts: true
  redis: true
  server_retry_timeout: 2000
  server_failure_limit: 1
  servers:
   - 127.0.0.1:6379:1

beta:
  listen: 127.0.0.1:22122
  hash: fnv1a_64
  hash_tag: "{}"
  distribution: ketama
  auto_eject_hosts: false
  timeout: 400
  redis: true
  servers:
   - 127.0.0.1:6380:1 server1
   - 127.0.0.1:6381:1 server2

配置文件中的关键字包括：

• listen：监听地址和端口
• client_connections：允许从redis客户端建立的连接数
• hash：哈希函数名称
• hash_tag：用于哈希的键的一部分
• distribution：键分布模式
• timeout：连接超时时间
• backlog：TCP backlog参数
• tcpkeepalive：是否启用TCP keepalive
• preconnect：是否在进程启动时预先连接到所有服务器
• redis：是否使用redis协议
• redis_auth：连接Redis服务器时进行身份验证
• redis_db：使用的数据库编号
• server_connections：可以打开到每个服务器的最大连接数
• auto_eject_hosts：是否在服务器连续失败时将其临时踢出
• server_retry_timeout：在服务器被临时踢出后等待重试的时间
• server_failure_limit：连续失败次数达到此值时将服务器临时踢出
• servers：服务器地址、端口和权重列表

4. 项目安装方式

Twemproxy可以通过以下步骤进行安装：

1. 下载Twemproxy的发行版tarball或克隆源代码仓库。
2. 使用 ./configure 命令配置安装选项。
3. 使用 make 命令构建项目。
4. 使用 sudo make install 命令安装项目。

以上步骤将帮助用户成功安装并使用Twemproxy。