CephFS 日志急救指南:cephfs-journal-tool 全面剖析与实战

原创2026-09-20 21:52:271,918 阅读
文章标签:分布式文件系统对象存储存储云原生集群管理高可用指标监控可观测性

CephFS 日志急救指南:cephfs-journal-tool 全面剖析与实战

当 CephFS 的元数据日志(mdlog)因异常断电、对象丢失或人为误操作而损坏时,文件系统可能无法正常挂载或启动。cephfs-journal-tool 正是 Ceph 为这类场景提供的专家级离线诊断与修复工具:它允许管理员在文件系统非活跃状态下检查日志健康度、备份与回灌日志、修改日志头指针、检索或清除日志事件,甚至从日志中恢复目录项(dentry)。读完本文,你将掌握 cephfs-journal-tool 的三种操作模式(journal、header、event)、全部子命令与过滤器的用法,并理解其背后基于 JournalScanner、Dumper、Resetter 等组件的实现原理。

⚠️ 使用前务必阅读:该工具会直接修改文件系统的内部数据结构(RADOS 中的日志对象与元数据对象)。请在操作前做好备份、逐条核对命令,并在不确定时寻求专家意见。作为额外保护,cephfs-journal-tool 无法在活跃(active)文件系统上运行——源码 src/tools/cephfs/JournalTool.cc 会检查对应 rank 是否处于 active 状态并直接返回 -EPERM。

语法总览:三种操作模式

工具整体语法如下(摘自 doc/cephfs/cephfs-journal-tool.rst 与工具自带 usage,见 src/tools/cephfs/JournalTool.cc):

cephfs-journal-tool [options] journal <inspect|import|export|reset>
cephfs-journal-tool [options] header <get|set> <trimmed_pos|expire_pos|write_pos|pool_id> <value>
cephfs-journal-tool [options] header recover [--force]
cephfs-journal-tool [options] event <get|splice|recover_dentries> [filter] <list|json|summary|binary>

三种模式分别作用于三个不同粒度的对象:

  • journal 模式:整个日志(journal),用于健康检查、整体备份与重置;
  • header 模式:日志头(header),用于查看与修正头指针字段;
  • event 模式:日志内部的事件(event),用于细粒度查看、筛选、删除与数据恢复。

在执行流程上,工具通过 JournalTool::main() 依次解析 --rank(必填)与 --journal(默认 mdlog)参数,建立与 RADOS 的连接后,将剩余参数分派到 main_journal / main_header / main_event 三个处理函数。--rank 支持 filesystem:{mds-rank|all} 形式,指定 all 时工具会对所有 rank 逐一执行(journal import 除外,见 can_execute_for_all_ranks,src/tools/cephfs/JournalTool.cc)。

Journal 模式:从整体评估日志健康

journal 模式是诊断工作的起点,用于评估整个日志的状态。

  • inspect:报告日志健康度,识别缺失的对象(missing objects)与损坏区域(corrupt regions)。需要注意:它只能确认“事件存在且可解码”,无法识别事件内部的不一致。
  • export <file> / import <file>:以稀疏文件(sparse file)格式读写日志的二进制转储。import 会校验导入日志的 FSID 与在线集群 FSID 是否一致,--force 可跳过该校验;export 对损坏日志(缺失对象)可能不可靠。
  • reset:截断日志,丢弃其中所有信息。--force 表示直接硬重置(hard reset),不再尝试从磁盘恢复。源码中 reset 命令还强制要求追加 --yes-i-really-really-mean-it 参数才会真正执行(见 JournalTool::main_journal),这是第二重保护。

示例:journal inspect

# cephfs-journal-tool journal inspect
Overall journal integrity: DAMAGED
Objects missing:
  0x1
Corrupt regions:
  0x400000-ffffffffffffffff

上述输出表示日志对象 0x1 缺失,且 0x400000 之后的区域无法解码。inspect 的实现位于 JournalTool::journal_inspect(),它创建 JournalScanner 扫描对象并调用 js.report() 输出报告。

示例:journal export / import

# cephfs-journal-tool journal export myjournal.bin
journal is 4194304~80643
read 80643 bytes at offset 4194304
wrote 80643 bytes at offset 4194304 to myjournal.bin
NOTE: this is a _sparse_ file; you can
    $ tar cSzf myjournal.bin.tgz myjournal.bin
      to efficiently compress it while preserving sparseness.

