文件导入和转存

JuiceFS 默认会将文件进行分块存储，并将元数据与数据剥离。正是这样的存储格式和分离架构，让 JuiceFS 得以成为高性能、强一致性文件系统。

但是在某些非常特殊的场景下，用户更需要直接在对象存储上保存原始文件，让对象存储里的文件能够脱离 JuiceFS 元数据使用，或者直接将对象存储中已有的大量文件直接导入 JuiceFS，使其可以通过 POSIX 访问，并利用上 JuiceFS 的强大缓存能力。在对象存储里保存完整文件并在 JuiceFS 中使用，我们称为「兼容格式」。而默认的文件分块存储的高性能模式，则称为「优化格式」。

从 5.0 开始，JuiceFS 极大改善了对兼容格式的支持，提供以下功能，来满足上述要求：

• 对象存储的「导入」功能，也就是 juicefs import 命令。确切地说，这个命令早已支持，但从 5.0 开始，导入的文件也支持读缓存。
• 「转存」功能，将 JuiceFS 中的分块格式文件，重新组合成完整文件上传至对象存储，让用户可以直接在对象存储中访问原始文件，一样支持读缓存。

导入对象存储已有文件

juicefs import 会扫描给定的对象存储地址，然后将目标文件的元数据信息写入 JuiceFS 元数据引擎，让这些文件在 JuiceFS 中也能访问，该操作并不会实际复制任何文件，文件仍原样保存在对象存储里，因此相较于 JuiceFS 原生的分块格式，这种存储格式称为「兼容格式」，意为和对象存储保持兼容。

导入的文件，使用上要注意：

• 导入的文件同样占用文件系统空间，会计入目录配额，并且参与计费；
• 可以修改文件名、权限，但无法修改对象存储数据。换言之，不论做何种操作，对象存储上的原始对象都不会变；
• 同样地，删除这些文件也只会删除其元数据，并不会真正删除对象存储中的源文件；
• 导入进 JuiceFS 的元数据，也不支持回收站，如果在 JuiceFS 中删除导入的文件，并不会在回收站找到他们，如果需要恢复，只能再次执行导入；
• 导入的文件和 JuiceFS 自身的文件没有明显区别，如果要辨别一个文件是否属于导入文件，可以使用 juicefs info，如果在 info 的输出中关注 object 字段（而没有 chunks 表格），来识别兼容格式。

缓存

从 JuiceFS 5.0 开始，导入的文件同样支持本地缓存和分布式缓存。虽然导入的文件并没有真正写入 JuiceFS 文件系统、经过 JuiceFS 的分块格式化，但实际缓存到本地盘时，仍然会被拆分为数据块（大小为文件系统的 block size），因此对于导入文件的缓存的使用和管理方式，和正常写入 JuiceFS 文件系统中的文件没有任何不同。

信息

特别地，如果需要将「外部桶」中的对象导入文件系统，请使用 5.2.20 或以上版本，才能支持缓存。

# 参数中不包含桶名，表示直接从文件系统所关联的桶导入文件
juicefs import / /jfs/imported

# 如果参数中包含同名（或者完整 Endpoint），则视为外部桶
# 这种导入方式需要 5.2.20 以上版本才支持缓存
juicefs import BUCKET/prefix /jfs

使用 JuiceFS 的缓存功能加速导入文件的读取时，需要注意一致性问题：由于导入的对象本身并不受 JuiceFS 管理，如果对象发生了修改，而没有重新导入到 JuiceFS 的话，因为可能存在旧版本的缓存，不确保能读到最新的数据。因此如果导入 JuiceFS 以后，对象发生了变更，则需要再次导入。而已有的缓存数据，会根据导入的对象的修改时间自动失效。确保能读到修改过后的数据。

因此，对于需要反复修改的对象，建议将数据整体迁移到 JuiceFS，推荐用 juicefs sync 将数据写入 JuiceFS，但归功于 JuiceFS 的 POSIX 兼容性，你也可以用任意其他工具。

观测

取决于使用方式，一个文件系统可能同时包含通过 JuiceFS 的「原生格式」写入的分块存储的文件，也可能存在直接从对象存储导入的完整文件，我们建议将这两类文件妥善管理，用不同的目录加以区分、避免混淆。如果未能恰当管理，可以使用 juicefs info 命令加以判断。

