Skip to main content

JuiceFS 云服务快速上手指南

提示

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

概念速览​

JuiceFS 是由对象存储和数据库组合驱动的分布式文件系统，「对象存储」用于数据存储，「数据库」用于元数据存储，由此而组成的文件系统支持在任何联网的服务器上共享挂载使用。

JuiceFS 云服务提供开箱即用的自研数据库，因此你只需准备对象存储。

系统要求​

  • 对象存储：你的所有数据都会存储在你自己的对象存储中，JuiceFS 云服务会在创建文件系统时自动帮你创建并绑定对象存储 Bucket，你需要提前准备目标平台的 对象存储 API 访问秘钥。
  • Python：请确保已经安装了 Python，建议使用 Python>=3.5，最低支持 Python 2.7。
  • FUSE：JuiceFS 通过 FUSE 实现对 POSIX 的兼容，因此使用前请确保系统已经安装了 FUSE：

Windows 注意事项​

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

另一方面，你也可以通过 Windows Subsystem for Linux（WSL）在 Linux 子系统中使用 JuiceFS 云服务客户端，安装和使用流程与 Linux 无异。

创建文件系统​

JuiceFS 云服务在官网控制台创建文件系统，新用户请先访问 JuiceFS 官网注册。登录到控制台，点击「创建文件系统」按钮。

其中，服务器区域是你的对象存储所在的平台及区域，JuiceFS 会根据你的选择为你匹配速度最快的元数据存储节点。

注意

如果列表中没有你想要的云平台或区域，请参照提示信息提交反馈，我们的工程师会尽快支持。

你可以创建任意数量的文件系统，每个文件系统需要绑定一个对象存储 Bucket。

默认由 JuiceFS 云服务客户端自动创建和绑定 Bucket，你也可以在「创建文件系统」时点击「高级选项」绑定一个已创建好的 Bucket。此外，你还可以在「高级选项」中调整文件系统的压缩算法，压缩特性默认开启，如果你存储的数据格式（如 Parquet、ORC）已经经过压缩处理请关闭 JuiceFS 的压缩特性。

注意

如果你使用的是腾讯云的 COS 对象存储，必须点击「高级选项」修改自动生成的 Bucket 名，为其带上 APPID 后缀，完整的格式为 <bucket>-<APPID>。点击「这里」查看如何获取腾讯云的 APPID。

创建完成，你将被重定向到设置页面，按照说明挂载新创建的文件系统。请特别留意页面中加粗显示的 Token，每个文件系统有唯一的 Token，挂载文件系统时需要使用。

挂载文件系统​

已创建的文件系统可以在任何联网的计算机上挂载，像本地磁盘一样使用。但对于生产场景，我们推荐在与对象存储同平台同区域的云服务器上挂载 JuiceFS，一方面可以使用云平台的内网通道获得更快的速度和更低的时延，另一方面也能节约对象存储公网访问的流量开销。

安装客户端​

注意

「云服务客户端」不同于「社区版客户端」，如果需要同时使用二者，为了避免名称冲突，请修改程序名称进行区分。例如，可以将云服务客户端改名为 juicefs-cloud。

Linux、macOS 可用下方命令安装 JuiceFS 云服务客户端。示例命令中的安装路径依照惯例设置为 /usr/local/bin，你也可以根据实际情况进行修改。

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

在执行以上命令的过程中如果遇到了 Permission denied 错误，请切换成 root 用户执行。

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

挂载​

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

sudo juicefs mount $VOL_NAME $MOUNTPOINT

请将 $VOL_NAME 替换成「创建文件系统」时设置的文件系统名，将 $MOUNTPOINT 替换成 JuiceFS 挂载点的路径。

客户端将会交互式地询问一系列认证信息，你需要文件系统的 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。再次挂载时会自动读取，无需重复输入。

验证无误后会自动完成文件系统挂载，客户端会以守护进程的形式运行在后台，相关日志会记录到 syslog (Facility: LOG_USER) 或 /var/log/juicefs.log，具体请参考「故障诊断和分析」。

客户端升级与平滑重启​

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

juicefs version --upgrade

客户端升级以后，还需要重新挂载，如果你已经在使用 JuiceFS>=4.6，可以通过 --restart 用一行命令同时完成客户端升级与平滑重启：

juicefs version --upgrade --restart

挂载命令本身也支持平滑重启（需要 Python>=3.3），直接运行 juicefs mount 命令即可，在 Python>=3.3 下，该特性会自动生效。

sudo juicefs mount myjfs /jfs
# 确认 JuiceFS 在以 Python>=3.3 执行
sudo ps -ef | grep juicefs
# 为了验证平滑重启起效，使用不同的挂载选项进行重新挂载
sudo juicefs mount myjfs /jfs --attrcacheto=3
# 挂载成功以后，检查新的挂载选项是否生效
sudo ps -ef | grep juicefs

对于更老版本的 Python，只能通过重新挂载才能使升级起效了。请见「卸载文件系统」。

开机自动挂载​

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

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 import 将这些文件的元数据导入到 JuiceFS：

juicefs import BUCKET-NAME/PREFIX TARGET-DIR-IN-JUICEFS

比如，将 my-bucket 中所有以 my-files 开头的文件导入到 /jfs/my-files 文件夹中：

juicefs import my-bucket/my-files /jfs/my-files

需要注意，juicefs import 的本质是将目标文件的元数据信息写入 JuiceFS 的元数据存储引擎，从而纳入 JuiceFS 的管辖，该操作并不会实际复制任何文件，文件仍原样保存在对象存储里。换言之，对于导入的文件，如果在文件系统中更改文件名、权限等属性，并不会被同步到对象存储中的源文件。同样地，删除这些文件也只会删除其元数据，并不会真正删除对象存储中的源文件。

此外，import 导入的文件也不支持缓存，无法利用到 JuiceFS 强大的缓存设计。

综上所述，如果用 juicefs import 导入对象存储中已有的文件，虽然能够正常使用，但却无法获得一个高性能的体验。如果对这部分数据追求最好的性能效果，建议将数据整体拷贝到 JuiceFS，我们推荐用 Juicesync 这款工具，但归功于 JuiceFS 的 POSIX 兼容性，你也可以用任意其他工具。

卸载文件系统​

注意

强制卸载使用中的文件系统可能导致数据丢失。执行操作前，请确认你已经备份了重要数据。

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

umount /jfs

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

对于 Linux 发行版，可以使用 -l 选项执行延迟卸载（立即卸载文件系统，但会等到设备不再繁忙时才清理资源）：

umount -l /jfs

对于 macOS，使用 diskutil 进行强制卸载：

diskutil unmount force /jfs

macOS 还可以在 Finder 左边栏 - 设备（Locations）找到本机，然后直接在 Finder 中点击弹出设备按钮来进行卸载。

最后，你可以手动杀掉 juicefs 客户端进程，也可以等它自己退出。

删除文件系统​

如果你需要删除云服务中创建的文件系统，出于数据安全的考虑，删除时应严格遵循以下步骤：

  1. 备份文件系统中所有数据；
  2. 在所有主机上卸载文件系统；
  3. 在官网控制台中删除文件系统；
  4. 删除文件系统相关的配置文件：rm $HOME/.juicefs/$VOL_NAME.conf。
最后于 更新