FoundationDB 磁盘快照备份与恢复Disk Snapshot Backup Restore完整实战指南【免费下载链接】foundationdbFoundationDB - the open source, distributed, transactional key-value store项目地址: https://gitcode.com/gh_mirrors/fo/foundationdb导读本文基于 FoundationDB 官方文档 disk-snapshot-backup.rst 展开系统讲解 FoundationDB 基于磁盘快照disk snapshot的备份与恢复方案它利用底层文件系统/磁盘的崩溃一致性crash-consistent快照能力在零停机的前提下获得数据库在某一时间点的完整一致性副本。读完本文你将掌握snapshot隐藏命令的完整用法、snapshot create binary的编写规范、白名单安全机制、9 个快照错误码的含义以及从备份到恢复的端到端操作流程并了解该功能在 fdbcli、Commit Proxy、Data Distributor 与 fdbserver 各层级的源码级实现原理。背景磁盘快照备份解决什么问题FoundationDB 的磁盘快照备份工具Disk Snapshot Backup会在不中断服务的情况下对所有持有持久化数据的磁盘存储disk store执行崩溃一致性快照从而获得数据库的一个**一致性、时间点级point-in-time**备份。其前置条件是运行 FoundationDB 的文件系统或磁盘必须支持崩溃一致性快照能力如云厂商的卷快照、存储一致性组、文件系统级快照等。工具本身只负责编排所有磁盘镜像的快照动作并确保它们能够恢复到一个一致的时间点恢复时通过把快照镜像复制或挂载回 FoundationDB 计算实例完成整个过程等同于集群被断电后重新启动。该方案通常用于测试与开发环境的数据准备合规性compliance要求的数据留存在硬件或软件故障场景下提供额外一层的保护。fdbbackup 与磁盘快照备份的对比FoundationDB 既有的 backups.rst 所描述的fdbbackup功能与磁盘快照备份都能提供时间点一致备份但二者工作在不同层级在性能、特性与外部依赖上差异明显维度fdbbackupKV 级备份磁盘快照备份工作层级key-value 层磁盘层备份方式从源集群复制全部键值对对所有持久化磁盘做崩溃一致性快照恢复方式将键值对回放到目标数据库复制/挂载磁盘镜像到新集群性能取决于数据量与读写吞吐通常很高数据不经过 FoundationDB 栈读写外部依赖无不要求磁盘系统具备快照能力依赖文件系统/磁盘的快照与恢复能力持续备份支持可灵活选择恢复点不支持持续备份在磁盘快照与恢复性能很高的环境中例如云厂商的卷快照磁盘快照方案可以非常快并且可以用高频率的备份来替代持续备份。注意本文中所有提到fdbbackup的地方均指 KV 级备份功能不要与磁盘快照备份混淆。功能限制使用磁盘快照备份前需要明确以下限制不支持持续备份continuous backup因此恢复时无法指定恢复版本不支持 Windows 操作系统数据加密依赖于磁盘系统磁盘层加密而非 FoundationDB 自身备份与恢复涉及的工具链需要运维人员按自身部署与环境自行开发当前版本中snapshot命令是fdbcli 隐藏命令计划在未来的补丁版本中解除隐藏。磁盘快照备份的实现原理源码视角在动手操作前先理解snapshot命令在集群内部的完整调用链这有助于排查问题。从源码可以还原出以下流程fdbcli 侧fdbcli/SnapshotCommand.cpp中的snapshotCommandActor生成一个随机 UIDdeterministicRandom()-randomUniqueID()并把用户输入的命令字符串拼装后调用数据库客户端的createSnapshot(uid, snap_cmd)接口命令工厂CommandFactory snapshotFactory(snapshot)注册该命令注释明确标注其为hidden commands, no help text for now。客户端 API 侧fdbclient/NativeAPI.cpp的createSnapshotActor与DatabaseContext::createSnapshot将快照请求发往集群。Commit Proxy 侧fdbserver/commitproxy/CommitProxyServer.cpp的proxySnapCreate是核心校验节点依次执行白名单校验解析快照命令的二进制路径调用isWhitelisted(commitData-whitelistedBinPathVec, binPath)检查不通过则抛出snap_path_not_whitelisted2505恢复状态校验若集群recoveryState ! RecoveryState::FULLY_RECOVERED抛出snap_not_fully_recovered_unsupported2506因为旧代 TLog 的持久化数据无法被快照覆盖log anti quorum 校验从事务状态存储读取log_anti_quorum配置大于 0 时抛出snap_log_anti_quorum_unsupported2507通过后将DistributorSnapRequest转发给 Data Distributor网络失败时按SNAP_NETWORK_FAILURE_RETRY_LIMIT指数退避重试。Data Distributor 侧fdbserver/datadistributor/DataDistribution.cpp的ddSnapCreate先通过trySetSnapshot临时禁用数据分布DD然后用race(dbInfoChange, ddSnapCreateCore(...), delay(SNAP_CREATE_MAX_TIMEOUT))执行快照若期间发生集群恢复dbInfo 变化则返回snap_with_recovery_unsupported2508若超时则返回timed_out执行完成后重新trySetEnabled恢复 DD。fdbserver 侧fdbserver/kvstore/FDBExecHelper.cpp的execHelperImpl真正生成子进程调用用户提供的snapshot create binary并自动追加--path、--tlog-spill-path可选、--version、--role、--uid等参数子进程运行时长由SNAP_CREATE_MAX_TIMEOUT约束ServerKnobs.cpp 中定义模拟环境默认 70 秒生产环境默认 300 秒。所有角色级快照错误码统一在 flow/include/flow/error_definitions.h 的 2500 段定义详见下文错误码表。备份前的准备工作在fdbserver上执行snapshot命令前需要完成以下配置编写snapshot create binary程序当被fdbserver调用时该程序负责对本地磁盘存储执行快照。它会被传入以下参数参数说明UID32 字节字母数字唯一标识符集群中所有节点收到的是同一个 UID用于标识本次备份关联的一组磁盘快照VersionFoundationDB 二进制的版本字符串Path需要被快照的 FoundationDBdatadir路径datadir配置见 configuration.rstTLog spill path可选参数以--tlog-spill-path传入当tlog角色单独配置了tlog-spill-datadir与datadir分离时提供Roletlog/storage/coordinator标识快照被调用的节点角色关于datadir与tlog-spill-datadir的语义可参考 configuration.rstdatadir是存放持久化数据文件的可写目录tlog-spill-datadir是可选的、用于存放事务日志溢出spill数据的独立目录未设置时溢出数据同样落在datadir。安装snapshot create binary安装在 FoundationDB 实例上的安全路径且必须能够被运行fdbserver的用户执行。配置白名单在 configuration.rst 的[fdbserver]配置段中新增配置项whitelist_binpath值为snapshot create binary的绝对路径。任何snapshot命令都会校验其二进制路径是否在白名单内这是一道安全机制防止客户端通过snapshot命令在集群上执行任意/不安全命令。示例whitelist_binpath /bin/snap_create.sh从源码看该配置在fdbserver启动时经 fdbserver.cpp 的--whitelist-binpath命令行选项解析OPT_WHITELIST_BINPATH最终由 Worker 传递给 Commit Proxy 并构建whitelistedBinPathVec白名单向量见 ProxyCommitData.h。收集额外的恢复元数据snapshot create binary应捕获恢复集群所需的任何附加数据例如将附加数据以标签tags形式存储在云环境中或存放在datadir内的附加文件/目录中一并快照。推荐收集的清单见下文备份规范一节。双路径一致性要求当传入--tlog-spill-path时snapshot create binary必须在返回成功前对--path与--tlog-spill-path两块磁盘协调地执行崩溃一致性快照——例如使用存储一致性组、共享卷组或先 quiesce/freeze 两个文件系统再逐卷创建快照确保两个路径恢复到同一个崩溃点。返回值约定程序任何失败都必须返回非零状态码成功返回 0。超时限制若snapshot create binary进程超过5 分钟未返回状态它会被杀死snapshot命令随即失败。该超时可通过 configuration.rst 中的SNAP_CREATE_MAX_TIMEOUT配置参数调整——源码默认值为生产环境 300 秒ServerKnobs.cpp默认值足够大通常无需修改。使用 snapshot 命令创建备份snapshot是 fdbcli 中的同步命令用法如下fdb snapshot /bin/snap_create.sh --param1 param1-value --param2 param2-value Snapshot command succeeded with UID c50263df28be44ebb596f5c2a849adbb命令接收一个snapshot create binary的完整路径返回执行状态可选地携带透传给该 binary 的附加参数。命令会返回一个唯一标识符UID用于标识一次备份的全部磁盘快照即使在失败的情况下也会返回 UID以便运维人员据此识别并清理部分创建的磁盘快照。以上述命令为例snapshot create binary会在tlog角色上以如下参数被调用--param1 param1-value --param2 param2-value --path /mnt/circus/data/4502 --version 6.2.6 --role tlog --uid c50263df28be44ebb596f5c2a849adbb关于同步性与耗时当snapshot成功返回时备份即视为完成且可恢复。完成一次备份的耗时取决于磁盘快照本身所需时间。例如若磁盘快照耗时 1 秒则整个备份应在 10 秒内完成此为一般性指导个别场景可能更长。如果命令被用户中止磁盘快照不得用于恢复因为备份状态未定义。命令失败或中止后运维人员可以重新发起一次snapshot命令重试。磁盘快照备份规范Specification下表列出了snapshot create binary应当收集的、有助于恢复的工件清单字段名 / 描述 / 信息来源字段名描述信息来源UID与某次备份所有snapshot create binary调用一同传入的唯一标识符磁盘快照可用该 UID 打标签snapshotCLI 命令输出中包含该 UIDFoundationDB Server Versionfdbserver的软件版本snapshot create binary的命令行参数CreationTime当前系统日期与时间调用系统时间获取FoundationDB Cluster File集群文件cluster file包含 cluster-name、magic 与协调者列表是集群的核心标识文件从集群文件所在位置读取fdbserver的命令行参数可通过/proc/$PPID/cmdline访问Config Knobs传给fdbserver的命令行参数来自fdbserver命令行参数或 foundationdb.confIP Address Port发起快照的fdbserver主机地址与端口信息来自fdbserver命令行参数LocalityDatamachine id、zone id 或其他 locality 信息来自fdbserver命令行参数Name for the snapshot file推荐的磁盘快照命名cluster-name:ip-addr:port:UID重要snapshot create binary不会在无持久化数据的进程上被调用例如 Cluster Controller、Master、CommitProxy。这些进程是无状态的无需快照但它们使用的任何特殊配置 knobs 需要由运维人员外部复制并在恢复后手工还原。磁盘快照的管理未使用的磁盘快照、或属于失败备份的磁盘快照需要由运维人员在外部自行删除例如清理云环境中的卷快照或备份目录FoundationDB 本身不负责快照的生命周期管理。错误码对照表snapshot命令可能返回以下错误码源码定义见 flow/include/flow/error_definitions.h名称代码描述处理建议snap_path_not_whitelisted2505快照创建二进制路径未加入白名单将snap create binary路径加入白名单后重试snap_not_fully_recovered_unsupported2506集群未完全恢复时不支持快照等待集群完成恢复后重试snap_log_anti_quorum_unsupported2507配置了 log anti quorum 时不支持该功能不支持 log anti quorum 配置snap_with_recovery_unsupported2508快照操作期间发生集群恢复快照进行中发生了恢复请重试snap_storage_failed2501快照 storage 节点失败确认snap create binary已安装且可被运行fdbserver的用户执行snap_tlog_failed2502快照 TLog 节点失败同上snap_coord_failed2503快照 coordinator 节点失败同上unknown_error4000发生未知错误同上snap_disable_tlog_pop_failed2500磁盘快照错误禁用 TLog pop 失败无需运维操作重试即可snap_enable_tlog_pop_failed2504磁盘快照错误恢复 TLog pop 失败无需运维操作重试即可磁盘快照恢复步骤恢复就是从快照的磁盘镜像中重新构建出集群。由于不支持持续备份没有选项可以指定恢复版本。恢复流程如下定位快照镜像借助 UID 或创建时间CreationTime识别与待恢复备份关联的磁盘快照镜像按主机归类按 IP 地址和/或 locality 信息将一次备份的磁盘镜像分组搭建新集群并挂载镜像搭建一个与源集群结构相似的新集群保持 FoundationDB 服务处于停止状态然后将快照磁盘镜像挂载或复制到集群中方式如下将旧 IP 地址与新 IP 地址一一映射用该映射指导磁盘镜像的恢复放置生成新集群文件根据新协调者coordinators磁盘存储的放置位置计算新的 fdb.cluster 文件并推送到新集群的所有实例启动服务在所有实例上启动 FoundationDB 服务注意多角色共享 datadir 的情况一个进程可能以多个带持久化数据的角色共享同一个datadir。此时snapshot create binary会为每个角色各创建一份快照。恢复前这些快照镜像需要额外处理如果某个角色的快照镜像中包含属于其他角色的文件必须将这些文件删除。集群启动并进入健康状态即表示恢复完成应用可以可选地做额外校验后开始使用集群。端到端示例单节点集群的备份与恢复以下示例在一个极度简化的单节点集群上用cp命令模拟快照创建与恢复仅用于演示真实环境的备份/恢复脚本必须遵循前文所述的全部步骤。第一步搭建单节点集群并写入数据按照项目文档搭建单节点集群后检查集群状态并写入示例键值fdb status Using cluster file /mnt/source/fdb.cluster. Configuration: Redundancy mode - single Storage engine - ssd-2 Coordinators - 1 Cluster: FoundationDB processes - 1 Zones - 1 Machines - 1 Memory availability - 30.6 GB per process on machine with least available Fault Tolerance - 0 machines Server time - 12/11/19 04:02:57 Data: Replication health - Healthy Moving data - 0.000 GB Sum of key-value sizes - 0 MB Disk space used - 210 MB Operating space: Storage server - 72.6 GB free on most full server Log server - 72.6 GB free on most full server Workload: Read rate - 9 Hz Write rate - 0 Hz Transactions started - 5 Hz Transactions committed - 0 Hz Conflict rate - 0 Hz Backup and DR: Running backups - 0 Running DRs - 0 Client time: 12/11/19 04:02:57 fdb writemode on fdb set key1 value1 Committed (76339236) fdb set key2 value2 Committed (80235963)第二步编写 snap create binary编写一个把datadir复制到用户指定目标目录的脚本#!/bin/sh while (( $# )); do case $1 in --uid) SNAPUID$2 shift 2 ;; --path) DATADIR$2 shift 2 ;; --role) ROLE$2 shift 2 ;; --destdir) DESTDIR$2 shift 2 ;; *) shift ;; esac done mkdir -p $DESTDIR/$SNAPUID/$ROLE || exit 1 cp $DATADIR/* $DESTDIR/$SNAPUID/$ROLE/ || exit 1 exit 0第三步安装脚本并配置白名单将脚本安装为/bin/snap_create.sh在 configuration.rst 的[fdbserver]段添加whitelist_binpath /bin/snap_create.sh然后停止并重启 foundationdb 服务使配置生效。第四步发起快照fdb snapshot /bin/snap_create.sh --destdir /mnt/backup Snapshot command succeeded with UID 69a5e0576621892f85f55b4ebfeb4312snapshot create binary会按角色分别调用一次本进程中依次为tlog、storage、coordinator参数如下--path /mnt/source/datadir --version 6.2.6 --role storage --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup --path /mnt/source/datadir --version 6.2.6 --role tlog --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup --path /mnt/source/datadir --version 6.2.6 --role coord --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup快照成功后所有镜像都在destdir中。以下是 coordinator 备份目录的示例文件列表$ ls /mnt/backup/69a5e0576621892f85f55b4ebfeb4312/coord/ coordination-0.fdq log2-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792.sqlite-wal processId coordination-1.fdq logqueue-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792-0.fdq storage-f0e72cdfed12a233e0e58291150ca597.sqlite log2-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792.sqlite logqueue-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792-1.fdq storage-f0e72cdfed12a233e0e58291150ca597.sqlite-wal第五步恢复恢复coordinator镜像准备恢复用的datadir并把所有 coordinator 相关文件复制进去$ cp /mnt/backup/69a5e0576621892f85f55b4ebfeb4312/coord/coord* /mnt/restore/datadir/对storage与tlog镜像重复上述步骤。随后为恢复准备新的fdb.cluster将协调者 IP 替换为新的地址例如znC1NC5b:iYHJLq7z10.2.80.40:4500 - znC1NC5b:iYHJLq7z10.2.80.41:4500本示例中foundationdb.conf可与源集群完全一致。所有镜像恢复完成后以指向/mnt/restore/datadir的datadir和新的fdb.cluster启动新的 fdbserver。第六步验证恢复结果fdb status Using cluster file /mnt/restore/fdb.cluster. Configuration: Redundancy mode - single Storage engine - ssd-2 Coordinators - 1 Cluster: FoundationDB processes - 1 Zones - 1 Machines - 1 Memory availability - 30.5 GB per process on machine with least available Fault Tolerance - 0 machines Server time - 12/11/19 09:04:53 Data: Replication health - Healthy Moving data - 0.000 GB Sum of key-value sizes - 0 MB Disk space used - 210 MB Operating space: Storage server - 72.5 GB free on most full server Log server - 72.5 GB free on most full server Workload: Read rate - 7 Hz Write rate - 0 Hz Transactions started - 3 Hz Transactions committed - 0 Hz Conflict rate - 0 Hz Backup and DR: Running backups - 0 Running DRs - 0 Client time: 12/11/19 09:04:53 fdb get key1 key1 is value1 fdb get key2 key2 is value2集群健康、示例键值完整说明备份与恢复流程成功。仓库中的测试与验证依据如果想深入了解该功能的正确性保障可研读 fdbserver/workloads/SnapTest.cpp这是一个专门针对磁盘快照的仿真工作负载覆盖了以下场景testID 0快照前写入偶数序号键snapKey*testID 1调用/bin/snap_create.sh创建快照并支持重复快照请求attemptDuplicateSnapshot测试预期首个请求以duplicate_snapshot_request失败失败时按SNAP_MINIMUM_TIME_GAP退避重试testID 2快照后写入奇数序号键testID 3恢复后全量扫描normalKeys范围校验只存在快照前的偶数键、且键值一一对应、数量为 1000以验证恢复点一致性testID 4用未加入白名单的/bin/snap_create1.sh发起快照断言必须得到snap_path_not_whitelisted或snap_not_fully_recovered_unsupported错误SnapTest.cpp验证白名单安全机制与恢复状态检查均生效。此外worker.cpp 中模拟环境的whitelistBinPaths配置/bin/snap_create.sh与 SimulatedCluster.cpp 中的相关参数传递共同支撑了仿真测试的端到端运行。这些测试是理解磁盘快照一致性边界的最佳教材。小结磁盘快照备份是 FoundationDB 在 KV 级fdbbackup之外提供的第二套备份机制它以磁盘层崩溃一致性快照 外部编排工具的方式在高性能快照基础设施上实现接近零开销的整库备份并以冷启动式的方式完成恢复。其核心运维要点可归纳为四条写好能理解--uid/--version/--path/--tlog-spill-path/--role参数的snapshot create binary、在whitelist_binpath中登记其路径、善用 UID 管理快照生命周期、恢复时严格按旧 IP → 新 IP 一一映射 新 fdb.cluster 多角色文件清理的流程执行。【免费下载链接】foundationdbFoundationDB - the open source, distributed, transactional key-value store项目地址: https://gitcode.com/gh_mirrors/fo/foundationdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 21:55:38 · 阅读 1.2k FoundationDB 磁盘快照备份与恢复（Disk Snapshot Backup Restore）完整实战指南
FoundationDB 磁盘快照备份与恢复Disk Snapshot Backup Restore完整实战指南【免费下载链接】foundationdbFoundationDB - the open source, distributed, transactional key-value store项目地址: https://gitcode.com/gh_mirrors/fo/foundationdb导读本文基于 FoundationDB 官方文档 disk-snapshot-backup.rst 展开系统讲解 FoundationDB 基于磁盘快照disk snapshot的备份与恢复方案它利用底层文件系统/磁盘的崩溃一致性crash-consistent快照能力在零停机的前提下获得数据库在某一时间点的完整一致性副本。读完本文你将掌握snapshot隐藏命令的完整用法、snapshot create binary的编写规范、白名单安全机制、9 个快照错误码的含义以及从备份到恢复的端到端操作流程并了解该功能在 fdbcli、Commit Proxy、Data Distributor 与 fdbserver 各层级的源码级实现原理。背景磁盘快照备份解决什么问题FoundationDB 的磁盘快照备份工具Disk Snapshot Backup会在不中断服务的情况下对所有持有持久化数据的磁盘存储disk store执行崩溃一致性快照从而获得数据库的一个**一致性、时间点级point-in-time**备份。其前置条件是运行 FoundationDB 的文件系统或磁盘必须支持崩溃一致性快照能力如云厂商的卷快照、存储一致性组、文件系统级快照等。工具本身只负责编排所有磁盘镜像的快照动作并确保它们能够恢复到一个一致的时间点恢复时通过把快照镜像复制或挂载回 FoundationDB 计算实例完成整个过程等同于集群被断电后重新启动。该方案通常用于测试与开发环境的数据准备合规性compliance要求的数据留存在硬件或软件故障场景下提供额外一层的保护。fdbbackup 与磁盘快照备份的对比FoundationDB 既有的 backups.rst 所描述的fdbbackup功能与磁盘快照备份都能提供时间点一致备份但二者工作在不同层级在性能、特性与外部依赖上差异明显维度fdbbackupKV 级备份磁盘快照备份工作层级key-value 层磁盘层备份方式从源集群复制全部键值对对所有持久化磁盘做崩溃一致性快照恢复方式将键值对回放到目标数据库复制/挂载磁盘镜像到新集群性能取决于数据量与读写吞吐通常很高数据不经过 FoundationDB 栈读写外部依赖无不要求磁盘系统具备快照能力依赖文件系统/磁盘的快照与恢复能力持续备份支持可灵活选择恢复点不支持持续备份在磁盘快照与恢复性能很高的环境中例如云厂商的卷快照磁盘快照方案可以非常快并且可以用高频率的备份来替代持续备份。注意本文中所有提到fdbbackup的地方均指 KV 级备份功能不要与磁盘快照备份混淆。功能限制使用磁盘快照备份前需要明确以下限制不支持持续备份continuous backup因此恢复时无法指定恢复版本不支持 Windows 操作系统数据加密依赖于磁盘系统磁盘层加密而非 FoundationDB 自身备份与恢复涉及的工具链需要运维人员按自身部署与环境自行开发当前版本中snapshot命令是fdbcli 隐藏命令计划在未来的补丁版本中解除隐藏。磁盘快照备份的实现原理源码视角在动手操作前先理解snapshot命令在集群内部的完整调用链这有助于排查问题。从源码可以还原出以下流程fdbcli 侧fdbcli/SnapshotCommand.cpp中的snapshotCommandActor生成一个随机 UIDdeterministicRandom()-randomUniqueID()并把用户输入的命令字符串拼装后调用数据库客户端的createSnapshot(uid, snap_cmd)接口命令工厂CommandFactory snapshotFactory(snapshot)注册该命令注释明确标注其为hidden commands, no help text for now。客户端 API 侧fdbclient/NativeAPI.cpp的createSnapshotActor与DatabaseContext::createSnapshot将快照请求发往集群。Commit Proxy 侧fdbserver/commitproxy/CommitProxyServer.cpp的proxySnapCreate是核心校验节点依次执行白名单校验解析快照命令的二进制路径调用isWhitelisted(commitData-whitelistedBinPathVec, binPath)检查不通过则抛出snap_path_not_whitelisted2505恢复状态校验若集群recoveryState ! RecoveryState::FULLY_RECOVERED抛出snap_not_fully_recovered_unsupported2506因为旧代 TLog 的持久化数据无法被快照覆盖log anti quorum 校验从事务状态存储读取log_anti_quorum配置大于 0 时抛出snap_log_anti_quorum_unsupported2507通过后将DistributorSnapRequest转发给 Data Distributor网络失败时按SNAP_NETWORK_FAILURE_RETRY_LIMIT指数退避重试。Data Distributor 侧fdbserver/datadistributor/DataDistribution.cpp的ddSnapCreate先通过trySetSnapshot临时禁用数据分布DD然后用race(dbInfoChange, ddSnapCreateCore(...), delay(SNAP_CREATE_MAX_TIMEOUT))执行快照若期间发生集群恢复dbInfo 变化则返回snap_with_recovery_unsupported2508若超时则返回timed_out执行完成后重新trySetEnabled恢复 DD。fdbserver 侧fdbserver/kvstore/FDBExecHelper.cpp的execHelperImpl真正生成子进程调用用户提供的snapshot create binary并自动追加--path、--tlog-spill-path可选、--version、--role、--uid等参数子进程运行时长由SNAP_CREATE_MAX_TIMEOUT约束ServerKnobs.cpp 中定义模拟环境默认 70 秒生产环境默认 300 秒。所有角色级快照错误码统一在 flow/include/flow/error_definitions.h 的 2500 段定义详见下文错误码表。备份前的准备工作在fdbserver上执行snapshot命令前需要完成以下配置编写snapshot create binary程序当被fdbserver调用时该程序负责对本地磁盘存储执行快照。它会被传入以下参数参数说明UID32 字节字母数字唯一标识符集群中所有节点收到的是同一个 UID用于标识本次备份关联的一组磁盘快照VersionFoundationDB 二进制的版本字符串Path需要被快照的 FoundationDBdatadir路径datadir配置见 configuration.rstTLog spill path可选参数以--tlog-spill-path传入当tlog角色单独配置了tlog-spill-datadir与datadir分离时提供Roletlog/storage/coordinator标识快照被调用的节点角色关于datadir与tlog-spill-datadir的语义可参考 configuration.rstdatadir是存放持久化数据文件的可写目录tlog-spill-datadir是可选的、用于存放事务日志溢出spill数据的独立目录未设置时溢出数据同样落在datadir。安装snapshot create binary安装在 FoundationDB 实例上的安全路径且必须能够被运行fdbserver的用户执行。配置白名单在 configuration.rst 的[fdbserver]配置段中新增配置项whitelist_binpath值为snapshot create binary的绝对路径。任何snapshot命令都会校验其二进制路径是否在白名单内这是一道安全机制防止客户端通过snapshot命令在集群上执行任意/不安全命令。示例whitelist_binpath /bin/snap_create.sh从源码看该配置在fdbserver启动时经 fdbserver.cpp 的--whitelist-binpath命令行选项解析OPT_WHITELIST_BINPATH最终由 Worker 传递给 Commit Proxy 并构建whitelistedBinPathVec白名单向量见 ProxyCommitData.h。收集额外的恢复元数据snapshot create binary应捕获恢复集群所需的任何附加数据例如将附加数据以标签tags形式存储在云环境中或存放在datadir内的附加文件/目录中一并快照。推荐收集的清单见下文备份规范一节。双路径一致性要求当传入--tlog-spill-path时snapshot create binary必须在返回成功前对--path与--tlog-spill-path两块磁盘协调地执行崩溃一致性快照——例如使用存储一致性组、共享卷组或先 quiesce/freeze 两个文件系统再逐卷创建快照确保两个路径恢复到同一个崩溃点。返回值约定程序任何失败都必须返回非零状态码成功返回 0。超时限制若snapshot create binary进程超过5 分钟未返回状态它会被杀死snapshot命令随即失败。该超时可通过 configuration.rst 中的SNAP_CREATE_MAX_TIMEOUT配置参数调整——源码默认值为生产环境 300 秒ServerKnobs.cpp默认值足够大通常无需修改。使用 snapshot 命令创建备份snapshot是 fdbcli 中的同步命令用法如下fdb snapshot /bin/snap_create.sh --param1 param1-value --param2 param2-value Snapshot command succeeded with UID c50263df28be44ebb596f5c2a849adbb命令接收一个snapshot create binary的完整路径返回执行状态可选地携带透传给该 binary 的附加参数。命令会返回一个唯一标识符UID用于标识一次备份的全部磁盘快照即使在失败的情况下也会返回 UID以便运维人员据此识别并清理部分创建的磁盘快照。以上述命令为例snapshot create binary会在tlog角色上以如下参数被调用--param1 param1-value --param2 param2-value --path /mnt/circus/data/4502 --version 6.2.6 --role tlog --uid c50263df28be44ebb596f5c2a849adbb关于同步性与耗时当snapshot成功返回时备份即视为完成且可恢复。完成一次备份的耗时取决于磁盘快照本身所需时间。例如若磁盘快照耗时 1 秒则整个备份应在 10 秒内完成此为一般性指导个别场景可能更长。如果命令被用户中止磁盘快照不得用于恢复因为备份状态未定义。命令失败或中止后运维人员可以重新发起一次snapshot命令重试。磁盘快照备份规范Specification下表列出了snapshot create binary应当收集的、有助于恢复的工件清单字段名 / 描述 / 信息来源字段名描述信息来源UID与某次备份所有snapshot create binary调用一同传入的唯一标识符磁盘快照可用该 UID 打标签snapshotCLI 命令输出中包含该 UIDFoundationDB Server Versionfdbserver的软件版本snapshot create binary的命令行参数CreationTime当前系统日期与时间调用系统时间获取FoundationDB Cluster File集群文件cluster file包含 cluster-name、magic 与协调者列表是集群的核心标识文件从集群文件所在位置读取fdbserver的命令行参数可通过/proc/$PPID/cmdline访问Config Knobs传给fdbserver的命令行参数来自fdbserver命令行参数或 foundationdb.confIP Address Port发起快照的fdbserver主机地址与端口信息来自fdbserver命令行参数LocalityDatamachine id、zone id 或其他 locality 信息来自fdbserver命令行参数Name for the snapshot file推荐的磁盘快照命名cluster-name:ip-addr:port:UID重要snapshot create binary不会在无持久化数据的进程上被调用例如 Cluster Controller、Master、CommitProxy。这些进程是无状态的无需快照但它们使用的任何特殊配置 knobs 需要由运维人员外部复制并在恢复后手工还原。磁盘快照的管理未使用的磁盘快照、或属于失败备份的磁盘快照需要由运维人员在外部自行删除例如清理云环境中的卷快照或备份目录FoundationDB 本身不负责快照的生命周期管理。错误码对照表snapshot命令可能返回以下错误码源码定义见 flow/include/flow/error_definitions.h名称代码描述处理建议snap_path_not_whitelisted2505快照创建二进制路径未加入白名单将snap create binary路径加入白名单后重试snap_not_fully_recovered_unsupported2506集群未完全恢复时不支持快照等待集群完成恢复后重试snap_log_anti_quorum_unsupported2507配置了 log anti quorum 时不支持该功能不支持 log anti quorum 配置snap_with_recovery_unsupported2508快照操作期间发生集群恢复快照进行中发生了恢复请重试snap_storage_failed2501快照 storage 节点失败确认snap create binary已安装且可被运行fdbserver的用户执行snap_tlog_failed2502快照 TLog 节点失败同上snap_coord_failed2503快照 coordinator 节点失败同上unknown_error4000发生未知错误同上snap_disable_tlog_pop_failed2500磁盘快照错误禁用 TLog pop 失败无需运维操作重试即可snap_enable_tlog_pop_failed2504磁盘快照错误恢复 TLog pop 失败无需运维操作重试即可磁盘快照恢复步骤恢复就是从快照的磁盘镜像中重新构建出集群。由于不支持持续备份没有选项可以指定恢复版本。恢复流程如下定位快照镜像借助 UID 或创建时间CreationTime识别与待恢复备份关联的磁盘快照镜像按主机归类按 IP 地址和/或 locality 信息将一次备份的磁盘镜像分组搭建新集群并挂载镜像搭建一个与源集群结构相似的新集群保持 FoundationDB 服务处于停止状态然后将快照磁盘镜像挂载或复制到集群中方式如下将旧 IP 地址与新 IP 地址一一映射用该映射指导磁盘镜像的恢复放置生成新集群文件根据新协调者coordinators磁盘存储的放置位置计算新的 fdb.cluster 文件并推送到新集群的所有实例启动服务在所有实例上启动 FoundationDB 服务注意多角色共享 datadir 的情况一个进程可能以多个带持久化数据的角色共享同一个datadir。此时snapshot create binary会为每个角色各创建一份快照。恢复前这些快照镜像需要额外处理如果某个角色的快照镜像中包含属于其他角色的文件必须将这些文件删除。集群启动并进入健康状态即表示恢复完成应用可以可选地做额外校验后开始使用集群。端到端示例单节点集群的备份与恢复以下示例在一个极度简化的单节点集群上用cp命令模拟快照创建与恢复仅用于演示真实环境的备份/恢复脚本必须遵循前文所述的全部步骤。第一步搭建单节点集群并写入数据按照项目文档搭建单节点集群后检查集群状态并写入示例键值fdb status Using cluster file /mnt/source/fdb.cluster. Configuration: Redundancy mode - single Storage engine - ssd-2 Coordinators - 1 Cluster: FoundationDB processes - 1 Zones - 1 Machines - 1 Memory availability - 30.6 GB per process on machine with least available Fault Tolerance - 0 machines Server time - 12/11/19 04:02:57 Data: Replication health - Healthy Moving data - 0.000 GB Sum of key-value sizes - 0 MB Disk space used - 210 MB Operating space: Storage server - 72.6 GB free on most full server Log server - 72.6 GB free on most full server Workload: Read rate - 9 Hz Write rate - 0 Hz Transactions started - 5 Hz Transactions committed - 0 Hz Conflict rate - 0 Hz Backup and DR: Running backups - 0 Running DRs - 0 Client time: 12/11/19 04:02:57 fdb writemode on fdb set key1 value1 Committed (76339236) fdb set key2 value2 Committed (80235963)第二步编写 snap create binary编写一个把datadir复制到用户指定目标目录的脚本#!/bin/sh while (( $# )); do case $1 in --uid) SNAPUID$2 shift 2 ;; --path) DATADIR$2 shift 2 ;; --role) ROLE$2 shift 2 ;; --destdir) DESTDIR$2 shift 2 ;; *) shift ;; esac done mkdir -p $DESTDIR/$SNAPUID/$ROLE || exit 1 cp $DATADIR/* $DESTDIR/$SNAPUID/$ROLE/ || exit 1 exit 0第三步安装脚本并配置白名单将脚本安装为/bin/snap_create.sh在 configuration.rst 的[fdbserver]段添加whitelist_binpath /bin/snap_create.sh然后停止并重启 foundationdb 服务使配置生效。第四步发起快照fdb snapshot /bin/snap_create.sh --destdir /mnt/backup Snapshot command succeeded with UID 69a5e0576621892f85f55b4ebfeb4312snapshot create binary会按角色分别调用一次本进程中依次为tlog、storage、coordinator参数如下--path /mnt/source/datadir --version 6.2.6 --role storage --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup --path /mnt/source/datadir --version 6.2.6 --role tlog --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup --path /mnt/source/datadir --version 6.2.6 --role coord --uid 69a5e0576621892f85f55b4ebfeb4312 --destdir /mnt/backup快照成功后所有镜像都在destdir中。以下是 coordinator 备份目录的示例文件列表$ ls /mnt/backup/69a5e0576621892f85f55b4ebfeb4312/coord/ coordination-0.fdq log2-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792.sqlite-wal processId coordination-1.fdq logqueue-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792-0.fdq storage-f0e72cdfed12a233e0e58291150ca597.sqlite log2-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792.sqlite logqueue-V_3_LS_2-b9990ae9bc00672f07264ad43d9d0792-1.fdq storage-f0e72cdfed12a233e0e58291150ca597.sqlite-wal第五步恢复恢复coordinator镜像准备恢复用的datadir并把所有 coordinator 相关文件复制进去$ cp /mnt/backup/69a5e0576621892f85f55b4ebfeb4312/coord/coord* /mnt/restore/datadir/对storage与tlog镜像重复上述步骤。随后为恢复准备新的fdb.cluster将协调者 IP 替换为新的地址例如znC1NC5b:iYHJLq7z10.2.80.40:4500 - znC1NC5b:iYHJLq7z10.2.80.41:4500本示例中foundationdb.conf可与源集群完全一致。所有镜像恢复完成后以指向/mnt/restore/datadir的datadir和新的fdb.cluster启动新的 fdbserver。第六步验证恢复结果fdb status Using cluster file /mnt/restore/fdb.cluster. Configuration: Redundancy mode - single Storage engine - ssd-2 Coordinators - 1 Cluster: FoundationDB processes - 1 Zones - 1 Machines - 1 Memory availability - 30.5 GB per process on machine with least available Fault Tolerance - 0 machines Server time - 12/11/19 09:04:53 Data: Replication health - Healthy Moving data - 0.000 GB Sum of key-value sizes - 0 MB Disk space used - 210 MB Operating space: Storage server - 72.5 GB free on most full server Log server - 72.5 GB free on most full server Workload: Read rate - 7 Hz Write rate - 0 Hz Transactions started - 3 Hz Transactions committed - 0 Hz Conflict rate - 0 Hz Backup and DR: Running backups - 0 Running DRs - 0 Client time: 12/11/19 09:04:53 fdb get key1 key1 is value1 fdb get key2 key2 is value2集群健康、示例键值完整说明备份与恢复流程成功。仓库中的测试与验证依据如果想深入了解该功能的正确性保障可研读 fdbserver/workloads/SnapTest.cpp这是一个专门针对磁盘快照的仿真工作负载覆盖了以下场景testID 0快照前写入偶数序号键snapKey*testID 1调用/bin/snap_create.sh创建快照并支持重复快照请求attemptDuplicateSnapshot测试预期首个请求以duplicate_snapshot_request失败失败时按SNAP_MINIMUM_TIME_GAP退避重试testID 2快照后写入奇数序号键testID 3恢复后全量扫描normalKeys范围校验只存在快照前的偶数键、且键值一一对应、数量为 1000以验证恢复点一致性testID 4用未加入白名单的/bin/snap_create1.sh发起快照断言必须得到snap_path_not_whitelisted或snap_not_fully_recovered_unsupported错误SnapTest.cpp验证白名单安全机制与恢复状态检查均生效。此外worker.cpp 中模拟环境的whitelistBinPaths配置/bin/snap_create.sh与 SimulatedCluster.cpp 中的相关参数传递共同支撑了仿真测试的端到端运行。这些测试是理解磁盘快照一致性边界的最佳教材。小结磁盘快照备份是 FoundationDB 在 KV 级fdbbackup之外提供的第二套备份机制它以磁盘层崩溃一致性快照 外部编排工具的方式在高性能快照基础设施上实现接近零开销的整库备份并以冷启动式的方式完成恢复。其核心运维要点可归纳为四条写好能理解--uid/--version/--path/--tlog-spill-path/--role参数的snapshot create binary、在whitelist_binpath中登记其路径、善用 UID 管理快照生命周期、恢复时严格按旧 IP → 新 IP 一一映射 新 fdb.cluster 多角色文件清理的流程执行。【免费下载链接】foundationdbFoundationDB - the open source, distributed, transactional key-value store项目地址: https://gitcode.com/gh_mirrors/fo/foundationdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考