如何设置对象存储
通过阅读 JuiceFS 的技术架构可以了解到,JuiceFS 是一个数据与元数据分离的分布式文件系统,以对象存储作为主要的数据存储,以 Redis、PostgreSQL、MySQL 等数据库作为元数据存储。
存储选项
在创建 JuiceFS 文件系统时,设置数据存储一般涉及以下几个选项:
--storage
指定文件系统要使用的存储类型,例如:--storage s3
。--bucket
指定存储访问地址,例如:--bucket https://myjuicefs.s3.us-east-2.amazonaws.com
。--access-key
和--secret-key
指定访问存储时的身份认证信息。
例如,以下命令使用 Amazon S3 对象存储创建文件系统:
juicefs format --storage s3 \
--bucket https://myjuicefs.s3.us-east-2.amazonaws.com \
--access-key abcdefghijklmn \
--secret-key nmlkjihgfedAcBdEfg \
redis://192.168.1.6/1 \
myjfs
其他选项
在执行 juicefs format
或 juicefs mount
命令时,可以在 --bucket
选项中以 URL 参数的形式设置一些特别的选项,比如 https://myjuicefs.s3.us-east-2.amazonaws.com?tls-insecure-skip-verify=true
中的 tls-insecure-skip-verify=true
即为跳过 HTTPS 请求的证书验证环节。
配置数据分片(Sharding)
创建文件系统时,可以通过 --shards
选项定义多个 Bucket 作为文件系统的底层存储。这样一来,系统会根据文件名哈希值将文件分散到多个 Bucket 中。数据分片技术可以将大规模数据并发写的负载分散到多个 Bucket 中,从而提高写入性能。
启用数据分片功能需要注意以下事项:
- 只能使用同一种对象存储下的多个 bucket
--shards
选项接受一个 0~256 之间的整数,表示将文件分散到多少个 Bucket 中。默认值为 0,表示不启用数据分片功能。- 需要使用整型数字通配符
%d
或许%x
之类指定用户生成 bucket 的 endpoint 的字符串,例如"http://192.168.1.18:9000/myjfs-%d"
,可以按照这样的格式预先创建 bucket,也可以在创建文件系统时由 JuiceFS 客户端自动创建; - 数据分片在创建时设定,创建完毕不允许修改。不可增加或减少 bucket,也不可以取消 shards 功能。
例如,以下命令创建了一个数据分片为 4 的文件系统:
juicefs format --storage s3 \
--shards 4 \
--bucket "https://myjfs-%d.s3.us-east-2.amazonaws.com" \
...
执行上述命令后,JuiceFS 客户端会创建 4 个 bucket,分别为 myjfs-0
、myjfs-1
、myjfs-2
和 myjfs-3
。
Access Key 和 Secret Key
一般而言,对象存储通过 Access Key ID 和 Access Key Secret 验证用户身份,对应到 JuiceFS 文件系统就是 --access-key
和 --secret-key
这两个选项(或者简称为 AK、SK)。
创建文件系统时除了使用 --access-key
和 --secret-key
两个选项显式指定,更安全的做法是通过 ACCESS_KEY
和 SECRET_KEY
环境变量传递密钥信息,例如:
export ACCESS_KEY=abcdefghijklmn
export SECRET_KEY=nmlkjihgfedAcBdEfg
juicefs format --storage s3 \
--bucket https://myjuicefs.s3.us-east-2.amazonaws.com \
redis://192.168.1.6/1 \
myjfs
公有云通常允许用户创建 IAM(Identity and Access Management)角色,例如:AWS IAM 角色 或 阿里云 RAM 角色,可将角色分配给 VM 实例。如果云服务器实例已经拥有读写对象存储的权限,则无需再指定 --access-key
和 --secret-key
。
使用临时访问凭证
永久访问凭证一般有两个部分:Access Key 和 Secret Key,而临时访问凭证一般包括 3 个部分:Access Key、Secret Key 与 token,并且临时访问凭证具有过期时间,一般在几分钟到几个小时之间。
如何获取临时凭证
不同云厂商的获取方式不同,一般是需要已具有相应权限用户的 Access Key、Secret Key 以及代表临时访问凭证的权限边界的 ARN 作为参数请求访问云服务厂商的 STS 服务器来获取临时访问凭证。这个过程一般可以由云厂商提供的 SDK 简化操作。比如 Amazon S3 获取临时凭证方式可以参考这个链接,阿里云 OSS 获取临时凭证方式可以参考这个链接。
如何使用临时访问凭证设置对象存储
使用临时凭证的方式与使用永久凭证差异不大,在格式化文件系统时,将临时凭证的 Access Key、Secret Key、token 分别通过 --access-key
、--secret-key
、--session-token
设置值即可。例如:
juicefs format \
--storage oss \
--access-key xxxx \
--secret-key xxxx \
--session-token xxxx \
--bucket https://bucketName.oss-cn-hangzhou.aliyuncs.com \
redis://localhost:6379/1 \
test1
由于临时凭证很快就会过期,所以关键在于格式化文件系统以后,如何在临时凭证过期前更新 JuiceFS 正在使用的临时凭证。一次凭证更新过程分为两步:
- 在临时凭证过期前,申请好新的临时凭证;
- 无需停止正在运行的 JuiceFS,直接使用
juicefs config Meta-URL --access-key xxxx --secret-key xxxx --session-token xxxx
命令热更新访问凭证。
新挂载的客户端会直接使用新的凭证,已经在运行的所有客户端也会在一分钟内更新自己的凭证。整个更新过程不会影响正在运行的业务。由于临时凭证过期时间较短,所以以上步骤需要长期循环执行才能保证 JuiceFS 服务可以正常访问到对象存储。
内网和外网 Endpoint
通常情况下,对象存储服务提供统一的 URL 进行访问,但云平台会同时提供内网和外网通信线路,比如满足条件的同平台云服务会自动解析通过内网线路访问对象存储,这样不但时延更低,而且内网通信产生的流量是免费的。
另外,一些云计算平台也区分内外网线路,但没有提供统一访问 URL,而是分别提供内网 Endpoint 和外网 Endpoint 地址。
JuiceFS 对这种区分内网外地址的对象存储服务也做了灵活的支持,对于共享同一个文件系统的场景,在满足条件的服务器上通过内网 Endpoint 访问对象存储,其他计算机通过外网 Endpoint 访问,可以这样使用:
- 创建文件系统时:
--bucket
建议使用内网 Endpoint 地址; - 挂载文件系统时:对于不满足内网线路的客户端,可以通过
--bucket
指定外网 Endpoint 地址。
使用内网 Endpoint 创建文件系统可以确保性能更好、延时更低,对于无法通过内网访问的客户端,可以在挂载文件系统时通过 --bucket
指定外网 Endpoint 进行挂载访问。
存储类 新增自 v1.1
对象存储通常支持多种存储类,如标准存储、低频访问存储、归档存储。不同的存储类会有不同的价格及服务可用性,你可以在创建 JuiceFS 文件系统时通过 --storage-class
选项设置默认的存储类,或者在挂载 JuiceFS 文件系统时通过 --storage-class
选项设置一个新的存储类。请查阅你所使用的对象存储的用户手册了解应该如何设置 --storage-class
选项的值(如 Amazon S3)。
当使用某些存储类(如归档、深度归档)时,数据无法立即访问,需要提前恢复数据并等待一段时间之后才能访问。
当使用某些存储类(如低频访问)时,会有最小计费单位,读取数据也可能会产生额外的费用,请查阅你所使用的对象存储的用户手册了解详细信息。
使用代理
如果客户端所在的网络环境受防火墙策略或其他因素影响需要通过代理访问外部的对象存储服务,使用的操作系统不同,相应的代理设置方法也不同,请参考相应的用户手册进行设置。
以 Linux 为例,可以通过创建 http_proxy
和 https_proxy
环境变量设置代理:
export http_proxy=http://localhost:8035/
export https_proxy=http://localhost:8035/
juicefs format \
--storage s3 \
... \
myjfs
支持的存储服务
如果你希望使用的存储类型不在列表中,欢迎提交需求 issue。
名称 | 值 |
---|---|
Amazon S3 | s3 |
Google 云存储 | gs |
Azure Blob 存储 | wasb |
Backblaze B2 | b2 |
IBM 云对象存储 | ibmcos |
Oracle 云对象存储 | s3 |
Scaleway | scw |
DigitalOcean Spaces | space |
Wasabi | wasabi |
Storj DCS | s3 |
Vultr 对象存储 | s3 |
Cloudflare R2 | s3 |
阿里云 OSS | oss |
腾讯云 COS | cos |
华为云 OBS | obs |
百度云 BOS | bos |
火山引擎 TOS | tos |
金山云 KS3 | ks3 |
青云 QingStor | qingstor |
七牛云 Kodo | qiniu |
新浪云 SCS | scs |
天翼云 OOS | oos |
移动云 EOS | eos |
京东云 OSS | s3 |
优刻得 US3 | ufile |
Ceph RADOS | ceph |
Ceph RGW | s3 |
Gluster | gluster |
Swift | swift |
MinIO | minio |
WebDAV | webdav |
HDFS | hdfs |
Apache Ozone | s3 |
Redis | redis |
TiKV | tikv |
etcd | etcd |
SQLite | sqlite3 |
MySQL | mysql |
PostgreSQL | postgres |
本地磁盘 | file |
SFTP/SSH | sftp |
NFS | nfs |
Amazon S3
S3 支持两种风格的 endpoint URI:「虚拟托管类型」和「路径类型」。区别如下:
- 虚拟托管类型:
https://<bucket>.s3.<region>.amazonaws.com
- 路径类型:
https://s3.<region>.amazonaws.com/<bucket>
其中 <region>
要替换成实际的区域代码,比如:美国西部(俄勒冈)的区域代码为 us-west-2
。点此查看所有的区域代码。
AWS 中国的用户,应使用 amazonaws.com.cn
域名。相应的区域代码信息点此查看。
如果 S3 的桶具有公共访问权限(支持匿名访问),请将 --access-key
设置为 anonymous
。
JuiceFS 中可选择任意一种风格来指定存储桶的地址,例如:
- 虚拟托管类型
- 路径类型
juicefs format \
--storage s3 \
--bucket https://<bucket>.s3.<region>.amazonaws.com \
... \
myjfs
juicefs format \
--storage s3 \
--bucket https://s3.<region>.amazonaws.com/<bucket> \
... \
myjfs
你也可以将 --storage
设置为 s3
用来连接 S3 兼容的对象存储,比如:
- 虚拟托管类型
- 路径类型
juicefs format \
--storage s3 \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
juicefs format \
--storage s3 \
--bucket https://<endpoint>/<bucket> \
... \
myjfs
所有 S3 兼容的对象存储服务其 --bucket
选项的格式为 https://<bucket>.<endpoint>
或者 https://<endpoint>/<bucket>
,默认的 region
为 us-east-1
,当需要不同的 region
的时候,可以通过环境变量 AWS_REGION
或者 AWS_DEFAULT_REGION
手动设置。
Google 云存储
Google 云采用 IAM 管理资源的访问权限,通过对服务账号授权,可以对云服务器、对象存储的访问权限进行精细化的控制。
对于归属于同一服务账号的云服务器和对象存储,只要该账号赋予了相关资源的访问权限,创建 JuiceFS 文件系统时无需提供身份验证信息,云平台会自行完成鉴权。
对于要从谷歌云平台外部访问对象存储的情况,比如要在本地计算机上使用 Google 云存储创建 JuiceFS 文件系统,则需要配置认证信息。由于 Google 云存储并不使用 Access Key ID 和 Access Key Secret,而是通过服务账号的 JSON 密钥文件验证身份。
请参考「以服务帐号身份进行身份验证」为服务账号创建 JSON 密钥文件并下载到本地计算机,通过 GOOGLE_APPLICATION_CREDENTIALS
环境变量定义密钥文件的路径,例如:
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/service-account-file.json"
可以把创建环境变量的命令写入 ~/.bashrc
或 ~/.profile
让 Shell 在每次启动时自动设置。
配置了传递密钥信息的环境变量以后,在本地和在 Google 云服务器上创建文件系统的命令是完全相同的。例如:
juicefs format \
--storage gs \
--bucket <bucket>[.region] \
... \
myjfs
可以看到,命令中无需包含身份验证信息,客户端会通过前面环境变量设置的 JSON 密钥文件完成对象存储的访问鉴权。同时,由于 bucket 名称是 全局唯一 的,创建文件系统时,--bucket
选项中只需指定 bucket 名称即可。
Azure Blob 存储
使用 Azure Blob 存储作为 JuiceFS 的数据存储,请先 查看文档 了解如何查看存储帐户的名称和密钥,它们分别对应 --access-key
和 --secret-key
选项的值。
--bucket
选项的设置格式为 https://<container>.<endpoint>
,请将其中的 <container>
替换为实际的 Blob 容器的名称,将 <endpoint>
替换为 core.windows.net
(Azure 全球)或 core.chinacloudapi.cn
(Azure 中国)。例如:
juicefs format \
--storage wasb \
--bucket https://<container>.<endpoint> \
--access-key <storage-account-name> \
--secret-key <storage-account-access-key> \
... \
myjfs
除了使用 --access-key
和 --secret-key
选项之外,你也可以使用 连接字符串 并通过 AZURE_STORAGE_CONNECTION_STRING
环境变量进行设定。例如:
# Use connection string
export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=XXX;AccountKey=XXX;EndpointSuffix=core.windows.net"
juicefs format \
--storage wasb \
--bucket https://<container> \
... \
myjfs
对于 Azure 中国用户,EndpointSuffix
的值为 core.chinacloudapi.cn
。
Backblaze B2
使用 Backblaze B2 作为 JuiceFS 的数据存储,需要先创建 application key,Application Key ID 和 Application Key 分别对应 Access Key 和 Secret Key。
Backblaze B2 支持两种访问接口:B2 原生 API 和 S3 兼容 API。
B2 原生 API
存储类型应设置为 b2
,--bucket
只需设置 bucket 名称。例如:
juicefs format \
--storage b2 \
--bucket <bucket> \
--access-key <application-key-ID> \
--secret-key <application-key> \
... \
myjfs
S3 兼容 API
存储类型应设置为 s3
,--bucket
应指定完整的 bucket 地址。例如:
juicefs format \
--storage s3 \
--bucket https://s3.eu-central-003.backblazeb2.com/<bucket> \
--access-key <application-key-ID> \
--secret-key <application-key> \
... \
myjfs
IBM 云对象存储
使用 IBM 云对象存储创建 JuiceFS 文件系统,你首先需要创建 API key 和 instance ID。API key 和 instance ID 分别对应 Access Key 和 Secret Key。
IBM 云对象存储为每一个区域提供了 公网
和 内网
两种 endpoint 地址,你可以根据实际需要选用。例如:
juicefs format \
--storage ibmcos \
--bucket https://<bucket>.<endpoint> \
--access-key <API-key> \
--secret-key <instance-ID> \
... \
myjfs
Oracle 云对象存储
Oracle 云对象存储支持 S3 兼容的形式进行访问,详细请参考官方文档。
该对象存储的 endpoint
格式为:${namespace}.compat.objectstorage.${region}.oraclecloud.com
,例如:
juicefs format \
--storage s3 \
--bucket https://<bucket>.<endpoint> \
--access-key <your-access-key> \
--secret-key <your-sceret-key> \
... \
myjfs
Scaleway
使用 Scaleway 对象存储作为 JuiceFS 数据存储,请先 查看文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的设置格式为 https://<bucket>.s3.<region>.scw.cloud
,请将其中的 <region>
替换成实际的区域代码,例如:荷兰阿姆斯特丹的区域代码是 nl-ams
。点此查看 所有可用的区域代码。
juicefs format \
--storage scw \
--bucket https://<bucket>.s3.<region>.scw.cloud \
... \
myjfs
DigitalOcean Spaces
使用 DigitalOcean Spaces 作为 JuiceFS 数据存储,请先 查看文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的设置格式为 https://<space-name>.<region>.digitaloceanspaces.com
,请将其中的 <region>
替换成实际的区域代码,例如:nyc3
。点此查看 所有可用的区域代码。
juicefs format \
--storage space \
--bucket https://<space-name>.<region>.digitaloceanspaces.com \
... \
myjfs
Wasabi
使用 Wasabi 作为 JuiceFS 数据存储,请先 查看文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的设置格式为 https://<bucket>.s3.<region>.wasabisys.com
,请将其中的 <region>
替换成实际的区域代码,例如:US East 1 (N. Virginia) 的区域代码为 us-east-1
。点此查看 所有可用的区域代码。
juicefs format \
--storage wasabi \
--bucket https://<bucket>.s3.<region>.wasabisys.com \
... \
myjfs
Tokyo (ap-northeast-1) 区域的用户,查看 这篇文档 了解 endpoint URI 的设置方法。
Storj DCS
使用 Storj DCS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
Storj DCS 兼容 AWS S3,存储类型使用 s3
,--bucket
格式为 https://gateway.<region>.storjshare.io/<bucket>
。<region>
为存储区域,目前 DCS 有三个可用存储区域:us1、ap1 和 eu1。
juicefs format \
--storage s3 \
--bucket https://gateway.<region>.storjshare.io/<bucket> \
--access-key <your-access-key> \
--secret-key <your-sceret-key> \
... \
myjfs
因为 Storj DCS 的 ListObjects API 并非完全 S3 兼容(返回结果没有实现排序功能),所以 JuiceFS 的部分功能无法使用,比如 juicefs gc
,juicefs fsck
,juicefs sync
,juicefs destroy
。另外,使用 juicefs mount
时需要关闭元数据自动备份功能,即加上 --backup-meta 0
。
Vultr 对象存储
Vultr 的对象存储兼容 S3 API,存储类型使用 s3
,--bucket
格式为 https://<bucket>.<region>.vultrobjects.com/
。例如:
juicefs format \
--storage s3 \
--bucket https://<bucket>.ewr1.vultrobjects.com/ \
--access-key <your-access-key> \
--secret-key <your-sceret-key> \
... \
myjfs
访问对象存储的 API 密钥可以在 管理控制台 中找到。
Cloudflare R2
R2 是 Cloudflare 的对象存储服 务,提供 S3 兼容的 API,因此用法与 Amazon S3 基本一致。请参照文档了解如何创建 Access Key 和 Secret Key。
juicefs format \
--storage s3 \
--bucket https://<ACCOUNT_ID>.r2.cloudflarestorage.com/myjfs \
--access-key <your-access-key> \
--secret-key <your-sceret-key> \
... \
myjfs
对于生产环境,建议通过 ACCESS_KEY
和 SECRET_KEY
环境变量传递密钥信息,例如:
export ACCESS_KEY=<your-access-key>
export SECRET_KEY=<your-sceret-key>
juicefs format \
--storage s3 \
--bucket https://<ACCOUNT_ID>.r2.cloudflarestorage.com/myjfs \
... \
myjfs
因为 Cloudflare R2 的 ListObjects
API 并非完全 S3 兼容(返回结果没有实现排序功能),所以 JuiceFS 的部分功能无法使用,比如 juicefs gc
、juicefs fsck
、juicefs sync
、juicefs destroy
。另外,使用 juicefs mount
时需要关闭元数据自动备份功能,即加上 --backup-meta 0
。
阿里云 OSS
使用阿里云 OSS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。如果你已经创建了 RAM 角色 并指派给了云服务器实例,则在创建文件系统时可以忽略 --access-key
和 --secret-key
选项。
阿里云也支持使用 Security Token Service (STS) 作为 OSS 的临时访问身份验证。如果你要使用 STS,请设置 ALICLOUD_ACCESS_KEY_ID
、ALICLOUD_ACCESS_KEY_SECRET
和 SECURITY_TOKEN
环境变量,不要设置 --access-key
and --secret-key
选项。例如:
# Use Security Token Service (STS)
export ALICLOUD_ACCESS_KEY_ID=XXX
export ALICLOUD_ACCESS_KEY_SECRET=XXX
export SECURITY_TOKEN=XXX
juicefs format \
--storage oss \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
阿里云 OSS 为每个区域都提供了 公网
和 内网
endpoint 链接,你可以根据实际的场景选用。
如果你是在阿里云的服务器上创建文件系统,可以在 --bucket
选项中直接指定 bucket 名称。例如:
# 在阿里云中运行
juicefs format \
--storage oss \
--bucket <bucket> \
... \
myjfs
腾讯云 COS
使用腾讯云 COS 作为 JuiceFS 数据存储,Bucket 名称格式为 <bucket>-<APPID>
,即需要在 bucket 名称后面指定 APPID
,点此查看 如何获取 APPID
。
--bucket
选项的完整格式为 https://<bucket>-<APPID>.cos.<region>.myqcloud.com
,请将 <region>
替换成你实际使用的存储区域,例如:上海的区域代码为 ap-shanghai
。点此查看 所有可用的区域代码。例如:
juicefs format \
--storage cos \
--bucket https://<bucket>-<APPID>.cos.<region>.myqcloud.com \
... \
myjfs
如果你是在腾讯云的服务器上创建文件系统,可以在 --bucket
选项中直接指定 bucket 名称。例如:
# 在腾讯云中运行
juicefs format \
--storage cos \
--bucket <bucket>-<APPID> \
... \
myjfs
华为云 OBS
使用华为云 OBS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.obs.<region>.myhuaweicloud.com
,请将 <region>
替换成你实际使用的存储区域,例如:北京一的区域代码为 cn-north-1
。点此查看 所有可用的区域代码。例如:
juicefs format \
--storage obs \
--bucket https://<bucket>.obs.<region>.myhuaweicloud.com \
... \
myjfs
如果是你在华为云的服务器上创建文件系统,可以在 --bucket
直接指定 bucket 名称。例如:
# 在华为云中运行
juicefs format \
--storage obs \
--bucket <bucket> \
... \
myjfs
百度 BOS
使用百度云 BOS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.<region>.bcebos.com
,请将 <region>
替换成你实际使用的存储区域,例如:北京的区域代码为 bj
。点此查看 所有可用的区域代码。例如:
juicefs format \
--storage bos \
--bucket https://<bucket>.<region>.bcebos.com \
... \
myjfs
如果你是在百度云的服务器上创建文件系统,可以在 --bucket
直接指定 bucket 名称。例如:
# 在百度云中运行
juicefs format \
--storage bos \
--bucket <bucket> \
... \
myjfs
火山引擎 TOS 新增自 v1.0.3
使用火山引擎 TOS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
火山引擎 TOS 为每个区域都提供了公网和内网 endpoint 链接,你可以根据实际的场景选用。
juicefs format \
--storage tos \
--bucket https://<bucket>.<endpoint>\
... \
myjfs
金山云 KS3
使用金山云 KS3 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
金山云 KS3 为每个区域都提供了公网和内网 endpoint 链接,你可以根据实际的场景选用。
juicefs format \
--storage ks3 \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
青云 QingStor
使用青云 QingStor 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.<region>.qingstor.com
,请将 <region>
替换成你实际使用的存储区域,例如:北京 3-A 的区域代码为 pek3a
。点此查看 所有可用的区域代码。例如:
juicefs format \
--storage qingstor \
--bucket https://<bucket>.<region>.qingstor.com \
... \
myjfs
所有 QingStor 兼容的对象存储服务其 --bucket
选项的格式为 http://<bucket>.<endpoint>
。
七牛云 Kodo
使用七牛云 Kodo 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.s3-<region>.qiniucs.com
,请将 <region>
替换成你实际使用的存储区域,例如:中国东部的区域代码为 cn-east-1
。点此查看 所有可用的区域代码。例如:
juicefs format \
--storage qiniu \
--bucket https://<bucket>.s3-<region>.qiniucs.com \
... \
myjfs
新浪云 SCS
使用新浪云 SCS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项格式为 https://<bucket>.stor.sinaapp.com
。例如:
juicefs format \
--storage scs \
--bucket https://<bucket>.stor.sinaapp.com \
... \
myjfs
天翼云 OOS
使用天翼云 OOS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.<endpoint>
,例如:
juicefs format \
--storage oos \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
移动云 EOS
使用移动云 EOS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
移动云 EOS 为每个区域都提供了 公网
和 内网
endpoint 链接,你可以根据实际的场景选用。例如:
juicefs format \
--storage eos \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
京东云 OSS
使用京东云 OSS 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
--bucket
选项的格式为 https://<bucket>.<region>.jdcloud-oss.com
,请将 <region>
替换成你实际使用的存储区域,区域代码点此查看 。例如:
juicefs format \
--storage s3 \
--bucket https://<bucket>.<region>.jdcloud-oss.com \
... \
myjfs
优刻得 US3
使用优刻得 US3 作为 JuiceFS 数据存储,请先参照 这篇文档 了解如何创建 Access Key 和 Secret Key。
优刻得 US3(原名 UFile)为每个区域都提供了 公网
和 内网
endpoint 链接,你可以根据实际的场景选用。例如:
juicefs format \
--storage ufile \
--bucket https://<bucket>.<endpoint> \
... \
myjfs
Ceph RADOS
Ceph 存储集群 具有消息传递层协议,该协议使客户端能够与 Ceph Monitor 和 Ceph OSD 守护程序进行交互。librados
API 使您可以与这两种类型的守护程序进行交互:
- Ceph Monitor 维护群集映射的主副本
- Ceph OSD Daemon (OSD) 将数据作为对象存储在存储节点上
JuiceFS 支持使用基于 librados
的本地 Ceph API。您需要分别安装 librados
库并重新编译 juicefs
二进制文件。
首先安装 librados
,建议使用匹配你的 Ceph 版本的 librados
,例如 Ceph 版本是 Octopus(v15.2.x),那么 librados
也建议使用 v15.2.x 版本。
- Debian 及衍生版本
- RHEL 及衍生版本
sudo apt-get install librados-dev
sudo yum install librados2-devel
然后为 Ceph 编译 JuiceFS(要求 Go 1.20+ 和 GCC 5.4+):
make juicefs.ceph
在使用 Ceph 时,原本 JuiceFS 客户端的对象存储参数的含义不太相同:
--bucket
是 Ceph 存储池,格式为ceph://<pool-name>
,存储池是用于存储对象的逻辑分区,使用前需要先创建好--access-key
选项的值是 Ceph 集群名称,默认集群名称是ceph
。--secret-key
选项的值是 Ceph 客户端用户名,默认用户名是client.admin
。
为了连接到 Ceph Monitor,librados
将通过搜索默认位置读取 Ceph 的配置文件,并使用找到的第一个。这些位置是:
CEPH_CONF
环境变量/etc/ceph/ceph.conf
~/.ceph/config
- 在当前工作目录中的
ceph.conf
创建一个文件系统:
juicefs.ceph format \
--storage ceph \
--bucket ceph://<pool-name> \
--access-key <cluster-name> \
--secret-key <user-name> \
... \
myjfs
Ceph RGW
Ceph Object Gateway 是在 librados
之上构建的对象存储接口,旨在为应用程序提供访问 Ceph 存储集群的 RESTful 网关。Ceph 对象网关支持 S3 兼容的接口,因此我们可以将 --storage
设置为 s3
。
--bucket
选项的格式为 http://<bucket>.<endpoint>
(虚拟托管类型),例如:
juicefs format \
--storage s3 \
--bucket http://<bucket>.<endpoint> \
... \
myjfs
Gluster
Gluster 是一款开源的软件定义分布式存储,单集群能支持 PiB 级别的数据。JuiceFS 通过 libgfapi
库与 Gluster 集群交互,使用前需要单独编译。
首先安装 libgfapi
(版本范围 6.0 - 10.1, 10.4+ 暂不支持):
- Debian 及衍生版本
- RHEL 及衍生版本
sudo apt-get install uuid-dev libglusterfs-dev glusterfs-common
sudo yum install glusterfs glusterfs-api-devel glusterfs-libs
然后编译支持 Gluster 的 JuiceFS:
make juicefs.gluster
现在我们可以创建出基于 Gluster 的 JuiceFS volume:
juicefs format \
--storage gluster \
--bucket host1,host2,host3/gv0 \
... \
myjfs
其中 --bucket
选项格式为 <host[,host...]>/<volume_name>
。注意这里的 volume_name
为 Gluster 中的卷名称,与 JuiceFS volume 自身的名字没有直接关系。
Swift
OpenStack Swift 是一种分布式对象存储系统,旨在从一台计算机扩展到数千台服务器。Swift 已针对多租户和高并发进行了优化。Swift 广泛适用于备份、Web 和移动内容的理想选择,可以无限量存储任何非结构化数据。
--bucket
选项格式为 http://<container>.<endpoint>
,container
用来设定对象的命名空间。
当前,JuiceFS 仅支持 Swift V1 authentication。
--access-key
选项的值是用户名,--secret-key
选项的值是密码。例如:
juicefs format \
--storage swift \
--bucket http://<container>.<endpoint> \
--access-key <username> \
--secret-key <password> \
... \
myjfs
MinIO
MinIO 是开源的轻量级对象存储,兼容 Amazon S3 API。
使用 Docker 可以很容易地在本地运行一个 MinIO 实例。例如,以下命令通过 --console-address ":9900"
为控制台设置并映射了 9900
端口,还将 MinIO 的数据路径映射到了当前目录下的 minio-data
文件夹中,你可以按需修改这些参数:
$ sudo docker run -d --name minio \
-p 9000:9000 \
-p 9900:9900 \
-e "MINIO_ROOT_USER=minioadmin" \
-e "MINIO_ROOT_PASSWORD=minioadmin" \
-v $PWD/minio-data:/data \
--restart unless-stopped \
minio/minio server /data --console-address ":9900"
容器创建成功以后使用以下地址访问:
- MinIO API:http://127.0.0.1:9000,这也是 JuiceFS 访问对象存储时所使用的的 API
- MinIO 管理界面:http://127.0.0.1:9900,用于管理对象存储本身,与 JuiceFS 无关
对象存储初始的 Access Key 和 Secret Key 均为 minioadmin
。
使用 MinIO 作为 JuiceFS 的数据存储,--storage
选项设置为 minio
。
juicefs format \
--storage minio \
--bucket http://127.0.0.1:9000/<bucket> \
--access-key minioadmin \
--secret-key minioadmin \
... \
myjfs
- 当前,JuiceFS 仅支持路径风格的 MinIO URI 地址,例如:
http://127.0.0.1:9000/myjfs
MINIO_REGION
环境变量可以用于设置 MinIO 的 region,如果不设置,默认为us-east-1
- 面对多节点 MinIO 集群,考虑在 Endpoint 中使用 DNS 域名,解析到各个 MinIO 节点,作为简易负载均衡,比如
http://minio.example.com:9000/myjfs
WebDAV
WebDAV 是 HTTP 的扩展协议,有利于用户间协同编辑和管理存储在万维网服务器的文档。JuiceFS 0.15+ 支持使用 WebDAV 协议的存储系统作为后端数据存储。
你需要将 --storage
设置为 webdav
,并通过 --bucket
来指定访问 WebDAV 的地址。如果存储系统启用了用户验证,用户名和密码可以通过 --access-key
和 --secret-key
来指定,例如:
juicefs format \
--storage webdav \
--bucket http://<endpoint>/ \
--access-key <username> \
--secret-key <password> \
... \
myjfs
HDFS
Hadoop 的文件系统 HDFS 也可以作为对象存储供 JuiceFS 使用。
当使用 HDFS 作为 JuiceFS 数据存储,--access-key
的值设置为用户名,默认的超级用户通常是 hdfs
。例如:
juicefs format \
--storage hdfs \
--bucket namenode1:8020 \
--access-key hdfs \
... \
myjfs
如果在创建文件系统时不指定 --access-key
,JuiceFS 会使用执行 juicefs mount
命令的用户身份或通过 Hadoop SDK 访问 HDFS 的用户身份。如果该用户没有 HDFS 的读写权限,则程序会失败挂起,发生 IO 错误。
JuiceFS 会尝试基于 $HADOOP_CONF_DIR
或 $HADOOP_HOME
为 HDFS 客户端加载配置。如果 --bucket
选项留空,将使用在 Hadoop 配置中找到的默认 HDFS。
bucket 参数支持格式如下:
[hdfs://]namenode:port[/path]
对于 HA 集群,bucket 参数可以:
[hdfs://]namenode1:port,namenode2:port[/path]
[hdfs://]nameservice[/path]
对于启用 Kerberos 的 HDFS,可以通过 KRB5KEYTAB
和 KRB5PRINCIPAL
环境变量来指定 keytab 和 principal。
Apache Ozone
Apache Ozone 是 Hadoop 的分布式对象存储系统,提供了 S3 兼容的 API。所以可以通过 S3 兼容的模式作为对象存储供 JuiceFS 使用。例如:
juicefs format \
--storage s3 \
--bucket http://<endpoint>/<bucket>\
--access-key <your-access-key> \
--secret-key <your-sceret-key> \
... \
myjfs
Redis
Redis 既可以作为 JuiceFS 的元数据存储,也可以作为数据存储,但当使用 Redis 作为数据存储时,建议不要存储大规模数据。
单机模式
--bucket
选项格式为 redis://<host>:<port>/<db>
。--access-key
选项的值是用户名,--secret-key
选项的值是密码。例如:
juicefs format \
--storage redis \
--bucket redis://<host>:<port>/<db> \
--access-key <username> \
--secret-key <password> \
... \
myjfs
Redis Sentinel
Redis Sentinel 模式下,--bucket
选项格式为 redis[s]://MASTER_NAME,SENTINEL_ADDR[,SENTINEL_ADDR]:SENTINEL_PORT[/DB]
。Sentinel 的密码则需要通过 SENTINEL_PASSWORD_FOR_OBJ
环境变量来声明。例如:
export SENTINEL_PASSWORD_FOR_OBJ=sentinel_password
juicefs format \
--storage redis \
--bucket redis://masterName,1.2.3.4,1.2.5.6:26379/2 \
--access-key <username> \
--secret-key <password> \
... \
myjfs
Redis 集群
Redis 集群模式下,--bucket
选项格式为 redis[s]://ADDR:PORT,[ADDR:PORT],[ADDR:PORT]
。例如:
juicefs format \
--storage redis \
--bucket redis://127.0.0.1:7000,127.0.0.1:7001,127.0.0.1:7002 \
--access-key <username> \
--secret-key <password> \
... \
myjfs
TiKV
TiKV 是一个高度可扩展、低延迟且易于使用的键值数据库。它提供原始和符合 ACID 的事务键值 API。
TiKV 既可以用作 JuiceFS 的元数据存储,也可以用于 JuiceFS 的数据存储。
建议使用独立部署的 TiKV 5.0+ 集群作为 JuiceFS 的数据存储
--bucket
选项格式类似 <host>:<port>,<host>:<port>,<host>:<port>
,其中 <host>
是 Placement Driver(PD)的地址。--access-key
和 --secret-key
选项没有作用,可以省略。例如:
juicefs format \
--storage tikv \
--bucket "<host>:<port>,<host>:<port>,<host>:<port>" \
... \
myjfs
不要使用同一个 TiKV 集群来存储元数据和数据,因为 JuiceFS 是使用不同的协议来存储元数据(支持事务的 TxnKV) 和数据 (不支持事务的 RawKV),TxnKV 的对象名会被编码后存储,即使添加了不同的前缀也可能导致它们的名字冲突。另外,建议启用 Titan 来提升存储数据的集群的性能。
设置 TLS
如果需要开启 TLS,可以通过在 Bucket URL 后以添加 query 参数的形式设置 TLS 的配置项,目前支持的配置项:
配置项 | 值 |
---|---|
ca | CA 根证书,用于用 TLS 连接 TiKV/PD |
cert | 证书文件路径,用于用 TLS 连接 TiKV/PD |
key | 私钥文件路径,用于用 TLS 连接 TiKV/PD |
verify-cn | 证书通用名称,用于验证调用者身份,详情 |
例子:
juicefs format \
--storage tikv \
--bucket "<host>:<port>,<host>:<port>,<host>:<port>?ca=/path/to/ca.pem&cert=/path/to/tikv-server.pem&key=/path/to/tikv-server-key.pem&verify-cn=CN1,CN2" \
... \
myjfs
etcd
etcd 是一个高可用高可靠的小规模键值数据库,既可以用作 JuiceFS 的元数据存储,也可以用于 JuiceFS 的数据存储。
etcd 默认会限制单个请求不能超过 1.5MB,需要将 JuiceFS 的分块大小(--block-size
选项)改成 1MB 甚至更低。
--bucket
选项需要填 etcd 的地址,格式类似 <host1>:<port>,<host2>:<port>,<host3>:<port>
。--access-key
和 --secret-key
选项填用户名和密码,当 etcd 没有启用用户认证时可以省略。例如:
juicefs format \
--storage etcd \
--block-size 1024 \ # 这个选项非常重要
--bucket "<host1>:<port>,<host2>:<port>,<host3>:<port>/prefix" \
--access-key myname \
--secret-key mypass \
... \
myjfs
设置 TLS
如果需要开启 TLS,可以通过在 Bucket URL 后以添加 query 参数的形式设置 TLS 的配置项,目前支持的配置项:
配置项 | 值 |
---|---|
cacert | CA 根证书 |
cert | 证书文件路径 |
key | 私钥文件路径 |
server-name | 服务器名称 |
insecure-skip-verify | 1 |
例子:
juicefs format \
--storage etcd \
--bucket "<host>:<port>,<host>:<port>,<host>:<port>?cacert=/path/to/ca.pem&cert=/path/to/server.pem&key=/path/to/key.pem&server-name=etcd" \
... \
myjfs
证书的路径需要使用绝对路径,并且确保所有需要挂载的机器上能用该路径访问到它们。
SQLite
SQLite 是全球广泛使用的小巧、快速、单文件、可靠、全功能的单文件 SQL 数据库引擎。
使用 SQLite 作为数据存储时只需要指定它的绝对路径即可。
juicefs format \
--storage sqlite3 \
--bucket /path/to/sqlite3.db \
... \
myjfs
由于 SQLite 是一款嵌入式数据库,只有数据库所在的主机可以访问它,不能用于多机共享场景。如果格式化时使用的是相对路径,会导致挂载时出问题,请使用绝对路径。
MySQL
MySQL 是受欢迎的开源关系型数据库之一,常被作为 Web 应用程序的首选数据库,既可以作为 JuiceFS 的元数据引擎也可以用来存储文件数据。跟 MySQL 兼容的 MariaDB、TiDB 等都可以用来作为数据存储。
使用 MySQL 作为数据存储时,需要提前创建数据库并添加想要权限,通过 --bucket
选项指定访问地址,通过 --access-key
选项指定用户名,通过 --secret-key
选项指定密码,示例如下:
juicefs format \
--storage mysql \
--bucket (<host>:3306)/<database-name> \
--access-key <username> \
--secret-key <password> \
... \
myjfs
创建文件系统后,JuiceFS 会在该数据库中创建名为 jfs_blob
的表用来存储数据。
不要漏掉 --bucket
参数里的括号 ()
。
PostgreSQL
PostgreSQL 是功能强大的开源关系型数据库,有完善的生态和丰富的应用场景,既可以作为 JuiceFS 的元数据引擎也可以作为数据存储。其他跟 PostgreSQL 协议兼容的数据库(比如 CockroachDB 等) 也可以用来作为数据存储。
创建文件系统时需要先创建好数据库并添加相应读写权限,使用 --bucket
选项来指定数据的地址,使用 --access-key
选项指定用户名,使用 --secret-key
选项指定密码,示例如下:
juicefs format \
--storage postgres \
--bucket <host>:<port>/<db>[?parameters] \
--access-key <username> \
--secret-key <password> \
... \
myjfs
创建文件系统后,JuiceFS 会在该数据库中创建名为 jfs_blob
的表用来存储数据。
故障排除
JuiceFS 客户端默认采用 SSL 加密连接 PostgreSQL,如果连接时报错 pq: SSL is not enabled on the server
说明数据库没有启用 SSL。可以根据业务场景为 PostgreSQL 启用 SSL 加密,也可以在 bucket URL 中添加参数 sslmode=disable
禁用加密验证。
本地磁盘
在创建 JuiceFS 文件系统时,如果没有指定任何存储类型,会默认使用本地磁盘作为数据存储,root 用户默认存储路径为 /var/jfs
,普通用户默认存储路径为 ~/.juicefs/local
。
例如,以下命令使用本地的 Redis 数据库和本地磁盘创建了一个名为 myfs
的文件系统:
juicefs format redis://localhost:6379/1 myjfs
本地存储通常仅用于了解和体验 JuiceFS 的基本功能,创建的 JuiceFS 存储无法被网络内的其他客户端挂载,只能单机使用。
SFTP/SSH
SFTP 全称 Secure File Transfer Protocol 即安全文件传输协议,它并不是文件存储。准确来说,JuiceFS 是通过 SFTP/SSH 这种文件传输协议对远程主机上的磁盘进行连接和读写,从而让任何启用了 SSH 服务的操作系统都可以作为 JuiceFS 的数据存储来使用。
例如,以下命令使用 SFTP 协议连接远程服务器 192.168.1.11
,在用户 tom
的 $HOME
目录下创建 myjfs/
文件夹作为文件系统的数据存储。
juicefs format \
--storage sftp \
--bucket 192.168.1.11:myjfs/ \
--access-key tom \
--secret-key 123456 \
...
redis://localhost:6379/1 myjfs
注意事项
--bucket
用来设置服务器的地址及存储路径,格式为[sftp://]<IP/Domain>:[port]:<Path>
。注意,目录名应该以/
结尾,端口号为可选项默认为22
,例如192.168.1.11:22:myjfs/
。--access-key
用来设置远程服务器的用户名--secret-key
用来设置远程服务器的密码
NFS
NFS - Network File System,即网络文件系统,是类 Unix 操作系统中很常用的文件共享服务,它可以让网络内的计算机能够像访问本地文件一样访问远程文件。
JuiceFS 支持使用 NFS 作为底层存储来构建文件系统,提供两种使用方式:本地挂载和直连模式。
本地挂载
JuiceFS v1.1 及之前的版本仅支持本地挂载的方式使用 NFS 作为底层存储,这种方式需要先在本地挂载 NFS 服务器上的目录,然后以本地磁盘的方式使用它来创建 JuiceFS 文件系统。
例如,先把远程 NFS 服务器 192.168.1.11
上的 /srv/data
目录挂载到本地的 /mnt/data
目录,然后再使用 file
模式访问。
$ sudo mount -t nfs 192.168.1.11:/srv/data /mnt/data
$ sudo juicefs format \
--storage file \
--bucket /mnt/data \
...
redis://localhost:6379/1 myjfs
从 JuiceFS 的角度来看,本地挂载的 NFS 仍然是本地磁盘,所以 --storage
选项设置为 file
。
同理,由于底层存储只能在挂载的设备上访问,所以要在多台设备上共享访问,则需要在每台设备上分别挂载 NFS 共享,或通过 WebDAV、S3 Gateway 等基于网络的方式来提供外部访问。