Borg 2 归档与 tar 互操作指南:export-tar 与 import-tar 全面解析

原创2026-09-21 11:33:251,991 阅读
文章标签:运维存储

Borg 2 归档与 tar 互操作指南:export-tar 与 import-tar 全面解析

导读:Borg 仓库以去重压缩的"归档(archive)"形式存储数据,而 tar 是 UNIX 生态中通用的打包交换格式。本文围绕 docs/usage/tar.rst 展开,系统讲解 borg export-tar 将归档导出为 tar 包、borg import-tar 将 tar 包导入回归档的完整用法,包括自动压缩检测、三种 tar 格式的元数据保真度差异、稀疏文件处理、仓库间迁移脚本,并结合 src/borg/archiver/tar_cmds.py 与对应测试验证底层实现原理。读完你可以在 Borg 仓库与 tar 生态(GNU tar、bsdtar、管道流式处理)之间自由转换数据,并实现跨仓库无损迁移。

命令总览:Borg 与 tar 双向互转

Borg 的归档格式与 tar 并不兼容,但 Borg 提供了两条命令在两者之间搭桥:

  • borg export-tar:从归档中提取内容,生成一个标准 tar 包(tarball);
  • borg import-tar:读取 tar 包(或其压缩变体),将其内容重新切块、去重后存入一个 Borg 归档。

这两条命令的文档分别自动生成自内置帮助并内联在 docs/usage/export-tar.rst.inc 与 docs/usage/import-tar.rst.inc 中,由 docs/usage/tar.rst 汇总并补充实战示例。实现上,两条命令都位于 src/borg/archiver/tar_cmds.py 的 TarMixIn 类中:do_export_tar(L344 起)与 do_import_tar(L524 起)。

典型的使用场景包括:

  • 将某个归档导出为 tar 交付给没有 Borg 的机器或第三方工具;
  • 将外部生成的 tar 包导入 Borg,获得去重、加密、压缩的备份能力;
  • 通过 export-tar ... - | import-tar ... - 的管道实现仓库间迁移(见下文"归档迁移脚本");
  • 将 tar 流直接通过 ssh 或 curl 转发到远程(流式处理)。

borg export-tar:从归档导出 tar 包

命令语法与参数

borg [common options] export-tar [options] NAME FILE [PATH...]
参数 说明
NAME 指定要导出的归档名
FILE 输出 tar 文件;传 - 表示写入标准输出
PATH 要提取的路径列表(可省略,省略即导出整个归档);支持模式匹配
选项 说明
--tar-filter 指定过滤器程序,对数据流进行管道过滤(默认 auto,按扩展名自动选择)
--list 输出处理的条目(文件、目录……)清单
--tar-format FMT 选择 tar 格式:BORG、PAX 或 GNU
--sparse 将含全零 chunk 的文件写为稀疏 tar 成员(GNU sparse format 1.0,仅 BORG 与 PAX 格式支持)
-e PATTERN, --exclude PATTERN 排除匹配 PATTERN 的路径
--exclude-from EXCLUDEFILE 从文件逐行读取排除模式
--pattern PATTERN 包含/排除匹配 PATTERN 的路径
--patterns-from PATTERNFILE 从文件逐行读取包含/排除模式
--strip-components NUMBER 去掉路径前 N 个路径元素;元素不足的路径会被静默跳过

另外还支持 --progress(显示进度;注意文档提示它比不显示进度更慢,因为需要对归档元数据多做一遍扫描)以及所有通用选项。默认 --tar-format 为 PAX(见 tar_cmds.py L690)。

例如,最基础的导出:

$ borg export-tar Monday Monday.tar
$ borg export-tar Monday - | head -c 1024   # 输出到 stdout

导出时默认导出整个归档,也可以用 PATH 参数与排除选项缩小范围,例如只导出 dir1 并排除 *.so:

$ borg export-tar Monday Monday.tar dir1 --exclude '*.so'

