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。
    • 对于腾讯云 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，具体请参考「问题排查方法」。

检查文件系统使用量及目录大小​

你可以通过 df 命令来查看文件系统使用量，以及 ls -l 命令来查看目录大小（注意不能使用 du 命令），具体说明请参考「容量与配额」文档。

验证文件系统​

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

juicefs bench /jfs

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

如果在验证文件系统的过程中遇到任何问题，请先参考「问题排查方法」文档。

客户端升级与平滑重启​

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

juicefs version --upgrade

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

juicefs version --upgrade --restart

阅读客户端架构了解平滑重启的原理。

开机自动挂载​

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

Linux​

将挂载信息写入 /etc/fstab，便能实现开机自动挂载。JuiceFS v4.8 及以上版本内置了自动更新 fstab 的功能（通过 --update-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

导入文件​

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

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

卸载文件系统​

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

umount /jfs

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

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

umount -l /jfs

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

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