企业官网建设流程全解析

• 存储
• 分布式文件系统
• 对象存储
• 云原生

本文以 CubeFS 官方集群部署文档为主线，完整讲解如何通过make build编译出cfs-server/cfs-client，并依次部署 Master、MetaNode、DataNode、ObjectNode、LcNode、FlashNode 六个服务组件（含可选的纠删码子系统），最终组合出一套可用于生产的高可用分布式存储集群。读完本文，你将掌握每个节点的 JSON 配置逐字段含义、端口规划、磁盘准备流程，以及集群搭建中最常见的三类故障（内存不足、端口占用、FUSE 挂载失败）的定位与解决手段。

一、部署前准备：编译构建与依赖环境

1.1 获取源码并编译

CubeFS 使用 Makefile 组织构建，一条命令即可同时编译服务端、客户端及相关依赖：

$ git clone https://gitcode.com/gh_mirrors/cu/cubefs $ cd cubefs $ make build

从仓库根目录的 Makefile 可以看到，build目标实际串联了server、authtool、client、cli、libsdk、fsck、fdstore、bcache、blobstore、deploy等多个子目标。构建成功后，在build/bin目录下会生成核心可执行文件：

• cfs-server：统一的服务端入口，通过-c参数加载不同角色的 JSON 配置文件，即可启动 Master、MetaNode、DataNode、ObjectNode、LcNode、FlashNode 等任意角色；
• cfs-client：FUSE 客户端，用于将卷挂载到本地目录；
• 此外还会生成cfs-cli（命令行管理工具）以及 blobstore 子系统的系列二进制。

1.2 依赖环境清单

部署前建议先核对以下依赖（详见 部署依赖说明）：

1.3 理解 cfs-server 的启动机制

cfs-server的行为由 cmd/cmd.go 定义：它通过flag解析-c（配置文件路径）、-f（前台运行）、-v（打印版本）、-redirect-std（是否将标准输出重定向到日志文件）等参数；随后读取配置文件，根据其中的role字段做模块分发：

• master→master.NewServer()
• metanode→metanode.NewServer()
• datanode→datanode.NewServer()
• objectnode→objectnode.NewServer()
• lcnode→lcnode.NewServer()
• flashnode→flashnode.NewFlashNode()

也就是说，所有服务节点共用一个二进制，靠配置文件里的role区分身份，这极大简化了部署物管理。默认情况下进程会以守护进程方式运行（先 fork 出子进程再以-f重新执行），日志级别支持debug / info / warn / error / critical，默认error。

二、整体架构与端口规划

集群模式下，各角色通过 Master 的 Raft 组互相发现并协同。官方建议 Master、MetaNode、DataNode 均至少部署 3 个实例以保证高可用。为便于后续配置，先给出各角色的默认端口规划：

三、安装 Master

Master 是集群的元数据中心与调度核心，负责卷管理、数据分片（DataPartition/MetaPartition）分配、节点心跳与故障检测。启动方式：

./cfs-server -c master.json

官方推荐至少启动 3 个 Master 实例组成 Raft 组。示例master.json：

