sidebar_label	sidebar_position	slug
如何设置对象存储	4	/how_to_setup_object_storage

JuiceFS 如何设置对象存储

通过阅读 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

其他参数

在执行 format 或 mount 命令时，可以在--bucket参数中以URL参数的形式设置一些特别的参数，比如https://myjuicefs.s3.us-east-2.amazonaws.com?tls-insecure-skip-verify=true 即为https请求跳过证书验证。

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。

使用临时访问凭证

永久访问凭证一般有两个部分，accessKey，secretKey，而临时访问凭证一般包括 3 个部分，accessKey，secretKey 与 token，并且临时访问凭证具有过期时间，一般在几分钟到几个小时之间。

如何获取临时凭证

不同云厂商的获取方式不同，一般是需要以具有相应权限用户的 accessKey，secretKey 以及代表临时访问凭证的权限边界的 ARN 作为参数请求访问云服务厂商的 STS 服务器来获取临时访问凭证。这个过程一般可以由云厂商提供的 SDK 简化操作。比如 AWS S3 获取临时凭证方式可以参考这个链接，阿里云 OSS 获取临时凭证方式可以参考这个链接。

如何使用临时访问凭证设置对象存储

使用临时凭证的方式与使用永久凭证差异不大，在文件系统 format 时，将临时凭证的 accessKey， secretKey， 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

由于临时凭证很快就会过期，所以关键在于在 format 文件系统后，如何在临时凭证过期前更新 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 进行挂载访问。

存储类型

对象存储通常支持多种存储类型，如标准存储、低频访问存储、归档存储。当创建对象存储 bucket 时你可以根据实际需求选择合适的存储类型，或者通过生命周期管理自动转换现有对象的存储类型。对于那些支持实时访问数据的存储类型（如标准存储、低频访问存储），可以作为 JuiceFS 底层的数据存储，而那些需要提前解冻才能访问的存储类型（如归档存储）则不行。

:::note 注意当使用某些存储类型（如低频访问）时，会有最小计费单位，读取数据也可能会产生额外的费用，请查阅你所使用的对象存储的用户手册了解详细信息。 :::

使用代理

如果客户端所在的网络环境受防火墙策略或其他因素影响需要通过代理访问外部的对象存储服务，使用的操作系统不同，相应的代理设置方法也不同，请参考相应的用户手册进行设置。

以 Linux 为例，可以通过创建 http_proxy 和 https_proxy 环境变量设置代理：

$ export http_proxy=http://localhost:8035/
$ export https_proxy=http://localhost:8035/
$ juicefs format \
    --storage s3 \
    ... \
    myjfs

支持的存储服务

如果你希望使用的存储类型不在列表中，欢迎提交需求 issue。

