在集群上独立运行 Alluxio：单 Master 部署的完整实战指南

• 存储
• 分布式文件系统
• 缓存
• 大数据

本文基于 Alluxio 官方中文文档 docs/cn/deploy/Running-Alluxio-on-a-Cluster.md，面向需要将 Alluxio 部署到真实多节点集群的运维与开发人员，完整讲解从先决条件、基本配置、启动验证到日常运维（停止、重启、动态扩缩 worker、更新配置）的全流程操作，并结合当前仓库的启动脚本与配置源码，深入剖析每个命令背后的实现机制，帮助你快速搭建一套可运行、可维护的独立 Alluxio 集群。

为什么需要"单 Master"部署，以及它的边界

在集群上部署 Alluxio 最简单的方式是使用单个 master：一台节点运行 master 进程，其余节点运行 worker 进程，worker 向 master 注册并报告自身状态。这种模式配置最少、启动最快，适合开发测试、小规模集群或对可用性要求不高的场景。

但必须明确其代价：单个 master 是整个集群的单点故障（SPOF）。如果 master 所在机器宕机或进程不可用，即便所有 worker 和底层存储都健康，整个 Alluxio 集群也无法对外提供服务。因此官方文档明确建议：生产环境强烈推荐使用高可用模式运行多个 master，具体方案可参考仓库中的 Running-Alluxio-On-a-HA-Cluster.md（HA 模式通过嵌入式日志或 Zookeeper 选举主 master，conf/masters文件中的说明对此有详细注释）。

先决条件

在动手部署之前，需要依次完成以下准备工作：

1. 下载并解压 Alluxio 二进制包从 Alluxio 官网下载预编译的二进制 tarball（版本号对应仓库的ALLUXIO_VERSION_STRING），解压后把整个目录复制到所有节点（包括运行 master 和 worker 的每一台机器）：

   $ tar -xvzpf alluxio-<VERSION>-bin.tar.gz

2. 配置免密 SSH 登录由于后续的集群管理命令（启动、停止、同步配置）需要从 master 节点通过 SSH 操作所有 worker 节点，需要配置从 master 到 worker 节点的免密 SSH 登录。常见做法是把 master 主机的公钥追加到 worker 上对应用户的~/.ssh/authorized_keys中。同时建议在~/.ssh/config中为所有节点设置StrictHostKeyChecking no之类的参数，避免首次连接交互确认导致自动化脚本卡住（bin/alluxio中的copyDir函数即使用-o StrictHostKeyChecking=no选项）。

3. 开放节点间 TCP 通信所有节点之间必须开放 RPC 端口。对于基本功能，确保每个节点上的RPC 端口（默认值：19998）是打开的。该默认值来自源码 core/common/src/main/java/alluxio/conf/PropertyKey.java，由属性alluxio.master.rpc.port控制，其历史别名是alluxio.master.port。

4. sudo 权限（可选）仅当期望 Alluxio 自动在 worker 节点上挂载 RAMFS（内存文件系统）时才需要给运行 Alluxio 的操作系统用户授予 sudo 特权。如果已经手工挂载好内存盘，或者改用NoMount模式，则无需 sudo。

基本配置：两份核心属性 + 一键同步

创建站点配置文件

在 master 节点上，参照模板创建conf/alluxio-site.properties配置文件：

$ cp conf/alluxio-site.properties.template conf/alluxio-site.properties

模板文件位于 conf/alluxio-site.properties.template，其中已经注释列出了常见属性分组：通用属性、安全属性、worker 属性和用户属性，可作为扩展配置的起点。

配置两个核心属性

在conf/alluxio-site.properties中，最少需要配置如下两行：

alluxio.master.hostname=<MASTER_HOSTNAME> alluxio.master.mount.table.root.ufs=<STORAGE_URI>

• alluxio.master.hostname：设置单个 master 节点的主机名。示例：alluxio.master.hostname=1.2.3.4或alluxio.master.hostname=node1.a.com。该属性同时被 job master 等组件引用（源码 PropertyKey.java）。
• alluxio.master.mount.table.root.ufs：设置挂载到 Alluxio 根目录的底层存储（UFS）URI。必须保证 master 节点和所有 worker 节点都能访问这个共享存储。示例：alluxio.master.mount.table.root.ufs=hdfs://1.2.3.4:9000/alluxio/root/或alluxio.master.mount.table.root.ufs=s3://bucket/dir/。

