Skip to main content

快速上手

提示

这是一份针对 JuiceFS 企业版编写的快速上手指南。如果你使用的是 JuiceFS 社区版,请访问社区版文档

如果你使用 JuiceFS 企业版(私有部署),阅读的时候需要注意,文档中的控制台链接均指向云服务控制台,你需要替换为实际的私有部署集群的控制台地址。私有部署和云服务所使用的软件完全相同,因此本文档站的内容同样适用于私有部署。

在安装和开始使用之前,需要确认以下事项:

  • 软件架构:简单阅读「技术架构」,就能迅速了解各组件的角色。
  • 对象存储:你的所有数据都会保存在你所选择的对象存储中,因此需要提前准备对象存储 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 控制台,然后点击「创建文件系统」按钮开始创建流程。

create file system

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

  • 文件系统名(Volume Name):每个文件系统的唯一标志,挂载文件系统时需要提供该名称。

  • 对象存储区域(Region):对象存储所在的平台及区域,选择距离自己应用主机最接近的地域来获得最佳性能。

    如果你希望使用的对象存储服务并未在这里列出(比如 Cloudflare R2),可以选择 S3,然后在 Bucket 处填写完整 Endpoint,这样便能够使用任意 S3 兼容的对象存储服务。

  • 回收站保存时间(Trash Expiration Time):回收站内文件的保存天数,设置为 0 以禁用此功能。回收站内文件仍参与计费,阅读文档了解更多。

  • 高级选项 Bucket(或者完整 Endpoint):可以使用已创建好的桶,如果桶不存在,JuiceFS 会尝试在挂载时创建(需要挂载时提供的 Access Key/Secret Key 具有创建桶的权限)。需要注意:
    • 如果希望使用其他并未列出的支持 S3 的对象存储服务,则在 Bucket 字段填写完整 Endpoint。以 R2 为例:https://<accountid>.r2.cloudflarestorage.com/mybucket
    • 该字段含义等同命令行客户端的 --bucket 参数,如果填写完整 Endpoint,则无法享受到内外网域名的智能探测功能(仅对区分内外网域名的对象存储服务生效,例如阿里云 OSS),阅读参数说明以详细了解;
    • 对于腾讯云 COS,推荐在 Bucket 后追加 APPID,形如 xxxxx-123456789。如果没有填写 APPID,挂载时将会需要交互式录入信息。
  • 高级选项 块大小(Block Size):对象存储文件块(Block)大小,考虑到不少对象存储都将 4MB 作为内部存储块大小,4MB 是一个较好的默认值,在大部分场景下都能获得更好表现。关于 JuiceFS 如何切分存储文件请详读「JuiceFS 如何存储文件」
  • 高级选项 压缩(Compression):用于指定文件系统的压缩算法,压缩能有效节约对象存储空间占用,但也对性能有一定影响。该特性默认开启,但如果你的数据格式(如 Parquet、ORC)已经经过压缩处理,请关闭该特性,否则会造成不必要的读放大。
  • 私有部署 单分区限制(Single Zone Limited):如果你已经在使用多分区集群,但集群中的某些文件系统规模较小,不需要多分区级别的性能,那么启用该选项将会将文件系统限制在单分区上(也就是 0 号分区)。这样的特殊对待能够让这些相对小规模的文件系统管理起来更简单。

创建完成,你将被重定向到设置页面,按照说明挂载新创建的文件系统。页面会加粗显示文件系统的客户端令牌,也就是 Token,客户端挂载文件系统时,正是使用该令牌,通过控制台进行认证、获取挂载相关的配置。

how-to-mount-fs-zh

挂载文件系统

为了挂载 JuiceFS,节点需要能够访问元数据服务,以及对象存储。对于生产环境,挂载点需要与元数据、对象存储服务位于同一个区域,才能获得最好的时延和性能。

安装客户端

Linux、macOS 可用下方命令将客户端安装至 /usr/local/bin(也可根据实际情况替换)。注意下载地址仅适用于云服务,私有部署用户需要访问文件系统的设置页面,按照页面提示进行下载安装。

curl -L https://juicefs.com/static/juicefs -o /usr/local/bin/juicefs && chmod +x /usr/local/bin/juicefs

在执行命令的过程中如果遇到了 Permission denied 错误,需要使用 sudo 或切换成 root 用户执行。

下载完毕后在命令行运行 juicefs --help,如果正常打印出帮助信息,就表示客户端安装完成了。如果报错 command not found,请检查你的系统环境变量设置,确保将 /usr/local/bin 加入 PATH

挂载

挂载文件系统的流程如下,注意命令需要 root 权限执行,普通用户身份会遭遇某些不便。

sudo juicefs mount $VOL_NAME $MOUNTPOINT

$VOL_NAME 需要替换成「创建文件系统」时设置的文件系统名,$MOUNTPOINT 则替换成实际挂载的路径,例如 /jfs

客户端将会交互式地询问一系列认证信息,你需要文件系统的 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.conf。再次挂载时会自动读取,无需重复输入。

验证无误后会自动完成文件系统挂载,客户端会以守护进程的形式运行在后台,日志路径默认为 /var/log/juicefs.log,具体请参考「问题排查方法」

常见误区

如果你是首次接触 JuiceFS,它和你以往使用的文件系统可能有不少区别,本节罗列一些容易引发误会的地方。

计费

  • JuiceFS 云服务和企业版提供的是元数据服务,因此收取的是元数据费用,并不包含对象存储中的数据费用。如果你使用公有云提供的对象存储服务,请额外注意这部分服务的费用;
  • JuiceFS 每个月会定期发送账单,但实际统计粒度为小时,系统会每小时上报用量并以此生成每月账单。如果在小时统计周期内创建并迅速删除了临时文件,这部分用量将不会计入账单。