# cephfs-journal-tool journal import myjournal.bin
undump myjournal.bin
start 4194304 len 80643
writing header 200.00000000
 writing 4194304~80643
done.

💡 最佳实践:在任何进一步操作之前,先执行 journal export <backup file> 备份日志。借助稀疏文件特性,可用 tar cSzf 压缩备份而保持稀疏性。

export 会先扫描日志并确认头部有效、无对象缺失(js.is_readable()),否则建议改用 rados CLI 逐个对象导出(见 JournalTool::journal_export())。

源码视角:reset 做了什么

journal reset 通过 Resetter 组件完成:硬重置(--force)直接调用 resetter.reset_hard(),普通重置则调用 resetter.reset()(JournalTool::journal_reset())。与“清空”的直觉不同,reset 实际上是截断日志并插入一条 EResetJournal 事件,保证后续 MDS 重放(replay)时知道日志边界已被重置。

Header 模式:查看与修复日志头指针

日志头(journal header)记录了一组关键指针,CephFS 依靠它们定位日志的读写位置。header 模式提供三种操作:

  • get:输出当前日志头的全部内容(JSON 格式)。
  • set <field> <value>:修改头字段。允许的字段为 trimmed_pos、expire_pos、write_pos 和 pool_id。从源码看,字段被直接映射到 Journaler::Header 的成员:trimmed_pos、expire_pos、write_pos 直接写入,而 pool_id 写入 layout.pool_id(见 JournalTool::main_header())。
  • recover:恢复 mdlog 中损坏的日志指针。它枚举日志事件并计算安全回退偏移:
    • trimmed_pos:设置为日志段中发现的第一个事件的位置;
    • expire_pos:设置为第一个 major segment 事件的位置;
    • read_pos:设置为第一个 major segment 事件的位置;
    • write_pos:设置为最后一个有效事件之后紧邻的位置。

示例:header get / set / recover

# cephfs-journal-tool header get
{ "magic": "ceph fs volume v011",
  "write_pos": 4274947,
  "expire_pos": 4194304,
  "trimmed_pos": 4194303,
  "stream_format": 1,
  "layout": { "stripe_unit": 4194304,
      "stripe_count": 1,
      "object_size": 4194304,
      "pool_id": 2,
      "pool_ns": ""}}

# cephfs-journal-tool header set trimmed_pos 4194303
Updating trimmed_pos 0x400000 -> 0x3fffff
Successfully updated header.

# cephfs-journal-tool --rank a:0 header recover
Proposed Journal Header Updates:
  trimmed_pos: 0x400000 -> 0x400000
  expire_pos:  0x415f74 -> 0x415f74
  read_pos:    0x415f74 -> 0x415f74
  write_pos:   0x41576c -> 0x41676c
  Target event type at proposed read_pos: EVENT_SUBTREEMAP
Dry-run mode enabled. Header modifications skipped.

# cephfs-journal-tool --rank a:0 header recover --force
Proposed Journal Header Updates:
  trimmed_pos: 0x400000 -> 0x400000
  expire_pos:  0x415f74 -> 0x415f74
  read_pos:    0x415f74 -> 0x415f74
  write_pos:   0x41576c -> 0x41676c
  Target event type at proposed read_pos: EVENT_SUBTREEMAP
Successfully recovered journal header.

注意 header get 中 magic 字段 "ceph fs volume v011" 是日志格式标识;layout 中 object_size 为 4MB(4194304),这也是日志对象的分段大小。

header recover 的适用边界与执行逻辑

从文档与源码可以归纳出 header recover 的三个关键约束:

  1. 信任前提:它假定日志起始指针(expire_pos)是合理的,并以此锚点确定扫描起点,再重新计算其余边界指针。因此,管理员在运行前应手动检查日志头,确认该指针在逻辑上说得通。
  2. 灾难场景不适用:当头对象完全丢失、或起始指针已不可修复地损坏时,本命令无法恢复未提交的元数据。
  3. 硬性要求:命令要求日志头存在且 magic 合法。若头缺失或完全无法识别(magic 不匹配 CEPH_FS_ONDISK_MAGIC),工具会直接中止。