原生格式的文件是分块存储的，因此 object 字段会详细罗列每一个关联的对象存储块，他们都组织在 chunks 目录下，就像这样：

$ juicefs info a
a :
  inode: 51
  files: 1
   dirs: 0
 length: 2 Bytes
   size: 4.00 KiB (4096 Bytes)
   path: /a
objects:
+------------+-------------------------------+------+--------+--------+
| chunkIndex |           objectName          | size | offset | length |
+------------+-------------------------------+------+--------+--------+
|          0 | poc/chunks/B5/54/54450357_0_2 |    2 |      0 |      2 |
...
+------------+-------------------------------+------+--------+--------+

如果文件是从对象存储直接导入而来，object 字段不会包含表格样式的数据块列表，而是只有一个对象存储文件路径。

$ juicefs info b
b :
  inode: 26
  files: 1
   dirs: 0
 length: 36 Bytes
   size: 4.00 KiB (4096 Bytes)
   path: /imported/b
 object: /mybucket/b
  mtime: 2025-02-12 14:52:19 +0800 CST

按需导入

从 5.1.3 开始，JuiceFS 支持「按需导入」，该功能在上一小节 import 的基础上，允许用户将整个对象存储桶映射为一个 JuiceFS 文件系统，并且在访问时才 list 对象存储、导入元数据。相比定期 import 的流程，按需导入的模式有以下好处：

• 不再需要定期 list，仅在访问发生时才现场解析，能够大大减轻对象存储的 list 压力；
• 只有访问过的部分，才会在 JuiceFS 文件系统建立元数据，未访问的路径，不会进行对象存储扫描并映射到 JuiceFS 中，因此也不会参与计费。计费策略上相当于「用多少，花多少」；
• 对象存储桶的文件量太大，完整导入整个桶会带来元数据较大内存压力，可以用按需导入的方式来兼顾。

注意

按需导入是一个实验性功能，其用法和设计都有可能面临未来调整，如果你有意进行试用和评估，请务必联系 Juicedata 工程师，和我们充分沟通，并与我们一起开展测试。

使用流程

该功能只支持从文件系统关联的桶导入文件，因此必须在创建文件系统之初，就将待导入的桶设置为文件系统的关联桶（在 JuiceFS Web 控制台的文件系统设置页面操作）。满足这个前提以后，才能在服务器上操作挂载。

下方命令中，--source=/ 的含义是将对象存储的根路径映射到文件系统的根。目前这个参数的写法是固定的，不支持设为 / 以外的值。

juicefs mount myjfs /jfs --source=/

挂载完毕以后，ls 便能看到对象存储的顶级目录：

$ cd /jfs
$ ls -alh
...
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir1
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir2
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir3

注意上方目录的 777 权限，JuiceFS 将目录权限赋予了特殊含义：凡是 777 的目录，都还没被实际访问过，因此并未完成元数据导入。但只要以任何形式访问这些目录下的内容，JuiceFS 就会立刻扫描对象存储、快速建立对应的文件目录结构。建立完成以后权限会发生变化：

# 用任何方式访问 dir1 下方的文件，既可以 cd 进入，也可以直接访问特定文件
$ ls dir1/file.txt

# 目录访问过以后，权限会从 777 变为 555
$ ls -alh
...
dr-xr-xr-x  5 root root  16K Nov 11 17:47 dir1
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir2
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir3

因此，在按需导入的工作流中，可以依据目录权限来判断加载的情况：777 代表尚未加载，如果不是 777，则说明目录已经导入元数据。可以读取或者运行预热。请勿自行篡改目录权限，否则会干扰按需导入的正常工作。

写入文件（不推荐）

和上方的 import 命令类似，你无法修改从对象存储中直接导入的文件。如果导入以后删除了这些文件，也只会删除他们在 JuiceFS 中的元数据索引，并不会对桶中数据产生任何影响。

不过事实上，一个按需导入的文件系统，仍然可以像正常的 JuiceFS 文件系统一样写入新文件，写入的文件并不是以完整文件格式直接上传对象存储，而是用 JuiceFS 标准的分块格式写入到对象存储桶的 /[volume-name]/chunks/ 目录下。因此如果确实进行了写入，对象存储桶里将会存在两种形式的数据：用于导入 JuiceFS 的完整文件，以及通过 JuiceFS 写入的分块格式数据块。

