Skip to main content

快速上手

提示

这是一份针对 JuiceFS 企业版编写的快速上手指南。如果你使用的是 JuiceFS 社区版，请访问社区版文档。

如果你使用 JuiceFS 企业版（私有部署），阅读的时候需要注意，文档中的控制台链接均指向云服务控制台，你需要替换为实际的私有部署集群的控制台地址。私有部署和云服务所使用的软件完全相同，因此本文档站的内容同样适用于私有部署。

在安装和开始使用之前，需要确认以下事项：

  • 软件架构：简单阅读「技术架构」，就能迅速了解各组件的角色。
  • 对象存储：你的所有数据都会保存在你所选择的对象存储中，因此需要提前准备对象存储 API 访问秘钥，挂载客户端时将会用到该信息。
  • Python：确保已经安装了 Python，为了享受到平滑升级等高级功能，建议使用 Python >= 3.5，最低则支持 Python 2.7。
  • FUSE：JuiceFS 通过 FUSE 实现对 POSIX 的兼容，因此使用前请确保系统已经安装了 FUSE：

创建文件系统​

你可以创建任意数量的文件系统，每个文件系统需要绑定一个对象存储 Bucket。访问并登录 JuiceFS 控制台，然后点击「创建文件系统」按钮开始创建流程。

create file system

表单中各项设置，在这里详细介绍：

  • 文件系统名（Volume Name）：每个文件系统的唯一标志，挂载文件系统时需要提供该名称。

  • 对象存储区域（Region）：对象存储所在的平台及区域，选择距离自己应用主机最接近的地域来获得最佳性能。

    如果你希望使用的对象存储服务并未在这里列出（比如 Cloudflare R2），可以选择 S3，然后在 Bucket 处填写完整 Endpoint，这样便能够使用任意 S3 兼容的对象存储服务。

  • 回收站保存时间（Trash Expiration Time）：回收站内文件的保存天数，设置为 0 以禁用此功能。回收站内文件仍参与计费，阅读文档了解更多。

  • ​高级选项 Bucket（或者完整 Endpoint）：可以使用已创建好的桶，如果桶不存在，JuiceFS 会尝试在挂载时创建（需要挂载时提供的 Access Key／Secret Key 具有创建桶的权限）。需要注意：
    • 如果希望使用其他并未列出的支持 S3 的对象存储服务，则在 Bucket 字段填写完整 Endpoint。以 R2 为例：https://<accountid>.r2.cloudflarestorage.com/mybucket；
    • 该字段含义等同命令行客户端的 --bucket 参数，如果填写完整 Endpoint，则无法享受到内外网域名的智能探测功能（仅对区分内外网域名的对象存储服务生效，例如阿里云 OSS），阅读参数说明以详细了解；
    • 对于腾讯云 COS，推荐在 Bucket 后追加 APPID，形如 xxxxx-123456789。如果没有填写 APPID，挂载时将会需要交互式录入信息。
  • ​高级选项 块大小（Block Size）：对象存储文件块（Block）大小，考虑到不少对象存储都将 4MB 作为内部存储块大小，4MB 是一个较好的默认值，在大部分场景下都能获得更好表现。关于 JuiceFS 如何切分存储文件请详读「JuiceFS 如何存储文件」。
  • ​高级选项 压缩（Compression）：用于指定文件系统的压缩算法，压缩能有效节约对象存储空间占用，但也对性能有一定影响。该特性默认开启，但如果你的数据格式（如 Parquet、ORC）已经经过压缩处理，请关闭该特性，否则会造成不必要的读放大。
  • ​私有部署 单分区限制（Single Zone Limited）：如果你已经在使用多分区集群，但集群中的某些文件系统规模较小，不需要多分区级别的性能，那么启用该选项将会将文件系统限制在单分区上（也就是 0 号分区）。这样的特殊对待能够让这些相对小规模的文件系统管理起来更简单。

创建完成，你将被重定向到设置页面，按照说明挂载新创建的文件系统。页面会加粗显示文件系统的客户端令牌，也就是 Token，客户端挂载文件系统时，正是使用该令牌，通过控制台进行认证、获取挂载相关的配置。