关于 include/exclude 模式的完整语法,可运行 borg help patterns 查看(对应手册页见 docs/man/borg-patterns.1)。

按扩展名自动压缩(--tar-filter=auto)

默认情况下(--tar-filter=auto),Borg 会根据 FILE 的文件扩展名自动判断是否压缩,并把 tar 流通过合适的过滤器后再写入文件:

扩展名 过滤器
.tar.gz / .tgz gzip
.tar.bz2 / .tbz bzip2
.tar.xz / .txz xz
.tar.zstd / .tar.zst / .tzst zstd(进程内压缩,level 3)
.tar.lz4 lz4

扩展名到过滤器的映射逻辑在源码 get_tar_filter 中实现。这里有个重要的设计取舍:zstd 是进程内(in-process)压缩,直接使用 libzstd 完成,不需要外部程序;其余格式则通过外部过滤器程序(gzip、bzip2、xz、lz4)管道完成。

为什么 Borg 不直接用 Python tarfile 内置的压缩?tar_cmds.py L354-L376 的注释给出了三点理由:

  1. 内置压缩与主程序跑在同一线程,会抢占 Borg 的 CPU 时间、降低吞吐;
  2. 内置方案选项有限(没有 lz4、zstd、brotli 等);
  3. 系统可能装了更优化的实现(如多线程的 pigz、pxz),外部过滤器可以免费获得这些加速。

而 zstd 之所以例外,是因为 Borg 本身就必须依赖 zstd 模块(Python 3.14+ 为标准库,否则用 backports.zstd),libzstd 的多线程压缩跑在 GIL 之外,且没有显著更优的外部工具。

多线程 zstd 压缩可通过环境变量 BORG_ZSTD_MT_WORKERS 开启(详见 docs/usage/general/environment.rst.inc):设置为数值 n,即用 n 个线程压缩单个 chunk;export-tar 压缩的是单个长流而非一个个 chunk,默认就使用 CPU 核数。多线程会牺牲少量压缩率换取速度,追求更小体积时建议设小或设 1。

自定义过滤器

除了自动检测,也可以显式指定 --tar-filter 程序。过滤器应从 stdin 读取未压缩的 tar 流,向 stdout 写出压缩/过滤后的 tar 流:

$ borg export-tar --tar-filter="gzip -9" Monday Monday.tar.gz
$ borg export-tar --tar-filter="xz -T0" Monday Monday.tar.xz

注意:一旦显式指定过滤器,就不再按扩展名判断;即使输出文件是 .tar.zst,显式 --tar-filter=zstd 也会走外部程序(对应测试见 tar_cmds_test.py L342-L356 的 test_tar_filter_zstd_external)。

三种 tar 格式与元数据保真度

--tar-format 决定生成哪种 tar 规范,也决定了能保留下多少 Borg 元数据:

--tar-format 规范 元数据
BORG Borg 特有格式,基于 PAX Borg 支持的全部元数据
PAX POSIX.1-2001 (pax) 格式 GNU 所支持项 + atime/ctime/mtime 纳秒精度 + xattrs
GNU GNU tar 格式 mtime 秒级精度,无 atime/ctime,无 ACL/xattrs/bsdflags

这意味着:

  • BORG 格式:PAX 的扩展头里额外携带 BORG.item.version 和 BORG.item.meta(把整个 Borg item 用 msgpack 序列化后 base64 编码写入 pax 头),因此往返无损——导出再导入后,所有 Borg 元数据(包括硬链接分组 hlid 等)都保留;
  • PAX 格式:适合需要与 GNU tar、bsdtar 等互操作的场景,能保留 xattr、ACL、纳秒时间戳,但硬链接分组信息无法保留;
  • GNU 格式:最通用但保真度最低,适合纯数据搬运。

pax 头的生成逻辑在 item_to_paxheaders 中:PAX 格式写入 atime/ctime/mtime、SCHILY.xattr.*、ACL 头;BORG 格式在此基础上追加 BORG.item.meta。导入侧 create_helper 会反向解析这些 pax 头还原 item。