{ "role": "master", "ip": "127.0.0.1", // 替换为宿主机 IP "listen": "17010", "prof":"17020", "id":"1", // 替换为对应的节点 ID（1/2/3） "peers": "1:127.0.0.1:17010,2:127.0.0.2:17010,3:127.0.0.3:17010", "retainLogs":"20000", "logDir": "/cfs/master/log", // Master 日志目录 "logLevel":"info", "walDir":"/cfs/master/data/wal", // Raft WAL 日志目录 "storeDir":"/cfs/master/data/store", // RocksDB 数据存储目录 "consulAddr": "http://consul.prometheus-cfs.local", "clusterName":"cubefs01", "metaNodeReservedMem": "1073741824" // 元数据节点保留内存，1G }

peers是 Raft 组成员信息，格式为id:ip:port，多个成员用逗号分隔，三台机器的id应分别为 1、2、3，且listen端口保持一致。storeDir目录必须预先存在，否则服务无法启动。

3.1 Master 配置参数全表

以下是 Master 详细配置 中列出的完整参数（均为 JSON 字符串/布尔格式）：

其中metaNodeReservedMem（默认 1G）是一个跨节点约束项：MetaNode 的totalMem必须大于该值，部署 MetaNode 时需留意。

四、安装 MetaNode

MetaNode 负责文件系统元数据的存储与管理（inode、dentry、扩展属性等），启动方式：

./cfs-server -c metanode.json

官方推荐至少启动 3 个 MetaNode 实例以保证元数据高可用。示例metanode.json：

{ "role": "metanode", "listen": "17210", "prof": "17220", "logLevel": "info", "metadataDir": "/cfs/metanode/data/meta", // 元数据快照存储目录 "logDir": "/cfs/metanode/log", // Metanode 日志目录 "raftDir": "/cfs/metanode/data/raft", "raftHeartbeatPort": "17230", "raftReplicaPort": "17240", "totalMem": "8589934592", // 最大可用内存，必须大于 Master 的 metaNodeReservedMem "consulAddr": "http://consul.prometheus-cfs.local", "exporterPort": 9501, "masterAddr": [ "127.0.0.1:17010", "127.0.0.2:17010", "127.0.0.3:17010" ] }

4.1 MetaNode 配置参数全表

4.2 MetaNode 的重要约束

详见 MetaNode 详细配置 的注意事项：

• listen、raftHeartbeatPort、raftReplicaPort三个端口在程序首次配置启动后不可修改；
• 相关配置信息记录在metadataDir目录下的constcfg文件中，如需强制修改，必须手动删除该文件；
• 这三个端口与 MetaNode 在 Master 中的注册信息相关，一旦修改，Master 将无法再定位到修改前的 MetaNode 信息。

五、安装 DataNode

DataNode 负责数据分片的实际存储与副本复制。官方建议使用独立磁盘作为数据目录，并配置多块磁盘以获得更高性能。

5.1 磁盘准备

• 查看机器磁盘信息，选择 CubeFS 要使用的磁盘：

  fdisk -l

• 格式化磁盘，建议格式化为 XFS：

  mkfs.xfs -f /dev/sdx

• 创建挂载目录：

  mkdir /data0

• 挂载磁盘：

  mount /dev/sdx /data0

5.2 启动 DataNode

./cfs-server -c datanode.json

官方推荐至少启动 3 个 DataNode 实例。示例datanode.json：

{ "role": "datanode", "listen": "17310", "prof": "17320", "logDir": "/cfs/datanode/log", "logLevel": "info", "raftHeartbeat": "17330", "raftReplica": "17340", "raftDir":"/cfs/datanode/log", "consulAddr": "http://consul.prometheus-cfs.local", "exporterPort": 9502, "mediaType": 1, // datanode 磁盘类型，1 表示 SSD，2 表示 HDD "masterAddr": [ "127.0.0.1:17010", "127.0.0.2:17010", "127.0.0.3:17010" ], "disks": [ "/data0:10737418240", // 磁盘挂载路径:保留空间（字节） "/data1:10737418240" ] }

disks数组的每个元素格式为磁盘挂载路径:保留空间，即除保留空间外的其余容量都交给 CubeFS 使用。

5.3 DataNode 配置参数全表

5.4 DataNode 的重要约束

与 MetaNode 类似（见 DataNode 详细配置）：listen、raftHeartbeat、raftReplica首次启动后不可修改；相关配置记录在raftDir目录下的constcfg文件中，强制修改需手动删除该文件。

六、安装 Object Gateway（可选）

ObjectNode 是 S3 兼容的对象存储网关。仅当需要使用对象存储服务时才需要部署。

./cfs-server -c objectnode.json

示例objectnode.json：

{ "role": "objectnode", "domains": [ "object.cfs.local" ], "listen": "17410", "masterAddr": [ "127.0.0.1:17010", "127.0.0.2:17010", "127.0.0.3:17010" ], "logLevel": "info", "logDir": "/cfs/Logs/objectnode" }

配置参数说明（详见 ObjectNode 详细配置）：

七、安装 Lcnode（可选）

LcNode 负责数据迁移与生命周期管理（例如将冷数据按策略迁移到低频/归档存储）。仅当需要使用数据迁移能力时才需要部署。

./cfs-server -c lifecycle.json

示例lifecycle.json：

{ "role": "lcnode", "listen": "17510", "masterAddr": [ "127.0.0.1:17010", "127.0.0.2:17010", "127.0.0.3:17010" ], "logLevel": "info", "logDir": "/cfs/Logs/lcnode" }

配置参数说明（详见 LcNode 详细配置）：

八、安装 FlashNode（可选）

FlashNode 是缓存加速节点，为文件读提供集群级加速。如果文件读取不需要缓存或集群加速，可省略该组件。

./cfs-server -c flashnode.json

示例flashnode.json：

{ "role": "flashnode", "listen": "18510", "prof": "18511", "logDir": "./logs", "masterAddr": [ "127.0.0.1:17010", "127.0.0.2:17010", "127.0.0.3:17010" ], "readRps": 100000, "disableTmpfs": true, "diskDataPath": [ "/path/data1:0" ], "zoneName":"default" }

配置参数说明（详见 FlashNode 详细配置）：

九、安装纠删码子系统（可选）

仅当需要使用纠删码（Erasure Coding）卷时才需要部署。CubeFS 的纠删码子系统即 Blobstore，由 access、clustermgr、proxy、scheduler、blobnode 等模块组成，模块之间存在依赖关系，需要按序部署。完整部署流程请参阅 使用纠删码存储系统；注意部署纠删码子系统前需提前准备好 kafka 与 consul 依赖。

十、常见问题排查（FAQ）

10.1 内存不足（bad totalMem config）

启动 MetaNode 时可能出现如下错误：

err(readFromProcess: sub-process: [cmd.go 323] Fatal: failed to start the CubeFS metanode daemon err bad totalMem config,Recommended to be configured as 80 percent of physical machine memory

原因与解决：totalMem配置不合理。官方建议将metanode.json中的totalMem调整为物理机内存的 80% 左右，且必须大于 Master 配置中的metaNodeReservedMem。

10.2 端口被占用

err(readFromProcess: sub-process: [cmd.go 311] cannot listen pprof 17320 err listen tcp :17320: bind: address already in use

解决：杀掉占用该端口的进程（通常是之前启动失败的残留节点），再重新启动服务。由于listen、raftHeartbeat、raftReplica等端口首次启动后不可随意修改，务必保证端口规划稳定。

10.3 FUSE 客户端挂载失败

挂载时出现：

# Mount failed err(readFromProcess: sub-process: [fuse.go 438] mount failed: fusermount: exec: "fusermount": executable file not found in $PATH)

排查步骤：

• 先检查 FUSE 是否已安装：

  $ rpm –qa|grep fuse $ yum install fuse

• 如果 FUSE 已安装但仍挂载失败，请参考 FUSE 客户端问题排查 逐项定位，常见原因还包括：挂载目录不存在、挂载点非空、挂载点处于 "Transport endpoint is not connected" 残留状态、配置文件中 Master 地址或卷名不正确等。

十一、部署后的下一步：创建卷并挂载验证

集群各节点启动成功后，即可用cfs-cli创建卷、用cfs-client挂载验证。完整验证步骤见 快速验证，核心流程如下：

1. 准备~/.cfs-cli.json（包含masterAddr与timeout），执行./build/bin/cfs-cli volume create ltptest ltptest创建卷；
2. 编写客户端配置（见 客户端配置），其中volName与owner必须与创建卷时一致；
3. 执行./build/bin/cfs-client -c client.conf启动客户端，用df -h检查挂载点是否出现类似cubefs-ltptest ... /home/cfs/client/mnt的记录，出现即表示挂载成功。

至此，一套由 Master + MetaNode + DataNode 组成、可按需扩展 ObjectNode / LcNode / FlashNode / 纠删码子系统的 CubeFS 集群模式部署即告完成。

• 存储
• 分布式文件系统
• 对象存储
• 云原生