JuiceFS 使用 TiKV 数据库上手指南

作为云原生的分布式存储系统，JuiceFS 在诞生之初就被设计成了插件式的结构，确保可以持续不断的将新技术整合到 JuiceFS 生态，像数据存储引擎和元数据引擎这两个核心部件，用户可以根据需要灵活选择。

JuiceFS 的数据存储引擎以对象存储为主，支持几乎所有公有云对象存储服务和私有对象存储系统，另外还支持 KV 存储、WebDAV 以及本地磁盘。元数据引擎则陆续开放了对 Redis、MySQL、PostgreSQL、SQLite 等数据库的支持。

最新发布的 JuiceFS v0.16 正式开放了对 TiKV 键值数据库的支持，进一步满足高性能、大规模数据存储场景下的弹性扩容需求。

本文就带领大家一起了解一下 JuiceFS 如何使用 TiKV 作为元数据引擎。

TiKV 简介

TiKV 是一个分布式事务型的键值数据库，具有高可扩展性、低延迟、易于使用的特点，它的性能优异，支持 PB 级万亿行数据规模的大数据处理能力。在设计上，TiKV 支持无限的水平扩展，提供了满足 ACID 约束的分布式事务接口，并且通过 Raft 协议 保证了多副本数据一致性以及高可用。

TiKV 由 PingCAP 公司开发，是云原生基金会（CNCF）孵化毕业的项目之一。

安装 TiKV

PingCAP 提供了 TiUP 包管理器，可以很方便的在 Linux 或 macOS 上安装 TiKV 等产品。

1. 安装 TiUP

$ curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

执行命令后，程序会自动检测当前的系统环境，自动下载并安装恰当的版本，最后会将 TiUP 的程序路径添加到终端的可执行路径中。

为了让设置生效，可以重启一个新终端。或者手动执行命令上设置生效，例如使用 bash 可以执行：

$ source .bash_profile

现在尝试执行命令 tiup -v ，看到类似下面的版本信息代表安装成功。

$ tiup -v 
1.5.4 tiup
Go Version: go1.16.6
Git Ref: v1.5.4
GitHash: b629670276269cd1518eb28f362a5180135cc985

2. 部署 TiKV 集群

为了便于测试，本文采用 TiUP 提供的 playground 组件在本地环境安装最小化的 TiKV 集群。

$ tiup playground --mode tikv-slim

部署成功后，终端会显示类似下面这样的信息：

PD client endpoints: [127.0.0.1:2379]
To view the Prometheus: http://127.0.0.1:9090
To view the Grafana: http://127.0.0.1:3000

其中 127.0.0.1:2379 是 TiKV 的 Placement Driver（PD），即 TiKV 集群的管理节点，JuiceFS 将通过该地址与 TiKV 进行数据交互。另外两个地址分别是 Prometheus 和 Grafana 服务，用来对 TiKV 集群进行监控和数据可视化，这里不做进一步展开，有兴趣可以查阅相关文档了解详情。

注意：TiUP 的 playground 组件主要用于在本地环境快速搭建 TiDB、TiKV 的最小化测试集群。生产环境部署请参考TiKV 官方文档。

安装 JuiceFS

JuiceFS 同时支持 Linux、Windows 和 macOS 系统，只需要下载对应版本的客户端程序放在系统的可执行路径中即可。例如，我当前使用的是 Linux 发行版，依次执行以下命令即可安装最新版本客户端。

检测当前系统信息并设置临时的环境变量：

