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.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，然后直接用 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 客户端进程，也可以等它自己退出。

删除文件系统​

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

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