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.juicefsjuicefs 可执行文件的软链接,操作系统解析 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