阿里云OSS-HDFS服务通过JindoFuse提供POSIX支持。JindoFuse可以把OSS-HDFS服务上的文件挂载到本地文件系统中,让您能够像操作本地文件系统一样操作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.dir common 日志目录。默认值为/tmp/jindodata-log
logger.sync common 输出日志的方式。取值如下:
  • true:同步输出日志。
  • false(默认值):异步输出日志。
logger.consolelogger common 是否打印日志。取值如下:
  • true:打印日志到终端。
  • false(默认值):不打印日志。
logger.level common 输出大于等于该等级的日志。
  • 开启终端日志

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

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

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

logger.verbose common 输出大于等于该等级的VERBOSE日志,等级范围为0~99,默认值为0,0表示不输出。
logger.cleaner.enable common 是否开启日志清理。取值如下:
  • true:开启日志清理。
  • false(默认值):不开启日志清理。
fs.oss.endpoint jindosdk 用于访问OSS-HDFS服务的地址,例如cn-hangzhou.oss-dls.aliyuncs.com
fs.oss.accessKeyId jindosdk 用于访问OSS-HDFS服务的AccessKey ID。
fs.oss.accessKeySecret jindosdk 用于访问OSS-HDFS服务的AccessKey Secret。