Skip to main content

快速上手

注意：这是一份针对 JuiceFS 托管服务 编写的快速上手指南，如果你只是想了解社区版 JuiceFS 客户端的使用，请查看社区版文档。

系统需求

  • 操作系统：JuiceFS 支持 Linux、macOS 和 Windows 系统，通过 FUSE 实现对 POSIX 的兼容，使用前请确保已经安装了 FUSE。大多数 Linux 发行版已经内置了 FUSE 模块。macOS 系统建议安装 macFUSE 实现对 FUSE 的支持。Windows 系统建议安装 WinFsp 实现对 FUSE 的支持。
  • 存储：使用 JuiceFS，所有数据都会存储在你自己的对象存储中，你可以提前在云平台手动创建对象存储 Bucket，也可以让 JuiceFS 托管服务自动帮你创建对象存储 Bucket。不论采用那种方式，你都需要提前准备好 访问对象存储 API 的秘钥。
  • Python：JuiceFS 托管服务依赖 Python 环境，为了确保能够正常使用，建议检查你的操作系统是否安装了 Python 2.5+ 或 Python 3.x。

创建文件系统

JuiceFS 的托管服务需要通过官方网站控制台创建文件系统，新用户请先在 JuiceFS 网站上完成注册。然后登录到你的控制台，点击“创建文件系统”按钮。

image

提示：在创建文件系统时，服务器区域 用来指定你的对象存储所在的服务商及区域。后续执行文件系统挂载操作时，如果对象存储不存在，JuiceFS 会根据你的设置，在指定的云平台的相应区域在你的云平台账户下创建对象存储。与此同时，为你自动匹配物理位置最近的官方元数据存储集群，用来存储你所有的元数据。

如果你要设置的云服务商或区域不在列表中，请按提示信息提交申请，我们的工程师会在 72 小时内支持所需的平台，24 小时内完成支持所需的区域。

如果你提前准备了对象存储，请勾选"高级选项"，填写你创建好的 Bucket 名。此外，在高级选中还可以调整文件系统的"块大小"、"压缩算法"。

image

文件系统创建完成，页面会自动跳转。接下来可以按照页面中的提示，将新创建的文件系统挂载到你的服务器。

image

在页面提供的帮助说明中有一个加粗显示 Token，当你在云服务器上挂载该文件系统时需要使用这个 Token 验证身份。你创建的每个文件系统都会生成唯一的 Token。

提示：可以根据需要创建任意数量的文件系统。在创建文件系统时，你既可以将已创建的对象存储 Bucket 指派给文件系统，也可以让 JuiceFS 自动在你的云平台账户上创建对象存储 Bucket。总之，使用 JuiceFS，所有数据都要存储在你自己的对象存储中。

挂载文件系统

安装 JuiceFS 客户端

托管服务提供了一个基于 Python 语言开发的 JuiceFS 客户端控制程序，它简化了 JuiceFS 客户端与官方元数据集群之间的连接，让你可以简单快速的挂载文件系统。在安装和使用之前，请确保已经安装了 Python 2.5+ 或 Python 3.x。

参照官网控制台的提示，执行以下命令下载 JuiceFS 客户端控制程序：

$ curl -L https://juicefs.com/static/juicefs -o juicefs && chmod +x juicefs

注意：JuiceFS 客户端控制程序本质上是一个控制 JuiceFS 开源客户端的脚本程序。为了便于使用，这里将控制程序命名为 juicefs。如果你要同时使用 JuiceFS 的客户端和托管服务提供的控制程序，由于二者的名称会冲突，建议修改控制程序的名称，例如：juicefs-ctl。

执行命令，看到返回了帮助信息，代表控制程序安装成功。

$ ./juicefs

juicefs COMMAND [options]

COMMAND could be:
auth      authorize a filesystem
mount     mount a filesystem
umount    umount a filesystem
info      show information of file or directory
lsof      list recent opened files
import    import files from existing object storage
rmr       remove all files/directories recursively
snapshot  create or remove snapshots
grep      parallelized file pattern searcher
profile   analyze log (Experimental)
benchmark run benchmark
warmup    build cache for target directories/files
version   show the version

通过命令行挂载

参照以下格式挂载文件系统，请将其中的 NAME-OF-JUICEFS 替换成实际的文件系统名称：

$ sudo ./juicefs mount NAME-OF-JUICEFS /jfs

首次挂载文件系统时，JuiceFS 控制程序会交互式的向你询问一系列信息，比如，以下命令将文件系统 quick 挂载到系统的 /jfs 目录，他会分别询问文件系统的 Token，以及访问对象存储 API 所需的 Access Key ID 和 Access Key Secret。

$ sudo ./juicefs mount quick /jfs
Token for quick: 4bc1xxxxxxxxx9591dec66
Access key ID for oss://juicefs-quick: LTxxxxxxxxxxxxVWL
Access key secret for oss://juicefs-quick: Xl7DpxxxxxxxxxxxxxxxDMhfUUa
OK, quick is ready at /jfs.

提示：只有在一个主机上初次挂载文件系统时需要提供 Token 等秘钥信息，挂载成功以后，这些秘钥信息会被保存在 $HOME/.juicefs 目录下的文件系统配置文件中。此后挂载时则不再需要手动提供，控制程序会从配置文件中自动读取这些信息。文件系统的 Token 可以在官网控制台中找到，对象存储的 API 访问秘钥可以 参照此文档 获取。

你提供的对象存储 API 访问秘秘钥，必须具创建 Bucket 的权限。

如果你使用 macOS 操作系统，可以用以下命令挂载：

$ ./juicefs mount NAME-OF-JUICEFS ~/jfs

挂载成功后，juicefs 控制程序会切换到后台运行，所有日志会记录到 syslog (Facility: LOG_USER)。

