使用JindoFuse实现以标准的文件系统接口读写OSS-HDFS数据

如果您希望将OSS-HDFS服务映射为一个本地文件系统，然后通过标准的文件系统接口（例如读、写、删除文件等）访问OSS-HDFS服务中的文件，您可以使用JindoFuse挂载访问的方式。JindoFuse是一个开源的分布式文件系统访问工具，同时兼容POSIX，使得AI应用程序可以直接使用OSS-HDFS服务作为数据存储和处理的解决方案。

前提条件

已开通并授权访问OSS-HDFS服务。具体操作，请参见开通并授权访问OSS-HDFS服务。

环境准备

您可以选择以下任意一种方式访问OSS-HDFS服务。

通过阿里云EMR访问OSS-HDFS服务，确保已创建EMR-3.44.0及以上版本或EMR-5.10.0及以上版本的集群。满足版本要求的EMR集群默认集成了JindoFuse。具体操作，请参见创建集群。
通过非阿里云EMR访问OSS-HDFS服务，确保已安装和部署4.6.2及以上版本JindoSDK。具体操作，请参见在非EMR集群中部署JindoSDK。

操作步骤

配置环境变量。

如果通过阿里云EMR访问OSS-HDFS服务，则直接跳过此步骤，执行下一步。

如果通过非阿里云EMR访问OSS-HDFS服务，则按照以下说明配置JindoFuse。

连接ECS实例。具体操作，请参见连接ECS实例。

添加环境变量。

以jindosdk-x.x.x（x.x.x表示JindoSDK的版本号）安装在root/路径为例。请根据JindoSDK安装的实际路径修改环境变量。

export JINDOSDK_HOME=/root/jindosdk-x.x.x
export HADOOP_CLASSPATH=`hadoop classpath`:${JINDOSDK_HOME}/lib/*
export JINDOSDK_CONF_DIR=/root/jindosdk-x.x.x/conf
export PATH=$PATH:$JINDOSDK_HOME/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${JINDOSDK_HOME}/lib/native

添加配置文件。

在JindoSDK的conf/目录下新建配置文件jindosdk.cfg。

在jindosdk.cfg配置文件中添加以下配置项。

[common]
logger.dir = /tmp/fuse-log

[jindosdk]
<!-- 以下以杭州地域为例，其他地域请根据实际情况替换。 -->
fs.oss.endpoint = cn-hangzhou.oss-dls.aliyuncs.com
<!-- 配置访问OSS-HDFS服务的AccessKeyId、AccessKeySecret。 -->
fs.oss.accessKeyId = LTAI********    
fs.oss.accessKeySecret = KZo1********

挂载OSS-HDFS服务。
1. 创建挂载点。
```
mkdir -p <mount-point>
```
2. 挂载OSS-HDFS服务。
```
jindo-fuse <mount_point> -ouri=[<oss_path>]
```
  -ouri需配置为待映射的dls路径，路径可以为Bucket根目录或者子目录。执行该命令会启动后台的守护进程，将指定的<oss_path>挂载到本地文件系统的<mount_point>。
  关于挂载Fuse过程中可以配置的挂载选项的更多信息，请参见挂载选项。
3. 执行以下命令，确认是否挂载成功。
```
ps -ef | grep jindo-fuse
```
  返回结果如下，说明已成功挂载OSS-HDFS服务。
```
root      2162     1  0 13:21 ?        00:00:00 jindo-fuse <mount_point> -ouri=[<oss_path>]
root      2714  2640  0 13:39 pts/0    00:00:00 grep --color=auto jindo-fuse
```
通过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/
```
（可选）取消挂载OSS-HDFS服务。
您可以使用以下两种方式取消挂载。
- 手动取消挂载
```
umount <mount_point>
```
- 自动取消挂载
```
-oauto_unmount
```
  使用以上命令支持通过killall -9 jindo-fuse发送SIGINT到jindo-fuse进程，进程退出前会自动取消挂载OSS-HDFS服务。

常见问题

如何排查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。