JuiceFS 云服务快速上手指南
这是一份针对 JuiceFS 云服务 编写的快速上手指南。如果你使用的是 JuiceFS 社区版,请访问社区版文档。
概念速览
JuiceFS 是由对象存储和数据库组合驱动的分布式文件系统,「对象存储」用于数据存储,「数据库」用于元数据存储,由此而组成的文件系统支持在任何联网的服务器上共享挂载使用。
JuiceFS 云服务提供开箱即用的自研数据库,因此你只需准备对象存储。
系统要求
- 对象存储:你的所有数据都会存储在你自己的对象存储中,JuiceFS 云服务会在创建文件系统时自动帮你创建并绑定对象存储 Bucket,你需要提前准备目标平台的 对象存储 API 访问秘钥。
- Python:请确保已经安装了 Python,建议使用 Python>=3.5,最低支持 Python 2.7。
- FUSE:JuiceFS 通过 FUSE 实现对 POSIX 的兼容,因此使用前请确保系统已经安装了 FUSE:
- 大多数 Linux 发行版已经内置了 FUSE 模块,可以用
fusermount -V
检查版本,如果内核并未编译或加载该模块,请查阅发行版手册处理。 - macOS 系统请安装 macFUSE,Apple silicon 设备需参考「在搭载 Apple 芯片的 Mac 上更改启动磁盘安全性设置」来安装内核扩展。
- 大多数 Linux 发行版已经内置了 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
- wget
curl -L https://juicefs.com/static/juicefs -o /usr/local/bin/juicefs && chmod +x /usr/local/bin/juicefs
wget 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 启动:
[Unit]
# JuiceFS mount 对应的 systemd unit 一般叫做 jfs.mount
# 可以用这个命令来确认:systemctl list-units | grep mount
After=network-online.target firewalld.service containerd.service jfs.mount
macOS
创建
~/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>加载上一步创建的文件,测试加载是否成功:
launchctl load ~/Library/LaunchAgents/com.juicefs. VOL_NAME.plist
launchctl start ~/Library/LaunchAgents/com.juicefs.VOL_NAME
ls $MOUNTPOINT如果没有挂载成功,可以在上述
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,然后直接用 cp
或 rsync
等工具将文件复制到 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
客户端进程,也可以等它自己退出。
删除文件系统
如果你需要删除云服务中创建的文件系统,出于数据安全的考虑,删除时应严格遵循以下步骤:
- 备份文件系统中所有数据;
- 在所有主机上卸载文件系统;
- 在官网控制台中删除文件系统;
- 删除文件系统相关的配置文件:
rm $HOME/.juicefs/$VOL_NAME.conf
。