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 版本客户端暂未开放下载,如有使用需求,请联系我们

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

创建文件系统

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

表单中各项设置,在这里详细介绍:

  • 文件系统名:你的 JuiceFS 文件系统名称,以小写字母开头,仅可包含小写字母、数字与连字符(-),长度 3-40 个字符。
  • 服务器区域:你的对象存储所在的平台及区域,JuiceFS 会根据你的选择为你匹配速度最快的元数据存储节点。
  • 回收站保存时间:回收站内文件的保存天数,设置为 0 以禁用此功能。回收站内文件仍参与计费,阅读文档了解更多。
  • 高级选项 Bucket 名称:该文件系统使用的存储桶,可以使用已创建好的桶,如果桶不存在,JuiceFS 会尝试在挂载时创建(需要挂载时提供的 Access Key/Secret Key 具有创建桶的权限)。特别地,对于腾讯云 COS,请按照页面提示在 Bucket 后追加 APPID
  • 高级选项 块大小:对象存储文件块(Block)大小,考虑到不少对象存储都将 4MB 作为内部存储块大小,4MB 是一个较好的默认值,在大部分场景下都能获得更好表现。关于 JuiceFS 如何切分存储文件请详读「JuiceFS 如何存储文件」
  • 高级选项 压缩:用于指定文件系统的压缩算法,压缩能有效节约对象存储空间占用,但也对性能有一定影响。该特性默认开启,但如果你的数据格式(如 Parquet、ORC)已经经过压缩处理,请关闭该特性,否则会造成不必要的读放大。

创建完成,你将被重定向到设置页面,按照说明挂载新创建的文件系统。请特别留意页面中加粗显示的 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,然后直接用 cprsync 等工具将文件复制到 JuiceFS。而如果文件量实在过于巨大,推荐使用 Juicesync 进行并发拷贝,能够有效提速。

卸载文件系统

注意

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

使用 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