实现上,JournalTool::recover_header() 通过流式扫描回调遍历全部日志事件,记录第一个事件位置、最后一个事件位置及其原始长度,并寻找最早出现的 major segment 边界事件(EVENT_SUBTREEMAP、EVENT_SUBTREEMAP_TEST、EVENT_LID、EVENT_RESETJOURNAL 之一)。扫描过程中若发现偏移不连续(gap),会打印 warning 并跳过继续。最终:

  • 默认(不带 --force)为 dry run:只把 "Proposed Journal Header Updates" 打印到控制台,不落盘;
  • 仅当显式传入 --force 时,才将更新后的头对象写回 RADOS(output.write_full(js.obj_name(0), header_bl))。

Event 模式:细粒度检索与数据恢复

Event 模式允许对日志内容进行详细检查与操作,可作用于日志中的全部事件,也可通过过滤器缩小范围:

cephfs-journal-tool event <action> [filter] <output>

动作(Actions)

  • get:从日志中读取事件;
  • splice:擦除日志中的事件或区域(用 ENoOp 事件填充覆盖,见 JournalTool::erase_region());
  • recover_dentries:从日志中恢复目录项。它执行一种选择性的离线重放:只读取日志中的 dentry,并且仅当其版本号大于底层存储(backing store)中的当前版本时才写回。源码 JournalTool::recover_dentries() 展示了完整的版本比较逻辑:对 fullbit / remotebit 逐项对比 fb.inode->version 与底层存储版本;对硬链接位(L/l)则退化为比较所在 dirfrag 的 fnode 版本;必要时还会重建缺失的 dirfrag 对象、创建缺失的 root inode,并在恢复完成后通过 consume_inos() 更新各 MDS 的 InoTable,防止已用 inode 号被再次分配。

过滤器(Filters)

过滤器可组合使用,语义为 AND(取各过滤器命中事件的交集):

过滤器 含义
--range <int begin>..[int end] 只包含 begin(含)到 end(不含)范围内的事件
--path <path substring> 只包含元数据路径中含指定字符串的事件
--inode <int> 只包含元数据中含指定 inode 的事件
--type <type string> 只包含指定类型的事件
--frag <ino>[.frag id] 只包含涉及该目录分片(directory fragment)的事件
--dname <string> 只包含目录分片内指定名称的 dentry 事件(必须与 --frag 联用)
--client <int> 只包含来自指定客户端会话 ID 的事件
--max-rss <bytes> (目前仅 recover_dentries 支持)按批次扫描并冲刷日志事件,限制工具的 RSS

其中 --max-rss 的实现细节值得关注:源码在 JournalTool::main_event() 中将用户指定的字节数除以 3(因为“一个解码后的事件约占其编码流的 3 倍”),得到批次大小,随后通过回调在累积到 EVENT_SUBTREEMAP / EVENT_SUBTREEMAP_TEST 事件且字节数达标时触发批量冲刷(flush),从而把峰值内存控制在设定范围内。

输出模式(Output modes)

  • binary:将每个事件写为独立的二进制文件,放在由 --path 指定的目录中(文件命名形如 0x<offset>_<TYPE>.bin,见 EventOutput::binary());
  • json:把所有事件作为一个 JSON 序列化的对象列表,写入 --path 指定的单个文件(EventOutput::json());
  • summary:在 stdout 输出人类可读的事件汇总(按类型统计计数);
  • list:在 stdout 输出每种事件的类型及受影响的文件路径的简明清单。

示例:event 模式

# cephfs-journal-tool event get json --path output.json
Wrote output to JSON file 'output.json'

# cephfs-journal-tool event get summary
Events by type:
  NOOP: 2
  OPEN: 2
  SESSION: 2
  SUBTREEMAP: 1
  UPDATE: 43

# cephfs-journal-tool event get list
0x400000 SUBTREEMAP:  ()
0x400308 SESSION:  ()
0x4003de UPDATE:  (setattr)
  /
0x40068b UPDATE:  (mkdir)
  diralpha
0x400d1b UPDATE:  (mkdir)
  diralpha/filealpha1
0x401666 UPDATE:  (unlink_local)
  stray0/10000000001
  diralpha/filealpha1
0x40228d UPDATE:  (unlink_local)
  diralpha
  stray0/10000000000
0x402bf9 UPDATE:  (scatter_writebehind)
  stray0
0x403150 UPDATE:  (mkdir)
  dirbravo
0x4037e0 UPDATE:  (openc)
  dirbravo/.filebravo1.swp