使用和管理

  • 不能用 du 命令来统计 JuiceFS 文件系统的目录用量,因为目录大小已经是递归统计值,包含了目录中所有文件的大小并实时更新,可以直接在命令行用 ls -alh 或通过 Web 控制台查看。如果对 JuiceFS 目录运行 du,得出的将是一个经过重复统计的错误值。这个行为在「容量与配额」有更详细的说明;
  • JuiceFS 默认启用了「回收站」,因此从文件系统里删除文件,会被移入回收站,不会从对象存储立刻删除;
  • 就算清空了回收站,对象存储里的数据块也未必能及时释放。删除文件以后,对象存储块会通过客户端的后台任务进行异步删除,也就是说,必须有活跃的挂载点存在,回收站清理才能正常运作。

投入使用

阅读本节内容,来确保刚刚创建的 JuiceFS 文件系统能够顺利地投入使用。

验证文件系统

当挂载好文件系统以后可以通过 juicefs bench 命令对文件系统进行基础的性能测试和功能验证,确保 JuiceFS 文件系统能够正常访问且性能符合预期:

juicefs bench /jfs

运行 juicefs bench 命令以后会根据指定的并发度(默认为 1)往 JuiceFS 文件系统中写入及读取 N 个大文件(默认为 1)及 N 个小文件(默认为 100),并统计读写的吞吐和单次操作的延迟,以及访问元数据引擎的延迟。

如果各项性能满足预期,那么输出结果会全部以绿色表示。如果看到了黄色或者红色,则说明存在性能隐患,建议用 juicefs statsjuicefs profile 等命令进行进一步排查,详细请阅读「问题排查方法」

导入数据

如果你已经有大量文件在对象存储桶中,可以将其直接以只读的方式「导入」JuiceFS,导入的文件支持用 JuiceFS 的缓存功能进行读取加速,但无法通过 JuiceFS 对其进行修改(如果发生修改,则需再次导入)。如果你的场景适合这样的用法,请参考「导入对象存储已有文件」文档。

如果已有数据需要正常读写,那么建议整体迁移到 JuiceFS,如果数据量并不大,当然可以直接用 cprsync 等工具进行数据迁移。但如果数据量巨大,推荐使用 juicefs sync 进行并发拷贝,能够有效提速。

备注

通过挂载点导入大文件的时候,需要特别注意:

  • 如果对象存储的上传带宽不足,低速的顺序写可能产生很多碎片,建议调整挂载点挂载参数,增加 --flush-wait=60s,具体原因请阅读数据同步与碎片合并
  • 导入数据的阶段可能发生许多预期之外的问题,包括上一点提到的产生过多碎片问题,或者单纯是操作错误导致数据需要重新导入。面对此种情况,删除或者被覆盖的数据同样会进入回收站予以保留,不恰当的回收站设置会引发对象存储费用增加。如果这对你的团队是个问题,建议在导入期间临时缩短回收站留存时长,或临时关闭回收站。

客户端升级与平滑重启

我们推荐持续更新 JuiceFS 客户端,以获得最新的改进与修复,用下方的命令便可以方便地获取最新版本客户端:

juicefs version --upgrade

客户端升级以后,还需要重新挂载,可以通过 --restart 用一行命令同时完成客户端升级与平滑重启:

juicefs version --upgrade --restart

mount 命令本身也支持平滑重新挂载,只需编辑挂载选项并重新运行 juicefs mount 即可:

# 确认挂载点已经存在
$ df -h /jfs
Filesystem Size Used Avail Use% Mounted on
JuiceFS:myjfs 1.0T 11G 1014G 1% /jfs

# 修改参数、重新挂载
# 如果忘记了当前的挂载命令,可以用上方示范的 ps 命令获取
$ juicefs mount myjfs /jfs --buffer-size=300
OK, myjfs is ready at /jfs.

# 检查运行时配置文件,确认参数生效
grep -i buffer /jfs/.config
提示
  • 平滑重启不支持修改 FUSE 参数。如果需要修改 FUSE 参数,必须卸载、重新挂载。
  • 平滑升级将会触发挂载点进行持久化操作,将缓冲区内未上传的数据尽快写入。在负载极高的场景下,可能无法在预期的时间内完成该操作,此时平滑升级将无法顺利工作,这种情况下,客户端日志会显示 mount point xxx is busy, stop upgrade 的错误信息。
  • 如果你仍在使用 4.9 或更早版本的客户端,守护进程是由 Python 启动的,这点和 5.0 及以上版本有别。对于这一类旧版客户端,需要使用 Python 3,才能享受到平滑重启和升级。

开机自动挂载

在确认挂载成功,可以正常使用以后,可以参考本节内容设置开机自动挂载。

Linux

将挂载信息写入 /etc/fstab,便能实现开机自动挂载。JuiceFS 客户端内置了自动更新 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

卸载文件系统

使用 umount 命令,就能卸载文件系统:

umount /jfs

如果命令行返回 umount: /jfs: target is busy.,说明文件系统正在使用,可以使用 lsof $MOUNTPOINT 找到并结束相关应用的进程后再执行卸载。

对于 Linux 发行版,可以使用 -l 选项执行延迟卸载(立即卸载文件系统,已经打开的文件句柄释放之后,客户端才真正退出):

umount -l /jfs

如果卸载出现异常,阅读「卸载错误」来排查并解决。