从源码看，该属性的全名是alluxio.master.mount.table.root.ufs，历史别名是alluxio.underfs.address；如果未显式配置，默认值为${alluxio.work.dir}/underFSStorage（即本地文件系统目录），仅适合单机体验，集群部署必须显式指向共享存储，见 PropertyKey.java。

将配置同步到所有节点

接下来把配置文件复制到所有其他 Alluxio 节点。将所有 worker 节点的 IP 地址或主机名逐行添加到conf/workers文件（每行一个，#开头的行为注释，参考 conf/workers），然后利用内置工具一键同步：

$ ./bin/alluxio copyDir conf/

该命令会把conf/目录通过rsync复制到conf/workers文件中指定的所有 worker 节点，同时也会同步到conf/masters中列出的 master 节点（实现位于 bin/alluxio）。成功执行后，所有 Alluxio 节点都拥有了相同的配置。这是启动 Alluxio 的最低配置，之后可按需追加其他配置项（如 RAMFS 大小、分层存储、安全认证等，模板文件中已给出示例）。

启动一个 Alluxio 集群

第一步：格式化 Alluxio

首次启动前，必须先格式化日志（journal）：

$ ./bin/alluxio formatMaster

注意：格式化日志会删除 Alluxio 中的所有元数据，但不会触及底层存储（UFS）中的数据，因此格式化后可以基于原有 UFS 数据重新建立文件系统视图。

值得一提的兼容性细节：formatMaster在当前版本中已被标记为废弃命令（执行时会提示 "formatMaster is deprecated - use formatJournal or formatMasters instead"），其内部实际转发到formatJournal，见 bin/alluxio。更推荐使用语义更明确的./bin/alluxio formatMasters（或formatJournal）。formatMasters会先通过getConf读取alluxio.master.journal.type：若日志类型为EMBEDDED（嵌入式日志），则通过alluxio-masters.sh在每个 master 节点上分别执行格式化；否则只需在本地执行一次formatJournal，见 bin/alluxio。

第二步：启动集群

启动前，请确认conf/workers文件中所有 worker 的主机名都是正确的。在 master 节点上运行：

$ ./bin/alluxio-start.sh all SudoMount

这条命令会：在当前节点启动 master；在conf/workers文件中指定的所有节点上启动全部 worker。SudoMount参数使 worker 尝试在 RAMFS 尚未挂载时用sudo特权挂载它。

关于挂载模式的进一步说明（来自 bin/alluxio-start.sh）：

如果未指定挂载模式，all动作默认假定为NoMount。脚本还提示：在 Linux 上为避免 sudo 需求，可将每个 worker 的ALLUXIO_RAM_FOLDER设为/dev/shm并使用NoMount（脚本会检查顶层存储别名是否为MEM以及 RAMFS 是否已挂载，见 bin/alluxio-start.sh）。

alluxio-start.sh支持的 ACTION 非常丰富（见 bin/alluxio-start.sh），除all外还有master/masters、worker/workers、proxy/proxies、job_master/job_worker等，可按需单独启停某一类进程；-f表示在启动前格式化日志与 UFS/worker 数据，-i backup可从指定 journal 备份恢复，-N表示启动前不终止旧进程，-c cache可在启动 worker 时用指定目录预填充缓存。

第三步：验证集群运行状态

要验证 Alluxio 是否正常运行，可访问http://<alluxio_master_hostname>:19999查看 Alluxio master 的状态页面（Web UI 端口 19999，RPC 端口 19998）。

Alluxio 附带一个简单的端到端示例程序，可在集群中读写示例文件，运行：

$ ./bin/alluxio runTests

该命令对应 bin/alluxio 中runTests动作，内部启动alluxio.cli.TestRunner类（源码位于 shell/src/main/java/alluxio/cli/TestRunner.java）。若输出显示读写测试成功，说明 master 与 worker 协作正常，集群已经就绪。

常用操作：集群日常运维手册

以下操作覆盖 Alluxio 集群生命周期中最常见的运维场景。

停止 Alluxio

停止整个集群：

$ ./bin/alluxio-stop.sh all

这会停止conf/workers和conf/masters中列出的所有节点上的所有进程（master、worker、proxy、job 服务等）。

也可以只停止某一类进程：

$ ./bin/alluxio-stop.sh masters # 停止所有 conf/masters 中的 master $ ./bin/alluxio-stop.sh workers # 停止所有 conf/workers 中的 worker

如果不想通过 SSH 登录所有节点来停止进程，可以在每个节点上本地执行：

