LizardFS 集群模式部署指南

目标：讲解如何将 LizardFS 从单机扩展为多 chunkserver 集群，实现数据多副本与横向扩容。通过「单机起两个 chunkserver + goal=2」真实实测验证复制机制，并给出跨主机多节点拓扑、metalogger 备份、shadow 高可用的配套部署建议。

⚠️ 停更风险提示：LizardFS 已停更（最后 release v3.12.0）。新集群建议优先评估仍在维护的 MooseFS 4 / JuiceFS。本文数据基于 v3.12.0 真实容器实测。

1. 集群架构

                  mfsmaster          192.168.110.12
               (9420 MATOCS 与 chunkserver 通信
                9421 MATOCL 客户端/管理
                9419 MATOML metalogger 备份)
               /            \
    chunkserver A          chunkserver B
    data端口 9422           data端口 9423
  /var/lib/lizardfs-chunks   /var/lib/lizardfs-chunks2
               \            /
          mfsmount /mnt/lizardfs （fuse POSIX 视图）

master：保存全部元数据，负责调度 chunk 分布与副本。
chunkserver：真正存储数据，文件按 64MiB 分块，副本数用 goal 控制。
客户端：挂载后直接与 chunkserver 做数据读写（master 只应答 chunk 位置）。

所有组件间用网卡真实 IP 通信（master-to-cs 用 9420，client-to-cs 用 9422 数据通道）。

2. 节点角色与端口定位

端口	节点间用途
9419	master（MATOML）← metalogger 备份
9420	master（MATOCS）← chunkserver 注册
9421	master（MATOCL）← 客户端挂载 / lizardfs-admin
9422	chunkserver（数据通道，默认）← 客户端读/写
9423+	第二个及之后的 chunkserver 数据端口

3. 单机多 chunkserver（最小复制集群实测）

在同一主机起第二个 chunkserver 实例，用于快速验证 goal=2。核心是让两个实例的锁(lock)、缓存(DATA_PATH)、HDD 目录、数据端口四者互不冲突：

DATA_PATH：实例 A /var/lib/lizardfs、实例 B /var/lib/lizardfs2（不同，否则锁冲突）。
HDD 目录：A /var/lib/lizardfs-chunks、B /var/lib/lizardfs-chunks2（不同）。
数据端口：A 默认 9422，B 改为 CSSERV_LISTEN_PORT=9423。

第二套配置 /usr/local/lizardfs/etc/mfs-chunks2/mfschunkserver.cfg：

WORKING_USER = lizardfs
WORKING_GROUP = lizardfs
DATA_PATH = /var/lib/lizardfs2
MASTER_HOST = 192.168.110.12
MASTER_PORT = 9420
HDD_CONF_FILENAME = /usr/local/lizardfs/etc/mfs-chunks2/mfshdd.cfg
CSSERV_LISTEN_PORT = 9423           # 数据端口与实例 A 区分

启动（用 -c 指定独立配置）：

mfschunkserver -c /usr/local/lizardfs/etc/mfs-chunks2/mfschunkserver.cfg start

日志（实测）：

mfschunkserver[6109]: connected to Master
mfschunkserver[6109]: scanning folder /var/lib/lizardfs-chunks2/: complete (0s)

4. 集群视图（实测）

lizardfs-admin list-chunkservers 192.168.110.12 9421

Server 192.168.110.12:9423:
        version: 3.12.0
        label: _
        chunks: 0
        used space: 288GiB / 751GiB
        chunks marked for removal: 0
        used space marked for removal: 0B / 0B
        errors: 0
Server 192.168.110.12:9422:
        version: 3.12.0
        label: _
        chunks: 2
        used space: 287GiB / 751GiB
        chunks marked for removal: 0
        used space marked for removal: 0B / 0B
        errors: 0

单机多 chunkserver 的 IP 相同、端口不同正是其正确形态；真实部署则把端口/MASTER_HOST 落到不同物理机获得不同 IP。

5. goal=2 双副本验证（实测）

mkdir -p /mnt/lizardfs/rep2
mfssetgoal 2 /mnt/lizardfs/rep2     # rep2: 2
mfsgetgoal /mnt/lizardfs/rep2       # rep2: 2
echo "replicated data - two copies on two chunkservers" > /mnt/lizardfs/rep2/data.bin
mfsfileinfo /mnt/lizardfs/rep2/data.bin

/mnt/lizardfs/rep2/data.bin:
        chunk 0: 0000000000000003_00000001 / (id:3 ver:1)
                copy 1: 192.168.110.12:9422:_
                copy 2: 192.168.110.12:9423:_

结论：goal=2 生效，同一文件产生两个副本，分别落在 9422 与 9423 两个不同 chunkserver 实例上。任一 chunkserver 宕机，副本仍完整可用。

6. 跨主机横向扩展

生产环境把 chunkserver 放到独立节点：

master     192.168.1.10   （mfsmaster，建议 SSD）
cs1       192.168.1.11   （mfschunkserver，数据盘 XFS/ext4）
cs2       192.168.1.12   （mfschunkserver）
csN       ...
metalogger 192.168.1.13  （可选，元数据备份）

扩展步骤（新增节点）：

# 1) 新节点按安装篇装好 LizardFS
# 2) mfschunkserver.cfg 指向 master：
#      MASTER_HOST = 192.168.1.10 ; MASTER_PORT = 9420
# 3) mfshdd.cfg 写数据盘目录
# 4) 启动
mfschunkserver -d start

master 会自动对该新 chunkserver 平衡迁移部分 chunk（含后台复制与再平衡任务）。

7. 元数据高可用：metalogger 与 shadow

metalogger：从 master 9419 端口持续接收 changelog，存为备份，master 故障时可接替。安装篇装 mfsmetalogger 后配置：

# /usr/local/lizardfs/etc/mfs/mfsmetalogger.cfg
WORKING_USER = lizardfs
WORKING_GROUP = lizardfs
DATA_PATH = /var/lib/lizardfs
MASTER_HOST = 192.168.1.10     # 网卡真实 IP
MASTER_PORT = 9419

shadow：另一份只读元数据副本，可秒级提升为 master（PERSONALITY = shadow + lizardfs-admin make-leader）。生产建议 ≥1 台 shadow + ≥1 台 metalogger。

8. 复制模式与 QoS/配额

副本模式：standard（显式副本数/goal）、xor（RAID5 式）、ec（RAID6 式纠删码）——旧版可用，结合自定目标。
分级：chunkserver LABEL + 自定义 mfsgoals.cfg 可实现跨机房/按介质副本。
配额：mfssetquota -o 100G -f 100000 /mnt/lizardfs/project（字节/文件/目录上限）。
回收站：mfssettrashtime 控制删除文件保留时长。

注：新版离线场景这些高级特性可能随停更缺少支持，文档仅列常用用法。

9. 扩容/缩容与再平衡

扩容：新增 chunkserver → master 自动把部分 chunk 迁移过去以便平衡。
缩容：先 lizardfs-admin df 观察负载；建议先调整 goal 或迁移后停机。
再平衡：master 后台任务（CHUNKS_LOOP / OPERATIONS_DELAY_*）自动纠正副本分布。

10. 常见问题

现象	原因与解决
goal=2 只有 1 个副本	chunkserver 数量 < 2，副本会等待补齐
第二实例锁冲突	两个实例 `DATA_PATH` 不同（第 3 节）
第二实例端口冲突	改 `CSSERV_LISTEN_PORT`（默认 9422）
chunkserver 连不上 master	`MASTER_HOST` 用网卡 IP，非 loopback