阿里云OSS-HDFS服务通过JindoFuse提供POSIX支持。JindoFuse可以把OSS-HDFS服务上的文件挂载到本地文件系统中，让您能够像操作本地文件系统一样操作OSS-HDFS服务中的文件。

前提条件

注意事项

EMR-3.44.0及以上版本或EMR-5.10.0及以上版本集群默认已安装JindoSDK以及所需依赖，您可以直接通过以上版本的EMR集群访问OSS-HDFS服务。

操作步骤

以下为非EMR环境下访问OSS-HDFS服务的操作步骤。

  1. 连接ECS实例。具体操作，请参见连接ECS实例。
  2. 安装Fuse3依赖。
    • CentOS
      yum install -y fuse3 fuse3-devel
    • Debian
      apt install -y fuse3 libfuse3-dev
  3. 配置客户端。
    1. 配置目录。
      解压下载的安装包。其中，x.x.x表示JindoSDK JAR包版本号。
      export JINDOSDK_CONF_DIR=/usr/lib/jindosdk-x.x.x/conf

      关于JindoFS SDK JAR包下载地址，请参见GitHub。

    2. 配置文件。
      使用.ini风格配置文件，配置文件的文件名为jindosdk.cfg，示例如下：
      [common]
logger.dir = /tmp/fuse-log

[jindosdk]
# 已开启HDFS服务的Bucket对应的Endpoint。以华东1（杭州）为例，填写为cn-hangzhou.oss-dls.aliyuncs.com。
fs.oss.endpoint = <your_endpoint>
# 用于访问OSS-HDFS服务的AccessKey ID和AccessKey Secret。阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
fs.oss.accessKeyId = <your_key_id>
fs.oss.accessKeySecret = <your_key_secret>
  4. 挂载JindoFuse。
    1. 创建挂载点。
      mkdir -p <mount-point>
    2. 挂载JindoFuse。
      jindo-fuse <mount_point> -ouri=[<oss_path>]

      -ouri需配置为待映射的dls路径，路径可以为Bucket根目录或者子目录。执行该命令会启动后台的守护进程，将指定的<oss_path>挂载到本地文件系统的<mount_point>。

      关于挂载Fuse过程中可以配置的挂载选项的更多信息，请参见挂载选项 。

  5. 访问JindoFuse。
    例如，当您将JindoFuse挂载到本地路径/mnt/jindodls/后，通过以下命令执行JindoFuse的基础操作：
    • 创建目录
      mkdir /mnt/oss/dir1
    • 列举/mnt/oss/下的所有目录：
      ls /mnt/oss/
    • 写入文件：
      echo "hello world" > /mnt/oss/dir1/hello.txt
    • 读取文件：
      cat /mnt/oss/dir1/hello.txt
    • 删除目录：
      rm -rf /mnt/oss/dir1/
  6. 取消挂载JindoFuse。
    您可以使用以下两种方式取消挂载JindoFuse：
    • 手动取消挂载JindoFuse
      umount <mount_point>
    • 自动取消挂载JindoFuse
      -oauto_unmount

      使用以上命令支持通过killall -9 jindo-fuse发送SIGINT到jindo-fuse进程，进程退出前会自动取消挂载JindoFuse。

常见问题

如何排查JindoFuse错误？

与JindoSDK调用API过程中可获取到详细的错误信息ErrorMsg不同，JindoFuse只显示操作系统预设的错误信息：

ls: /mnt/oss/: Input/output error

如果您需要定位具体的错误原因，请前往JindoSDK配置项logger.dir指定路径下的jindosdk.log文件。如下为使用JindoFuse过程中常见的鉴权错误信息：

EMMDD HH:mm:ss jindofs_connectivity.cpp:13] Please check your Endpoint/Bucket/RoleArn.
Failed test connectivity, operation: mkdir, errMsg: [RequestId]: 618B8183343EA53531C62B74 [HostId]: oss-cn-shanghai-internal.aliyuncs.com [ErrorMessage]: [E1010]HTTP/1.1 403 Forbidden ...

收到以上报错信息后，请自行排查Endpoint、Bucket以及RoleArn配置信息是否正确。关于Endpoint、Bucket、RoleArn的配置详情，请参见非EMR集群接入OSS-HDFS服务快速入门。

如果遇到程序类报错，请提交工单申请处理。

附录一：支持特性

目前JindoFuse支持以下POSIX API：