我们目前不推荐在按需导入的文件系统中写入文件，这不仅会增加管理复杂度，需要辨别哪些文件是导入的、不支持修改，哪些文件是通过原生的分块格式写入，还会有数据丢失的风险：待元数据过期，下次扫描、重建元数据的时候，将会删除多余的文件和目录，引发数据丢失。

元数据有效期

导入以后，对象存储一侧的文件仍可能面临增删或修改，可以用 --refersh-interval 这个参数控制元数据有效期，默认 1 分钟过期（--refresh-interval=1m）。也就是说，在访问过一个目录 1 分钟后，再次 ls 时，会出现卡顿情况，这个卡顿就是 JuiceFS 在重新扫描对象存储对应的路径、重建元数据。

默认 1 分钟的过期时间，可能会造成访问的时候经常有卡顿现象，可以考虑将有效期设置更长时间，牺牲时效性来换取更快的使用体验：

juicefs mount myjfs /jfs --source=/ --refresh-interval=1h

如此设定后，导入的元数据会在 1 小时后过期。过期以后再访问，比如运行 ls，或者 lookup 一个不存在的文件时，都会触发更新元数据。当多个客户端同时要进行扫描时，会使用文件锁确保只有一个客户端在做扫描，避免重复扫描给对象存储造成更大压力。取决于数据量大小以及对象存储的 list 性能，扫描的过程仍然可能会卡住一段时间，元数据再次建立以后，就又恢复先前的高速访问。因此用户需要确定对象存储桶的更新频率，然后根据业务对时效性的要求来恰当设置更新间隔。

如果业务对访问延迟敏感、无法接受元数据过期以后首次访问的卡顿，那么也可以启用异步刷新，访问的时候会异步触发重新扫描，不等待重建完成。

juicefs mount myjfs /jfs --source=/ --refresh-interval=1h --refresh-in-background

需要注意，开启了异步刷新后，就不再满足由 --refresh-interval 定义的时效性，以上方的一小时设置为例，如果启用了异步更新，那么过期后 ls 不保证能看到过去一小时新增的文件，只有同步更新模式才能保证这一点。

计费策略

按需导入是真正意义上的「用多少、花多少」，虽然把整个对象存储桶都映射到文件系统，但只有在 JuiceFS 文件系统重建立了元数据的部分，才真正纳入文件系统用量、参与计费。

比方说：Bucket 里含有 1TB 数据，分布在若干个子目录中（确切地说，是分布在若干个前缀下面，对象存储并没有“目录”概念），但是只有一个 50GB 的目录被实际访问了，那么文件系统的用量是 50GB，会按照 50GB 进行收费。

如果随着业务进展，这 50GB 文件不再需要使用，那么用户直接从文件系统中删除对应的子目录，就能立刻停止对他进行计费。

目录被删除以后，对象存储桶中数据不会有任何变化，只是这个目录本身在 JuiceFS 文件系统中不可见。如果需要在文件系统中恢复这个目录，需要等元数据过期之后，再次 ls 其父目录，就能触发新一轮扫描、重建该目录。重建完毕以后，目录会回到 777 的初始化状态，并不占用文件系统空间、也不参与计费。只有实际打开这个目录以后，才会对目录内的对象进行扫描重建。

总结下来，在按需导入的文件系统中，对于用不到的数据，可以放心删除，不会影响对象存储中的数据。而如果删除之后发现对应的数据需要再次使用，则等元数据过期后重新访问，就能还原出来。

缓存数据和预热

运行预热命令（juicefs warmup）会将已经建立元数据的部分进行预热，也就是权限为 555 的目录。如果对权限为 777 的目录进行预热，那么由于尚未扫描导入，JuiceFS 客户端不会下载任何其中的数据。这样的设计允许用户可以完全按需下载所需的数据，访问过哪些目录，预热的时候就会下载其中的数据，没访问过的目录就不会下载。这样的用法足够灵活，因此用户也必须将需要预热的目录提前进行访问、建立元数据。

用上方的案例进行示范：

$ ls -alh
...
dr-xr-xr-x  5 root root  16K Nov 11 17:47 dir1
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir2
drwxrwxrwx  2 root root 4.0K Nov 11 17:35 dir3

# 对 777 目录进行预热，不会下载任何数据
$ juicefs warmup dir3