记住密钥

如果不想通过交互的方式提供密码，可以通过下面的方式用命令行参数的方式提供（此方式方便自动化）：

$ sudo ./juicefs auth --token TOKEN --accesskey ACCESSKEY --secretkey SECRETKEY NAME
$ sudo ./juicefs mount NAME-OF-JUICEFS MOUNTPONT

或者也可以直接放一个 JSON 配置文件到 $HOME/.juicefs/NAME.conf，内容如下：

{"token": TOKEN, "accesskey": ACCESSKEY, "secretkey": SECRETKEY}

开机自动挂载

Linux

将 JuiceFS 控制程序重命名并拷贝到主机的 /sbin 目录：

$ sudo cp ./juicefs /sbin/mount.juicefs

编辑 /etc/fstab 配置文件，另起新行添加以下记录，注意将其中的 NAME-OF-JUICEFS 替换成你实际的文件系统名称，将 /jfs 替换成你实际要使用的挂载点：

NAME-OF-JUICEFS   /jfs     juicefs    _netdev   0 0

注意：CentOS 6 默认不会在启动时自动挂载网络文件系统，需要运行下面的命令启用自动挂载：

$ sudo chkconfig --add netfs

macOS

在以下说明中，会使用一些变量指代应填的值，请注意替换：

  • NAME 文件系统名
  • PATH_TO_JUICEFS juicefs 路径（如：/usr/local/bin/juicefs）
  • MOUNTPOINT 挂载路径

  1. 参照 卸载文件系统 确保目标挂载路径处于卸载状态

  2. 参照 记住密钥 将授权信息保存在本地文件

  3. 在 ~/Library/LaunchAgents 下创建文件 com.juicefs.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.NAME</string>
            <key>ProgramArguments</key>
            <array>
                    <string>PATH_TO_JUICEFS</string>
                    <string>mount</string>
                    <string>NAME</string>
                    <string>MOUNTPOINT</string>
            </array>
            <key>RunAtLoad</key>
            <true/>
    </dict>
    </plist>

  4. 加载上一步创建的文件, 测试加载是否成功：

    launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
    launchctl start ~/Library/LaunchAgents/com.juicefs.NAME
    ls MOUNTPOINT

  5. 如果没有挂载成功，可以在上述 plist 文件中添加以下配置：

    <key>StandardErrorPath</key>
    <string>/tmp/mycommand.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/mycommand.out</string>

    通过以下命令就可以重新加载更新后的配置，查看输出：

    launchctl unload ~/Library/LaunchAgents/com.juicefs.NAME.plist
    launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
    cat /tmp/mycommand.out
    cat /tmp/mycommand.err

Docker 容器中挂载

JuiceFS 支持被 Docker 或者其他容器挂载，操作前需要确保容器有访问 FUSE 设备的权限。执行以下命令开启容器的 FUSE 访问权限：

$ sudo docker run --cap-add SYS_ADMIN --device=/dev/fuse --security-opt apparmor:unconfined

导入已有的文件

如果在你使用 JuiceFS 之前，已经在对象存储中存入了一些文件。可以使用 JuiceFS 控制程序的 import 命令，将已有的文件导入到 JuiceFS 文件系统中。

命令格式如下：

$ sudo ./juicefs import BUCKET-NAME/PREFIX TARGET-DIR-IN-JUICEFS

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

$ sudo ./juicefs import my-bucket/my-files /jfs/my-files

执行导入操作只会把这些文件的元数据写入到 JuiceFS 的元数据存储，而这些文件仍旧原样保存在对象存储中，你仍然可以继续用对象存储的 API 去访问它们。

导入完成后，你可以在 JuiceFS 中随意更改这些文件的属性，比如修改文件名或权限等，这些改动不会被同步到对象存储。同样的，在 JuiceFS 中删除这些导入的文件，也只会删除这些文件的元数据，并不会实际删除对象存储中的文件。

提示：执行导入操作时，会使用挂载时的设置的对象存储 API 访问秘钥，请确保秘钥对导入的文件有读权限。

快照

快照是对目录或文件在某个特定时点的状态创建的数据副本，这是一种非常有意义的数据备份和保护机制。在关键操作之前创建快照，一旦发生故障，就可以通过快照将数据恢复到创建快照时的状态。

JuiceFS 控制程序支持原子快照，你可以立即制作文件或目录的副本。快照会重用底层的数据块，只有当数据块被修改时才会复制。

一个快照可以以如下方式进行创建：

$ ./juicefs snapshot SRC DST

提示：只能为 JuiceFS 文件系统上的文件或文件夹创建快照，而且快照只能保存在源文件所在的文件系统中。

可以使用 -d 选项删除快照:

$ ./juicefs snapshot -d DST

提示：./juicefs snapshot -d 只会删除快照。否则，命令会输出“Operation not permitted”。

卸载文件系统

注意：卸载文件系统存在一定的操作风险，卸载一个使用中的文件系统可能会导致数据丢失。在执行卸载操作之前，请确认你已经备份了重要数据。

卸载文件系统可以使用系统提供的 umount 命令：

$ sudo umount /jfs

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

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

$ sudo umount /jfs -l

对于 macOS 系统，可以使用 force 选项进行强制卸载：

$ sudo diskutil unmount force /jfs

然后你可以手动杀掉 juicefs 控制程序进程，也可以等它自己退出。

删除文件系统

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

  1. 备份文件系统中所有数据；
  2. 在主机上卸载文件系统；
  3. 在官网控制台中删除文件系统；
  4. 在主机的 $HOME/.juicefs 目录中找到并删除文件系统的配置文件，通常是 <YOUR-FS-NAME>.conf 形式命名的。