apache/bookkeeper

Apache Bookkeeper Docker镜像文档

镜像概述和主要用途

Apache Bookkeeper是Apache软件基金会的开源项目，提供复制日志服务，用于构建复制状态机。日志包含一系列事件，可应用于状态机，Bookkeeper保证每个副本状态机按相同顺序接收所有事件。本Docker镜像提供便捷的Bookkeeper运行环境，支持独立模式和集群模式部署，依赖Zookeeper进行状态存储和Bookie（Bookkeeper服务器）节点发现，适用于本地开发、测试及集群功能演示。

核心功能和特性

• 可靠复制日志：提供高可用的复制日志服务，确保分布式系统中各副本状态机数据一致性
• 多部署模式：支持单容器独立运行和多容器集群部署
• Zookeeper集成：依赖Zookeeper存储元数据和实现Bookie节点自动发现
• 灵活配置：支持通过环境变量或挂载配置文件自定义Bookkeeper参数
• 可扩展性：支持动态扩展Bookie节点数量和客户端应用（如dice）实例

使用场景和适用范围

• 本地开发测试：快速搭建Bookkeeper环境验证基本功能
• 集群演示：展示Bookkeeper集群的部署、扩展及故障转移能力
• 分布式系统原型：作为底层复制日志服务构建分布式应用原型

使用方法和配置说明

独立BookKeeper集群

可在单个容器中运行独立BookKeeper集群，模拟本地部署：

bash
docker run -it \
     --entrypoint "/bin/bash" \
     apache/bookkeeper \
     -c "/opt/bookkeeper/bin/bookkeeper localbookie 3"

也可先启动容器，再在容器内执行bin/bookkeeper localbookie 3

测试集群：需先进入容器，执行BookKeeper shell命令：

bash
# 进入容器
docker exec -it <容器ID或名称> bash

# 测试命令示例
./bin/bookkeeper shell listbookies -rw
./bin/bookkeeper shell simpletest

TL;DR — BookKeeper集群

Docker Compose

通过docker-compose快速部署完整集群：

bash
git clone https://github.com/apache/bookkeeper
cd bookkeeper/docker
docker-compose up -d

默认启动3个Bookie节点和1个dice应用，日志示例：

bookie1_1    | 2017-12-08 23:18:11,315 - INFO  - [bookie-io-1:BookieRequestHandler@51] - Channel connected  [id: 0x405d690e, L:/172.19.0.3:3181 - R:/172.19.0.6:34922]
bookie2_1    | 2017-12-08 23:18:11,326 - INFO  - [bookie-io-1:BookieRequestHandler@51] - Channel connected  [id: 0x7fa8645d, L:/172.19.0.4:3181 - R:/172.19.0.6:38862]
dice_1       | Value = 1, epoch = 5, leading

扩展dice应用数量：

bash
docker-compose up -d --scale dice=3

扩展Bookie节点数量：

bash
docker-compose up -d --scale bookie1=3

关闭集群（清理容器避免残留数据影响下次启动）：

bash
docker-compose down

Makefile

通过Makefile部署集群：

bash
git clone https://github.com/apache/bookkeeper
cd bookkeeper/docker
make run-demo

无X环境（如默认MacOS）需在6个终端分别执行：

bash
make run-zk
make run-bk BOOKIE=1
make run-bk BOOKIE=2
make run-bk BOOKIE=3
make run-dice
make run-dice

重启集群前需清理数据：sudo rm -rf /tmp/test_bk，避免Zookeeper连接失败

分步部署

1. 创建Docker网络

创建专用网络确保容器间名称解析一致性：

bash
docker network create "bk_network"

2. 启动Zookeeper

使用官方Zookeeper镜像在创建的网络中启动Zookeeper：

bash
docker run -d \
    --network "bk_network" \
    --name "test_zookeeper" \
    --hostname "test_zookeeper" \
    zookeeper

3. 初始化元数据存储

首次部署集群需初始化元数据（当前BookKeeper镜像启动首个Bookie时会自动执行此步骤）：

bash
docker run -it --rm \
    --network "bk_network" \
    --env BK_zkServers=test_zookeeper:2181 \
    apache/bookkeeper \
    /opt/bookkeeper/bin/bookkeeper shell metaformat

4. 启动Bookie节点

启动3个Bookie节点组成集群：

bash
# 启动bookie1
docker run -it\
    --network "bk_network" \
    --env BK_zkServers=test_zookeeper:2181 \
    --name "bookie1" \
    --hostname "bookie1" \
    apache/bookkeeper

# 同理启动bookie2和bookie3，只需修改--name和--hostname

5. 运行客户端应用

使用dice应用测试集群（验证 leader 选举和日志写入）：

bash
docker run -it --rm \
    --network "bk_network" \
    --env ZOOKEEPER_SERVERS=test_zookeeper:2181 \
    caiok/bookkeeper-tutorial

配置说明

配置方式

Bookkeeper支持两种配置方式，优先级从高到低为：

1. 环境变量：格式为BK_<原配置键>，如BK_zkServers对应配置文件中的zkServers
2. 挂载配置文件：将本地配置目录挂载到容器/opt/bookkeeper/conf目录

配置示例（混合使用两种方式）：

bash
docker run --name bookie1 -d \
    -v $(local_configure_dir):/opt/bookkeeper/conf/ \  # 挂载配置文件
    -e BK_bookiePort=3181 \                           # 环境变量设置端口
    -e BK_zkServers=zk-server1:2181,zk-server2:2181 \ # 环境变量设置Zookeeper地址
    -e BK_journalPreAllocSizeMB=32 \                  # 环境变量设置日志预分配大小
    apache/bookkeeper

配置覆盖规则

环境变量值会覆盖挂载配置文件中的对应值。例如：

• 挂载的bk_server.conf中设置zkServers=zk-server3:2181
• 同时通过-e BK_zkServers=zk-server1:2181,zk-server2:2181设置环境变量
• 最终生效值为环境变量指定的zk-server1:2181,zk-server2:2181

常用环境变量

配置文件说明

容器内配置文件位于/opt/bookkeeper/conf，源自Bookkeeper源码仓库的https://github.com/apache/bookkeeper/tree/master/bookkeeper-server/conf%EF%BC%8C%E4%B8%BB%E8%A6%81%E6%96%87%E4%BB%B6%E5%8C%85%E6%8B%AC%EF%BC%9A

• bk_server.conf：核心服务配置
• bkenv.sh：环境变量配置
• log4j2.xml：服务日志配置
• log4j2.shell.xml：shell命令日志配置

建议修改前先熟悉各文件功能及默认配置。

注意事项

• 事务日志存储：journal目录应使用专用存储设备以保证性能，避免与其他IO密集型操作共享磁盘
• 数据清理：如需重置Bookie节点，可执行以下命令（替换默认启动命令）：

  bash
  # 清理cookie并格式化
  /opt/bookkeeper/bin/bookkeeper shell bookieformat -nonInteractive -force -deleteCookie
  # 启动自动恢复
  /opt/bookkeeper/bin/bookkeeper autorecovery
  

许可信息

镜像中软件的许可信息参见https://github.com/apache/bookkeeper/blob/master/LICENSE%E3%80%82