Borg 2 归档与 tar 互操作指南:export-tar 与 import-tar 全面解析
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 的注释给出了三点理由:
- 内置压缩与主程序跑在同一线程,会抢占 Borg 的 CPU 时间、降低吞吐;
- 内置方案选项有限(没有 lz4、zstd、brotli 等);
- 系统可能装了更优化的实现(如多线程的
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 V7tar;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 等),可在导入时按需调整存储策略。