how-to-mount-fs-zh

挂载文件系统​

为了挂载 JuiceFS，节点需要能够访问元数据服务，以及对象存储。对于生产环境，挂载点需要与元数据、对象存储服务位于同一个区域，才能获得最好的时延和性能。

Linux、macOS​

Linux、macOS 可用下方命令将客户端安装至 /usr/local/bin（也可根据实际情况替换）。注意下载地址仅适用于云服务，私有部署用户需要访问文件系统的设置页面，按照页面提示进行下载安装。

curl -L https://juicefs.com/static/juicefs -o /usr/local/bin/juicefs && chmod +x /usr/local/bin/juicefs

在执行命令的过程中如果遇到了 Permission denied 错误，需要使用 sudo 或切换成 root 用户执行。

下载完毕后在命令行运行 juicefs --help，如果正常打印出帮助信息，就表示客户端安装完成了。如果报错 command not found，请检查你的系统环境变量设置，确保将 /usr/local/bin 加入 PATH。

挂载文件系统的流程如下，注意命令需要 root 权限执行，普通用户身份会遭遇某些不便。

sudo juicefs mount $VOL_NAME $MOUNTPOINT

$VOL_NAME 需要替换成「创建文件系统」时设置的文件系统名，$MOUNTPOINT 则替换成实际挂载的路径，例如 /jfs。

客户端将会交互式地询问一系列认证信息，你需要文件系统的 token，以及对象存储 API 密钥（确保对 Bucket 有完全操控权限）。

$ sudo juicefs mount myjfs /jfs
Token for myjfs: xxxxx
Access key ID for oss://juicefs-myjfs: xxxxx
Access key secret for oss://juicefs-myjfs: xxxxx
OK, myjfs is ready at /jfs.

关于交互式录入，需要注意以下几点：

  • 只有首次挂载文件系统时需要提供认证信息，这些信息会被保存在 $HOME/.juicefs/$VOL_NAME.conf。再次挂载时会自动读取，无需重复输入；
  • 交互式操作不便于脚本自动挂载，因此对于自动化场景，需要提前运行 juicefs auth 生成客户端配置文件。关于自动化批量挂载，还可以阅读自动化部署了解更多常用实践；
  • 使用 5.1.6 或者更新版本客户端，可以配合 Web 控制台，将对象存储的认证信息（Access Key、Secret Key）储存在控制台的文件系统设置中，客户端认证时则可跳过、不再提供这部分信息。如果在你的环境中有大量不同用户挂载 JuiceFS 文件系统，可以考虑使用这种方法管理对象存储的认证信息。

验证无误后会自动完成文件系统挂载，客户端会以守护进程的形式运行在后台，日志路径默认为 /var/log/juicefs.log，具体请参考「问题排查方法」。

Windows​

从 5.2 开始，JuiceFS 开始公测 Windows 客户端。如果不希望使用 Beta 版本，也可以通过 WSL 2 在 Linux 子系统中使用 JuiceFS 云服务客户端，安装和使用流程与 Linux 无异。但由于 WSL 2 需要硬件虚拟化，云主机往往无此条件，请提前确认。

点此下载 Windows 客户端，除此之外还应该安装 WinFsp 才能实现对 FUSE 的支持。

安装完毕以后，客户端的前台挂载需以管理员模式运行 CMD 或 PowerShell 程序，并打开 JuiceFS 客户端检查是否可以正常执行。

PS C:\> ./juicefs.exe -V
juicefs version 5.2.1 (2025-05-28 6ebc8e9)

执行 auth 子命令来从控制台获取配置文件，配置文件将默认生成在 C:\Users\<username>\.juicefs 下。

PS C:\> .\juicefs.exe auth juicefs --token xxx --access-key xxx --secret-key xxx

如果你正在使用 JuiceFS 私有部署，那么还需要额外设置企业版控制台对应的访问地址：

PS C:\> .\juicefs.exe auth juicefs --token xxx --access-key xxx --secret-key xxx --console-url http://<onprem-console-ip>