特性说明
getattr()查询文件属性，类似ls。
mkdir()创建目录，类似mkdir。
rmdir()删除目录，类似rm -rf。
unlink()删除文件，类似unlink。
rename()重命名文件或目录，类似mv。
read()顺序读取。
pread()随机读。
write()顺序写。
pwrite()随机写。
flush()刷新内存到内核缓冲区。
fsync()刷新内存到磁盘。
release()关闭文件。
readdir()读取目录。
create()创建文件。
open() O_APPEND通过追加写的方式打开文件。
open() O_TRUNC通过覆盖写的方式打开文件。
ftruncate()截断已打开的文件。
truncate()截断未打开的文件，类似truncate -s。
lseek()指定打开文件中的读写位置。
chmod()修改文件权限，类似chmod。
access()查询文件权限。
utimes()修改文件的存储时间和更改时间。
setxattr()修改文件的xattr属性。
getxattr()获取文件的xattr属性。
listxattr()列举文件的xattr属性。
removexattr()删除文件的xattr属性。
lock()支持posix锁，类似fcntl。
fallocate()为文件预分配物理空间。
symlink()创建软连接，目前仅支持在OSS-HDFS服务中使用，且不支持缓存加速。
readlink()读取软连接。

附录二：挂载选项

挂载JindoFuse过程中可以配置的挂载选项如下表所示：

名称是否必选参数说明使用示例
uri是配置需要映射的dls路径。路径可以是Bucket根目录-ouri=oss://bucket.endpoint/，也可以是子目录-ouri=oss://bucket.endpoint/subdir。 -ouri=oss://examplebucket.cn-beijing.oss-dls.aliyuncs.com/
f否启动进程。默认使用守护进程方式后台启动。使用该参数时，推荐开启终端日志。-f
d否使用Debug模式，在前台启动进程。使用该参数时，推荐开启终端日志。-d
auto_unmount否fuse进程退出后自动卸载挂载点。-oauto_unmount
ro否只读挂载，启用参数后不允许写操作。-oro
direct_io否开启该选项后，读写文件可以绕过页高速缓冲存储器（Page Cache）。-odirect_io
kernel_cache否开启后该选项后，通过内核缓存优化读性能。-okernel_cache
auto_cache否默认开启自动缓存。与kernel_cache不同的是，如果文件大小或修改时间发生变化，则缓存失效。-oauto_cache
entry_timeout否文件名读取成功缓存保留时间，单位为秒。该选项用于性能优化。0表示不缓存。默认值为0.1。-oentry_timeout=60
attr_timeout否文件属性缓存保留时间，单位为秒。该选项用于性能优化。0表示不缓存。默认值为0.1。-oattr_timeout=60
negative_timeout否文件名读取失败缓存保留时间，单位为秒。该选项用于性能优化。0表示不缓存。默认值为0.1。-onegative_timeout=0
jindo_entry_size否目录条目缓存数量，用于优化readdir性能。0表示不缓存。默认值为5000。-ojindo_entry_size=5000
jindo_attr_size否文件属性缓存数量，用于优化getattr性能。0表示不缓存。默认值为50000。-ojindo_attr_sizet=50000
max_idle_threads否最大空闲线程数。默认值为10。-omax_idle_threads=10
metrics_port否开启HTTP端口，用于输出metrics，例如http://localhost:9090/brpc_metrics。默认值为9090。-ometrics_port=9090
enable_pread否使用pread接口读取文件。-oenable_pread

附录三：配置选项

配置项配置节点说明
logger.dircommon日志目录。默认值为/tmp/jindodata-log。
logger.synccommon输出日志的方式。取值如下：
  • true：同步输出日志。
  • false（默认值）：异步输出日志。
logger.consoleloggercommon是否打印日志。取值如下：
  • true：打印日志到终端。
  • false（默认值）：不打印日志。
logger.levelcommon输出大于等于该等级的日志。
  • 开启终端日志

    日志等级范围为0~6，日志级别对应关系如下：

    • 0：TRACE
    • 1：DEBUG
    • 2（默认值）：INFO
    • 3：WARN
    • 4：ERROR
    • 5：CRITICAL
    • 6：OFF
  • 关闭终端日志

    使用文件日志时，如果日志等级<=1，表示WARN。日志等级>1，表示INFO。

logger.verbosecommon输出大于等于该等级的VERBOSE日志，等级范围为0~99，默认值为0，0表示不输出。
logger.cleaner.enablecommon是否开启日志清理。取值如下：
  • true：开启日志清理。
  • false（默认值）：不开启日志清理。
fs.oss.endpointjindosdk用于访问OSS-HDFS服务的地址，例如cn-hangzhou.oss-dls.aliyuncs.com
fs.oss.accessKeyIdjindosdk用于访问OSS-HDFS服务的AccessKey ID。
fs.oss.accessKeySecretjindosdk用于访问OSS-HDFS服务的AccessKey Secret。