拓冰网站定制 
TigerBeetle 容器化部署指南使用 Docker / Docker Compose 运行 TigerBeetle 集群【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle导读TigerBeetle 以单个、小型、静态链接的二进制文件分发官方并不推荐用 Docker 额外包一层抽象来运行它但当开发环境或 CI 基础设施已经以容器为核心时直接使用官方镜像快速拉起单机实例或多节点集群依然非常实用。本文以 docs/operating/deploying/docker.md 为主线完整讲解镜像获取、数据文件格式化、单节点启动、Docker Compose 三副本集群编排以及 seccomp、内存锁定、OOM、调试镜像等容器场景下的典型故障排查并结合仓库源码补充format/start参数语义、数据文件命名规则与镜像构建方式等底层细节让读者在容器内也能正确、安全地部署 TigerBeetle。为什么官方不推荐用 Docker 运行 TigerBeetleTigerBeetle 被设计成一个“单进程、单二进制”的数据库官方安装方式见 docs/operating/installing.md是直接下载预编译的可执行文件或者在目标机器上运行构建产物。由于二进制本身静态链接、无外部依赖直接部署在目标机器上已经足够简单此时再引入 Docker 这类容器抽象反而增加了额外复杂度收益却很小。这一点在源码中也有直接印证发布脚本 src/scripts/release.zig 的注释明确写道“Docker is not required and not recommended for running TigerBeetle. A container is published just for convenience of consumers expecting one!”也就是说官方发布容器镜像主要是“满足期望使用容器的用户的便利性”而不是推荐的生产部署路径。生产环境更推荐每个副本独占一台物理机/虚拟机由 systemd 等监督进程守护详见 systemd 部署指南 与 集群推荐。因此本文的适用场景是开发环境、本地实验、CI 冒烟测试或已有容器基础设施、需要快速验证的场景。理解这一前提有助于正确解读后面出现的各种“非典型”配置。获取官方镜像GitHub Container RegistryTigerBeetle 的 Docker 镜像发布在 GitHub Container RegistryGHCR镜像名称为ghcr.io/tigerbeetle/tigerbeetle官方文档给出的镜像地址为ghcr.io/tigerbeetle/tigerbeetle拉取最新版本docker pull ghcr.io/tigerbeetle/tigerbeetle除常规镜像外还存在一个:debug调试镜像标签如ghcr.io/tigerbeetle/tigerbeetle:tag-debug用于获取更好的 panic 堆栈信息后文“调试 panic”一节会详细说明。关于镜像本身从 src/scripts/release.zig 的publish_docker实现可以了解几个容器细节镜像基于alpine:latest并在其中通过apk add tini安装tini作为 PID 1 入口ENTRYPOINT [tini, --, /tigerbeetle]。这是因为 TigerBeetle 自身不安装信号处理器而 PID 1 没有默认的 SIGTERM 处理器直接用二进制作 PID 1 会导致docker stop挂起tini 作为 PID 1 可以正确转发信号。镜像使用buildx同时构建linux/amd64与linux/arm64两个平台分别对应x86_64-linux与aarch64-linux的预编译二进制TARGETARCH为 amd64/arm64。发布流程在推送后还会执行一次最佳努力测试docker run ... version --verbose断言输出中包含ReleaseSafeRelease 镜像或Debug调试镜像模式以及对应的 release triple。由于发布脚本会把编译产物zig-out/dist 下的 zip解压后 COPY 进镜像容器内的二进制与官方发布的二进制是一致的因此容器内命令用法与裸机完全一致。第一步格式化数据文件formatTigerBeetle 的每个副本都对应一个本地数据文件文件内既包含状态机数据也记录了该文件属于哪个集群、哪个副本docs/operating/deploying/README.md 中建议按${CLUSTER_ID}_${REPLICA_INDEX}.tigerbeetle命名例如0_0.tigerbeetle。在使用 Docker 时数据文件必须通过 volume 挂载到宿主机否则容器销毁后数据随之丢失。格式化单副本数据文件docker run --security-opt seccompunconfined \ -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \ format --cluster0 --replica0 --replica-count1 /data/0_0.tigerbeetle正常输出类似info(io): creating 0_0.tigerbeetle... info(io): allocating 660.140625MiB...这条命令中的三个参数语义如下与 命令行帮助 中的format定义一致参数说明--clusterinteger128 位无符号十进制整数形式的集群 ID。默认会生成随机集群 ID官方部署文档提醒集群 ID0保留用于测试生产请使用随机值。启动时源码 main.zig 也会对cluster 0输出警告“A cluster id of 0 is reserved for testing and benchmarking, do not use in production.”--replicaindex当前副本的零基索引解释为--addresses数组的下标索引 ≥ replica-count 时该副本为 standby。同一集群内各副本的--replica必须互不相同--replica-countinteger参与复制replication的副本总数。当前版本集群大小创建后不可更改format完成时会在宿主机$(pwd)/data目录下生成0_0.tigerbeetle数据文件。关于--security-opt seccompunconfinedDocker 25.0.0 及更新版本默认的 seccomp 配置会阻止io_uring相关系统调用而 TigerBeetle 的 Linux I/O 层正是基于io_uring实现见 src/io/linux.zig。因此在 Docker 下运行 TigerBeetle 几乎总是需要该选项详见下文“故障排查”一节。第二步启动单节点服务start格式化完成后即可启动服务监听端口通过-p 3000:3000映射到宿主机docker run -it --security-opt seccompunconfined \ -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \ start --addresses0.0.0.0:3000 /data/0_0.tigerbeetle启动成功后的日志形如info(io): opening 0_0.tigerbeetle... info(main): 0: cluster0: listening on 0.0.0.0:3000start命令的核心参数为--addressesaddresses。从 cli.zig 的帮助文本看接受以逗号分隔的 IPv4/IPv6 地址与端口列表顺序有意义必须与集群所有副本及客户端保持一致addresses[i]对应副本i地址或端口二选一可以省略省略时使用默认地址/端口源码中取自constants.address与constants.port全部副本必须传入同一份--addresses列表且addresses[replica_index]必须是该副本自己的地址。因此在上面的单节点命令中0.0.0.0:3000表示该副本在容器内监听 3000 端口宿主机通过-p 3000:3000访问。启动过程中只要未指定--developmentTigerBeetle 还会尝试锁定进程全部内存见 main.zig调用stdx.memory_lock_allocated即 src/stdx/mlock.zig 中的mlockall以避免内核 swap 把内存页换出、绕过存储容错机制。若锁定失败会输出警告日志并提示生产副本考虑授予CAP_IPC_LOCK、提高 MEMLOCK 进程限制或系统级关闭 swap——这正是后文 macOS 小节error: SystemResources的根源。第三步用 Docker Compose 运行三副本集群为每个副本分别格式化数据文件集群中每个副本都需要自己的数据文件且--replica各不相同--cluster与--replica-count必须一致docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica0 --replica-count3 /data/0_0.tigerbeetle docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica1 --replica-count3 /data/0_1.tigerbeetle docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica2 --replica-count3 /data/0_2.tigerbeetle注意数据文件记录了它属于集群中的哪个副本。因此0_0.tigerbeetle只能由--replica0的进程打开不能在后续启动时错配文件与副本索引。编写 docker-compose.yml官方文档给出的三副本 compose 文件完整如下原样继承version: 3.7 ## # Note: this example might only work with linux using network_mode:host because of 2 reasons: # # 1. When specifying an internal docker network, other containers are only available using dns based routing: # e.g. from tigerbeetle_0, the other replicas are available at tigerbeetle_1:3002 and # tigerbeetle_2:3003 respectively. # # 2. Tigerbeetle performs some validation of the ip address provided in the --addresses parameter # and wont let us specify a custom domain name. # # The workaround for now is to use network_mode:host in the containers instead of specifying our # own internal docker network ## services: tigerbeetle_0: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_0.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined tigerbeetle_1: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_1.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined tigerbeetle_2: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_2.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined要点解读三个服务共用同一份--addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003这是集群全量地址列表顺序即副本索引。三个副本分别打开0_0.tigerbeetle、0_1.tigerbeetle、0_2.tigerbeetle。network_mode: host是当前必需的变通方案注释解释了原因——1若使用 Docker 内部网络副本间只能通过 DNS 路由发现彼此如tigerbeetle_1:3002而2TigerBeetle 会对--addresses中的 IP 做校验不允许自定义域名。因此在修复该限制之前官方示例要求 host 网络模式该示例主要针对 Linux 环境。host 网络模式下端口 3001/3002/3003 直接暴露在宿主机上因此不能再写-p端口映射。seccompunconfined以security_opt形式写入 compose作用与docker run中的同名参数一致都是为了放行io_uring。启动集群docker-compose up启动日志示意注意info(main)中输出的0:、1:、2:即副本索引以及message_bus建立副本间连接、clock同步的日志Starting tigerbeetle_0 ... done Starting tigerbeetle_2 ... done Recreating tigerbeetle_1 ... done Attaching to tigerbeetle_0, tigerbeetle_2, tigerbeetle_1 tigerbeetle_1 | info(io): opening 0_1.tigerbeetle... tigerbeetle_2 | info(io): opening 0_2.tigerbeetle... tigerbeetle_0 | info(io): opening 0_0.tigerbeetle... tigerbeetle_0 | info(main): 0: cluster0: listening on 0.0.0.0:3001 tigerbeetle_2 | info(main): 2: cluster0: listening on 0.0.0.0:3003 tigerbeetle_1 | info(main): 1: cluster0: listening on 0.0.0.0:3002 tigerbeetle_0 | info(message_bus): connected to replica 1 tigerbeetle_0 | info(message_bus): connected to replica 2 tigerbeetle_1 | info(message_bus): connected to replica 2 tigerbeetle_1 | info(message_bus): connection from replica 0 tigerbeetle_2 | info(message_bus): connection from replica 0 tigerbeetle_2 | info(message_bus): connection from replica 1 tigerbeetle_0 | info(clock): 0: system time is 83ns ahead tigerbeetle_2 | info(clock): 2: system time is 83ns ahead tigerbeetle_1 | info(clock): 1: system time is 78ns ahead ... and so on ...当看到三个副本之间message_bus的 connection 日志时说明副本间已建立复制连接三副本集群处于可服务状态。客户端需要连接的地址即宿主机上的127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003与--addresses顺序一致。容器场景下的故障排查Troubleshootingerror: PermissionDenied如果启动时出现该错误很可能是 Docker 版本为 25.0.0 或更新此类版本默认 seccomp 配置会默认阻止 io_uring而 TigerBeetle 的 Linux I/O 依赖 io_uring。解决办法是显式传入--security-opt seccompunconfined或在 compose 的security_opt中配置放行相关系统调用。这也是本文所有 Docker 命令都带该参数的原因。exited with code 137如果容器退出码为 137 且 TigerBeetle 没有任何日志输出通常是 Linux OOMKiller 杀掉了进程137 128 SIGKILL。常见诱因与对策在虚拟机内运行 Docker/PodmanmacOS 上 Docker Desktop 即属于此类尝试提高虚拟机的内存上限开发环境下可通过降低缓存占用减少内存例如启动时加上--cache-grid256MiB。--cache-grid参数在 cli.zig 中有说明网格缓存grid cache相当于 TigerBeetle 的页缓存应尽可能设置得大在只运行 TigerBeetle 的机器上建议约为“总内存 − 3GiBTigerBeetle− 1GiB系统”例如 16GiB 机器设 12GiB默认值来自编译期常量constants.grid_cache_size_defaultsrc/constants.zig。开发/测试时将其调小如 256MiB即可显著降低内存占用。调试 panicDebugging panics如果 TigerBeetle 发生 panic 且你能复现可以改用:debug标签的调试镜像获取更完整的堆栈信息docker run -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle:debug \ start --addresses0.0.0.0:3000 /data/0_0.tigerbeetle调试镜像对应 Debug 构建模式发布镜像为 ReleaseSafe 模式发布脚本正是通过version --verbose输出中的构建模式来验证镜像类型src/scripts/release.zig。注意调试镜像仅用于定位问题不应作为生产运行镜像。macOS 上的特殊情况error: SystemResources在 macOS 的 Docker 中运行 TigerBeetle 若出现error: SystemResources通常是容器阻止了 TigerBeetle 锁定内存memory lock。内存锁定既为 io_uring 所需也用于防止内核 swap 绕过 TigerBeetle 的存储容错机制源码中对应 src/stdx/mlock.zig 的mlockall调用锁定时遇到RLIMIT_MEMLOCK不足会输出警告而底层 I/O 层在 io_uring 资源受限时也会返回error.SystemResources见 src/io/linux.zig。放开 MEMLOCK 限制在 Docker 下提高内存锁定上限可任选以下方式之一docker run时附加--cap-add IPC_LOCKdocker run时附加--ulimit memlock-1:-1或修改$HOME/.docker/daemon.json的默认 ulimit 并重启 Docker for Mac 应用{ ... other settings ... default-ulimits: { memlock: { Hard: -1, Name: memlock, Soft: -1 } }, ... other settings ... }如果使用 Docker Compose则需要在对应服务上添加IPC_LOCKcapability... rest of docker-compose.yml ... services: tigerbeetle_0: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_0.tigerbeetle network_mode: host cap_add: # HERE - IPC_LOCK # HERE volumes: - ./data:/data ... rest of docker-compose.yml ...IPC_LOCK之所以必要是因为 TigerBeetle 在生产模式下未加--development会主动mlockall锁定已分配内存容器默认的 MEMLOCK 上限会阻止该操作放开后即可正常锁定内存。这与 main.zig 中“生产副本可考虑以CAP_IPC_LOCK特权运行”的告警建议相互印证。相关背景讨论可参考官方仓库的 issue #92见 docker.md 末尾。生产环境部署的正确姿势再次强调容器部署的定位Docker 方案适合开发、测试与快速验证。若在容器中运行 TigerBeetle请务必牢记以下清单始终使用--security-opt seccompunconfinedDocker ≥ 25.0.0 默认阻止 io_uring数据文件必须挂载为 volume 并做好宿主机持久化与备份三副本集群在 Linux 上需使用network_mode: host才能让副本间通过--addresses直接互通生产集群请使用非零随机 cluster ID三副本仅是测试配置生产建议六副本见 集群推荐并由监督进程守护systemd在只运行 TigerBeetle 的机器上按“总内存 − 4GiB”量级配置--cache-grid开发环境可调小以省内存。对于真正追求“mission critical safety and performance”的生产部署官方推荐路径是通过 安装指南 获取静态链接二进制直接部署在专用机器上用 systemd 托管进程、按 部署总览 的流程获取二进制 → format 数据文件 → start 启动副本完成集群搭建。本文的容器方案可以与之并行使用作为本地联调与 CI 环境的最便捷入口。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TigerBeetle 容器化部署指南：使用 Docker / Docker Compose 运行 TigerBeetle 集群
TigerBeetle 容器化部署指南使用 Docker / Docker Compose 运行 TigerBeetle 集群【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle导读TigerBeetle 以单个、小型、静态链接的二进制文件分发官方并不推荐用 Docker 额外包一层抽象来运行它但当开发环境或 CI 基础设施已经以容器为核心时直接使用官方镜像快速拉起单机实例或多节点集群依然非常实用。本文以 docs/operating/deploying/docker.md 为主线完整讲解镜像获取、数据文件格式化、单节点启动、Docker Compose 三副本集群编排以及 seccomp、内存锁定、OOM、调试镜像等容器场景下的典型故障排查并结合仓库源码补充format/start参数语义、数据文件命名规则与镜像构建方式等底层细节让读者在容器内也能正确、安全地部署 TigerBeetle。为什么官方不推荐用 Docker 运行 TigerBeetleTigerBeetle 被设计成一个“单进程、单二进制”的数据库官方安装方式见 docs/operating/installing.md是直接下载预编译的可执行文件或者在目标机器上运行构建产物。由于二进制本身静态链接、无外部依赖直接部署在目标机器上已经足够简单此时再引入 Docker 这类容器抽象反而增加了额外复杂度收益却很小。这一点在源码中也有直接印证发布脚本 src/scripts/release.zig 的注释明确写道“Docker is not required and not recommended for running TigerBeetle. A container is published just for convenience of consumers expecting one!”也就是说官方发布容器镜像主要是“满足期望使用容器的用户的便利性”而不是推荐的生产部署路径。生产环境更推荐每个副本独占一台物理机/虚拟机由 systemd 等监督进程守护详见 systemd 部署指南 与 集群推荐。因此本文的适用场景是开发环境、本地实验、CI 冒烟测试或已有容器基础设施、需要快速验证的场景。理解这一前提有助于正确解读后面出现的各种“非典型”配置。获取官方镜像GitHub Container RegistryTigerBeetle 的 Docker 镜像发布在 GitHub Container RegistryGHCR镜像名称为ghcr.io/tigerbeetle/tigerbeetle官方文档给出的镜像地址为ghcr.io/tigerbeetle/tigerbeetle拉取最新版本docker pull ghcr.io/tigerbeetle/tigerbeetle除常规镜像外还存在一个:debug调试镜像标签如ghcr.io/tigerbeetle/tigerbeetle:tag-debug用于获取更好的 panic 堆栈信息后文“调试 panic”一节会详细说明。关于镜像本身从 src/scripts/release.zig 的publish_docker实现可以了解几个容器细节镜像基于alpine:latest并在其中通过apk add tini安装tini作为 PID 1 入口ENTRYPOINT [tini, --, /tigerbeetle]。这是因为 TigerBeetle 自身不安装信号处理器而 PID 1 没有默认的 SIGTERM 处理器直接用二进制作 PID 1 会导致docker stop挂起tini 作为 PID 1 可以正确转发信号。镜像使用buildx同时构建linux/amd64与linux/arm64两个平台分别对应x86_64-linux与aarch64-linux的预编译二进制TARGETARCH为 amd64/arm64。发布流程在推送后还会执行一次最佳努力测试docker run ... version --verbose断言输出中包含ReleaseSafeRelease 镜像或Debug调试镜像模式以及对应的 release triple。由于发布脚本会把编译产物zig-out/dist 下的 zip解压后 COPY 进镜像容器内的二进制与官方发布的二进制是一致的因此容器内命令用法与裸机完全一致。第一步格式化数据文件formatTigerBeetle 的每个副本都对应一个本地数据文件文件内既包含状态机数据也记录了该文件属于哪个集群、哪个副本docs/operating/deploying/README.md 中建议按${CLUSTER_ID}_${REPLICA_INDEX}.tigerbeetle命名例如0_0.tigerbeetle。在使用 Docker 时数据文件必须通过 volume 挂载到宿主机否则容器销毁后数据随之丢失。格式化单副本数据文件docker run --security-opt seccompunconfined \ -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \ format --cluster0 --replica0 --replica-count1 /data/0_0.tigerbeetle正常输出类似info(io): creating 0_0.tigerbeetle... info(io): allocating 660.140625MiB...这条命令中的三个参数语义如下与 命令行帮助 中的format定义一致参数说明--clusterinteger128 位无符号十进制整数形式的集群 ID。默认会生成随机集群 ID官方部署文档提醒集群 ID0保留用于测试生产请使用随机值。启动时源码 main.zig 也会对cluster 0输出警告“A cluster id of 0 is reserved for testing and benchmarking, do not use in production.”--replicaindex当前副本的零基索引解释为--addresses数组的下标索引 ≥ replica-count 时该副本为 standby。同一集群内各副本的--replica必须互不相同--replica-countinteger参与复制replication的副本总数。当前版本集群大小创建后不可更改format完成时会在宿主机$(pwd)/data目录下生成0_0.tigerbeetle数据文件。关于--security-opt seccompunconfinedDocker 25.0.0 及更新版本默认的 seccomp 配置会阻止io_uring相关系统调用而 TigerBeetle 的 Linux I/O 层正是基于io_uring实现见 src/io/linux.zig。因此在 Docker 下运行 TigerBeetle 几乎总是需要该选项详见下文“故障排查”一节。第二步启动单节点服务start格式化完成后即可启动服务监听端口通过-p 3000:3000映射到宿主机docker run -it --security-opt seccompunconfined \ -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle \ start --addresses0.0.0.0:3000 /data/0_0.tigerbeetle启动成功后的日志形如info(io): opening 0_0.tigerbeetle... info(main): 0: cluster0: listening on 0.0.0.0:3000start命令的核心参数为--addressesaddresses。从 cli.zig 的帮助文本看接受以逗号分隔的 IPv4/IPv6 地址与端口列表顺序有意义必须与集群所有副本及客户端保持一致addresses[i]对应副本i地址或端口二选一可以省略省略时使用默认地址/端口源码中取自constants.address与constants.port全部副本必须传入同一份--addresses列表且addresses[replica_index]必须是该副本自己的地址。因此在上面的单节点命令中0.0.0.0:3000表示该副本在容器内监听 3000 端口宿主机通过-p 3000:3000访问。启动过程中只要未指定--developmentTigerBeetle 还会尝试锁定进程全部内存见 main.zig调用stdx.memory_lock_allocated即 src/stdx/mlock.zig 中的mlockall以避免内核 swap 把内存页换出、绕过存储容错机制。若锁定失败会输出警告日志并提示生产副本考虑授予CAP_IPC_LOCK、提高 MEMLOCK 进程限制或系统级关闭 swap——这正是后文 macOS 小节error: SystemResources的根源。第三步用 Docker Compose 运行三副本集群为每个副本分别格式化数据文件集群中每个副本都需要自己的数据文件且--replica各不相同--cluster与--replica-count必须一致docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica0 --replica-count3 /data/0_0.tigerbeetle docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica1 --replica-count3 /data/0_1.tigerbeetle docker run --security-opt seccompunconfined -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle format --cluster0 --replica2 --replica-count3 /data/0_2.tigerbeetle注意数据文件记录了它属于集群中的哪个副本。因此0_0.tigerbeetle只能由--replica0的进程打开不能在后续启动时错配文件与副本索引。编写 docker-compose.yml官方文档给出的三副本 compose 文件完整如下原样继承version: 3.7 ## # Note: this example might only work with linux using network_mode:host because of 2 reasons: # # 1. When specifying an internal docker network, other containers are only available using dns based routing: # e.g. from tigerbeetle_0, the other replicas are available at tigerbeetle_1:3002 and # tigerbeetle_2:3003 respectively. # # 2. Tigerbeetle performs some validation of the ip address provided in the --addresses parameter # and wont let us specify a custom domain name. # # The workaround for now is to use network_mode:host in the containers instead of specifying our # own internal docker network ## services: tigerbeetle_0: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_0.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined tigerbeetle_1: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_1.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined tigerbeetle_2: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_2.tigerbeetle network_mode: host volumes: - ./data:/data security_opt: - seccompunconfined要点解读三个服务共用同一份--addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003这是集群全量地址列表顺序即副本索引。三个副本分别打开0_0.tigerbeetle、0_1.tigerbeetle、0_2.tigerbeetle。network_mode: host是当前必需的变通方案注释解释了原因——1若使用 Docker 内部网络副本间只能通过 DNS 路由发现彼此如tigerbeetle_1:3002而2TigerBeetle 会对--addresses中的 IP 做校验不允许自定义域名。因此在修复该限制之前官方示例要求 host 网络模式该示例主要针对 Linux 环境。host 网络模式下端口 3001/3002/3003 直接暴露在宿主机上因此不能再写-p端口映射。seccompunconfined以security_opt形式写入 compose作用与docker run中的同名参数一致都是为了放行io_uring。启动集群docker-compose up启动日志示意注意info(main)中输出的0:、1:、2:即副本索引以及message_bus建立副本间连接、clock同步的日志Starting tigerbeetle_0 ... done Starting tigerbeetle_2 ... done Recreating tigerbeetle_1 ... done Attaching to tigerbeetle_0, tigerbeetle_2, tigerbeetle_1 tigerbeetle_1 | info(io): opening 0_1.tigerbeetle... tigerbeetle_2 | info(io): opening 0_2.tigerbeetle... tigerbeetle_0 | info(io): opening 0_0.tigerbeetle... tigerbeetle_0 | info(main): 0: cluster0: listening on 0.0.0.0:3001 tigerbeetle_2 | info(main): 2: cluster0: listening on 0.0.0.0:3003 tigerbeetle_1 | info(main): 1: cluster0: listening on 0.0.0.0:3002 tigerbeetle_0 | info(message_bus): connected to replica 1 tigerbeetle_0 | info(message_bus): connected to replica 2 tigerbeetle_1 | info(message_bus): connected to replica 2 tigerbeetle_1 | info(message_bus): connection from replica 0 tigerbeetle_2 | info(message_bus): connection from replica 0 tigerbeetle_2 | info(message_bus): connection from replica 1 tigerbeetle_0 | info(clock): 0: system time is 83ns ahead tigerbeetle_2 | info(clock): 2: system time is 83ns ahead tigerbeetle_1 | info(clock): 1: system time is 78ns ahead ... and so on ...当看到三个副本之间message_bus的 connection 日志时说明副本间已建立复制连接三副本集群处于可服务状态。客户端需要连接的地址即宿主机上的127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003与--addresses顺序一致。容器场景下的故障排查Troubleshootingerror: PermissionDenied如果启动时出现该错误很可能是 Docker 版本为 25.0.0 或更新此类版本默认 seccomp 配置会默认阻止 io_uring而 TigerBeetle 的 Linux I/O 依赖 io_uring。解决办法是显式传入--security-opt seccompunconfined或在 compose 的security_opt中配置放行相关系统调用。这也是本文所有 Docker 命令都带该参数的原因。exited with code 137如果容器退出码为 137 且 TigerBeetle 没有任何日志输出通常是 Linux OOMKiller 杀掉了进程137 128 SIGKILL。常见诱因与对策在虚拟机内运行 Docker/PodmanmacOS 上 Docker Desktop 即属于此类尝试提高虚拟机的内存上限开发环境下可通过降低缓存占用减少内存例如启动时加上--cache-grid256MiB。--cache-grid参数在 cli.zig 中有说明网格缓存grid cache相当于 TigerBeetle 的页缓存应尽可能设置得大在只运行 TigerBeetle 的机器上建议约为“总内存 − 3GiBTigerBeetle− 1GiB系统”例如 16GiB 机器设 12GiB默认值来自编译期常量constants.grid_cache_size_defaultsrc/constants.zig。开发/测试时将其调小如 256MiB即可显著降低内存占用。调试 panicDebugging panics如果 TigerBeetle 发生 panic 且你能复现可以改用:debug标签的调试镜像获取更完整的堆栈信息docker run -p 3000:3000 -v $(pwd)/data:/data ghcr.io/tigerbeetle/tigerbeetle:debug \ start --addresses0.0.0.0:3000 /data/0_0.tigerbeetle调试镜像对应 Debug 构建模式发布镜像为 ReleaseSafe 模式发布脚本正是通过version --verbose输出中的构建模式来验证镜像类型src/scripts/release.zig。注意调试镜像仅用于定位问题不应作为生产运行镜像。macOS 上的特殊情况error: SystemResources在 macOS 的 Docker 中运行 TigerBeetle 若出现error: SystemResources通常是容器阻止了 TigerBeetle 锁定内存memory lock。内存锁定既为 io_uring 所需也用于防止内核 swap 绕过 TigerBeetle 的存储容错机制源码中对应 src/stdx/mlock.zig 的mlockall调用锁定时遇到RLIMIT_MEMLOCK不足会输出警告而底层 I/O 层在 io_uring 资源受限时也会返回error.SystemResources见 src/io/linux.zig。放开 MEMLOCK 限制在 Docker 下提高内存锁定上限可任选以下方式之一docker run时附加--cap-add IPC_LOCKdocker run时附加--ulimit memlock-1:-1或修改$HOME/.docker/daemon.json的默认 ulimit 并重启 Docker for Mac 应用{ ... other settings ... default-ulimits: { memlock: { Hard: -1, Name: memlock, Soft: -1 } }, ... other settings ... }如果使用 Docker Compose则需要在对应服务上添加IPC_LOCKcapability... rest of docker-compose.yml ... services: tigerbeetle_0: image: ghcr.io/tigerbeetle/tigerbeetle command: start --addresses0.0.0.0:3001,0.0.0.0:3002,0.0.0.0:3003 /data/0_0.tigerbeetle network_mode: host cap_add: # HERE - IPC_LOCK # HERE volumes: - ./data:/data ... rest of docker-compose.yml ...IPC_LOCK之所以必要是因为 TigerBeetle 在生产模式下未加--development会主动mlockall锁定已分配内存容器默认的 MEMLOCK 上限会阻止该操作放开后即可正常锁定内存。这与 main.zig 中“生产副本可考虑以CAP_IPC_LOCK特权运行”的告警建议相互印证。相关背景讨论可参考官方仓库的 issue #92见 docker.md 末尾。生产环境部署的正确姿势再次强调容器部署的定位Docker 方案适合开发、测试与快速验证。若在容器中运行 TigerBeetle请务必牢记以下清单始终使用--security-opt seccompunconfinedDocker ≥ 25.0.0 默认阻止 io_uring数据文件必须挂载为 volume 并做好宿主机持久化与备份三副本集群在 Linux 上需使用network_mode: host才能让副本间通过--addresses直接互通生产集群请使用非零随机 cluster ID三副本仅是测试配置生产建议六副本见 集群推荐并由监督进程守护systemd在只运行 TigerBeetle 的机器上按“总内存 − 4GiB”量级配置--cache-grid开发环境可调小以省内存。对于真正追求“mission critical safety and performance”的生产部署官方推荐路径是通过 安装指南 获取静态链接二进制直接部署在专用机器上用 systemd 托管进程、按 部署总览 的流程获取二进制 → format 数据文件 → start 启动副本完成集群搭建。本文的容器方案可以与之并行使用作为本地联调与 CI 环境的最便捷入口。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考