注意
本文档适用于 Ceph 的开发版本。
CephFS 镜像
CephFS 支持通过 cephfs-mirror 工具将快照异步推送到远程 CephFS 文件系统。快照同步通过镜像快照数据，然后（在远程文件系统的给定目录上）创建与正在同步的快照同名的快照来实现。
要求
主（本地）和辅助（远程）Ceph 集群版本应为 Pacific 或更高版本。
关键思想
对于目录中的给定快照对，cephfs-mirror 守护程序将依靠 CephFS 快照差异功能 来识别目录树中的更改。差异将应用于远程文件系统中的目录，从而只同步在两个快照之间发生更改的文件。
目前，快照数据通过批量复制到远程文件系统进行同步。
注意
不支持同步硬链接——硬链接文件将作为单独的文件进行同步。
创建用户
首先为主（本地）集群的镜像守护程序创建一个用户。此用户需要对元数据池具有写权限以创建 RADOS 对象（索引对象）用于 watch/notify 操作，并对数据池具有读权限。
ceph auth get-or-create client.mirror mon 'profile cephfs-mirror' mds 'allow r' osd 'allow rw tag cephfs metadata=*, allow r tag cephfs data=*' mgr 'allow r'
为每个文件系统对等体（在辅助/远程集群上）创建一个用户。此用户需要对 MDS（用于拍摄快照）和 OSD 具有完全权限
ceph fs authorize <fs_name> client.mirror_remote / rwps
添加对等体时应使用此用户（作为对等体规范的一部分）。
启动镜像守护程序
使用 systemctl(1) 单元文件生成镜像守护程序
systemctl enable cephfs-mirror@mirror
systemctl start cephfs-mirror@mirror
通过使用 -f 选项运行以下命令，在前台运行 cephfs-mirror 守护程序
cephfs-mirror --id mirror --cluster site-a -f
注意
此处指定的用户是 mirror，如 创建用户 部分所述创建。
镜像设计
CephFS 支持通过 cephfs-mirror 工具将快照异步复制到远程 CephFS 文件系统。对于给定的目录，快照通过将快照数据传输到远程文件系统，并创建与正在同步的快照同名的快照来实现同步。
快照同步顺序
虽然选择用于同步的快照顺序无关紧要，但快照是根据创建顺序（使用 snap-id）选择的。
快照化身
快照可能会被删除并（使用相同的名称）重新创建，但内容不同。一个“旧”快照可能已被同步（早些时候），而快照的重新创建可能发生在镜像被禁用时。使用快照名称来推断继续点会导致“新”快照（化身）永远不会被选中进行同步。
辅助文件系统上的快照存储了它同步自的快照的 snap-id。此元数据存储在 MDS 上的 SnapInfo 结构中。
接口
mirroring 模块（Manager 插件）提供了用于管理目录快照镜像的接口。Manager 接口（大部分）是用于管理文件系统镜像的监视器命令的包装器，是推荐的控制接口。
镜像模块和接口
镜像模块提供了一个用于管理目录快照镜像的接口。该模块作为 Ceph Manager 插件实现。镜像模块不管理镜像守护程序的生成（和终止）。systemctl(1) 是启动和停止镜像守护程序的首选方式。将来，镜像守护程序将由 cephadm 部署和管理（跟踪器：http://tracker.ceph.com/issues/47261）。
管理器模块负责将目录分配给镜像守护程序进行同步。可以生成多个镜像守护程序以实现目录快照同步的并发性。当镜像守护程序生成（或终止）时，镜像模块会发现修改后的镜像守护程序集，并在新集合中重新平衡目录分配，从而提供高可用性。
注意
具有多个镜像守护程序的配置目前未经测试。只推荐单个镜像守护程序。
镜像模块默认禁用。要启用镜像，请运行以下命令
ceph mgr module enable mirroring
镜像模块提供了一系列用于控制目录快照镜像的命令。要添加或删除目录，必须为给定的文件系统启用镜像。要启用镜像，请运行以下形式的命令
ceph fs snapshot mirror enable <fs_name>
注意
镜像模块命令使用 fs snapshot mirror 前缀，这与使用 fs mirror 前缀的监视器命令不同。请确保使用模块命令（即 fs snapshot mirror）。
要禁用镜像，请运行以下形式的命令
ceph fs snapshot mirror disable <fs_name>
启用镜像后，添加一个对等体，目录快照将镜像到该对等体。对等体遵循 <client>@<cluster> 规范，并在添加时分配一个唯一的 ID (UUID)。有关如何创建用于镜像的 Ceph 用户的信息，请参阅 创建用户 部分。
要添加对等体，请运行以下形式的命令
ceph fs snapshot mirror peer_add <fs_name> <remote_cluster_spec> [<remote_fs_name>] [<remote_mon_host>] [<cephx_key>]
<remote_fs_name> 是可选的，默认值为 <fs_name>（在远程集群上）。
这要求远程集群 Ceph 配置和用户密钥环在主集群中可用。有关详细信息，请参阅 引导对等体 部分。peer_add 子命令还支持传递远程集群的监视器地址和用户密钥。然而，引导对等体是添加对等体的推荐方式。
注意
目前只支持单个对等体。peer_add 命令已弃用，并将在未来的版本中删除。请改用 peer_bootstrap 命令。
要删除对等体，请运行以下形式的命令
ceph fs snapshot mirror peer_remove <fs_name> <peer_uuid>
注意
有关如何找出对等体 UUID，请参阅 镜像守护程序状态 部分。
要列出文件系统镜像对等体，请运行以下形式的命令
ceph fs snapshot mirror peer_list <fs_name>
要配置要镜像的目录，请运行以下形式的命令
ceph fs snapshot mirror add <fs_name> <path>
要停止目录镜像快照，请运行以下形式的命令
ceph fs snapshot mirror remove <fs_name> <path>
只允许绝对目录路径。此外，路径由镜像模块规范化。这意味着 /a/b/../b 等同于 /a/b
mkdir -p /d0/d1/d2
ceph fs snapshot mirror add cephfs /d0/d1/d2 {}
ceph fs snapshot mirror add cephfs /d0/d1/../d1/d2
Error EEXIST: directory /d0/d1/d2 is already tracked
添加目录进行镜像后，不允许添加其子目录或祖先目录进行镜像
ceph fs snapshot mirror add cephfs /d0/d1
Error EINVAL: /d0/d1 is a ancestor of tracked path /d0/d1/d2
ceph fs snapshot mirror add cephfs /d0/d1/d2/d3
Error EINVAL: /d0/d1/d2/d3 is a subtree of tracked path /d0/d1/d2
有关检查目录映射（到镜像守护程序）和目录分配的命令在 镜像守护程序状态 部分中详细介绍。
引导对等体
添加对等体（通过 peer_add）要求对等体集群配置和用户密钥环在主集群（Manager 主机和运行镜像守护程序的主机）中可用。通过引导和导入对等体令牌可以避免此要求。对等体引导涉及通过运行以下形式的命令在对等体集群上创建引导令牌
ceph fs snapshot mirror peer_bootstrap create <fs_name> <client_entity> <site-name>
例如
ceph fs snapshot mirror peer_bootstrap create backup_fs client.mirror_remote site-remote
{"token": "eyJmc2lkIjogIjBkZjE3MjE3LWRmY2QtNDAzMC05MDc5LTM2Nzk4NTVkNDJlZiIsICJmaWxlc3lzdGVtIjogImJhY2t1cF9mcyIsICJ1c2VyIjogImNsaWVudC5taXJyb3JfcGVlcl9ib290c3RyYXAiLCAic2l0ZV9uYW1lIjogInNpdGUtcmVtb3RlIiwgImtleSI6ICJBUUFhcDBCZ0xtRmpOeEFBVnNyZXozai9YYUV0T2UrbUJEZlJDZz09IiwgIm1vbl9ob3N0IjogIlt2MjoxOTIuMTY4LjAuNTo0MDkxOCx2MToxOTIuMTY4LjAuNTo0MDkxOV0ifQ=="}
site-name 指的是用于标识远程文件系统的用户定义字符串。在 peer_add 接口的上下文中，site-name 是在 remote_cluster_spec 中传入的 cluster 名称。
通过运行以下形式的命令在主集群中导入引导令牌
ceph fs snapshot mirror peer_bootstrap import <fs_name> <token>
例如
ceph fs snapshot mirror peer_bootstrap import cephfs eyJmc2lkIjogIjBkZjE3MjE3LWRmY2QtNDAzMC05MDc5LTM2Nzk4NTVkNDJlZiIsICJmaWxlc3lzdGVtIjogImJhY2t1cF9mcyIsICJ1c2VyIjogImNsaWVudC5taXJyb3JfcGVlcl9ib290c3RyYXAiLCAic2l0ZV9uYW1lIjogInNpdGUtcmVtb3RlIiwgImtleSI6ICJBUUFhcDBCZ0xtRmpOeEFBVnNyZXozai9YYUV0T2UrbUJEZlJDZz09IiwgIm1vbl9ob3N0IjogIlt2MjoxOTIuMTY4LjAuNTo0MDkxOCx2MToxOTIuMTY4LjAuNTo0MDkxOV0ifQ==
镜像守护程序状态
镜像守护程序会异步通知文件系统镜像状态和对等体更新的更改。
CephFS 镜像模块提供了 mirror daemon status 接口用于检查镜像守护程序的状态。运行以下命令以检查镜像守护程序的状态
ceph fs snapshot mirror daemon status
例如
ceph fs snapshot mirror daemon status | jq
[
{
"daemon_id": 284167,
"filesystems": [
{
"filesystem_id": 1,
"name": "a",
"directory_count": 1,
"peers": [
{
"uuid": "02117353-8cd1-44db-976b-eb20609aa160",
"remote": {
"client_name": "client.mirror_remote",
"cluster_name": "ceph",
"fs_name": "backup_fs"
},
"stats": {
"failure_count": 1,
"recovery_count": 0
}
}
]
}
]
}
]
显示每个镜像守护程序实例的条目，以及包括已配置的对等体和基本统计信息在内的信息。有关更详细的统计信息，请使用如下所述的 admin socket 接口。
CephFS 镜像守护程序提供 admin socket 命令来查询镜像状态。要列出 mirror status 的可用命令，请运行以下命令
ceph --admin-daemon /path/to/mirror/daemon/admin/socket help
{
....
....
"fs mirror status cephfs@360": "get filesystem mirror status",
....
....
}
具有 fs mirror status 前缀的命令提供镜像已启用文件系统的镜像状态。请注意，cephfs@360 的格式为 filesystem-name@filesystem-id。此格式是必需的，因为镜像守护程序会异步通知文件系统镜像状态（文件系统可以被删除并以相同的名称重新创建）。
目前（2025 年 5 月），该命令提供有关镜像状态的最小信息
ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok fs mirror status cephfs@360
{
"rados_inst": "192.168.0.5:0/1476644347",
"peers": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"remote": {
"client_name": "client.mirror_remote",
"cluster_name": "site-a",
"fs_name": "backup_fs"
}
}
},
"snap_dirs": {
"dir_count": 1
}
}
上面命令输出中的 Peers 部分显示了对等体信息，例如唯一的对等体 ID (UUID) 和规范。如 镜像模块和接口 部分所述，删除现有对等体需要对等体 ID。
具有 fs mirror peer status 前缀的命令返回对等体同步状态。此类命令采用 filesystem-name@filesystem-id peer-uuid 形式，如以下示例所示
ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok fs mirror peer status cephfs@360 a2dc7784-e7a1-4723-b103-03ee8d8768f8
{
"/d0": {
"state": "idle",
"last_synced_snap": {
"id": 120,
"name": "snap1",
"sync_duration": 0.079997898999999997,
"sync_time_stamp": "274900.558797s"
},
"snaps_synced": 2,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
同步统计信息（例如 snaps_synced、snaps_deleted 和 snaps_renamed）在守护程序重新启动时或（部署多个镜像守护程序时）目录重新分配给另一个镜像守护程序时重置。
目录可以处于以下状态之一
- `idle`: The directory is currently not being synchronized
- `syncing`: The directory is currently being synchronized
- `failed`: The directory has hit upper limit of consecutive failures
当目录达到配置的连续同步失败次数时，镜像守护程序将其标记为 failed。将重试这些目录的同步。默认情况下，目录被标记为失败之前的连续失败次数由 cephfs_mirror_max_consecutive_failures_per_directory 配置选项控制（默认值：10）。失败目录的重试间隔由 cephfs_mirror_retry_failed_directories_interval 配置选项控制（默认值：60s）。
例如，添加常规文件进行同步会导致 failed 状态
ceph fs snapshot mirror add cephfs /f0
ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok fs mirror peer status cephfs@360 a2dc7784-e7a1-4723-b103-03ee8d8768f8
{
"/d0": {
"state": "idle",
"last_synced_snap": {
"id": 120,
"name": "snap1",
"sync_duration": 0.079997898999999997,
"sync_time_stamp": "274900.558797s"
},
"snaps_synced": 2,
"snaps_deleted": 0,
"snaps_renamed": 0
},
"/f0": {
"state": "failed",
"snaps_synced": 0,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
这允许用户添加不存在的目录进行同步。镜像守护程序将目录标记为失败并重试（频率较低）。当目录存在时，镜像守护程序会注意到成功的快照同步并取消标记失败状态。
禁用镜像后，文件系统的 fs mirror status 命令将不会显示在命令帮助中。
镜像模块提供了一些命令来显示目录映射和分配信息。要检查目录已映射到哪个镜像守护程序，请运行以下形式的命令
ceph fs snapshot mirror dirmap cephfs /d0/d1/d2
{
"instance_id": "404148",
"last_shuffled": 1601284516.10986,
"state": "mapped"
}
注意
instance_id 是与镜像守护程序关联的 RADOS 实例 ID。
当运行多个镜像守护程序时，state 和 last_shuffled 等其他信息很有用。
如果没有镜像守护程序正在运行，则相同的命令显示以下内容
ceph fs snapshot mirror dirmap cephfs /d0/d1/d2
{
"reason": "no mirror daemons running",
"state": "stalled"
}
这表示没有镜像守护程序正在运行，镜像已停止。
重新添加对等体
当重新添加（重新分配）对等体到另一个集群中的文件系统时，请确保所有镜像守护程序已停止与该对等体同步。这可以通过 fs mirror status admin socket 命令进行检查（Peer UUID 不应显示在命令输出中）。我们建议在将同步的目录重新添加到另一个文件系统之前从对等体中清除它们（尤其是那些可能存在于新主文件系统中的目录）。如果您将对等体重新添加到与以前同步的同一主文件系统，则不需要这样做。
功能状态
cephfs-mirror 守护程序默认构建。它遵循 WITH_CEPHFS CMake 规则）。