# 只有提前访问过、建立了元数据的目录，才会真正进行预热
$ juicefs warmup dir1

和「导入」命令一样，按需导入的文件支持本地和分布式缓存，因此使用体验完全一致，请阅读链接所指的小节了解详细情况。

转存

功能启用以后，文件会在指定时间后被转存成完整文件、保存在对象存储。

使用场景

• 文件由 JuiceFS 写入，但希望后续也能通过对象存储直接读取，对接云上生态。之所以强调直接读取，是因为 JuiceFS 也提供 S3 接口，如果你只是需要为文件系统暴露 S3 接口，应该使用 S3 网关。

• 希望直接使用对象存储的生命周期管理、归档功能，将冷数据进行归档处理。归档的数据要求是已经合并转存为完整文件的状态，可以脱离 JuiceFS 元数据直接使用。

  注意，该场景的重点仍然是脱离 JuiceFS 使用，如果你仅仅是希望实现在 JuiceFS 中读写冷热数据，可以用 --storage-class 来为客户端指定存储级别，这是更合适的方式。

• 由于数据合规性条例，必须在对象存储上保存原始文件。

• 其他需要将对象存储数据方便地脱离 JuiceFS 使用的情况。

不应使用的场景

转存是针对少数极特殊场景推出的实验性功能，如果你的场景并未在上方列出，那么绝不应该使用此功能。启用转存会给文件系统带来一些重要的限制（比如转存后的文件是只读的），继续阅读下方的功能概览以了解。

举例说明，下列场景就不应该使用转存功能：

• 需要用 S3 接口访问 JuiceFS 文件系统。我们为这种需求提供 S3 网关功能，让文件系统可以通过 S3 API 访问，完全不需要使用转存功能。
• 冷热数据分离读写。我们的客户端支持指定存储级别，可以在 juicefs auth 指定 --storage-class 参数，来指定客户端的存储级别，实现在同一个文件系统内写入不同存储级别的文件。

功能概览

从对象存储的文件列表观察转存过程，效果如下：

# 转存前
mybucket/
├── chunks
│   ├── 41
│   │   └── 1
│   │       ├── 1000001_0_4194304
│   │       └── 1000001_10_4194304
│   ├── 43
│   │   └── 1
│   │       ├── 1000003_0_4194304
...

# 转存后，文件会被原样写入对象存储，保留目录结构，原本分块格式的数据块会被删除
mybucket/
├── bigfile1.tar.gz
├── chunks
├── dir/bigfile2.tar.gz

由于「转存」的目的是脱离 JuiceFS 分块格式，在对象存储上进行「原样存储」，因此正如上方所示范的，文件会按照文件系统里的目录结构进行存储，因此如果开启转存，文件系统必须要独占对象存储桶，决不能一桶多用（也不能将该桶用于其他 JuiceFS 文件系统），否则将容易发生冲突、甚至导致数据丢失。

转存后的文件，也不再支持内容修改，写操作会直接报错提示没有权限。虽无法编辑，但可以进行 mv，该命令在 JuiceFS 中会被解释为「跨设备拷贝 + 删除」，相当于从兼容格式将文件正常读出，然后再以分块格式写回 JuiceFS，成为一个全新的文件，然后再删除源文件。由于 mv 将文件从兼容格式重新转为了分块格式，因此文件又可以正常编辑了，直到等待了指定时间以后，被再次转存。

启用转存的文件系统，所有目录再创建一段时间之后（包括空目录），就不能移动（mv），只能删除重建。

注意

转存文件不支持回收站，删除以后不会出现在回收站、无法恢复，对象存储一侧也会通过客户端后台任务进行异步清理。

转存功能目前处于内测阶段，如有需要请联系 Juicedata 工程师，我们会为你名下指定的文件系统启用该功能。启用完毕以后，在文件系统的设置页面设置好转存等待时长（一旦开启无法撤销），就能开始使用该功能。

缓存

兼容格式的文件支持本地缓存和分布式缓存。虽然转存文件已不再是分块格式，但实际缓存到本地盘时，仍然会被拆分为数据块（大小为文件系统的 block size），因此对于转存文件的缓存的使用和管理方式，和分块格式没有任何不同。

但也需要注意，转存完成后，由于元数据变化，文件已有的缓存会失效，可能需要再次预热来重新建立缓存。