CephFS Snapshot Mirroring 快照镜像完全指南:架构、部署与运维监控
CephFS Snapshot Mirroring 快照镜像完全指南:架构、部署与运维监控
导读
本文基于 Ceph 官方文档与仓库源码,系统讲解 CephFS 快照镜像(Snapshot Mirroring)功能的完整知识体系:从异步推送式复制原理、用户与 Peer 配置、守护进程部署,到镜像目录管理、状态监控、指标格式与性能调优,帮助你在生产环境中搭建跨集群的 CephFS 灾难恢复(DR)链路,并借助源码级细节深入理解其底层工作机制。
一、快照镜像是什么:异步推送式复制
CephFS 通过 cephfs-mirror 工具支持将快照异步、以推送(push-based)方式复制到远端 CephFS 文件系统。同步流程分两步:
- 镜像快照数据:将源快照对应的目录数据同步到远端文件系统的对应目录;
- 创建同名远端快照:数据同步完成后,在远端文件系统为给定目录创建与源快照同名的快照。
这意味着镜像的是"目录 + 快照"这个组合,而非整个文件系统。快照之间的同步在后续版本还支持基于 snapdiff/blockdiff 的增量同步(sync-mode 为 delta),首次或无法增量时则采用全量树复制(sync-mode 为 full)。
版本要求:主(本地)集群与次(远端)集群的 Ceph 版本均应为 Pacific 或更新版本(对应官方版本策略,请以实际部署版本为准)。
从源码结构看,cephfs-mirror 守护进程位于 src/tools/cephfs_mirror/,其入口 src/tools/cephfs_mirror/main.cc 创建 Mirror 对象并初始化 Messenger、MonClient 后进入事件循环。核心组件包括:
Mirror/FSMirror:守护进程主体与文件系统级镜像管理;ClusterWatcher/MirrorWatcher:监听集群与文件系统事件;InstanceWatcher:实例(守护进程)发现与心跳;PeerReplayer:真正执行快照回放(replay),并运行 per-peer tick 线程(详见"多线程快照同步"一节)。
二、创建用户:本地镜像用户与远端 Peer 用户
2.1 本地 cephfs-mirror 守护进程用户(主集群)
在主(本地)集群创建供 cephfs-mirror 守护进程使用的 Ceph 用户。该用户需要:
- 元数据池的 写 能力:用于创建 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'
其中 mon 'profile cephfs-mirror' 授予镜像专用的 Monitor 权限 profile,osd 'allow rw tag cephfs metadata=*' 允许在元数据池上创建/写入 watch/notify 所需的索引对象,allow r tag cephfs data=* 允许读取数据池中的数据。
2.2 远端 Peer 用户(次/远端集群)
为每个文件系统 Peer 在次(远端)集群创建 Ceph 用户。该用户需要对 MDS 和 OSD 拥有完整权限(远端需要创建快照,因此 MDS 上需要 p 权限即快照权限):
$ ceph fs authorize <fs_name> client.mirror_remote / rwps
该用户会作为 peer specification 的一部分在添加 Peer 时提供。rwps 中的 p(path/snapshot 权限)是远端创建同名快照所必需的。
三、部署与启动 cephfs-mirror 守护进程
3.1 systemd 管理
cephfs-mirror 守护进程由 systemd 管理(instance 名为 mirror):
$ systemctl enable cephfs-mirror@mirror
$ systemctl start cephfs-mirror@mirror
对应的 systemd 单元文件位于 systemd/cephfs-mirror@.service.in。
3.2 前台运行(调试)
$ cephfs-mirror --id mirror --cluster site-a -f
注意:这里指定的用户是
mirror,其创建方法见上文"创建用户"一节。-f表示前台运行,便于调试;实际生产通常由 systemd/cephadm 托管。
3.3 cephadm 部署(推荐)
在大多数情况下,最好使用 cephadm 接口来部署:
$ ceph orch apply cephfs-mirror
部署多个镜像守护进程(指定放置规格):
$ ceph orch apply cephfs-mirror --placement=<placement-spec>
例如在三个不同主机上部署三个 cephfs-mirror 守护进程:
$ ceph orch apply cephfs-mirror --placement="3 host1,host2,host3"
3.4 多守护进程与 M/N 负载分担
可以部署多个 cephfs-mirror 守护进程以实现并发同步和高可用。镜像守护进程之间使用简单的 M/N 策略 分担同步负载:M 是目录数,N 是 cephfs-mirror 守护进程数。目录到实例的映射由 mgr 的 mirroring 模块维护(详见下节)。
官方提示:目前推荐部署单个镜像守护进程,运行多个守护进程尚未经过完整测试。多守护进程场景下,目录重排(reshuffle)会导致 per-session 计数器重置(详见"快照同步指标字段"一节)。
四、Mirroring 模块与命令体系
4.1 两种命令前缀:模块命令 vs Monitor 命令
Manager 的 mirroring 模块 提供了管理目录快照镜像的接口,它们是 Monitor 命令的(大部分)包装,是推荐的控制接口。
- 模块命令:以
fs snapshot mirror为前缀(如ceph fs snapshot mirror enable); - Monitor 命令:以
fs mirror为前缀(如fs mirror enable)。
重要警告:如果使用 Monitor 命令而非模块命令启用镜像,由于缺少
cephfs_mirror索引对象,镜像守护进程将进入 failed 状态。因此在本场景下务必使用模块命令。
从 src/pybind/mgr/mirroring/module.py 可以看到全部模块命令及其实现绑定:fs snapshot mirror enable/disable、peer_add/peer_list/peer_remove、peer_bootstrap create/import、add/remove/ls、dirmap、show distribution、daemon status、status、checkpoint add/remove/ls/now 等。
4.2 启用 mirroring 模块
mirroring 模块默认禁用,启用命令:
$ ceph mgr module enable mirroring
mirroring 模块的职责是将目录分配给镜像守护进程进行同步。多个镜像守护进程可以同时运行以获得目录快照同步的并发性;当守护进程被拉起或终止时,模块会发现镜像守护进程集合的变化,并在新集合上重新平衡目录分配,从而提供高可用性。这一逻辑实现在 src/pybind/mgr/mirroring/fs/dir_map/policy.py 的 Policy 类中:每个目录维护 instance_id、mapped_time、状态与转移动作,实例增删时触发目录的 acquire/release 重排。
4.3 启用 / 禁用文件系统镜像
为某个文件系统启用快照镜像(必须先启用模块):
$ ceph fs snapshot mirror enable <fs_name>
禁用:
$ ceph fs snapshot mirror disable <fs_name>
从 src/pybind/mgr/mirroring/fs/snapshot_mirror.py 的 enable_mirror 实现可见,启用时模块会先在元数据池中创建 cephfs_mirror RADOS 对象(create_mirror_object),再向 Monitor 发送 fs mirror enable 命令——这正是模块命令与裸 Monitor 命令的差异所在:缺少该索引对象会导致守护进程进入 failed 状态。
4.4 支持镜像的文件类型
以下文件类型受镜像支持:
- 常规文件(
-) - 目录文件(
d) - 符号链接文件(
l)
其他文件类型会被镜像忽略,因此不会出现在成功同步的 Peer 上。
五、配置 Peer(远端对端)
5.1 添加 Peer
启用镜像后,需要添加用于接收目录快照的 Peer。Peer 以 <client>@<cluster> 格式指定(本文档中称为 remote_cluster_spec)。Peer 添加时会被分配一个唯一 ID(UUID)。
$ ceph fs snapshot mirror peer_add <fs_name> <remote_cluster_spec> [<remote_fs_name>] [<remote_mon_host>] [<cephx_key>]
<remote_cluster_spec>格式为client.<id>@<cluster_name>;<remote_fs_name>可选,默认与<fs_name>相同(指远端集群上的文件系统名)。
该命令成功的前提是:远端集群的 Ceph 配置与用户 keyring 在主集群可用。例如,远端集群上创建了名为 client_mirror 的用户,对名为 remote_fs 的远端文件系统拥有 rwps 权限(见"创建用户"一节),且远端集群名为 remote_ceph(即主集群上远端集群配置文件名为 remote_ceph.conf),则向主文件系统 primary_fs 添加远端文件系统作为 Peer 的命令为:
$ ceph fs snapshot mirror peer_add primary_fs client.mirror_remote@remote_ceph remote_fs
为避免在主集群中维护远端集群配置文件与远端 Ceph 用户 keyring,可以使用 bootstrap Peer 方式(将远端集群信息存储在主集群的 Monitor config store 中),详见下一节。
peer_add支持传递远端集群 Monitor 地址与用户密钥,但 bootstrap Peer 是推荐方式。另外,目前仅支持单个 Peer;peer_add命令已被标记为废弃(deprecated),将在未来版本移除,请改用peer_bootstrap create命令。
5.2 移除 / 列出 Peer
$ ceph fs snapshot mirror peer_remove <fs_name> <peer_uuid>
$ ceph fs snapshot mirror peer_list <fs_name>
peer_remove 需要 Peer UUID(可通过 peer_list 或 admin socket 获取)。
六、Bootstrap Peers(推荐方式)
通过 peer_add 添加 Peer 需要 Peer 集群配置与用户 keyring 在主集群可用(Manager 主机与运行镜像守护进程的主机)。可以通过引导(bootstrap)并导入 Peer token 来避免这一要求。
6.1 在 Peer 集群创建 Bootstrap Token
$ 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 中 @ 之后的部分(集群名)。
从源码 src/pybind/mgr/mirroring/fs/snapshot_mirror.py 的 peer_bootstrap_create 可见,token 实际是一个 base64 编码的 JSON 对象,包含 fsid(远端集群 FSID)、filesystem(远端文件系统名)、user(client.<id>)、site_name、key(CephX 密钥)与 mon_host(Monitor 地址列表)。
6.2 在主集群导入 Token
$ ceph fs snapshot mirror peer_bootstrap import <fs_name> <token>
例如:
$ ceph fs snapshot mirror peer_bootstrap import cephfs eyJmc2lkIjogIjBkZjE3MjE3LWRmY2QtNDAzMC05MDc5LTM2Nzk4NTVkNDJlZiIsICJmaWxlc3lzdGVtIjogImJhY2t1cF9mcyIsICJ1c2VyIjogImNsaWVudC5taXJyb3JfcGVlcl9ib290c3RyYXAiLCAic2l0ZV9uYW1lIjogInNpdGUtcmVtb3RlIiwgImtleSI6ICJBUUFhcDBCZ0xtRmpOeEFBVnNyZXozai9YYUV0T2UrbUJEZlJDZz09IiwgIm1vbl9ob3N0IjogIlt2MjoxOTIuMTY4LjAuNTo0MDkxOCx2MToxOTIuMTY4LjAuNTo0MDkxOV0ifQ==
导入时模块会解码 token,校验 fsid 与远端集群是否一致、源与目标是否同一集群同一文件系统(防止自我镜像),并在远端文件系统根目录设置 ceph.mirror.info 扩展属性(xattr)以标记 Peer 归属;添加成功后,mon_host、key 等远端信息以 cephfs/mirror/peer/<fs>/<uuid> 为 key 存入 Monitor config store。
七、管理镜像目录
7.1 添加 / 列出 / 移除目录
$ ceph fs snapshot mirror add <fs_name> <path>
$ ceph fs snapshot mirror ls <fs_name>
$ ceph fs snapshot mirror remove <fs_name> <path>
只允许绝对目录路径。
7.2 路径规范化
mirroring 模块会规范化路径:例如 /a/b/../b 等价于 /a/b。路径始终从 CephFS 文件系统根目录开始,而非主机系统的挂载点。示例:
$ 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
7.3 祖先 / 子树限制
目录加入镜像后,不允许再镜像其子目录或祖先目录:
$ 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
即同一时刻一个目录只能被镜像一次,且镜像目录之间不能存在祖先/后代关系。
八、触发快照镜像
镜像目录配置完成后,在主集群为配置的目录创建快照即可触发镜像:
$ mkdir -p /d0/d1/d2/.snap/snap1
创建快照后,cephfs-mirror 守护进程(通过 PeerReplayer)会:扫描目录 → 发现新快照 → 同步数据 → 在远端创建同名快照。
九、镜像状态监控
9.1 守护进程状态(daemon status)
mirroring 模块提供 mirror daemon status 接口:
$ ceph fs snapshot mirror daemon status
[
{
"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",
"mon_host": "[v2:192.168.64.5:40183,v1:192.168.64.5:40184]",
"fsid": "5682c8e5-50cd-4cfd-b75c-5354dcdda487"
},
"stats": {
"failure_count": 1,
"recovery_count": 0
}
}
]
}
]
}
]
每个镜像守护进程实例显示一条记录,包含已配置 Peer 与基本统计。Peer 信息包括远端文件系统名(fs_name)、集群 Monitor 地址(mon_host)与集群 FSID(fsid)。其中 mon_host 与 fsid 由模块从 Monitor config store 中的 peer 配置读取(见 snapshot_mirror.py 的 daemon_status 实现)。
9.2 快照同步指标(fs snapshot mirror status)
mirroring 模块提供 fs snapshot mirror status 命令查询已镜像文件系统的每目录快照同步指标。这是从 Ceph CLI 检查镜像进度的推荐方式,无需使用 cephfs-mirror admin socket。
语法:
$ ceph fs snapshot mirror status <fs_name> [<mirrored_dir_path>] [--peer_uuid=<peer_uuid>]
| 参数 | 说明 |
|---|---|
<fs_name> |
主集群上已启用镜像的文件系统 |
<mirrored_dir_path>(可选) |
已配置镜像的目录绝对路径(例如 /d0);省略时返回所有镜像目录(受 --peer_uuid 约束)的指标 |
--peer_uuid=<peer_uuid>(可选) |
镜像 Peer 的 UUID(来自 ceph fs snapshot mirror peer_list);省略时返回所有已配置 Peer 的指标。两者都指定时,仅报告该目录/Peer 组合 |
示例:
# 所有目录与所有 Peer
$ ceph fs snapshot mirror status cephfs
# 单个镜像目录,所有 Peer
$ ceph fs snapshot mirror status cephfs /d0
# 单个 Peer 的所有目录
$ ceph fs snapshot mirror status cephfs --peer_uuid=a2dc7784-e7a1-4723-b103-03ee8d8768f8
# 单个目录 + 单个 Peer
$ ceph fs snapshot mirror status cephfs /d0 --peer_uuid=a2dc7784-e7a1-4723-b103-03ee8d8768f8
输出格式:命令返回顶层含 metrics key 的 JSON 对象。每目录统计嵌套在 metrics/<mirrored-dir-path>/peer/<peer-uuid> 下,因此同一目录路径可对多个 Peer 分别报告而不发生 key 冲突。
当启用镜像但未配置 Peer 时,命令成功并返回空 metrics 对象:
$ ceph fs snapshot mirror status cephfs
{
"metrics": {}
}
目录已加入镜像但尚未同步任何快照时,Manager 报告与 admin socket 相同的默认空闲统计(state 为 idle,snap 计数器为零,无 last_synced_snap)。整文件系统查询包含镜像策略中的每个目录,对尚无 omap 条目的目录或 Peer 使用这些默认值。最小空闲示例(一个目录、一个 Peer):
$ ceph fs snapshot mirror status cephfs /d0
{
"metrics": {
"/d0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "idle",
"snaps_synced": 0,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
}
}
}
快照同步完成后,last_synced_snap、current_syncing_snap、snaps_synced、snaps_deleted、snaps_renamed 等字段与 admin socket 输出一致(由拥有该目录的守护进程活跃地持久化 omap 更新时)。mgr 命令还包含 metrics_updated_at(上次 omap 写入的墙上时钟时间)。时长与字节数以可读格式呈现(如 33s、149.94 MiB)。
错误场景:命令在以下情况以非零退出码和错误信息失败:
<fs_name>不存在;- 文件系统未启用镜像;
<mirrored_dir_path>不是绝对路径、未配置镜像或不在镜像策略中;<peer_uuid>未针对该文件系统配置。
9.3 快照同步指标字段(Snapshot sync metric fields)
ceph fs snapshot mirror status 与 fs mirror peer status 报告相同的核心每目录同步字段。cephfs-mirror 守护进程将这些字段(以及下述 omap 元数据)写入元数据池 omap(位于 cephfs_mirror RADOS 对象上),使 mirroring Manager 模块无需访问镜像守护进程主机或 admin socket 即可读取并服务于 ceph fs snapshot mirror status。守护进程重启时,仅有一小部分字段会从 omap 重新加载回内存,其余字段在新会话中重建或重置。
ceph fs snapshot mirror status 额外暴露 metrics_updated_at,即该目录与 Peer 上次 omap 写入的墙上时钟时间。该字段不在 fs mirror peer status 中(后者读取守护进程的实时内存状态,无需单独的持久化时间戳)。在 mgr 命令中,该字段帮助运维人员判断 omap 支撑的指标新鲜度——取决于 omap 持久化间隔(cephfs_mirror_tick_interval)与 Manager 响应缓存(snapshot_mirror_metrics_cache_enabled 与 snapshot_mirror_metrics_cache_ttl)。
9.3.1 Per-session 计数器
snaps_synced、snaps_deleted、snaps_renamed 会写入 omap,但只统计当前守护进程会话内的活动。cephfs-mirror 守护进程启动或目录被重新分配给另一守护进程时,不会从 omap 加载它们,因此计数器在守护进程重启和目录重排(多守护进程部署中)后会重置为零。admin socket 立即反映该变化;omap 在新拥有守护进程写入更新条目之前,可能仍保存上一会话的值。
9.3.2 Omap 持久化与重启恢复
| 字段 | 写入 omap | 守护进程重启时加载 | 说明 |
|---|---|---|---|
last_synced_snap(及其子字段) |
是 | 是 | 跨守护进程重启存活;加载时与远端 snap map 对账 |
current_syncing_snap |
是(同步期间) | 否 | 恢复同步时重建 |
snaps_synced、snaps_deleted、snaps_renamed |
是 | 否 | 写入 omap 但属 per-session;重启时不加载 |
state、failure_reason |
是 | 否 | 反映最后写入者的视图,直到 omap 再次更新 |
_instance_id |
是 | 否 | 内部字段;Manager 用于陈旧检测,CLI 输出中省略 |
metrics_updated_at |
是 | 否 | 上次 omap 写入的墙上时钟时间(mgr CLI 中为 ISO-8601);仅由 ceph fs snapshot mirror status 暴露(fs mirror peer status 没有) |
9.3.3 Omap 清理
目录从镜像移除时,cephfs-mirror 守护进程会从 cephfs_mirror 对象中删除对应的 omap 条目。
9.4 目录状态(Directory states)
一个目录(在每个 Peer 下)可以处于以下状态之一:
idle:目录当前未被同步;syncing:目录正在同步。current_syncing_snap对象描述进行中的快照同步(字段表见下文);stale:Manager 在持久化 omap 数据不再被活跃镜像守护进程实例拥有时报告(见"陈旧进度检测")。current_syncing_snap被省略;failed:目录达到连续同步失败次数上限。可能带有failure_reason字符串。
9.5 陈旧进度检测(Stale progress detection)
每个 omap 条目记录一个内部 _instance_id(最后一次写入该条目的 cephfs-mirror 守护进程的 RADOS 客户端实例)。Manager 将该值与活跃镜像守护进程实例集合、以及 mirroring 模块目录映射中当前分配给该目录的实例进行比较:
- 若持久化的
_instance_id不在活跃镜像实例中,该条目被报告为stale(无论持久化的state是什么); - 若目录的已跟踪实例与持久化的
_instance_id不同,且持久化state不是idle,该条目被报告为stale(例如目录在同步中途被重排到另一守护进程)。
两种情况下 current_syncing_snap 都会从输出中省略。stale 状态仅由 ceph fs snapshot mirror status 报告,因为它可以读取 omap(即使没有镜像守护进程在运行)。admin socket 需要活跃的 cephfs-mirror 守护进程;守护进程未运行时 ceph --admin-daemon 命令会失败。
守护进程重启后:cephfs-mirror 重启后立即,omap 可能仍包含上一会话写入的指标(包括陈旧的 _instance_id)。Manager 可能报告 stale,直到新守护进程实例写入更新后的 omap 条目。omap 中的 per-session 计数器同样可能反映上一会话,直到新守护进程持久化;重启守护进程上的 admin socket 已显示这些计数器为零。
9.6 指标缓存(Caching)
为降低元数据池负载,Manager 在内存中维护两个短期缓存,用于返回 fs snapshot mirror status 的格式化指标:
- 完整缓存(Complete cache):每个文件系统一条记录,包含所有镜像目录与 Peer(一次完整 omap 快照)。用于
ceph fs snapshot mirror status <fs_name>以及可选的--peer_uuid过滤; - 部分缓存(Partial cache):按文件系统、目录路径与 Peer 集合为 key 的每目录 omap 读取。单目录查询(
<fs_name> <mirrored_dir_path>)先查看完整缓存;未命中时使用部分缓存,这样完整缓存冷启动时不会触发全量 omap 扫描。
缓存默认启用(snapshot_mirror_metrics_cache_enabled)。禁用时每次查询直接读取 omap。启用时两个缓存的默认 TTL 为 15 秒(snapshot_mirror_metrics_cache_ttl)。TTL 内的重复查询可能无需再次读取 omap;缓存过期后,下次查询从 omap 重新加载。相关实现见 src/pybind/mgr/mirroring/fs/metrics/cache.py 与 module.py 中的模块选项定义。
9.7 与 admin socket 的对比
ceph fs snapshot mirror status |
fs mirror peer status(admin socket) |
|---|---|
| 通过 Ceph CLI 经由 Manager 调用 | 在镜像守护进程主机上用 ceph --admin-daemon 调用 |
| 读取元数据池 omap 中持久化的指标 | 读取镜像守护进程的内存状态 |
last_synced_snap 跨守护进程重启存活(来自 omap) |
last_synced_snap 在守护进程启动时从 omap 恢复 |
| Per-session 计数器可能滞后于 omap,直到拥有守护进程重新持久化 | Per-session 计数器在守护进程重启时重置为零 |
当 omap 写入者不再活跃时可报告 stale |
需要运行中的镜像守护进程(无活跃实例时不可用) |
包含 metrics_updated_at(上次 omap 写入时间) |
不存在;仅读取实时内存状态 |
| 可按镜像目录路径与 Peer UUID 过滤 | 报告给定 Peer 的所有镜像目录 |
结论:在特定镜像守护进程主机上做交互式调试时,admin socket 仍有用;运维与监控集成偏好标准 ceph 子命令时,使用 fs snapshot mirror status。
十、admin socket 命令详解
10.1 查看可用命令
CephFS 镜像守护进程提供 admin socket 命令查询镜像状态:
$ 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。这种格式是必须的,因为镜像守护进程异步接收文件系统镜像状态通知(文件系统可能被删除后用同名重建)。
10.2 文件系统镜像状态
该命令目前提供镜像状态的少量信息:
$ 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 部分显示 Peer 信息,包括唯一 peer-id(UUID)与规格(spec)。移除已有 Peer 时需要该 peer-id(见"Mirroring 模块"一节)。
10.3 Peer 同步状态(fs mirror peer status)
以 fs mirror peer status 开头的命令提供 Peer 同步状态。命令参数格式为 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
{
"metrics": {
"/d0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "idle",
"last_synced_snap": {
"id": 120,
"name": "snap1",
"crawl_duration": "2s",
"datasync_queue_wait_duration": "1s",
"sync_duration": "33s",
"sync_time_stamp": "2026-07-15T12:00:00.558797+0530",
"sync_bytes": "149.94 MiB",
"sync_files": 5000
},
"snaps_synced": 2,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
}
}
}
每目录字段嵌套在 metrics/<mirrored-dir-path>/peer/<peer-uuid> 下,同一目录路径可对多个 Peer 分别报告而不发生 key 冲突。
10.4 同步进行中(syncing 状态)
目录正在同步时,镜像守护进程将其标记为 syncing,fs mirror peer status 在 current_syncing_snap 下显示正在同步的快照:
$ ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok fs mirror peer status cephfs@360 a2dc7784-e7a1-4723-b103-03ee8d8768f8
{
"metrics": {
"/d0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "syncing",
"current_syncing_snap": {
"id": 121,
"name": "snap2",
"sync-mode": "full",
"avg_read_throughput_bytes": "13.03 MiB/s",
"avg_write_throughput_bytes": "24.24 MiB/s",
"crawl": {
"state": "completed",
"duration": "2s"
},
"datasync_queue_wait": {
"state": "complete",
"duration": "1s"
},
"bytes": {
"sync_bytes": "60.40 MiB",
"total_bytes": "149.94 MiB",
"sync_percent": "40.29%"
},
"files": {
"sync_files": 2013,
"total_files": 5000,
"sync_percent": "40.26%"
},
"eta": "7s"
},
"snaps_synced": 2,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
}
}
}
同步完成时,镜像守护进程将其标记回 idle。
state 为 syncing 时,current_syncing_snap 包含以下进度字段:
| 字段 | 说明 |
|---|---|
sync-mode |
快照以全量树复制(full)还是增量 snapdiff/blockdiff(delta)同步 |
avg_read_throughput_bytes |
本次快照同步从主文件系统的平均读取速率 |
avg_write_throughput_bytes |
本次快照同步向远端 Peer 的平均写入速率 |
crawl.state |
目录树遍历状态:in-progress 或 completed。in-progress 时 bytes.total_bytes 与 files.total_files 仅反映已发现内容且可能持续增长;completed 后这些总数在本次快照同步中完全确定 |
crawl.duration |
已用的遍历时间,或 crawl.state 为 completed 后的总遍历时间 |
datasync_queue_wait.state |
快照仍在数据同步队列中等待(waiting)还是已开始传输(complete) |
datasync_queue_wait.duration |
已用的队列等待时间,或传输开始后的总队列等待时间 |
bytes.sync_bytes |
本次快照已同步的文件数据量 |
bytes.total_bytes |
本次快照同步已发现的文件数据总量。crawl.state 为 in-progress 时随遍历增加;completed 后为最终值 |
bytes.sync_percent |
已同步的 total_bytes 百分比 |
files.sync_files |
本次快照已同步的文件数 |
files.total_files |
本次快照同步已发现的文件总数。in-progress 时随遍历增加;completed 后为最终值 |
files.sync_percent |
已同步的 total_files 百分比 |
eta |
完成快照同步的预计剩余时间;样本不足时为 calculating... |
last_synced_snap 包含上次完成快照同步的额外字段:
| 字段 | 说明 |
|---|---|
crawl_duration |
该快照同步中遍历目录树的总耗时 |
datasync_queue_wait_duration |
文件传输开始前快照在数据同步队列中的总等待时间 |
sync_duration |
快照同步的总耗时 |
sync_time_stamp |
同步完成时间 |
sync_bytes |
该快照同步的文件数据总量 |
sync_files |
该快照同步的文件数 |
十一、值格式化规范
状态输出中的多个字段以可读格式呈现而非原始数字:
11.1 时长(Durations)
涉及字段:crawl_duration、datasync_queue_wait_duration、sync_duration、crawl.duration、datasync_queue_wait.duration、eta。
耗时四舍五入到最近整秒,以天/时/分/秒组合显示,格式随数量级自适应:
<SS>s— 仅秒(不足一分钟时),如2s、33s;<M>m <SS>s— 分 + 秒(不足一小时时),如5m 12s;<H>h <MM>m <SS>s— 时 + 分 + 秒(不足一天时),如1h 05m 30s;<D>d <HH>h <MM>m <SS>s— 天 + 时 + 分 + 秒(一天及以上),如1d 02h 30m 45s。
11.2 数据大小(Data sizes)
涉及字段:sync_bytes、bytes.sync_bytes、bytes.total_bytes 以及 last_synced_snap 中的字节数。
字节数使用二进制(IEC)单位,保留两位小数,单位自动从 B、KiB、MiB、GiB、TiB、PiB(1024 的幂)中选择。例如 149.94 MiB。
11.3 吞吐量(Throughput)
涉及字段:avg_read_throughput_bytes 与 avg_write_throughput_bytes。
每秒字节数的平均传输速率,使用与数据大小相同的二进制单位并附加 /s 后缀。例如 13.03 MiB/s 表示每秒 13.03 mebibytes。
11.4 百分比(Percentages)
涉及字段:bytes.sync_percent 与 files.sync_percent。
完成百分比保留两位小数并附加 % 后缀,如 40.29%。
11.5 计数(Counts)
涉及字段:sync_files、total_files、snaps_synced、snaps_deleted、snaps_renamed 与快照 id。
纯无符号整数,无单位后缀。
11.6 时间戳(Timestamp)
涉及字段:sync_time_stamp(以及 mgr status 中的 metrics_updated_at)。
墙上时钟时间以带亚秒精度与时区偏移的 ISO-8601 本地时间打印(如 2026-07-15T12:00:00.558797+0530)。sync_time_stamp 是快照同步完成时间;metrics_updated_at 是该目录与 Peer 上次 omap 写入时间。Omap 持久化与 counter dump(last_sync_timestamp)仍存储 Unix epoch 秒。
snaps_synced、snaps_deleted、snaps_renamed 是 per-session 计数器:只统计当前 cephfs-mirror 守护进程会话内的活动,重启时不从 omap 恢复,守护进程重启或目录被重新分配给另一镜像守护进程(多守护进程部署)时重置为零。
十二、失败处理与 failed 状态
当目录经历配置数量的连续同步失败时,镜像守护进程将其标记为 failed。这些目录的同步会被重试。默认连续失败次数阈值由 cephfs_mirror_max_consecutive_failures_per_directory 配置项控制(默认 10),失败目录的重试间隔由 cephfs_mirror_retry_failed_directories_interval 配置项控制(默认 60 秒)。
例如,添加一个常规文件进行同步会导致 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
{
"metrics": {
"/d0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "idle",
"last_synced_snap": {
"id": 121,
"name": "snap2",
"crawl_duration": "2s",
"datasync_queue_wait_duration": "1s",
"sync_duration": "44s",
"sync_time_stamp": "2026-07-15T12:05:33.600797+0530",
"sync_bytes": "149.94 MiB",
"sync_files": 5000
},
"snaps_synced": 3,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
},
"/f0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "failed",
"snaps_synced": 0,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
}
}
}
这实际上允许用户添加一个尚不存在的目录进行同步:镜像守护进程会将其标记为 failed 并(以更低频率)重试;目录创建后,成功同步时守护进程会清除 failed 状态。
注意:在远端文件系统的 .snap 目录中添加新快照或新目录,会导致对应配置目录进入 failed 状态(因为远端不应被写入快照)。在远端文件系统上:
$ ceph fs subvolume snapshot create cephfs subvol1 snap2 group1
# 或
$ mkdir /d0/.snap/snap2
$ ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok fs mirror peer status cephfs@360 a2dc7784-e7a1-4723-b103-03ee8d8768f8
{
"metrics": {
"/d0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "failed",
"failure_reason": "snapshot 'snap2' has invalid metadata",
"last_synced_snap": {
"id": 120,
"name": "snap1",
"crawl_duration": "2s",
"datasync_queue_wait_duration": "1s",
"sync_duration": "33s",
"sync_time_stamp": "2026-07-15T12:00:00.558797+0530",
"sync_bytes": "149.94 MiB",
"sync_files": 5000
},
"snaps_synced": 2,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
},
"/f0": {
"peer": {
"a2dc7784-e7a1-4723-b103-03ee8d8768f8": {
"state": "failed",
"snaps_synced": 0,
"snaps_deleted": 0,
"snaps_renamed": 0
}
}
}
}
}
当快照或目录从远端文件系统移除后,守护进程会在待处理快照(如有)成功同步后清除 failed 状态。
重要:在远端文件系统上为正在镜像的目录设置 snap-schedule(快照计划)会导致镜像守护进程报告
invalid metadata之类的错误。重要:请将远端文件系统视为只读。CephFS 本身不强制执行这一点,但通过正确的 MDS caps,用户将无法在远端文件系统中对目录创建快照。
当镜像被禁用时,对应文件系统的 fs mirror status 命令不会出现在命令帮助中。
十三、监控指标(Metrics)
CephFS 将镜像指标导出为带标签的 Perf Counters(Labeled Perf Counters),供监控工具抓取(例如通过 ceph-exporter 抓取到 Prometheus)。运维人员可以通过镜像守护进程 admin socket 的 counter dump 命令查看。
快照镜像相关的三组带标签计数器:
cephfs_mirror_mirrored_filesystems— 按镜像守护进程上的主文件系统统计(例如directory_count、mirroring_peers);cephfs_mirror_peers— 按文件系统上单个 Peer 的所有镜像目录聚合;cephfs_mirror_directory— 按镜像目录路径与 Peer 统计(新增)。
fs mirror peer status 与 ceph fs snapshot mirror status 返回的 JSON 以人类可读形式描述相同的同步状态,而 cephfs_mirror_directory 计数器以数值 gauge 形式向监控系统暴露该状态。
13.1 访问 Perf Counters
在运行 cephfs-mirror 的主机上:
$ ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok counter dump
带标签的组以顶层 JSON 数组出现(如 "cephfs_mirror_directory": [ ... ])。每个数组元素包含 labels 对象与 counters 对象。在同一 admin socket 上使用 counter schema 可列出计数器名称与类型。
文件系统镜像指标(cephfs_mirror_mirrored_filesystems):
| 名称 | 类型 | 说明 |
|---|---|---|
| mirroring_peers | Gauge | 参与镜像的 Peer 数 |
| directory_count | Gauge | 正在同步的目录总数 |
| mirrored_filesystems | Gauge | 已镜像的文件系统总数 |
| mirror_enable_failures | Counter | 启用镜像失败次数 |
Peer 复制指标(cephfs_mirror_peers):
| 名称 | 类型 | 说明 |
|---|---|---|
| snaps_synced | Counter | 该文件系统上该 Peer 已同步的快照总数(所有目录合计) |
| sync_bytes | Counter | 正在同步的总字节数 |
| sync_failures | Counter | 失败的快照同步总数 |
| snaps_deleted | Counter | 已删除快照总数 |
| snaps_renamed | Counter | 已重命名快照总数 |
| avg_sync_time | Gauge | 所有快照同步的平均耗时 |
| last_synced_start | Gauge | 上次同步快照的同步开始时间 |
| last_synced_end | Gauge | 上次同步快照的同步结束时间 |
| last_synced_duration | Gauge | 上次同步的耗时 |
| last_synced_bytes | Counter | 上次同步快照的总字节数 |
Peer 级计数器以 source_fscid、source_filesystem、peer_cluster_name、peer_cluster_filesystem 为标签。它们不包含 peer_uuid 或 directory;如需按路径细分请使用 cephfs_mirror_directory。
13.2 每目录复制指标(cephfs_mirror_directory)
cephfs_mirror_directory 带标签计数器组报告单个镜像目录路径向单个 Peer 的快照镜像进度。目录加入镜像(fs snapshot mirror add)时创建一个 perf counter 实例,目录从策略移除时删除。
这与 fs mirror peer status 中 metrics/<mirrored-dir-path>/peer/<peer-uuid> 下的每目录字段对应,但使用适合绘图与告警的原始数值(每秒字节数、秒、基点)。
标签:
| 标签 | 说明 |
|---|---|
source_fscid |
主集群上的文件系统集群 ID |
source_filesystem |
主集群上的文件系统名 |
peer_uuid |
镜像 Peer UUID(区分同一目录路径镜像到多个 Peer 的情况) |
peer_cluster_name |
Peer 的远端集群名 |
peer_cluster_filesystem |
Peer 上的远端文件系统名 |
directory |
镜像目录路径(例如 /parent/d1) |
示例(一个目录、一个 Peer):
$ ceph --admin-daemon /var/run/ceph/cephfs-mirror.asok counter dump
{
"cephfs_mirror_directory": [
{
"labels": {
"source_fscid": "360",
"source_filesystem": "cephfs",
"peer_uuid": "8a85ab25-70f9-48e9-b82d-56324e75209b",
"peer_cluster_name": "site-a",
"peer_cluster_filesystem": "backup_fs",
"directory": "/parent/d1"
},
"counters": {
"dir_state": 0,
"current_snap_id": 0,
"snaps_synced": 1,
"last_snap_id": 3,
"last_sync_bytes": 157286400,
"last_sync_files": 5000,
...
}
}
]
}
通过 ceph-exporter 导出时,计数器名称会加前缀(例如 ceph_cephfs_mirror_directory_current_sync_bytes)并附带标签维度。
更新频率:
- 当前同步 gauges(
current_*、crawl_*、datasync_wait_*、同步中的dir_state):由 per-peer tick 线程按cephfs_mirror_tick_interval(默认 5 秒)配置的间隔刷新。仅更新该守护进程上活跃注册同步的目录; - 上次同步 gauges(
last_*):快照同步完成与目录加入镜像时更新; - 汇总 gauges(
snaps_synced、snaps_deleted、snaps_renamed):对应每目录计数器变化时更新(同步完成、快照删除、快照重命名)。
与 fs mirror peer status 的映射:
| Perf counter | Admin socket / mgr JSON 字段 | 说明 |
|---|---|---|
dir_state |
state |
0 = idle,1 = syncing,2 = failed(不含 stale;stale 仅 mgr 报告) |
current_snap_id |
current_syncing_snap.id |
idle 或 failed 时为 0 |
current_sync_mode |
current_syncing_snap.sync-mode |
0 = full,1 = delta |
current_read_bps / current_write_bps |
avg_read_throughput_bytes / avg_write_throughput_bytes |
原始每秒字节数(非可读字符串) |
crawl_state / crawl_duration_seconds |
current_syncing_snap.crawl |
见下方 crawl 状态表 |
datasync_wait_state / datasync_wait_duration_seconds |
current_syncing_snap.datasync_queue_wait |
见下方 datasync 等待状态表 |
current_sync_bytes / current_total_bytes / current_sync_bytes_percent |
current_syncing_snap.bytes |
百分比为基点(4029 = 40.29%) |
current_sync_files / current_total_files / current_sync_files_percent |
current_syncing_snap.files |
百分比为基点 |
current_eta_valid / current_eta_seconds |
current_syncing_snap.eta |
current_eta_valid:0 = 计算中,1 = ETA 可用 |
last_snap_id 与 last_*_duration_seconds、last_sync_bytes、last_sync_files |
last_synced_snap |
时长为秒;字节为原始计数 |
last_sync_timestamp |
last_synced_snap.sync_time_stamp |
Perf counter 为 Unix epoch 秒;admin/mgr JSON 显示 ISO-8601 本地时间 |
snaps_synced / snaps_deleted / snaps_renamed |
目录级同名字段 | 守护进程重启或目录重分配时重置(与 admin socket 相同) |
目录状态(dir_state):
| 值 | 含义 |
|---|---|
0 |
Idle — 该目录当前没有正在同步的快照 |
1 |
Syncing — current_* gauges 反映进行中的快照同步 |
2 |
Failed — 目录达到连续失败上限;current_* gauges 被清零 |
当 dir_state 为 0 或 2 时,所有 current_*、crawl_*、datasync_wait_* 计数器均置零。
当前同步快照计数器(dir_state 为 1 时存在,对应 fs mirror peer status 的 current_syncing_snap):
| 计数器 | 类型 | 说明 |
|---|---|---|
current_snap_id |
Gauge | 正在同步的快照 ID |
current_sync_mode |
Gauge | 0 = 全量同步,1 = delta(snapdiff/blockdiff) |
current_read_bps |
Gauge | 本次同步的平均主端读取吞吐(每秒字节数) |
current_write_bps |
Gauge | 本次同步的平均远端写入吞吐(每秒字节数) |
crawl_state |
Gauge | 0 = 不适用,1 = 进行中,2 = 已完成 |
crawl_duration_seconds |
Gauge | 遍历时长(秒)(进行中为已用时间,完成后为总时间) |
datasync_wait_state |
Gauge | 0 = 无,1 = 在数据同步队列中等待,2 = 已开始传输 |
datasync_wait_duration_seconds |
Gauge | 在数据同步队列中的时间(秒) |
current_sync_bytes |
Gauge | 本次快照已同步的字节数 |
current_total_bytes |
Gauge | 本次快照同步已发现的字节总数 |
current_sync_bytes_percent |
Gauge | 同步进度(基点,10000 = 100.00%) |
current_sync_files |
Gauge | 已同步的文件数 |
current_total_files |
Gauge | 本次快照同步已发现的文件总数 |
current_sync_files_percent |
Gauge | 文件进度(基点) |
current_eta_valid |
Gauge | 0 = ETA 尚不可用(admin socket 显示 calculating...),1 = ETA 可用 |
current_eta_seconds |
Gauge | current_eta_valid 为 1 时的预计剩余秒数 |
上次同步快照计数器(每次成功同步后更新,对应 last_synced_snap):
| 计数器 | 类型 | 说明 |
|---|---|---|
last_snap_id |
Gauge | 上次成功同步的快照 ID |
last_crawl_duration_seconds |
Gauge | 该次同步的目录遍历时长 |
last_datasync_wait_duration_seconds |
Gauge | 该次同步的数据同步队列等待时长 |
last_sync_duration_seconds |
Gauge | 该快照同步的总耗时 |
last_sync_timestamp |
Time | 该次同步完成时的墙上时钟时间(utime_t) |
last_sync_bytes |
Gauge | 该快照同步的字节数 |
last_sync_files |
Gauge | 该快照同步的文件数 |
每目录快照汇总计数器:
| 计数器 | 类型 | 说明 |
|---|---|---|
snaps_synced |
Gauge | 上次计数器重置以来成功同步的快照数 |
snaps_deleted |
Gauge | 上次重置以来传播到 Peer 的快照删除数 |
snaps_renamed |
Gauge | 上次重置以来传播到 Peer 的快照重命名数 |
这些计数器在镜像守护进程重启或目录被重新分配给另一镜像守护进程时重置,与 fs mirror peer status 一致。
13.3 Per-peer tick 线程
cephfs-mirror 守护进程处理的每个镜像 Peer 在其 PeerReplayer 中运行一个专用 tick 线程。该线程每 cephfs_mirror_tick_interval 秒(默认 5)唤醒一次,每次迭代都重新读取该配置项(因此配置变更无需重启守护进程即可生效),并运行周期性镜像工作。相关实现位于 src/tools/cephfs_mirror/PeerReplayer.cc(m_tick_thread 的创建与 tick() 逻辑)。
目前,tick 线程为守护进程上活跃注册同步的每个目录刷新 cephfs_mirror_directory perf counters 的 current_*、crawl_*、datasync_wait_* 与 dir_state 字段。
示例——为镜像守护进程用户将 tick 间隔设为 10 秒:
$ ceph config set client.mirror cephfs_mirror_tick_interval 10
十四、配置选项参考
以下为 cephfs-mirror 守护进程的完整配置项(定义见 src/common/options/cephfs-mirror.yaml.in),均为 advanced 级别:
| 配置项 | 默认值 | 说明 |
|---|---|---|
cephfs_mirror_max_concurrent_directory_syncs |
3 |
最大并发快照同步遍历(crawler)线程数。控制可同时被遍历的目录快照数。注意 crawler 线程还执行目录创建、文件删除、快照删除/重命名等条目操作(最小值 1) |
cephfs_mirror_max_datasync_threads |
6 |
CephFS 镜像数据同步线程池的最大工作线程数。这些线程处理 crawler 线程为镜像目录快照产生的文件同步任务(最小值 1) |
cephfs_mirror_distribute_datasync_threads |
true |
是否将数据同步线程均匀分配到多个快照。启用时工作线程在活跃快照间公平调度,防止单个大快照独占全部线程导致其他快照饥饿;禁用时 datasync 线程处理完一个快照再切换到另一个,可提升单个大快照的吞吐但可能增加其他排队快照的延迟。多目录镜像场景下建议启用 |
cephfs_mirror_datasync_files_per_batch |
64 |
数据同步线程在每个调度周期处理的最大文件数(达到后让出线程重新检查调度逻辑)。仅当 cephfs_mirror_distribute_datasync_threads 启用时生效。批次越小线程在快照间轮换越频繁,批次越大通过减少线程重分配开销提升吞吐(最小值 1) |
cephfs_mirror_blockdiff_min_file_size |
16_M |
文件大小阈值(字节):大于该值的文件在镜像时使用块级 diff(仅同步快照间修改的块区间),小于等于该值的文件执行全量文件复制(小文件块级 diff 收益不明显) |
cephfs_mirror_action_update_interval |
2 |
处理待处理镜像更新动作的间隔(秒)(最小值 1) |
cephfs_mirror_restart_mirror_on_blocklist_interval |
30 |
重启被 blocklist 的镜像实例的间隔(秒);设为 0 禁用(最小值 0) |
cephfs_mirror_max_snapshot_sync_per_cycle |
3 |
目录被工作线程选中镜像时,一个周期内镜像的快照数量上限(最小值 1) |
cephfs_mirror_directory_scan_interval |
10 |
扫描配置目录以镜像快照的间隔(秒)(最小值 1) |
cephfs_mirror_tick_interval |
5 |
per-peer tick 线程运行周期性镜像工作的间隔(秒)。每次迭代重新读取,配置变更无需重启即生效(最小值 1) |
cephfs_mirror_max_consecutive_failures_per_directory |
10 |
将目录标记为 failed 前的连续同步失败次数。失败目录以更低频率重试(最小值 0) |
cephfs_mirror_retry_failed_directories_interval |
60 |
失败目录的同步重试间隔(秒)(最小值 1) |
cephfs_mirror_restart_mirror_on_failure_interval |
20 |
重启失败镜像实例的间隔(秒);设为 0 禁用(最小值 0) |
cephfs_mirror_mount_timeout |
10 |
挂载主/次(远端)Ceph 文件系统的超时(秒)。集群不可达时更高的值可能导致镜像守护进程挂起;用于覆盖通常的 client_mount_timeout(最小值 0) |
cephfs_mirror_perf_stats_prio |
5 |
镜像守护进程复制 perf counters 的优先级。优先级不低于 mgr_stats_threshold 时守护进程向 Manager 发送 perf counter 数据(范围 0–11) |
此外,Manager mirroring 模块还有两个模块选项(定义于 src/pybind/mgr/mirroring/module.py,均为 runtime 可调):
# 是否缓存 fs snapshot mirror status 的 omap 指标(默认 true)
$ ceph config set mgr mgr/mirroring/snapshot_mirror_metrics_cache_enabled false
# 缓存 TTL:启用缓存后 Manager 缓存格式化响应的时长(默认 15 秒)
$ ceph config set mgr mgr/mirroring/snapshot_mirror_metrics_cache_ttl 15
十五、多线程快照同步
CephFS 镜像采用多线程架构提升同步性能。工作负载被拆分为两个独立的线程池:
- Crawler 线程池:负责快照遍历(crawl);
- 数据同步线程池:负责并发文件传输。
对应配置参数:
cephfs_mirror_max_concurrent_directory_syncs:控制可并发遍历的快照数;cephfs_mirror_max_datasync_threads:控制数据同步可用的线程总数。
将遍历与数据传输分离,即使有大型文件传输在进行,快照发现与进度报告也能继续推进。
十六、重新添加 Peer 的注意事项
将 Peer 重新添加(重新分配)到另一集群的文件系统时,请确保所有镜像守护进程已停止向该 Peer 同步。可通过 fs mirror status admin socket 命令检查(Peer UUID 不应再出现在命令输出中)。此外,建议在将 Peer 重新添加到另一个文件系统前,清除 Peer 上已同步的目录(尤其是新主文件系统中可能存在的那些目录)。如果 Peer 是重新添加到之前同步过的同一主文件系统,则无此要求。
十七、快照镜像检查点(Checkpoints)
CephFS 镜像支持检查点(Checkpoint),用于跟踪特定快照的复制状态。检查点允许你标记重要快照并监控它们是否已成功同步到远端站点,为灾难恢复就绪度提供可见性。
详细内容请参阅仓库中的 doc/cephfs/cephfs-mirroring-checkpoints.rst(检查点命令参考、生命周期与最佳实践)。要点如下:
- 核心概念:检查点是放置在快照上的标记,用于跟踪其复制状态。被检查点的快照(及其之前的所有快照)成功同步到远端文件系统后,检查点自动变为
complete; - 状态生命周期:
created(等待同步或同步中)→complete(已复制到远端)或failed(同步出错,将自动重试); - 关键特性:自动状态检测、跨守护进程重启持久化、按目录独立维护。
基本命令:
# 为快照添加检查点
$ ceph fs snapshot mirror checkpoint add <fs_name> <dir_path> <snap_name>
# 列出目录的所有检查点
$ ceph fs snapshot mirror checkpoint ls <fs_name> <dir_path>
# 移除检查点
$ ceph fs snapshot mirror checkpoint remove <fs_name> <dir_path> <snap_name>
# 在最新快照上创建检查点
$ ceph fs snapshot mirror checkpoint now <fs_name> <dir_path>
典型工作流:
# 1. 在镜像目录中创建快照
mkdir /mnt/cephfs/data/.snap/daily_backup_2026_06_01
# 2. 标记重要快照为检查点
ceph fs snapshot mirror checkpoint add myfs /data daily_backup_2026_06_01
# 3. 监控检查点状态
ceph fs snapshot mirror checkpoint ls myfs /data --format json-pretty
输出示例:
{
"dir_root": "/data",
"checkpoints": [
{
"snap_id": 100,
"snap_name": "daily_backup_2026_06_01",
"status": "complete",
"created_at": "2026-06-01T23:00:00.000000+0000",
"updated_at": "2026-06-01T23:15:00.000000+0000"
},
{
"snap_id": 102,
"snap_name": "daily_backup_2026_06_03",
"status": "created",
"created_at": "2026-06-03T23:00:00.000000+0000",
"updated_at": "2026-06-03T23:00:00.000000+0000"
}
]
}
重要注意事项:
- 删除带检查点的快照会使检查点元数据永久丢失:同步完成前删除,检查点永远不会到达
complete;同步完成后删除,数据已复制但检查点历史丢失。最佳实践是在删除快照前用checkpoint ls确认其已到达complete; - 检查点跨快照重命名存活,但命令必须使用新名称:
checkpoint ls会显示新名称,checkpoint remove使用旧名称会报 "snapshot not found"; - 检查点的添加、状态更新与失败标记在 src/tools/cephfs_mirror/PeerReplayer.cc 中实现(
checkpoint_sync_complete、checkpoint_sync_failed、initialize_checkpoints等),快照同步成功/失败时自动更新对应检查点状态。
十八、总结:一套完整的 DR 数据保护方案
CephFS 快照镜像通过 cephfs-mirror 守护进程 + Manager mirroring 模块的组合,提供了一套异步、推送式、目录级快照复制方案:
- 部署:主集群创建
client.mirror用户,远端集群创建client.mirror_remote(rwps)用户;通过 systemd 或 cephadm 部署守护进程;启用 mgr mirroring 模块; - 配置:
fs snapshot mirror enable启用文件系统镜像,通过peer_bootstrap create/import(推荐)或peer_add配置 Peer,再用fs snapshot mirror add添加镜像目录; - 触发:在镜像目录的
.snap下创建快照即自动开始复制; - 监控:
daemon status查看守护进程与 Peer 健康,fs snapshot mirror status查看每目录同步进度(omap 持久化、支持 stale 检测),admin socket 用于单机调试,perf counters 接入 Prometheus/ceph-exporter做长期监控与告警; - 调优:通过 crawler/数据同步双线程池参数、tick 间隔、失败重试策略与块级 diff 阈值等配置项平衡吞吐与延迟;
- 保障:检查点功能为关键快照提供复制状态追踪,为合规审计、SLA 验证与容灾演练提供依据。
遵循"将远端文件系统视为只读"、不在远端配置 snap-schedule、谨慎管理快照生命周期(避免删除带活跃检查点的快照)等最佳实践,即可构建稳定可靠的跨集群 CephFS 快照容灾链路。