$ JFS_LATEST_TAG=$(curl -s https://api.github.com/repos/juicedata/juicefs/releases/latest | grep 'tag_name' | cut -d '"' -f 4 | tr -d 'v')

使用 wget 下载适配当前系统的最新版 JuiceFS 客户端安装包：

$ wget "https://github.com/juicedata/juicefs/releases/download/v${JFS_LATEST_TAG}/juicefs-${JFS_LATEST_TAG}-linux-amd64.tar.gz"

解压安装包：

$ mkdir juice && tar -zxvf "juicefs-${JFS_LATEST_TAG}-linux-amd64.tar.gz" -C juice

将 JuiceFS 客户端安装到 /usr/local/bin ：

$ sudo install juice/juicefs /usr/local/bin

执行命令，看到返回 juicefs 的命令帮助信息，代表客户端安装成功。

$ juicefs

NAME:
   juicefs - A POSIX file system built on Redis and object storage.

USAGE:
   juicefs [global options] command [command options] [arguments...]

VERSION:
   0.16.1 (2021-08-16 2edcfc0)

COMMANDS:
   format   format a volume
   mount    mount a volume
   umount   unmount a volume
   gateway  S3-compatible gateway
   sync     sync between two storage
   rmr      remove directories recursively
   info     show internal information for paths or inodes
   bench    run benchmark to read/write/stat big/small files
   gc       collect any leaked objects
   fsck     Check consistency of file system
   profile  analyze access log
   stats    show runtime stats
   status   show status of JuiceFS
   warmup   build cache for target directories/files
   dump     dump metadata into a JSON file
   load     load metadata from a previously dumped JSON file
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --verbose, --debug, -v  enable debug log (default: false)
   --quiet, -q             only warning and errors (default: false)
   --trace                 enable trace log (default: false)
   --no-agent              Disable pprof (:6060) and gops (:6070) agent (default: false)
   --help, -h              show help (default: false)
   --version, -V           print only the version (default: false)

COPYRIGHT:
   AGPLv3

另外，你也可以访问 JuiceFS GitHub Releases 页面选择其他版本进行手动安装。

使用

为了便于演示，这里我参照 JuiceFS 快速上手指南，在本地搭建了一个 MinIO 对象存储，访问地址是 http://127.0.0.1:9000，Access Key ID 和 Access Key Secret 均为 minioadmin。

1. 创建文件系统

以下命令使用 JuiceFS 客户端提供的 format 子命令创建了一个名为 mystor 的文件系统，其中 TiKV 数据库地址格式参照官方文档设置，即使用 TiKV 集群的 PD 地址：

$ juicefs format \
    --storage minio \
    --bucket http://127.0.0.1:9000/mystor \
    --access-key minioadmin \
    --secret-key minioadmin \
    tikv://127.0.0.1:2379/mystor \
    mystor

参数说明：

• --storage：指定数据存储引擎，这里使用的是 minio。
• --bucket：指定存储桶访问地址，这里使用的是我在 MinIO 上提前创建的名为 mystor 的存储桶。
• --access-key 和 --secret-key：指定访问对象存储 API 的秘钥。
• 使用 TiKV 存储元数据时，设置集群的 PD 地址，当与其他应用共用同一个 TiKV 时，建议添加 prefix，这里在 PD 地址中指定了 mystor 前缀。

看到类似下面的输出，代表文件系统创建成功：

2021/08/12 23:28:36.932241 juicefs[101222] <INFO>: Meta address: tikv://127.0.0.1:2379/mystor
[2021/08/12 23:28:36.932 +08:00] [INFO] [client.go:214] ["[pd] create pd client with endpoints"] [pd-address="[127.0.0.1:2379]"]
[2021/08/12 23:28:36.935 +08:00] [INFO] [base_client.go:346] ["[pd] switch leader"] [new-leader=http://127.0.0.1:2379] [old-leader=]
[2021/08/12 23:28:36.935 +08:00] [INFO] [base_client.go:126] ["[pd] init cluster id"] [cluster-id=6995548759432331426]
[2021/08/12 23:28:36.935 +08:00] [INFO] [client.go:238] ["[pd] create tso dispatcher"] [dc-location=global]
2021/08/12 23:28:36.936892 juicefs[101222] <INFO>: Data uses minio://127.0.0.1:9000/mystor/mystor/
2021/08/12 23:28:36.976722 juicefs[101222] <INFO>: Volume is formatted as {Name:mystor UUID:0c9594a8-fe2c-463c-a4b6-eb815f38c843 Storage:minio Bucket:http://127.0.0.1:9000/mystor AccessKey:minioadmin SecretKey:removed BlockSize:4096 Compression:none Shards:0 Partitions:0 Capacity:0 Inodes:0 EncryptKey:}

2. 挂载文件系统

使用 mount 子命令，将文件系统挂载到当前用户家目录下的 jfs 目录：

$ sudo juicefs mount -d tikv://127.0.0.1:2379/mystor ~/jfs

这里使用了 sudo 命令，以超级用户权限执行文件系统挂载操作，目的是为了让 JuiceFS 能够正常建立并使用 /var/jfsCache 目录缓存数据。

看到类似下面的输出，代表文件系统挂载成功：

2021/08/12 23:34:44.288136 juicefs[101873] <INFO>: Meta address: tikv://127.0.0.1:2379/mystor
[2021/08/12 23:34:44.288 +08:00] [INFO] [client.go:214] ["[pd] create pd client with endpoints"] [pd-address="[127.0.0.1:2379]"]
[2021/08/12 23:34:44.291 +08:00] [INFO] [base_client.go:346] ["[pd] switch leader"] [new-leader=http://127.0.0.1:2379] [old-leader=]
[2021/08/12 23:34:44.291 +08:00] [INFO] [base_client.go:126] ["[pd] init cluster id"] [cluster-id=6995548759432331426]
[2021/08/12 23:34:44.291 +08:00] [INFO] [client.go:238] ["[pd] create tso dispatcher"] [dc-location=global]
2021/08/12 23:34:44.296270 juicefs[101873] <INFO>: Data use minio://127.0.0.1:9000/mystor/mystor/
2021/08/12 23:34:44.296768 juicefs[101873] <INFO>: Disk cache (/var/jfsCache/0c9594a8-fe2c-463c-a4b6-eb815f38c843/): capacity (1024 MB), free ratio (10%), max pending pages (15)
2021/08/12 23:34:44.800551 juicefs[101873] <INFO>: OK, mystor is ready at /home/herald/jfs

使用 df 命令，可以看到文件系统的挂载情况：

$ df -Th
文件系统           类型          容量   已用  可用   已用% 挂载点
JuiceFS:mystor fuse.juicefs       1.0P   64K  1.0P    1%   /home/herald/jfs

文件系统挂载成功以后，现在就可以像使用本地硬盘那样，在 ~/jfs 目录中存储数据了。

3. 查看文件系统信息

JuiceFS 客户端的 status 子命令可以查看一个文件系统的基本信息和连接状态。

$ juicefs status tikv://127.0.0.1:2379/mystor
{
  "Setting": {
    "Name": "mystor",
    "UUID": "9f50f373-a7ec-4d5b-b790-3defbf6d0509",
    "Storage": "minio",
    "Bucket": "http://127.0.0.1:9000/mystor",
    "AccessKey": "minioadmin",
    "SecretKey": "removed",
    "BlockSize": 4096,
    "Compression": "none",
    "Shards": 0,
    "Partitions": 0,
    "Capacity": 0,
    "Inodes": 0
  },
  "Sessions": [
    {
      "Sid": 2,
      "Heartbeat": "2021-08-13T10:43:35+08:00",
      "Version": "0.16-dev (2021-08-12 a871c3d)",
      "Hostname": "herald-manjaro",
      "MountPoint": "/home/herald/jfs",
      "ProcessID": 6309
    }
  ]
}

在返回的信息中可以详细的了解到一个文件系统使用的数据存储引擎信息，以及当前挂载了该文件系统的主机情况。

另外，v0.16 以后的客户端还可以通过查看挂载点根目录下的 .config 虚拟文件了解文件系统的详细配置信息：

$ sudo cat ~/jfs/.config
{
 "Meta": {
  "Strict": true,
  "Retries": 10,
  "CaseInsensi": false,
  "ReadOnly": false,
  "OpenCache": 0,
  "MountPoint": "jfs",
  "Subdir": ""
 },
 "Format": {
  "Name": "myabc",
  "UUID": "e9d8373c-7ced-49d9-a033-75f6abb44854",
  "Storage": "minio",
  "Bucket": "http://127.0.0.1:9000/mystor",
  "AccessKey": "minioadmin",
  "SecretKey": "removed",
  "BlockSize": 4096,
  "Compression": "none",
  "Shards": 0,
  "Partitions": 0,
  "Capacity": 0,
  "Inodes": 0
 },
 "Chunk": {
  "CacheDir": "/var/jfsCache/e9d8373c-7ced-49d9-a033-75f6abb44854",
  "CacheMode": 384,
  "CacheSize": 1024,
  "FreeSpace": 0.1,
  "AutoCreate": true,
  "Compress": "none",
  "MaxUpload": 20,
  "Writeback": false,
  "Partitions": 0,
  "BlockSize": 4194304,
  "GetTimeout": 60000000000,
  "PutTimeout": 60000000000,
  "CacheFullBlock": true,
  "BufferSize": 314572800,
  "Readahead": 0,
  "Prefetch": 1
 },
 "Version": "0.16.1 (2021-08-16 2edcfc0)",
 "Mountpoint": "jfs"
}

提示：需要特别注意的是，本文使用的是本地的演示环境。如果需要在多台主机共享挂载同一个 JuiceFS 文件系统时，你需要确保部署的对象存储和 TiKV 集群能够被所有的主机正常访问。

4. 卸载文件系统

你可以使用 JuiceFS 客户端提供的 umount 子命令卸载文件系统，比如：

$ sudo juicefs umount ~/jfs

注意：强制卸载使用中的文件系统可能导致数据损坏或丢失，请务必谨慎操作。

5. 开机自动挂载

如果你不想每次重启系统都要重新手动挂载 JuiceFS，可以设置自动挂载。

首先，需要将 juicefs 客户端重命名为 mount.juicefs 并复制到 /sbin/ 目录：

$ sudo cp /usr/local/bin/juicefs /sbin/mount.juicefs

编辑 /etc/fstab 配置文件，新增一条记录：

tikv://127.0.0.1:2379/mystor    /home/herald/jfs       juicefs     _netdev,cache-size=20480     0  0

挂载选项中 cache-size=20480 代表分配 20GB 本地磁盘空间作为 JuiceFS 的缓存使用，请根据实际的硬件配置决定分配的缓存大小。一般来说，为 JuiceFS 分配更大的缓存空间，可以获得更好的性能表现。

你可以根据需要调整上述配置中的 FUSE 挂载选项。

总结

对于 JuiceFS 而言，开放对 TiKV 的支持具有里程碑意义。它填补了 Redis 做元数据引擎时横向扩容困难的问题，同时又填补了 MySQL、PostgreSQL 等 SQL 数据库的性能短板，为用户在元数据引擎选型时多提供了一个新选择。

开源社区贡献指南

JuiceFS 是在 AGPLv3 协议下开源的项目，开源软件的发展离不开每一个人的支持，一篇文章、一页文档、一个想法、一个建议、报告或修复一个 Bug，这些贡献不论大小都是推动开源项目不断发展的动力。

你可以为开源社区做的事情：

• 加星关注项目 https://github.com/juicedata/juicefs
• 在论坛发表你的看法
• 在 Issues 认领开发任务
• 完善 JuiceFS 的文档
• 在你自己的博客、微博、微信、Vlog 等自媒体分享有关 JuiceFS 的一切
• 加入 JuiceFS 的微信群或 Slack 频道
• 把 JuiceFS 告诉更多人，让更多人使用由你我共同维护的产品！

我们诚挚的邀请每一个热爱开源的人加入到我们的社区，让我们一起把 JuiceFS 做的更好！