RustFS 专用 Docker Compose 场景配置指南4 节点分布式集群测试与可观测性验证【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs本文以 RustFS 仓库中.docker/compose/目录下的专用 Docker Compose 配置为线索系统讲解如何用一套容器化方案快速拉起 4 节点分布式集群、执行带故障转移Failover与基准测试的端到端校验脚本以及通过 OTLP 协议验证 Trace/Metric/Log 采集链路。读完本文你将掌握 RustFS 集群测试场景的完整命令、关键环境变量RUSTFS_VOLUMES、RUSTFS_OBS_ENDPOINT、RUSTFS_OBS_LOGGER_LEVEL等的含义与调优方法并能自行区分推荐的生产级可观测性栈与仅用于最小化测试的遗留方案。目录定位这些 Compose 文件是做什么的在 RustFS 仓库的 .docker/compose/README.md 中明确说明该目录存放的是面向特定测试场景的专用 Docker Compose 配置而非生产部署模板。其定位可以概括为两点集群测试Cluster Testing模拟一个 4 节点的 RustFS 分布式集群用于验证分布式存储逻辑、一致性consensus与故障转移failover。遗留/最小化可观测性Legacy / Minimal Observability一个精简版观测栈已标记为 Deprecated废弃仅保留用于历史参考或特定最小化测试。需要特别注意的是README 给出了一个明确的官方建议如果目标是可观测性请优先使用 .docker/observability/ 目录下全新的一体化观测栈Prometheus、Grafana、Tempo、Loki、OpenTelemetry Collector 全家桶带持久化存储与优化配置而不要使用本目录下的docker-compose.observability.yaml。配置文件清单当前 .docker/compose/ 目录中与 README 直接相关的核心配置文件如下文件用途状态docker-compose.cluster.yaml4 节点 RustFS 分布式集群基于镜像启动推荐用于集群测试docker-compose.cluster.local-build.yml4 节点集群本地源码构建镜像供校验脚本使用docker-compose.cluster.local-build.profiling-amd64.yml4 节点集群 内置 CPU Profiling OTLP 上报用于 Profiling 与 Trace 验证docker-compose.observability.yaml最小化观测栈Deprecated请改用 .docker/observability/docker-compose.yml集群测试配置docker-compose.cluster.yaml该文件定义了node0到node3四个完全对称的服务。以node0为例其关键配置如下services: node0: image: rustfs/rustfs:latest # 可替换为你的镜像名与标签 container_name: node0 hostname: node0 environment: - RUSTFS_VOLUMEShttp://node{0...3}:9000/data/rustfs{0...3} - RUSTFS_ADDRESS0.0.0.0:9000 - RUSTFS_CONSOLE_ENABLEtrue - RUSTFS_ACCESS_KEY${RUSTFS_ACCESS_KEY:-rustfsadmin-local} - RUSTFS_SECRET_KEY${RUSTFS_SECRET_KEY:-rustfssecret-local} platform: linux/amd64 ports: - 9000:9000 # 宿主机 9000 端口映射到容器 9000 端口 volumes: - ../../target/x86_64-unknown-linux-gnu/release/rustfs:/app/rustfs command: /app/rustfs其余节点node1、node2、node3结构完全一致仅宿主机端口依次为9001、9002、9003。理解这份配置的核心在于以下几个环境变量RUSTFS_VOLUMES声明整个集群共享的卷拓扑http://node{0...3}:9000/data/rustfs{0...3}是一个带花括号展开的分布式存储描述——4 个节点彼此通过 HTTP 协议挂载各自的存储卷。这是 RustFS 分布式部署的入口配置。RUSTFS_ADDRESS节点监听地址0.0.0.0:9000表示监听所有网卡接口的 9000 端口。RUSTFS_CONSOLE_ENABLEtrue启用 RustFS 管理控制台。RUSTFS_ACCESS_KEY/RUSTFS_SECRET_KEY管理凭据配置中使用了${VAR:-default}语法允许通过宿主机环境变量覆盖未设置时回退到默认值rustfsadmin-local/rustfssecret-local。volumes挂载该示例直接把宿主机上编译好的target/x86_64-unknown-linux-gnu/release/rustfs二进制挂载进容器并执行实现改代码→重新编译→重启容器的快速迭代这也意味着它默认面向 Linux/amd64 编译产物。遗留观测栈配置docker-compose.observability.yaml该文件曾经承载一套完整的观测栈Tempo、OTel Collector、Jaeger、Prometheus、Loki、Pyroscope、Grafana从源码看其设计思路是RustFS 通过RUSTFS_OBS_ENDPOINThttp://otel-collector:4318上报 OTLP 数据由 Collector 分发给 Tempo/JaegerTrace、PrometheusMetric、LokiLog最终在 Grafana 统一可视化。但 README 已明确将其标记为Deprecated当前仓库中的全新推荐方案位于 .docker/observability/docker-compose.yml具备持久化卷、健康检查与生产级参数调优。因此在实际使用中除非你需要一个最小化的快速验证环境否则应直接使用新栈。快速上手拉起 4 节点集群在项目根目录执行docker compose -f .docker/compose/docker-compose.cluster.yaml up -d启动后4 个 RustFS 实例分别暴露在宿主机9000、9001、9002、9003端口。你可以用它来做分布式存储逻辑、一致性consensus与故障转移failover的初步验证。脚本化 4 节点验证推荐方式对于需要本地源码构建镜像 故障转移检查 基准测试一条龙执行的场景README 明确推荐使用仓库自带的校验脚本 scripts/run_four_node_cluster_failover_bench.sh# 默认模式WAIT_PROBE_MODEservice # 该模式避免本地环境中 /health/ready 仍返回 503 时产生误报 # 而此时服务路径实际已可用。 ./scripts/run_four_node_cluster_failover_bench.sh如果你希望以/health/ready 200作为严格的就绪门禁则使用严格模式WAIT_PROBE_MODEready ./scripts/run_four_node_cluster_failover_bench.sh这个脚本从源码层面看scripts/run_four_node_cluster_failover_bench.sh封装了完整的测试流水线以下几个要点值得注意默认组合同时拉起 .docker/observability/docker-compose.yml 观测栈与.docker/compose/docker-compose.cluster.local-build.yml集群可通过--without-observability关闭观测栈。本地构建默认通过Dockerfile.source构建本地镜像rustfs/rustfs:local-4node可用--skip-build跳过。故障转移验证默认停止node4FAILOVER_NODEnode4预热 5 秒后以 1 秒间隔持续采样 60 秒FAILOVER_WARMUP_SECS5、FAILOVER_SAMPLE_SECS60、FAILOVER_INTERVAL_SECS1观察集群在节点宕机后的恢复表现。基准测试默认对 4 个节点BENCH_WARP_HOSTS指向9000~9003执行 warp 风格压测对象大小1KiB,4KiB,11MiBENCH_SIZES时长60s并发度默认 8/16/32/64/128。就绪探测默认等待 180 秒WAIT_TIMEOUT_SECS180并支持WAIT_PROBE_MODEservice|ready两种探测模式切换。产物输出基准结果默认写入target/bench/four-node-failover-时间戳/可用--out-dir自定义。保持运行脚本结束后默认关闭 Compose 服务如需保留运行环境可加--keep-up。这种脚本即文档的方式非常适合 CI 或本地回归验证一条命令即可复现分布式集群的故障转移与性能表现。Profiling Trace 验证让观测数据真正可见针对性能分析与链路追踪验证仓库提供了专门的 profiling 版本 Composedocker compose -f .docker/compose/docker-compose.cluster.local-build.profiling-amd64.yml up -d从该文件源码可以看出它在 4 节点集群的基础上追加了两类能力1. OTLP 观测数据上报每个节点都配置了- RUSTFS_OBS_ENDPOINT${RUSTFS_OBS_ENDPOINT:-http://host.docker.internal:4318} - RUSTFS_OBS_LOGGER_LEVEL${RUSTFS_OBS_LOGGER_LEVEL:-info} - RUSTFS_OBS_PROFILING_ENDPOINT${RUSTFS_OBS_PROFILING_ENDPOINT:-http://host.docker.internal:4040} - RUSTFS_OBS_PROFILING_EXPORT_ENABLED${RUSTFS_OBS_PROFILING_EXPORT_ENABLED:-true}并添加了extra_hosts: host.docker.internal:host-gateway使容器内可以通过host.docker.internal访问宿主机上的 OTLP Collector默认4318端口与 Pyroscope默认4040端口。2. 内置 CPU Profiling每个节点默认开启- RUSTFS_ENABLE_PROFILING${RUSTFS_ENABLE_PROFILING:-true} - RUSTFS_PROF_CPU_MODE${RUSTFS_PROF_CPU_MODE:-continuous} - RUSTFS_PROF_CPU_FREQ${RUSTFS_PROF_CPU_FREQ:-99} - RUSTFS_PROF_OUTPUT_DIR${RUSTFS_PROF_OUTPUT_DIR:-/tmp/rustfs-profiles}即默认以 99Hz 连续采样 CPU Profile并输出到容器内/tmp/rustfs-profiles同时通过RUSTFS_OBS_PROFILING_EXPORT_ENABLEDtrue将 Profile 推送到 Pyroscope 持续分析。关键行为说明README 重点强调RUSTFS_OBS_ENDPOINT是 OTLP/HTTP 基础 URLRustFS 会自动在其后拼接/v1/traces、/v1/metrics、/v1/logs三个标准路径分别上报三种数据。因此该变量只需配置到 Collector 的 HTTP 接收根地址即可。启动阶段通常先产生日志与指标这并不能保证 Trace 立即可见。Trace 只有在真实 HTTP/S3/gRPC 请求命中 RustFS 后才会出现。RUSTFS_OBS_LOGGER_LEVELinfo会保留顶层请求 Span但过滤掉大量嵌套的debug级 Span。如果 Tempo/Jaeger 中链路稀疏请先尝试切换到debug级别再排查 Collector而不是直接怀疑 OTLP 路由出了问题。最小化 Trace 验证流程README 给出了一个三步验证法# 1. 以更丰富的 Span 可见性启动 profiling Compose RUSTFS_OBS_LOGGER_LEVELdebug \ docker compose -f .docker/compose/docker-compose.cluster.local-build.profiling-amd64.yml up -d # 2. 启动后产生真实请求流量 curl -I http://127.0.0.1:9000/health curl -I http://127.0.0.1:9000/health/ready # 3. 再到 Tempo / Jaeger 中检查链路 # Grafana: http://localhost:3000 # Jaeger: http://localhost:16686如果此时日志和指标都有、但 Trace 稀疏最可能的原因是还没有真实请求流量/health这类轻量探活不一定触发完整请求 Spaninfo级别过滤掉了嵌套 Span而非 OTLP 路由失败。只有真实业务请求如 S3 的 PUT/GET、gRPC 内部调用才会让 Trace 链路丰满起来。已废弃最小化观测栈的使用如果你的场景只是极简的观测验证仍可运行遗留配置docker compose -f .docker/compose/docker-compose.observability.yaml up -d但请务必知晓该配置已被标记为 Deprecated官方推荐使用 .docker/observability/docker-compose.yml 取代。新栈在 .docker/observability/README.md 中有完整说明其核心架构为采集应用通过 OTLP 协议Metrics、Logs、Traces上报到 OpenTelemetry Collector处理与导出Collector 完成批处理、内存限制等处理后分发——Traces 到 Tempo主与 Jaeger辅、Metrics 到 Prometheus、Logs 到 Loki可视化Grafana 统一对接 Prometheus、Tempo、Loki、Jaeger实现指标、日志、链路之间的无缝跳转关联。新栈还附带了预置的 Grafana 面板如rustfs.json、GET 性能优化系列面板与 Prometheus 告警规则.docker/observability/prometheus-rules/并支持通过docker-compose-tempo-ha-override.yml切换到 Kafka 支撑的高可用 Tempo 模式。常见问题与排查要点围绕.docker/compose/的日常使用可归纳出以下排查要点本地构建与镜像选择docker-compose.cluster.yaml使用预构建镜像rustfs/rustfs:latest并挂载本地二进制需要本地源码构建时改用docker-compose.cluster.local-build.yml脚本默认使用它或 profiling 版本。Apple Silicon 等非 amd64 宿主机可通过RUSTFS_DOCKER_PLATFORMlinux/amd64强制平台。健康检查口径脚本默认以service模式探测避免本地/health/ready503 误报需要严格就绪门禁时切到WAIT_PROBE_MODEready。Trace 稀疏≠Collector 故障先确认是否有真实业务流量、再尝试RUSTFS_OBS_LOGGER_LEVELdebug提升 Span 可见度最后才排查 OTLP 路由。凭据覆盖所有节点均支持通过${RUSTFS_ACCESS_KEY:-...}/${RUSTFS_SECRET_KEY:-...}由宿主机环境变量统一注入避免硬编码凭据进入仓库。总结.docker/compose/是 RustFS 为特定测试场景量身定制的 Compose 集合docker-compose.cluster.yaml解决如何快速拉起 4 节点分布式集群scripts/run_four_node_cluster_failover_bench.sh 解决如何一键完成构建、故障转移验证与压测profiling 版本解决如何在集群上同时验证性能 Profile 与 OTLP 链路追踪而遗留的docker-compose.observability.yaml则已被 .docker/observability/ 下的生产级一体化观测栈取代。按需组合这些配置即可在本地或 CI 中高效、可复现地验证 RustFS 的分布式行为与可观测性能力。【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