测试 test_roundtrip_pax_borg 验证了 --tar-format=BORG 的完整往返保真,而 test_import_tar_hardlinks 明确验证了关键差异:BORG 格式能把硬链接分组原样还原(st_nlink 保持 2),PAX/GNU 格式则退化为"内容去重但各自独立"的普通文件。

稀疏文件导出:--sparse

对包含大量全零 chunk 的文件(典型如磁盘镜像、VM 镜像、数据库文件),--sparse 会把它们写成 GNU sparse format 1.0 的稀疏 tar 成员:只存储 hole map(空洞映射)和非零数据,全零区段不再逐字写出。

$ borg export-tar --sparse disk-images disk-images.tar

要点:

  • 仅支持 --tar-format BORG 或 PAX;用 GNU 会直接报错:--sparse requires --tar-format BORG or PAX(见 do_export_tar 校验 与测试 test_export_tar_sparse_gnu_format_error);
  • 空洞检测在 Borg 内容 chunk 的粒度上进行,不依赖原文件在文件系统上是不是稀疏文件(但过短或不对齐的零区段可能仍会字面存储);
  • 稀疏感知的 tar 实现(GNU tar、bsdtar 以及 borg import-tar / borg extract --sparse)可以还原为稀疏文件;不感知稀疏的 tar 实现会把成员解成 GNUSparseFile.0/<name>,内含原始 hole map 和数据段(GNU tar 自己生成的稀疏 tar 也有同样现象);
  • 当存储(非空洞)数据 ≥ 8 GiB 时,存储大小在 tar 头里用 base-256 编码(GNU/star 大数编码,GNU tar、libarchive/bsdtar、Python 都能读),逻辑文件大小本身不受限。

底层实现细节相当讲究:chunks_to_sparse_info(L159-L239)把连续全零 chunk 合并成空洞、并对齐到 512 字节 tar 块边界(GNU tar 的稀疏读取器按块处理数据段,不对齐会失步),文件以空洞结尾时追加 (realsize, 0) 终止项,与 GNU tar 的行为一致;SparseTarInfo(L242-L276)则特意不写 pax "size" 记录(稀疏读取器会因此失步),存储大小始终放在 ustar size 字段里,超出八进制上限时手工打补丁改为 base-256 编码并重算校验和。

一个容易被忽视的细节:sparsify_tarinfo 会先判断稀疏化是否划算——如果 hole map 本身的体积比省下的空洞还大(stored_size >= realsize),就仍按普通稠密成员输出(测试 test_export_tar_sparse_not_worthwhile 验证了这一点)。测试 test_export_tar_sparse 还验证了稀疏导出确实显著减小 tar 体积(测试语料中约省 800+ KiB 空洞),test_export_tar_sparse_gnutar 验证了 GNU tar 解包后能真正恢复为稀疏文件(st_blocks * 512 < st_size)。

borg import-tar:把 tar 包导入归档

命令语法与参数

borg [common options] import-tar [options] NAME TARFILE
参数 说明
NAME 指定新归档名
TARFILE 输入 tar 文件;传 - 表示从标准输入读取
选项 说明
--tar-filter 过滤器程序(默认 auto,按扩展名自动解压)
-s, --stats 打印新归档的统计信息
--list 输出处理的条目清单
--filter STATUSCHARS 只显示指定状态字符的条目
--json 以 JSON 输出统计(隐含 --stats)
--ignore-zeros 忽略输入 tar 中的全零填充块(用于拼接的多个 tar 包)

Archive 选项(与 borg create 的归档级选项一致):

