使用 Docker Compose 安装

准备工作

安装 Docker 和 Compose v2。为 Docker 虚拟机预留至少 4 GiB 内存及数 GiB 可用磁盘空间。镜像支持 Linux AMD64 和 ARM64。集群镜像 eloqdata/lavik:0.1.0-beta.1-cluster 包含 Data、Meta、lavik-ctl、redis-cli 和初始化工具，使用 Minimal 版本的内核 TCP 和 io_uring，不含 SPDK/DPDK 或 Lavik Admin。

这是在一台 Docker 主机上运行的本地评估集群，无法抵御主机故障。它使用 beta.1 的 NuRaft Meta 实现。请使用新卷，不要复用较新源码版 Admin 快速入门的卷。全部 16,384 个槽最初归属一个主节点，通过原生复制同步至从节点，角色由 Meta 管理。

固定网桥子网 172.30.92.0/24 必须未被占用。每个 Docker 守护进程仅运行一份此示例。需要调整时，请在首次启动前同时修改 compose.yaml 和 cluster.toml 中的地址，保持一致。容器以 UID/GID 10001:10001 运行，通过 seccomp=unconfined 允许 io_uring，无需特权模式。

下载并启动集群

将配套的 Compose 文件和清单下载到新目录。链接固定到 dockerimages 分支中适用于 beta.1 的快照，无需克隆仓库或编译。两个文件必须放在同一目录，后续 Compose 命令均在该目录中执行。

初始主节点发布 localhost:6379，从节点发布 localhost:6380。如果端口被占用，请先执行 export LAVIK_PRIMARY_PORT=16779 LAVIK_FOLLOWER_PORT=16780，并在后续 Compose 命令中保留这些设置。每个 Data 节点的 LAVIK_DATA_SIZE 默认为 1G，LAVIK_THREADS 默认为 2。

mkdir -p lavik-compose
cd lavik-compose
curl --fail --location --output compose.yaml \
  https://raw.githubusercontent.com/eloqdata/lavik/a1770a78b52e0bb9ec32e20b92af6282e73efabd/deploy/docker/compose.yaml
curl --fail --location --output cluster.toml \
  https://raw.githubusercontent.com/eloqdata/lavik/a1770a78b52e0bb9ec32e20b92af6282e73efabd/deploy/docker/cluster.toml
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs -f bootstrap

等待日志显示 “Cluster is READY (one primary, one follower).” 且 bootstrap 成功退出。Ctrl-C 只停止跟踪日志，不会停止容器。容器健康检查仅表示进程可用，请使用 cluster-status 检查 cluster_ready 和当前主节点。若初始化失败，先检查 docker compose logs bootstrap 及集群状态，不要通过删除卷来修复不确定的状态。

连接并检查复制

docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c SET hello lavik
docker compose exec primary redis-cli -c GET hello

# Read on one connection after replication catches up.
printf 'READONLY\nGET hello\n' | docker compose exec -T follower redis-cli --raw

SET 返回 OK，GET 返回 lavik。从节点读取会在同一连接上发送 READONLY 和 GET；若值尚未同步，请等待复制追上后重试。primary 和 follower 服务名仅描述初始角色，实际角色可能发生变化。

集群通告 Docker 内部地址。需要跟随 MOVED 重定向的集群客户端必须在 Compose 网络内运行，上述 exec 命令满足此条件。macOS 上的宿主机客户端可直连发布端口，但无法跟随指向网桥地址的重定向。远程部署需要所有节点和客户端都能访问的地址，以及认证和 TLS。本示例仅向回环地址发布 Data 端口，不发布 Meta 端口，Docker 网络内使用明文通信。

体验受控故障转移

集群就绪且复制追上后，使用镜像内的 lavik-ctl 转移 group-1 的主节点所有权，随后检查 cluster-status。redis-cli -c 在 Compose 网络内部运行，因此可以跟随旧主节点返回的重定向。

docker compose exec meta-1 lavik-ctl failover group-1 \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin \
  --failover-timeout-ms 60000
docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c GET hello

停止并恢复集群

docker compose down --timeout 60
docker compose up -d
docker compose logs -f bootstrap
# After bootstrap exits successfully, check readiness and the current owner.
docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c GET hello

两个 Data 节点和三个 Meta 节点各自拥有命名卷，docker compose down 会保留这五个卷。再次启动时，Meta 加载持久化拓扑；bootstrap 仅初始化尚未初始化的集群，否则等待恢复，不会重新强制应用最初的角色分配。恢复期间自动故障转移可能改变主节点，请通过 cluster-status 查询，不要依赖服务名。

仅在明确要完全重置时使用 docker compose down --volumes，它会永久删除全部五个数据库卷。日常重启或升级切勿添加 --volumes。修改 LAVIK_DATA_SIZE 不会调整已有数据文件的大小。

管理主从集群并配置 Grafana →