Skip to main content

快速上手

提示

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

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

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

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

Windows 版本客户端暂未开放下载，如有使用需求，请联系我们。

另一方面，你也可以通过 WSL 2 在 Linux 子系统中使用 JuiceFS 云服务客户端，安装和使用流程与 Linux 无异。但由于 WSL 2 需要硬件虚拟化，云主机往往无此条件，请提前确认。

创建文件系统​

你可以创建任意数量的文件系统，每个文件系统需要绑定一个对象存储 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 可用下方命令将客户端安装至 /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。再次挂载时会自动读取，无需重复输入。

验证无误后会自动完成文件系统挂载，客户端会以守护进程的形式运行在后台，日志路径默认为 /var/log/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，具体原因请阅读数据同步与碎片合并；
  • 导入数据的阶段可能发生许多预期之外的问题，包括上一点提到的产生过多碎片问题，或者单纯是操作错误导致数据需要重新导入。面对此种情况，删除或者被覆盖的数据同样会进入回收站予以保留，不恰当的回收站设置会引发对象存储费用增加。如果这对你的团队是个问题，建议在导入期间临时缩短回收站留存时长，或临时关闭回收站。

客户端升级与平滑重启​

我们推荐持续更新 JuiceFS 客户端，以获得最新的改进与修复，用下方的命令便可以方便地获取最新版本客户端：

juicefs version --upgrade

客户端升级以后，还需要重新挂载，可以通过 --restart 用一行命令同时完成客户端升级与平滑重启：

juicefs version --upgrade --restart

mount 命令本身也支持平滑重新挂载，只需编辑挂载选项并重新运行 juicefs mount 即可：

# 确认挂载点已经存在
$ df -h /jfs
Filesystem     Size  Used Avail Use% Mounted on
JuiceFS:myjfs  1.0T   11G 1014G   1% /jfs

# 修改参数、重新挂载
# 如果忘记了当前的挂载命令，可以用上方示范的 ps 命令获取
$ juicefs mount myjfs /jfs --buffer-size=300
OK, myjfs is ready at /jfs.

# 检查运行时配置文件，确认参数生效
grep -i buffer /jfs/.config
提示
  • 平滑重启不支持修改 FUSE 参数。如果需要修改 FUSE 参数，必须卸载、重新挂载。
  • 平滑升级将会触发挂载点进行持久化操作，将缓冲区内未上传的数据尽快写入。在负载极高的场景下，可能无法在预期的时间内完成该操作，此时平滑升级将无法顺利工作，这种情况下，客户端日志会显示 mount point xxx is busy, stop upgrade 的错误信息。
  • 如果你仍在使用 4.9 或更早版本的客户端，守护进程是由 Python 启动的，这点和 5.0 及以上版本有别。对于这一类旧版客户端，需要使用 Python 3，才能享受到平滑重启和升级。

开机自动挂载​

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

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

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

最后于 更新
Follow us on X
Let's chat on Slack