使用JindoFuse實現以標準的檔案系統介面讀寫OSS-HDFS資料 - Object Storage Service

如果您希望將OSS-HDFS服務對應為本地檔案系統，並通過標準檔案系統介面（如讀、寫、刪除檔案等）訪問OSS-HDFS服務中的檔案，可以使用JindoFuse掛載訪問。JindoFuse是一個開源的、相容POSIX的Distributed File System訪問工具，使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 = yourAccessKeySecret

掛載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檔案。常見鑒權錯誤資訊如下：

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配置資訊是否正確。配置詳情，請參見非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_size=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。