选项 说明
--comment COMMENT 给归档添加注释
--timestamp TIMESTAMP 手动指定归档创建时间(`yyyy-mm-ddThh:mm:ss[(+
--chunker-params PARAMS 指定切块参数,格式为 buzhash,MIN,MAX,HASH_MASK,WINDOW 或 buzhash64,...,NC_LEVEL 或 fastcdc,MIN,MAX,HASH_MASK,NC_LEVEL;默认 fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION 选择压缩算法(默认 lz4),细节见 borg help compression
--digests ALGOS 对每个文件内容计算指定哈希摘要并存入归档条目,逗号分隔如 blake3,或 none;默认 none

自动解压与过滤器

与 export 对称,import-tar 默认按扩展名自动选择解压过滤器:

扩展名 过滤器
.tar.gz / .tgz gzip -d
.tar.bz2 / .tbz bzip2 -d
.tar.xz / .txz xz -d
.tar.zstd / .tar.zst / .tzst zstd(进程内解压)
.tar.lz4 lz4 -d

显式 --tar-filter 时,过滤器应从 stdin 读压缩数据,向 stdout 输出未压缩的 tar 流,例如:

$ borg import-tar --tar-filter="zstd -d" dst archive.tar.zst

支持读取的 tar 格式

import-tar 能读取以下 tar 格式:

  • BORG:Borg 特有(基于 PAX);
  • PAX:POSIX.1-2001;
  • GNU:GNU tar;
  • POSIX.1-1988(ustar);
  • UNIX V7 tar;
  • SunOS tar(含扩展属性)。

import-tar 不需要 --sparse 选项:输入 tar 中的稀疏成员(老式 GNU 与 PAX 稀疏格式)会被正确读取,其空洞在导入后成为去重后的全零 chunk——也就是说,稀疏文件进入 Borg 后天然以最小成本存储。

多条 tar 拼接导入

如果想把多个 tar 包合并进同一个归档,可以直接把它们用 cat 拼接成一个文件,再配合 --ignore-zeros 跳过各包之间的结束标记(全零块)导入:

$ cat part1.tar part2.tar part3.tar > combined.tar
$ borg import-tar --ignore-zeros all combined.tar

测试 test_import_concatenated_tar_with_ignore_zeros 验证了拼接导入的正确性;不传 --ignore-zeros 时,第二个包会被结束标记截断(L388-L410 的负向测试确认了这一行为)。

导入的底层流程

导入时数据流是这样的:解压后的 tar 流交给 Python tarfile 流式读取(mode="r|",见 do_import_tar),每个条目按类型分派到 TarfileObjectProcessors(src/borg/archive.py L1990):普通文件走 process_file,用配置的 chunker 重新切块,再经 ChunksProcessor.process_file_chunks 计算 chunk 哈希、去重入库;符号链接、设备、FIFO、硬链接、目录各有独立处理分支。硬链接在 tar 里是"首个实例存内容、后续实例引用"的模型,导入时复用首个实例的 chunk(因此无论格式如何内容都会去重)。

与 borg create 的一个关键差异:import-tar 不支持排除文件(没有 --exclude 选项)。其余大部分 borg create 的行为(chunker、压缩、digests、归档系列等)都适用,可参考 docs/usage/create.rst。

实战示例:从导出到导入的完整工作流

以下示例全部取自 docs/usage/tar.rst 并加以展开:

# 1. 导出未压缩 tar
$ borg export-tar Monday Monday.tar

# 2. 导入未压缩 tar
$ borg import-tar Monday Monday.tar

# 3. 排除部分文件类型并 gzip 压缩
$ borg export-tar Monday Monday.tar.gz --exclude '*.so'

# 4. 用更高压缩级(gzip -9)导出
$ borg export-tar --tar-filter="gzip -9" Monday Monday.tar.gz

# 5. 跨仓库直接搬运(管道连接 export-tar 与 import-tar)
$ borg -r repoA export-tar --tar-format=BORG archive - | borg -r repoB import-tar archive -

# 6. 导出后不落盘,直接 POST 到远程
$ borg export-tar Monday - | curl --data-binary @- https://somewhere/to/POST

# 7. 远程解包(tarpipe)
$ borg export-tar Monday - | ssh somewhere "cd extracted; tar x"

# 8. 把磁盘镜像导出为稀疏 tar(GNU sparse 1.0)
$ borg export-tar --sparse disk-images disk-images.tar

注意示例 5 使用了 --tar-format=BORG——如果希望在迁移后保留 Borg 的全部元数据(含硬链接分组),BORG 格式是唯一选择。

归档迁移脚本:批量复制所有归档

docs/usage/tar.rst 还提供了一个 bash 脚本(之所以用 bash,是因为它用了进程替换 <( )),把 repo1 的所有归档逐一搬运到 repo2。脚本默认只打印命令,去掉 echo 才会真正执行:

while read -r N I T
do
  echo "borg -r repo1 export-tar --tar-format=BORG aid:$I - | borg -r repo2 import-tar --timestamp=$T $N -"
done < <(borg -r repo1 repo-list --format='{name} {id} {time:%Y-%m-%dT%H:%M:%S}{NL}')

脚本逻辑拆解:

  • borg -r repo1 repo-list --format=... 输出三列:归档名 {name}、归档 ID {id}、创建时间 {time:...};
  • export-tar 用 aid:$I(archive ID)精确指定归档,--tar-format=BORG 保证元数据无损;
  • import-tar --timestamp=$T 把原始创建时间写回新归档,保持时间戳一致;
  • 两者通过管道 | 连接,数据流直接进 repo2,不落中间文件。

保留下来的:归档名、归档时间戳、归档内容(所有条目的元数据与数据)。

会丢失的:部分归档级元数据(如原始命令行、执行时间等)。

注意事项(原文档明确提示):

  • 每个归档的数据都会完整流过管道——管道是"哑"的,不会因去重而减少传输量或时间;
  • 可以给命令加上压缩(例如 --tar-filter="gzip -1")减少网络传输;
  • 远程仓库时把管道放到 ssh 上(如示例 7 的 tarpipe 模式);
  • 可以给 export-tar 加上 --sparse,让全零 chunk 区段以紧凑的稀疏映射传输,而不是逐字传零字节。

源码与测试印证

如果你关心这些行为在代码里如何落地,以下是可深入查阅的位置:

  • 命令入口与参数解析:src/borg/archiver/tar_cmds.py 的 build_parser_tar,定义了 export-tar / import-tar 的全部参数、默认值与校验;
  • 导出主流程:do_export_tar / _export_tar(L344-L522),含 matcher 构建、路径剥离(--strip-components)、硬链接管理(HardLinkManager)、稀疏化;
  • 导入主流程:do_import_tar / _import_tar(L524-L604),含 tar 流式读取、按条目类型分派、归档保存;
  • 条目类型转换:item_to_tarinfo(L46-L110)处理普通文件/目录/符号链接/块设备/字符设备/FIFO,不支持的类型会告警跳过;
  • pax 头编解码:item_to_paxheaders(导出)与 create_helper(导入);
  • 稀疏实现:chunks_to_sparse_info、SparseTarInfo、gnu_sparse_10_map(L159-L290);
  • 过滤器解析:get_tar_filter 与进程内 zstd 过滤器(L301-L342)。

测试套件 src/borg/testsuite/archiver/tar_cmds_test.py 覆盖了上述绝大部分行为:基础导出/导入往返、.gz/.zst 压缩与互操作(zstd 输出可被标准 zstd -d 解压)、--strip-components、硬链接(含 BORG 格式保真)、稀疏导出的体积收益与 GNU tar 互操作、base-256 大文件编码、ACL/xattr 往返、路径规范化(./ 前缀去除)、.. 路径拒绝(unexpected '..' element in path)、拼接 tar 的 --ignore-zeros 导入、--json 统计等。

最后提醒一点:导出命令面对的是已有归档,因此 export-tar 使用 borg [common options] 而非仓库选项——但读写仓库都需要 -r/--repo(或 BORG_REPO 环境变量),示例中的 -r repoA/-r repoB 正是在指定源与目标仓库;import-tar 由于要写入新归档,还支持上文列出的全部 Archive 选项(chunker、压缩、digests 等),可在导入时按需调整存储策略。

登录后查看全文
borg