Name	Value
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`
阿里云 OSS	`oss`
腾讯云 COS	`cos`
华为云 OBS	`obs`
百度云 BOS	`bos`
金山云 KS3	`ks3`
网易云 NOS	`nos`
青云 QingStor	`qingstor`
七牛云 Kodo	`qiniu`
新浪云 SCS	`scs`
天翼云 OOS	`oos`
移动云 EOS	`eos`
优刻得 US3	`ufile`
Ceph RADOS	`ceph`
Ceph RGW	`s3`
Swift	`swift`
MinIO	`minio`
WebDAV	`webdav`
HDFS	`hdfs`
Apache Ozone	`s3`
Redis	`redis`
TiKV	`tikv`
etcd	`etcd`
SQLite	`sqlite3`
MySQL	`mysql`
PostgreSQL	`postgres`
本地磁盘	`file`

Amazon S3

S3 支持两种风格的 endpoint URI：虚拟托管类型 和 路径类型。

虚拟托管类型：https://<bucket>.s3.<region>.amazonaws.com
路径类型：https://s3.<region>.amazonaws.com/<bucket>

其中 <region> 要替换成实际的区域代码，比如：美国西部（俄勒冈）的区域代码为 us-west-2。点此查看所有的区域代码。

:::note 注意 AWS 中国的用户，应使用 amazonaws.com.cn 域名。相应的区域代码信息点此查看。 :::

:::note 注意如果 S3 的桶具有公共访问权限（支持匿名访问），请将 --access-key 设置为 anonymous。 :::

JuiceFS v0.12 之前的版本仅支持虚拟托管类型，v0.12 以及之后的版本两种风格都支持。例如：

# 虚拟托管类型
$ 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

:::tip 提示所有 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> \
    ... \
    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

:::note 注意对于 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

:::note 注意 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

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 密钥可以在管理控制台中找到。

阿里云 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 名称。例如：

# Running within Tencent Cloud
$ 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 名称。例如：

# Running within Huawei Cloud
$ 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 名称。例如：

# Running within Baidu Cloud
$ juicefs format \
    --storage bos \
    --bucket <bucket> \
    ... \
    myjfs

金山云 KS3

使用金山云 KS3 作为 JuiceFS 数据存储，请先参照这篇文档了解如何创建 Access key 和 Secret key。

金山云 KS3 为每个区域都提供了 公网 和 内网 endpoint 链接，你可以根据实际的场景选用。

$ juicefs format \
    --storage ks3 \
    --bucket https://<bucket>.<endpoint> \
    ... \
    myjfs

网易云 NOS

使用网易云 NOS 作为 JuiceFS 数据存储，请先参照这篇文档了解如何创建 Access key 和 Secret key。

网易云 NOS 为每个区域都提供了 公网 和 内网 endpoint 链接，你可以根据实际的场景选用。例如：

$ juicefs format \
    --storage nos \
    --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

:::note 注意所有 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

优刻得 US3

使用优刻得 US3 作为 JuiceFS 数据存储，请先参照这篇文档了解如何创建 Access key 和 Secret key。

优刻得 US3（原名 UFile）为每个区域都提供了 公网 和 内网 endpoint 链接，你可以根据实际的场景选用。例如：

$ juicefs format \
    --storage ufile \
    --bucket https://<bucket>.<endpoint> \
    ... \
    myjfs

Ceph RADOS

:::note 注意 JuiceFS 支持的 Ceph 最低版本是 Luminous（v12.2.*），请确认你的 Ceph 版本是否符合要求。 :::

Ceph 存储集群具有消息传递层协议，该协议使客户端能够与 Ceph Monitor 和 Ceph OSD 守护程序进行交互。librados API 使您可以与这两种类型的守护程序进行交互：

Ceph Monitor 维护群集映射的主副本
Ceph OSD Daemon (OSD) 将数据作为对象存储在存储节点上

JuiceFS 支持使用基于 librados 的本地 Ceph API。您需要分别安装 librados 库并重新编译 juicefs 二进制文件。

首先安装 librados：

:::note 注意建议使用匹配你的 Ceph 版本的 librados，例如 Ceph 版本是 Octopus（v15.2.*），那么 librados 也建议使用 v15.2.* 版本。某些 Linux 发行版（如 CentOS 7）自带的 librados 版本可能较低，如果编译 JuiceFS 失败可以尝试下载更高版本的安装包。 :::

# Debian based system
$ sudo apt-get install librados-dev

# RPM based system
$ sudo yum install librados2-devel

然后为 Ceph 编译 JuiceFS（要求 Go 1.17+ 和 GCC 5.4+）：

$ make juicefs.ceph

存储池是用于存储对象的逻辑分区，您可能需要首先创建一个存储池。 --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

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 管理界面：http://127.0.0.1:9900
MinIO API：http://127.0.0.1:9000

对象存储初始的 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

:::note 注意当前，JuiceFS 仅支持路径风格的 MinIO URI 地址，例如：http://127.0.0.1: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。

对于 HA 群集，可以像下面这样一起指定 NameNodes 的地址：--bucket=namenode1:port,namenode2:port。

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

TiKV

TiKV 是一个高度可扩展、低延迟且易于使用的键值数据库。它提供原始和符合 ACID 的事务键值 API。

TiKV 既可以用作 JuiceFS 的元数据存储，也可以用于 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

:::note 注意不要使用同一个集群来存储元数据和数据，因为 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 的分块大小改成 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

:::note 注意由于 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 的表用来存储数据。

:::note 注意不要漏掉 --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 加密，也可以在元数据 URL 中添加参数 sslmode=disable 禁用加密验证。

本地磁盘

在创建 JuiceFS 文件系统时，如果没有指定任何存储类型，会默认使用本地磁盘作为数据存储，root 用户默认存储路径为 /var/jfs，普通用户默认存储路径为 ~/.juicefs/local。

例如，以下命令使用本地的 Redis 数据库和本地磁盘创建了一个名为 myfs 的文件系统：

$ juicefs format redis://localhost:6379/1 myjfs

本地存储通常仅用于了解和体验 JuiceFS 的基本功能，创建的 JuiceFS 存储无法被网络内的其他客户端挂载，只能单机使用。

Files

how_to_setup_object_storage.md

Latest commit

History

how_to_setup_object_storage.md

File metadata and controls

JuiceFS 如何设置对象存储

存储参数

其他参数

Access Key 和 Secret Key

使用临时访问凭证

如何获取临时凭证

如何使用临时访问凭证设置对象存储

内网和外网 Endpoint

存储类型

使用代理

支持的存储服务

Amazon S3

Google 云存储

Azure Blob 存储

Backblaze B2

B2 原生 API

S3 兼容 API

IBM 云对象存储

Oracle 云对象存储

Scaleway

DigitalOcean Spaces

Wasabi

Storj DCS

Vultr 对象存储

阿里云 OSS

腾讯云 COS

华为云 OBS

百度 BOS

金山云 KS3

网易云 NOS

青云 QingStor

七牛云 Kodo

新浪云 SCS

天翼云 OOS

移动云 EOS

优刻得 US3

Ceph RADOS

Ceph RGW

Swift

MinIO

WebDAV

HDFS

Apache Ozone

Redis

TiKV

设置 TLS

etcd

设置 TLS

SQLite

MySQL

PostgreSQL

故障排除

本地磁盘