VictoriaMetrics vmrestore 实战指南：可断点续传的备份恢复、rsync 式同步与源码级原理

VictoriaMetrics vmrestore 实战指南可断点续传的备份恢复、rsync 式同步与源码级原理【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetricsvmrestore是 VictoriaMetrics 的官方恢复工具负责将vmbackup生成的备份还原到本地存储目录支持断点续传、增量恢复对非空目标目录执行类似rsync --delete的同步以及对象存储带宽限速。读完本篇你将掌握vmrestore的完整命令行用法、可复制的恢复流程、全部-help参数含义并能从源码层面理解恢复流程中的“备份完整性校验、parts 差量同步、文件预分配与中断恢复”机制。1. vmrestore 是什么vmrestore从 vmbackup 创建的备份中恢复 VictoriaMetrics 数据与vmbackup互为对偶工具。备份端vmbackup将本地数据目录切分为固定大小的 part 对象上传到远端存储恢复端vmrestore则反向列出远端与本地的 parts 清单删除多余文件、只下载缺失的 part最终得到一个与备份完全一致的-storageDataPath目录。从 app/vmrestore/main.go 可以看到核心参数定义src flag.String(src, , Source path with backup on the remote storage. Example: gs://bucket/path/to/backup, s3://bucket/path/to/backup, azblob://container/path/to/backup or fs:///path/to/local/backup\n Note: If custom S3 endpoint is used, URL should contain only name of the bucket, while hostname of S3 server must be specified via the -customS3Endpoint command-line flag.) storageDataPath flag.String(storageDataPath, victoria-metrics-data, Destination path where backup must be restored. ...) concurrency flag.Int(concurrency, 10, The number of concurrent workers. Higher concurrency may reduce restore duration) maxBytesPerSecond flagutil.NewBytes(maxBytesPerSecond, 0, The maximum download speed. There is no limit if it is set to 0) skipBackupCompleteCheck flag.Bool(skipBackupCompleteCheck, false, Whether to skip checking for backup complete file in -src. ...) SkipPreallocation flag.Bool(skipFilePreallocation, false, Whether to skip pre-allocated files. This will likely be slower in most cases, but allows restores to resume mid file on failure)1.1 可中断、可续传v1.139.0 起支持预分配恢复过程可以在任何时刻被中断。重新以相同参数启动vmrestore时会自动续传。从 v1.139.0 开始行为取决于文件预分配file preallocation是否开启预分配开启默认续传从“最后一个完整文件”重新开始通过-skipFilePreallocation关闭预分配续传从文件内部的中断点mid file继续。源码中对应的实现在 lib/backup/actions/restore.go未设置-skipFilePreallocation时会启用UseTmpFiles即每个文件先写入.tmp临时文件完成后重命名见 lib/backup/fslocal/fslocal.go 的PreallocateFile/FinalizeFile/CleanupTmpFiles。续传时CleanupTmpFiles会清掉上次中断留下的半成品.tmp文件这正是“从最后一个完整文件恢复”的实现基础。1.2 “restore in progress” 锁文件Restore.Run的第一步是创建锁文件防止 VictoriaMetrics 与恢复过程同时写同一目录lib/backup/actions/restore.go。锁文件名由 lib/backup/backupnames/filenames.go 定义restore-in-progress恢复中与backup_complete.ignore备份完成标记。因此恢复期间必须停止 VictoriaMetrics恢复完成、锁文件被移除后再启动。2. 使用方法Usage恢复过程中必须停止 VictoriaMetrics。执行以下命令将-src指定的备份恢复进-storageDataPath./vmrestore -srcstorageType://path/to/backup -storageDataPathlocal/path/to/restore2.1-src支持的备份源存储类型storageType://path/to/backup必须是vmbackup创建备份时使用相同 scheme 的路径。支持的类型如下scheme 解析逻辑见 lib/backup/actions/util.go 的NewRemoteFS存储类型scheme 示例说明GCS-srcgs://bucket/path/to/backup官方文档同时接受gcs://S3-srcs3://bucket/path/to/backupAWS S3 及任意 S3 兼容存储Azure Blob Storage-srcazblob://container/path/to/backupS3 兼容存储MinIO、Ceph 等-srcs3://bucket/...配合-customS3Endpoint使用自定义 S3 endpoint 时URL 中只写 bucket 名主机名由-customS3Endpoint指定本地文件系统-srcfs:///absolute/path/to/backup注意fs://后必须是绝对路径vmbackup会阻止将备份存入-storageDataPath指向的目录因为该目录只能由 VictoriaMetrics 或vmstorage管理2.2-storageDataPath恢复目标目录local/path/to/restore是数据恢复的目标文件夹。恢复完成后该目录必须作为-storageDataPath传给 VictoriaMetrics或vmstorage。目标目录可以为非空原有旧文件会被备份中的文件替换即最终效果类似rsync --delete。源码中这一步发生在 lib/backup/actions/restore.go通过common.PartsDifference(dstParts, srcParts)计算出本地多出的 parts删除“缺失 part 位于 offset 0”的整个文件针对部分下载文件的处理参见其注释中对 GitHub issue #487 的说明随后RemoveEmptyDirs清理空目录。3. 恢复流程的源码级解析main函数中整个恢复动作被压缩为一次actions.Restore调用app/vmrestore/main.go并注册了 SIGTERM 监听收到停止信号即取消 context优雅终止app/vmrestore/main.go。Restore.Run的完整流程lib/backup/actions/restore.go可分为五步完整性校验除非指定-skipBackupCompleteCheck否则要求-src中存在backup_complete.ignore文件缺失意味着“备份不完整”或“旧版备份”并会直接报错提示可以传入-skipBackupCompleteCheck强制恢复。清理临时文件dst.CleanupTmpFiles()删除上次中断留下的.tmp文件。列出并校验 parts分别列出 src/dst 的所有 part并逐文件校验 part 是否无间隙、无重叠地覆盖整个文件invalid size/overlap/gap三类错误确保备份结构完整。删除多余、下载缺失先删除本地多余文件再对PartsDifference(srcParts, dstParts)得到的缺失 parts 分组并发下载。并发调度由runParallelPerPath实现lib/backup/actions/util.go同一文件内的 parts 交给同一个 worker 顺序处理保证文件按 offset 顺序增长。进度日志与收尾runWithProgress每 10 秒打印一次已下载字节数、百分比、速度和预计完成时间结束时汇总restored X bytes in Y seconds; deleted Z bytes; downloaded W bytes最后移除restore-in-progress锁文件。单个 part 的下载是“管道化”的远端读 goroutine 通过io.Pipe把数据写给本地directWriteCloserlib/backup/actions/restore.go读写并行避免整块缓冲在内存中。每个写入字节数累计到vm_backups_downloaded_bytes_total指标可在vmrestore的/metrics页面默认:8421观察。3.1 断点续传如何工作增量恢复Restore结构体注释明确写道“If dst points to existing directory, then incremental restore is performed, i.e. only new data is downloaded from src”lib/backup/actions/restore.go。因此“续传”不需要任何额外状态文件——每次启动都重新对 src 与 dst 做 parts 差集天然幂等# 第一次正常恢复假设中途被 kill ./vmrestore -srcs3://my-bucket/backups/2026-09-13T00:00:00Z -storageDataPath/path/to/vm-data # 第二次相同参数重启只补齐缺失的 part ./vmrestore -srcs3://my-bucket/backups/2026-09-13T00:00:00Z -storageDataPath/path/to/vm-data区别在于预分配模式默认预分配下未完成文件对应的.tmp会在下次启动时被CleanupTmpFiles删除并从 offset 0 重新下载加-skipFilePreallocation后不走.tmp路径NewDirectWriteCloser直接按p.Offsetseek 到目标文件内断点处续写lib/backup/fslocal/fslocal.go代价是整体吞吐通常更低。3.2 目标目录安全护栏两处源码级防护值得注意Run开头会校验 src 中每个 part 的相对路径都落在-storageDataPath内part file ... would be written outside storage directoryfslocal.NewDirectWriteCloser也再次断言防止备份中构造的路径把文件写到存储目录之外lib/backup/actions/restore.go。4. 排障Troubleshooting云存储凭据问题按 Connecting VM components to cloud storage 中的指引配置 GCS/S3/Azure 凭据相关参数见下文-credsFilePath、-configFilePath等。恢复占满网络带宽设置-maxBytesPerSecond限制下载速度支持 KB/MB/GB 等后缀0 表示不限制。本地写端由 lib/backup/fslocal/bandwidth_limiter.go 的带宽限流器实现。因临时错误中断用相同参数重启vmrestore即可恢复流程会自动续传见第 3.1 节。提示找不到backup complete文件说明备份可能不完整或来自不写该标记的旧版本vmbackup。确认备份确实完整后可加-skipBackupCompleteCheck强制恢复。5. 高级用法完整参数说明运行vmrestore -help可查看全部选项。下面按功能域整理了全部参数默认值与-help输出一致5.1 恢复核心参数参数默认值说明-src空远端备份路径。例gs://bucket/path/to/backup、s3://bucket/path/to/backup、azblob://container/path/to/backup或fs:///path/to/local/backup。使用自定义 S3 endpoint 时URL 只写 bucket 名主机名通过-customS3Endpoint指定-storageDataPathvictoria-metrics-data恢复目标目录恢复期间 VictoriaMetrics 必须停止。目录可非空内容将与-src同步类似rsync --delete-concurrency10并发 worker 数调高可缩短恢复耗时-maxBytesPerSecond0最大下载速度0 表示不限速支持 KB/MB/GB/TB/KiB/MiB/GiB/TiB 后缀-skipBackupCompleteCheckfalse跳过对-src中backup_complete文件的检查可用于恢复未生成该文件的旧备份-skipFilePreallocationfalse跳过文件预分配。多数场景下更慢但允许失败后在文件内部断点处续传-enableTCP6false为监听与拨号启用 IPv6默认仅使用 IPv4-memory.allowedBytes0VictoriaMetrics 缓存可占用的内存字节数非零时覆盖-memory.allowedPercent。过低会提高缓存未命中率更多 CPU 与磁盘 IO过高会挤占 OS 页缓存-memory.allowedPercent60同上以百分比指定5.2 存储认证与 S3 兼容存储参数参数默认值说明-credsFilePath空GCS 或 S3 凭据文件路径不设置时从默认位置加载-configFilePath空S3 配置文件路径不设置时从默认位置加载-configProfile空S3 配置 profile 名未设置时读取AWS_PROFILE/AWS_DEFAULT_PROFILE环境变量否则用 DefaultSharedConfigProfile-customS3Endpoint空S3 兼容存储如 MinIO的自定义 endpoint不设置时连接 AWS S3-s3ForcePathStyletrue是否以 bucket 名前缀拼接 endpointpath-style 访问默认开启-s3SSEKMSKeyId空S3 兼容存储的 SSE KMS Key ID-s3StorageClass空上传对象使用的 S3 Storage ClassGLACIER、DEEP_ARCHIVE、GLACIER_IR、INTELLIGENT_TIERING、ONEZONE_IA、OUTPOSTS、REDUCED_REDUNDANCY、STANDARD、STANDARD_IA。恢复场景一般不涉及上传主要为与备份工具共享的存储参数-s3TLSInsecureSkipVerifyfalse连接 S3 endpoint 时是否跳过 TLS 证书校验-deleteAllObjectVersionsfalse删除对象时是否连带清除对象存储中的历史版本开启版本控制的桶中默认只删除当前版本-envflag.enable未设置允许从环境变量读取 flag环境变量优先级低于命令行详见 Single-server VictoriaMetrics 的环境变量说明-envflag.prefix空-envflag.enable开启时环境变量的前缀不同存储类型的认证示例参考 Connecting VM components to cloud storage。5.3 HTTP 服务端与安全参数参数默认值说明-httpListenAddr:8421导出/metrics指标的 TCP 地址vmrestore用它暴露恢复进度指标-http.connTimeout2m0s入站连接超时便于在 TCP 层负载均衡的集群间均匀分摊连接0 表示不断连-http.idleConnTimeout1m0s空闲入站连接超时-http.disableKeepAlivefalse禁用 HTTP keep-alive-http.disableCORSfalse禁用所有来源*的 CORS-http.disableResponseCompressionfalse禁用 HTTP 响应压缩以节省 CPU默认开启压缩以节省带宽-http.header.csp空Content-Security-Policy响应头值建议default-src self-http.header.disableServerHostnamefalse禁用X-Server-Hostname响应头-http.header.frameOptions空X-Frame-Options响应头值-http.header.hsts空Strict-Transport-Security响应头值建议max-age31536000; includeSubDomains-http.pathPrefix空所有 HTTP 路径前缀如-http.pathPrefix/foo/bar后请求都走/foo/bar/*便于反向代理-http.maxGracefulShutdownDuration7sHTTP 服务优雅关闭的最长耗时-http.shutdownDelay0关闭 HTTP 服务前的延迟期间/health返回非 OK供负载均衡器把流量切走-httpAuth.username/-httpAuth.password空HTTP Basic Auth 凭据username 为空即关闭认证。password 支持file://与http(s)://读取-flagsAuthKey空/flags端点的鉴权 key通过authKey查询参数传递覆盖-httpAuth.*支持file://、http(s)://取值-metricsAuthKey空/metrics端点鉴权 key用法同上-pprofAuthKey空/debug/pprof/*端点鉴权 key用法同上-metrics.exposeMetadatafalse在/metrics中暴露 TYPE/HELP 元数据供需要该信息的采集系统使用5.4 TLS 参数企业版能力以 Enterprise 二进制为准参数说明-tls是否为对应-httpListenAddr启用 TLS数组型设置后必须提供-tlsCertFile与-tlsKeyFile-tlsCertFile/-tlsKeyFile证书与私钥文件路径建议优先 ECDSA文件每秒自动重读可热更新-tlsMinVersion最低 TLS 版本TLS10/TLS11/TLS12/TLS13-tlsCipherSuites可选的 TLS 密码套件列表-mtls是否要求客户端证书仅 Enterprise 二进制需配合-tls使用-mtlsCAFile校验客户端证书使用的 TLS Root CA仅 Enterprise 二进制-tlsAutocertCacheDir/-tlsAutocertEmail/-tlsAutocertHostsLets Encrypt 自动证书相关参数仅 Enterprise 二进制-tlsAutocertHosts会覆盖-tlsCertFile/-tlsKeyFile且-httpListenAddr必须监听 4435.5 文件系统与 IO 调优参数参数默认值说明-fs.disableMmap按架构是否用pread()代替mmap()读取数据文件。64 位架构默认用 mmap读小块数据更快32 位架构因无法读大于 2^32 字节的文件而用 pread-fs.disableMincorefalse禁用mincore()系统调用。老版本 ZFS低于 2.1.5上 mincore 可能触发 ZFS bug可据此关闭-fs.maxConcurrency64文件操作的最大并发 goroutine 数。核数少的系统调低可减少 Go 调度延迟NFS/Ceph 等高延迟存储上调高可降低数据写入延迟-filestream.disableFadvisefalse禁用读取大文件时的fadvise()。该调用防止后台 merge/备份期间 OS 页缓存逐出最近访问的数据极少数 CPU 开销过大的场景可禁用-internStringMaxLen500允许被 intern 的字符串最大长度调低省内存但更耗 CPU-internStringCacheExpireDuration6m0sintern 字符串缓存过期时间-internStringDisableCachefalse完全禁用 intern 字符串缓存以 CPU 换内存5.6 日志参数参数默认值说明-loggerLevelINFO最低日志级别INFO/WARN/ERROR/FATAL/PANIC-loggerFormatdefault日志格式default 或 json-loggerJSONFields空JSON 日志字段重命名如ts:timestamp,msg:message支持字段ts、level、caller、msg-loggerOutputstderr日志输出stderr 或 stdout-loggerTimezoneUTC日志时间戳使用的 IANA 时区如America/New_York、Europe/Berlin、Etc/GMT3、Local-loggerDisableTimestampsfalse不写时间戳-loggerMaxArgLen5000单个日志参数最大长度超出部分截断为arg_start..arg_end-loggerErrorsPerSecondLimit0每秒 ERROR 消息上限超出部分被抑制0 表示不限-loggerWarnsPerSecondLimit0每秒 WARN 消息上限超出部分被抑制0 表示不限5.7 Push 指标参数参数默认值说明-pushmetrics.url空将/metrics指标推送到的远端 URL 列表默认不推送-pushmetrics.interval10s推送间隔-pushmetrics.disableCompressionfalse推送时禁用请求体压缩-pushmetrics.extraLabel空为所有推送指标附加标签如-pushmetrics.extraLabelinstancefoo-pushmetrics.header空为每次推送请求附加 HTTP 头如-pushmetrics.headerAuthorization: Basic foobar5.8 许可证与其他参数说明-licenseVictoriaMetrics Enterprise 许可证 key仅 Enterprise 二进制也见 enterprise.md-licenseFile许可证 key 文件路径仅 Enterprise 二进制-licenseFile.reloadInterval重新加载许可证文件的间隔默认1h0m0s仅 Enterprise 二进制-license.forceOffline启用许可证离线校验需许可证支持仅 Enterprise 二进制-eula已废弃请改用-license/-licenseFile-version显示版本6. 从源码构建 vmrestore官方推荐使用二进制发布版vmutils-*归档。如需自行构建以当前仓库为准开发构建安装 Go。在仓库根目录执行make vmrestore产物vmrestore放入bin目录。生产构建安装 Docker。在仓库根目录执行make vmrestore-prod产物vmrestore-prod放入bin目录。构建 Docker 镜像# 默认以 alpine 为基础镜像构建 victoriametrics/vmrestore:PKG_TAG make package-vmrestore # 手动指定镜像 tag PKG_TAGfoobar make package-vmrestore # 换用其他基础镜像例如 scratch ROOT_IMAGEscratch make package-vmrestore其中PKG_TAG默认根据仓库源码自动生成。7. 小结vmrestore的核心用法只有两个参数-srcscheme://backup path与-storageDataPathlocal path恢复期间 VictoriaMetrics 必须停止恢复过程幂等且可中断续传默认预分配模式下从最后一个完整文件续传加-skipFilePreallocation可从文件内部断点续传对非空目标目录vmrestore按 parts 差集删除多余文件并补齐缺失文件效果等同rsync --delete遇到backup complete缺失、带宽占满、临时错误等问题的处理方式见第 4 节全部-help参数说明见第 5 节恢复流程实现可对照 lib/backup/actions/restore.go 与 lib/backup/fslocal/fslocal.go 阅读。【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考