0x404032 UPDATE:  (openc)
  dirbravo/.filebravo1.swpx

# cephfs-journal-tool event get --path filebravo1 list
0x40785a UPDATE:  (openc)
  dirbravo/filebravo1
0x4103ee UPDATE:  (cap update)
  dirbravo/filebravo1

# cephfs-journal-tool event splice --range 0x40f754..0x410bf1 summary
Events by type:
  OPEN: 1
  UPDATE: 2

# cephfs-journal-tool event recover_dentries summary
Events by type:
  LID: 1
  SUBTREEMAP: 1
Errors: 0

# cephfs-journal-tool event get --inode=1099511627776 list
0x40068b UPDATE:  (mkdir)
  diralpha
0x400d1b UPDATE:  (mkdir)
  diralpha/filealpha1
0x401666 UPDATE:  (unlink_local)
  stray0/10000000001
  diralpha/filealpha1
0x40228d UPDATE:  (unlink_local)
  diralpha
  stray0/10000000000

# cephfs-journal-tool event get --frag=1099511627776 --dname=filealpha1 list
0x400d1b UPDATE:  (mkdir)
  diralpha/filealpha1
0x401666 UPDATE:  (unlink_local)
  stray0/10000000001
  diralpha/filealpha1

# cephfs-journal-tool event get binary --path bin_events
Wrote output to binary files in directory 'bin_events'

从 list 输出可以看到 list 模式会同时打印事件偏移(如 0x4003de)、事件类型(如 UPDATE)、子操作(如 mkdir、unlink_local、openc)以及受影响的路径,其中路径前的偏移与 --range 过滤器使用的偏移是同一套坐标,便于交叉定位。

补充说明:recover_dentries 支持 --dry_run 参数(仅 mdlog 类型可用,见 JournalTool::main_event()),用于在不写 RADOS 的前提下预演恢复过程。若恢复目标元数据池与当前文件系统池不同,还可使用 --alternate-pool <name> 指定备选元数据池(JournalTool::main_event())。

通用选项与特殊选项

选项 说明
--rank=<filesystem>:{mds-rank|all} 指定文件系统、MDS rank 或全部 rank(必填)
--journal=<mdlog|purge_queue> 日志类型,默认 mdlog;只有 mdlog 支持 event 模式。使用 purge_queue 时,日志扫描器会创建 PurgeItem 对象并加入 EventMap 处理
--alternate-pool <name> 使用 recover_dentries 时指向备选元数据池
--max-rss <bytes> recover_dentries 事件恢复时每批允许的最大 RSS

关于 purge_queue:JournalScanner::set_journal_ino()(src/tools/cephfs/JournalScanner.cc)会根据类型解析日志 inode——purge_queue 对应 MDS_INO_PURGE_QUEUE + rank,而 mdlog 则需先读取日志指针对象(MDS_INO_LOG_POINTER_OFFSET + rank)来定位实际日志头(JournalScanner::scan_pointer())。这解释了为什么 mdlog 扫描失败时常见报错是 "Pointer ... is absent / unreadable / corrupt"。

实战建议与验证

  1. 先备份,再动手:任何修改前先 cephfs-journal-tool journal export <file>;reset 前务必确认 --yes-i-really-really-mean-it 的含义。
  2. 诊断顺序:journal inspect 评估整体健康 → header get 人工核对指针合理性 → 视情况 header recover(先 dry run 看提案,再 --force 落盘)→ 需要细粒度操作时再进入 event 模式。
  3. 测试验证:仓库自带冒烟测试 qa/workunits/suites/cephfs_journal_tool_smoke.sh 覆盖了 export/import 往返一致性、journal reset、header set、event get summary/json/binary、event recover_dentries、event splice 以及 header recover(dry-run 与 --force)的完整链路,可作为理解工具行为的参考范例。测试脚本还揭示了一个关键运维细节:recover_dentries 会修改元数据对象(尤其是 InoTable),导致日志与元数据不再一致,因此测试在恢复目录项后执行 journal reset 与 cephfs-table-tool all reset session 使集群回到一致状态——真实故障恢复时也应参考这一顺序。
  4. 保持只读心态:header set、event splice、journal reset 都是破坏性操作,务必先在测试集群上演练;对不确定的场景优先使用 dry-run 类路径(如 header recover 默认行为、event recover_dentries --dry_run)。

相关源码路径速查

登录后查看全文
ceph