认证完毕以后，执行挂载命令：

PS C:\> ./juicefs.exe mount juicefs J:
2025/05/29 12:34:48.254250 juicefs[36668] <INFO>: Running as Windows system service. [[email protected]:839]
2025/05/29 12:34:50.341701 juicefs[36668] <INFO>: Juicefs system service started successfully. [[email protected]:933]

挂载完毕以后，客户端的日志路径默认为 C:\Users\<username>\AppData\Local\juicefs.log，检查该日志来判断挂载点是否正常工作。

常见误区​

如果你是首次接触 JuiceFS，它和你以往使用的文件系统可能有不少区别，本节罗列一些容易引发误会的地方。

计费​

  • JuiceFS 云服务和企业版提供的是元数据服务，因此收取的是元数据费用，并不包含对象存储中的数据费用。如果你使用公有云提供的对象存储服务，请额外注意这部分服务的费用；
  • JuiceFS 每个月会定期发送账单，但实际统计粒度为小时，系统会每小时上报用量并以此生成每月账单。如果在小时统计周期内创建并迅速删除了临时文件，这部分用量将不会计入账单。

使用和管理​

  • 不能用 du 命令来统计 JuiceFS 文件系统的目录用量，因为目录大小已经是递归统计值，包含了目录中所有文件的大小并实时更新，可以直接在命令行用 ls -alh 或通过 Web 控制台查看。如果对 JuiceFS 目录运行 du，得出的将是一个经过重复统计的错误值。这个行为在「容量与配额」有更详细的说明；
  • JuiceFS 默认启用了「回收站」，因此从文件系统里删除文件，会被移入回收站，不会从对象存储立刻删除；
  • 就算清空了回收站，对象存储里的数据块也未必能及时释放。删除文件以后，对象存储块会通过客户端的后台任务进行异步删除，也就是说，必须有活跃的挂载点存在，回收站清理才能正常运作。

投入使用​

阅读本节内容，来确保刚刚创建的 JuiceFS 文件系统能够顺利地投入使用。

验证文件系统​

当挂载好文件系统以后可以通过 juicefs bench 命令对文件系统进行基础的性能测试和功能验证，确保 JuiceFS 文件系统能够正常访问且性能符合预期：

juicefs bench /jfs

运行 juicefs bench 命令以后会根据指定的并发度（默认为 1）往 JuiceFS 文件系统中写入及读取 N 个大文件（默认为 1）及 N 个小文件（默认为 100），并统计读写的吞吐和单次操作的延迟，以及访问元数据引擎的延迟。

如果各项性能满足预期，那么输出结果会全部以绿色表示。如果看到了黄色或者红色，则说明存在性能隐患，建议用 juicefs stats 或 juicefs profile 等命令进行进一步排查，详细请阅读「问题排查方法」。

导入数据​

如果你已经有大量文件在对象存储桶中，可以将其直接以只读的方式「导入」JuiceFS，导入的文件支持用 JuiceFS 的缓存功能进行读取加速，但无法通过 JuiceFS 对其进行修改（如果发生修改，则需再次导入）。如果你的场景适合这样的用法，请参考「导入对象存储已有文件」文档。

如果已有数据需要正常读写，那么建议整体迁移到 JuiceFS，如果数据量并不大，当然可以直接用 cp 或 rsync 等工具进行数据迁移。但如果数据量巨大，推荐使用 juicefs sync 进行并发拷贝，能够有效提速。

备注

通过挂载点导入大文件的时候，需要特别注意：

  • 如果对象存储的上传带宽不足，低速的顺序写可能产生很多碎片，建议调整挂载点挂载参数，增加 --flush-wait=60s，具体原因请阅读数据同步与碎片合并；
  • 导入数据的阶段可能发生许多预期之外的问题，包括上一点提到的产生过多碎片问题，或者单纯是操作错误导致数据需要重新导入。面对此种情况，删除或者被覆盖的数据同样会进入回收站予以保留，不恰当的回收站设置会引发对象存储费用增加。如果这对你的团队是个问题，建议在导入期间临时缩短回收站留存时长，或临时关闭回收站。