$ ./bin/alluxio-stop.sh master # 停止本地 master $ ./bin/alluxio-stop.sh worker # 停止本地 worker

重新启动 Alluxio

与首次启动类似。只要conf/workers和conf/masters已配置好，重新启动整个集群：

$ ./bin/alluxio-start.sh all

注意：alluxio-start.sh在启动前默认会先终止本类旧进程（除非加-N），因此重启时通常无需先手动停止。

单独启动 masters 或 workers：

$ ./bin/alluxio-start.sh masters # 启动 conf/masters 中全部的 master $ ./bin/alluxio-start.sh workers # 启动 conf/workers 中全部的 worker

逐节点本地启动：

$ ./bin/alluxio-start.sh master # 启动本地 master $ ./bin/alluxio-start.sh worker # 启动本地 worker

格式化日志

在任何 master 节点上，运行：

$ ./bin/alluxio formatMaster

再次强调：格式化日志会删除 Alluxio 中的全部元数据，但不会触及底层存储中的数据。执行前务必确认这是预期操作（例如初始化全新的 Alluxio 命名空间、或需要彻底重建元数据时）。

动态添加 / 减少 worker

添加 worker：动态扩容就像"以适当配置启动一个新的 worker 进程"一样简单。多数情况下，新 worker 的配置应与其他 worker 完全一致（通过bin/alluxio copyDir conf/同步）。在新 worker 节点上运行：

$ ./bin/alluxio-start.sh worker SudoMount # 启动本地 worker

worker 启动后会向 master 注册，随即成为 Alluxio 集群的一部分，无需重启 master。

减少 worker：只需停止该 worker 进程：

$ ./bin/alluxio-stop.sh worker # 停止本地 worker

worker 停止后，master 会在预定的超时时间后将此 worker 标记为缺失。该超时由 master 参数alluxio.master.worker.timeout控制——源码 PropertyKey.java 中该属性的默认值为5min（别名alluxio.master.worker.timeout.ms），含义是"master 与 worker 之间判定 worker 丢失的超时时间"。超时后 master 视该 worker 为"丢失"，不再将其纳入集群；若后续该 worker 恢复，可再次通过worker动作启动并重新注册。

更新 master 配置

要修改 master 相关配置（例如根 UFS 地址、HA 相关参数等），必须按顺序操作：

1. 停止服务（./bin/alluxio-stop.sh all或按需停止 masters/workers）；
2. 在 master 节点上更新conf/alluxio-site.properties；
3. 将文件复制到所有节点（例如./bin/alluxio copyDir conf/）；
4. 重新启动服务（参考上文"重新启动 Alluxio"）。

更新 worker 配置

如果只是为某个 worker 更新局部配置（例如调整分配给该 worker 的存储容量、修改存储路径或 tiered storage 层级），无需停止和重启 master 节点：

1. 只停止本地 worker：./bin/alluxio-stop.sh worker；
2. 更新该 worker 上的conf/alluxio-site.properties；
3. 重新启动该 worker：./bin/alluxio-start.sh worker。

worker 重启后即携带新配置重新注册到 master。

常用配置参数速查

结合 conf/alluxio-site.properties.template 与 core/common/src/main/java/alluxio/conf/PropertyKey.java 源码，梳理集群部署中最常涉及的参数如下：

其中alluxio.worker.ramdisk.size的默认值由源码动态计算：优先取操作系统总物理内存的 2/3，若无法获取（非标准平台）则回退为1GB，见 PropertyKey.java。

小结

单 master 模式是理解 Alluxio 集群部署的最佳起点：它只用两个核心配置项（master 主机名 + 根 UFS 地址）、一条同步命令（copyDir）和一条启动命令（alluxio-start.sh all）就能拉起一套可用的分布式缓存集群，并通过runTests快速验证读写链路。日常运维中，alluxio-stop.sh与alluxio-start.sh支持按all/masters/workers/ 单节点粒度精细控制；worker 支持不重启 master 的动态扩缩；master 配置变更则需"停止—修改—同步—重启"的完整流程。

需要再次强调：单 master 存在单点故障，投入生产前务必阅读仓库中的 Running-Alluxio-On-a-HA-Cluster.md，并参考 conf/masters 文件中对 HA 模式（嵌入式日志或 Zookeeper 选举）的注释说明，将集群切换到高可用架构。

• 存储
• 分布式文件系统
• 缓存
• 大数据