开机自动挂载​

在确认挂载成功，可以正常使用以后，可以参考本节内容设置开机自动挂载。

Linux​

将挂载信息写入 /etc/fstab，便能实现开机自动挂载。JuiceFS 客户端内置了自动更新 fstab 的功能：

# 需要 root 权限才能修改 /etc/fstab
$ sudo juicefs mount --update-fstab $VOL_NAME $MOUNTPONT
$ grep $VOL_NAME /etc/fstab
<VOL_NAME> <MOUNTPONT> juicefs _netdev 0 0
备注

CentOS 6 默认不会在启动时自动挂载网络文件系统，需要运行下面的命令启用自动挂载：

sudo chkconfig --add netfs

如果你有意自行控制，请注意：

  • 需要创建一个从 /sbin/mount.juicefs 到 juicefs 可执行文件的软链接，操作系统解析 fstab 时会调用 /sbin/mount.juicefs 命令。

  • 挂载命令所包含的各种参数，也需要在 fstab options 列加以声明，注意去掉 - 前缀，并将参数取值以 = 连接，举例说明：

    $ sudo juicefs mount --update-fstab $VOL_NAME $MOUNTPONT -b --max-uploads=1 --prefetch 2 --writeback myjfs /jfs -o max_read=3
    # -o 是 FUSE options，在 fstab 中需特殊对待
    $ grep $VOL_NAME /etc/fstab
    <VOL_NAME>  <MOUNTPONT> juicefs _netdev,background,max-uploads=1,max_read=3,prefetch=2,writeback 0 0

如果你为依赖 JuiceFS 的服务也设置了开机自启动，可能需要对启动顺序进行管理。以 Docker 为例，用以下 systemd unit file 来保证 JuiceFS 先于 Docker 启动：

/etc/systemd/system/docker.service.d/override.conf
[Unit]
# JuiceFS mount 对应的 systemd unit 一般叫做 jfs.mount
# 可以用这个命令来确认：systemctl list-units | grep mount
After=network-online.target firewalld.service containerd.service jfs.mount

macOS​

  1. 创建 ~/Library/LaunchAgents/com.juicefs.VOL_NAME.plist，注意大写单词需要做变量替换：

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
            <key>Label</key>
            <string>com.juicefs.VOL_NAME</string>
            <key>ProgramArguments</key>
            <array>
                    <string>/usr/local/bin/juicefs</string>
                    <string>mount</string>
                    <string>VOL_NAME</string>
                    <string>MOUNTPOINT</string>
            </array>
            <key>RunAtLoad</key>
            <true/>
    </dict>
    </plist>

  2. 加载上一步创建的文件，测试加载是否成功：

    launchctl load ~/Library/LaunchAgents/com.juicefs. VOL_NAME.plist
    launchctl start ~/Library/LaunchAgents/com.juicefs.VOL_NAME
    ls $MOUNTPOINT

  3. 如果没有挂载成功，可以在上述 plist 文件中添加日志相关配置：

    <key>StandardErrorPath</key>
    <string>/tmp/juicefs.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/juicefs.out</string>

    重新加载更新后的配置，查看输出：

    launchctl unload ~/Library/LaunchAgents/com.juicefs.VOL_NAME.plist
    launchctl load ~/Library/LaunchAgents/com.juicefs.VOL_NAME.plist
    cat /tmp/mycommand.out
    cat /tmp/mycommand.err

卸载文件系统​

使用 umount 命令，就能卸载文件系统：

umount /jfs

如果命令行返回 umount: /jfs: target is busy.，说明文件系统正在使用，可以使用 lsof $MOUNTPOINT 找到并结束相关应用的进程后再执行卸载。

对于 Linux 发行版，可以使用 -l 选项执行延迟卸载（立即卸载文件系统，已经打开的文件句柄释放之后，客户端才真正退出）：

umount -l /jfs

如果卸载出现异常，阅读「卸载错误」来排查并解决。

最后于 更新
在 X 上关注我们
在 Slack 上交流
加入微信用户群