JindoFuse使用指南

OSS/OSS-HDFS可以通過JindoFuse提供POSIX支援，將OSS/OSS-HDFS上的檔案掛載到本地檔案系統中，讓您能夠像操作本地檔案系統一樣操作OSS/OSS-HDFS上的檔案。

環境準備

EMR環境中，預設已安裝JindoSDK，可以直接使用。
說明
訪問OSS-HDFS，需建立EMR-3.42.0及以上版本或EMR-5.8.0及以上版本的叢集。
非EMR環境，請先安裝部署JindoSDK，詳情請參見在非EMR叢集中部署JindoSDK。
說明
訪問OSS-HDFS，需部署JindoSDK 4.x及以上版本。

依賴準備

說明

以下版本已預設安裝所需依賴，無需執行此操作。

EMR-3.44.0及之後版本或EMR-5.10.0及之後版本。
JindoSDK 4.6.2及之後版本。

JindoSDK 4.5.0及之前版本，需安裝以下依賴。

# CentOS
sudo yum install -y fuse3 fuse3-devel
# Debian
sudo apt install -y fuse3 libfuse3-dev

JindoSDK 4.5.1及之後版本，需依賴libfuse 3.7+。

例如，執行以下命令安裝fuse-3.11。

# build fuse required meson & ninja, for debian: apt install -y pkg-config meson ninja-build
sudo yum install -y meson ninja-build

# compile fuse required newer g++ (only CentOS)
sudo yum install -y scl-utils
sudo yum install -y alinux-release-experimentals
sudo yum install -y devtoolset-8-gcc devtoolset-8-gdb devtoolset-8-binutils devtoolset-8-make devtoolset-8-gcc-c++
sudo su -c "echo 'source /opt/rh/devtoolset-8/enable' > /etc/profile.d/g++.sh"
source /opt/rh/devtoolset-8/enable
sudo ln -s /opt/rh/devtoolset-8/root/bin/gcc /usr/local/bin/gcc
sudo ln -s /opt/rh/devtoolset-8/root/bin/g++ /usr/local/bin/g++

# compile & install libfuse
wget https://github.com/libfuse/libfuse/releases/download/fuse-3.11.0/fuse-3.11.0.tar.xz
xz -d fuse-3.11.0.tar.xz
tar xf fuse-3.11.0.tar
cd fuse-3.11.0/
mkdir build; cd build
meson ..
sudo ninja install

掛載JindoFuse

執行以下命令，建立一個掛載點。
```
mkdir -p <mount_point>
```
<mount_point>需替換為一個本地路徑。例如：/mnt/oss/。
執行以下命令，掛載JindoFuse。
```
jindo-fuse <mount_point> -ouri=<oss_path>
```
<oss_path>需替換為待映射的OSS/OSS-HDFS路徑，路徑可以為Bucket根目錄或者子目錄。例如：oss://examplebucket.cn-shanghai.oss-dls.aliyuncs.com/subdir/。
此命令會啟動一個背景守護進程，將指定的<oss_path>掛載到本地檔案系統的<mount_point>。
說明
掛載OSS和OSS-HDFS路徑的方式基本一致，僅路徑中的endpoint略有不同。更多資訊，請參見OSS/OSS-HDFS快速入門。
執行以下命令，確認是否掛載成功。
```
ps -ef | grep jindo-fuse
```
jindo-fuse進程存在，且啟動參數與預期一致，說明掛載成功。

訪問JindoFuse

如果將JindoFS服務掛載到了本地/mnt/oss/，可以執行以下命令訪問JindoFuse。

查看/mnt/oss/路徑下的所有目錄
```
ls /mnt/oss/
```
建立目錄
```
mkdir /mnt/oss/dir1
```

寫入檔案

echo "hello world" > /mnt/oss/dir1/hello.txt

讀取檔案
```
cat /mnt/oss/dir1/hello.txt
```
顯示hello world
刪除目錄
```
rm -rf /mnt/oss/dir1/
```

卸載JindoFuse

若您想卸載之前掛載的掛載點，可以使用如下命令。

umount <mount_point>

您也可以使用-oauto_unmount參數，自動卸載掛載點。使用該參數後，支援killall -9 jindo-fuse發送SIGINT給jindo-fuse進程，該進程退出前會自動卸載掛載點。

特性支援

目前JindoFuse已經支援以下POSIX API。

特性	說明	OSS	OSS-HDFS

特性	說明	OSS	OSS-HDFS
getattr()	查詢檔案屬性	支援	支援
mkdir()	建立目錄	支援	支援
rmdir()	刪除目錄	支援	支援
unlink()	刪除檔案	支援	支援
rename()	重新命名檔案	支援	支援
read()	順序讀取	支援	支援
pread()	隨機讀取	支援	支援
write()	順序寫入	支援	支援
pwrite()	隨機寫入	不支援	支援
flush()	重新整理記憶體到核心緩衝區	JindoFuse 6.7.0之前版本：僅在以追加寫方式（O_APPEND）開啟的檔案時有效。 JindoFuse 6.7.0及之後版本：預設支援。更多詳情，請參見關閉檔案後，是否能保證資料已經寫入到OSS？	支援
fsync()	重新整理記憶體到磁碟	僅支援以追加寫方式開啟的檔案。	支援
release()	關閉檔案	支援	支援
readdir()	讀取目錄	支援	支援
create()	建立檔案	支援	支援
open() O_APPEND	通過追加寫的方式開啟檔案	支援，使用時有限制值，請參見使用限制。	支援
open() O_TRUNC	通過覆蓋寫的方式開啟檔案	支援	支援
ftruncate()	對開啟的檔案進行截斷	不支援	支援
truncate()	對未開啟的檔案進行截斷	不支援	支援
lseek()	指定開啟檔案中的讀寫位置	不支援	支援
chmod()	修改檔案許可權	不支援	支援
access()	查詢檔案許可權	支援	支援
utimes()	修改檔案的存取時間和更改時間	不支援	支援
setxattr()	修改檔案xattr屬性	不支援	支援
getxattr()	擷取檔案xattr屬性	不支援	支援
listxattr()	列舉檔案xattr屬性	不支援	支援
removexattr()	刪除檔案xattr屬性	不支援	支援
lock()	支援posix鎖	不支援	支援
fallocate()	為檔案預分配物理空間	不支援	支援
symlink()	建立軟串連	不支援	目前僅支援OSS-HDFS內部使用，且不支援緩衝加速。
readlink()	讀取軟串連	不支援	支援

進階使用

掛載參數選項如下所示。

參數	是否必選	JindoData版本	參數說明	使用範例

參數	是否必選	JindoData版本	參數說明	使用範例
uri	是	4.3.0及之後版本	配置需要映射的OSS路徑。路徑可以是根目錄，也可以是子目錄。例如：oss://examplebucket/或oss://examplebucket/subdir。	`-ouri=oss://examplebucket/`
f	否	4.3.0及之後版本	在前端啟動進程。預設使用守護進程方式後台啟動。使用該參數時，建議開啟終端日誌。	`-f`
d	否	4.3.0及之後版本	使用Debug模式，在前端啟動進程。使用該參數時，建議開啟終端日誌。	`-d`
auto_unmount	否	4.3.0及之後版本	fuse進程退出後自動卸載掛載節點。	`-oauto_unmount`
ro	否	4.3.0及之後版本	唯讀掛載，啟用後不允許寫操作。	`-oro`
direct_io	否	4.3.0及之後版本	開啟後，讀寫檔案可以繞過Page Cache。	`-odirect_io`
kernel_cache	否	4.3.0及之後版本	開啟後，利用核心緩衝最佳化讀效能。	`-okernel_cache`
auto_cache	否	4.3.0及之後版本	與kernel_cache二選一，與kernel_cache不同的是，如果檔案大小或修改時間發生變化，緩衝就會失效。預設開啟。	無
entry_timeout	否	4.3.0及之後版本	檔案名稱讀取緩衝保留時間（秒），用於最佳化效能。預設值：60。0表示不緩衝。	`-oentry_timeout=60`
attr_timeout	否	4.3.0及之後版本	檔案屬性緩衝保留時間（秒），用於最佳化效能。預設值：60。0表示不緩衝。	`-oattr_timeout=60`
negative_timeout	否	4.3.0及之後版本	檔案名稱讀取失敗緩衝保留時間（秒），用於最佳化效能。預設值：60。0表示不緩衝。	`-onegative_timeout=0`
max_idle_threads	否	4.3.0及之後版本	處理核心回調的空閑線程池。預設值：10。	`-omax_idle_threads=10`
xengine	否	4.3.0及之後版本	開啟緩衝。	`-oxengine`
pread	否	4.5.1及之後版本	預設使用順序讀。開啟後，使用隨機讀代替順序讀，適用於隨機讀遠多於順序讀的情境。	`-opread`
no_symlink	否	4.5.1及之後版本	配置後，關閉symlink功能。	`-ono_symlink`
no_writeback	否	4.5.1及之後版本	配置後，關閉writeback功能。	`-ono_writeback`
no_flock	否	4.5.1及之後版本	配置後，關閉flock功能。	`-ono_flock`
no_xattr	否	4.5.1及之後版本	配置後，關閉xttar功能。	`-ono_xattr`

配置參數選項如下所示。

配置項	預設值	說明

配置項	預設值	說明
logger.dir	/tmp/bigboot-log	日誌目錄，若不存在會自動建立。
logger.sync	false	是否同步輸出日誌，false表示非同步輸出。
logger.consolelogger	false	列印日誌到終端。
logger.level	2	輸出大於等於該等級的日誌，取值如下： 0：TRACE 1：DEBUG 2：INFO 3：WARN 4：ERROR 5：CRITICAL 6：OFF
logger.verbose	0	輸出大於等於該等級的VERBOSE日誌，等級範圍為0-99，0表示不輸出。
logger.cleaner.enable	false	是否開啟日誌清理功能。
fs.oss.endpoint	無	訪問JindoFS服務的地址，例如：oss-cn-xxx.aliyuncs.com。
fs.oss.accessKeyId	無	訪問JindoFS服務需要的AccessKey ID。
fs.oss.accessKeySecret	無	訪問JindoFS服務需要的AccessKey Secret。

支援在掛載時同時指定JindoSDK配置參數和掛載選項，掛載時指定參數的優先順序需高於設定檔，例如：

jindo-fuse <mount_point> -ouri=[<oss_path>] -ofs.oss.endpoint=[<YOUR_ENDPOINT>] -ofs.oss.accessKeyId=[<YOUR_KEY_ID>] -ofs.oss.accessKeySecret=[<YOUR_KEY_SECRET>]

常見問題

使用JindoFuse時如何定位錯誤資訊？

不同於使用JindoSDK調用API時可以擷取更為具體的錯誤資訊，JindoFuse只能顯示作業系統預設的錯誤資訊。如果需要定位具體的錯誤原因，可以根據JindoSDK配置中的logger.dir，在指定路徑下的jindosdk.log檔案中，尋找具體的錯誤。

關閉檔案後，是否能保證資料已經寫入到OSS？

JindoFuse 6.7.0之前版本：
- 追加寫入模式：如果檔案是以追加寫方式開啟的，那麼在調用close()時，通常會觸發一個隱式的flush()操作，這可以確保資料從使用者空間緩衝區重新整理到核心緩衝區，並最終寫入到OSS。追加寫通過AppendObject實現，但該操作有一些限制，詳情請參見AppendObject。
- 非追加寫入模式：如果檔案不是以追加寫方式開啟的，那麼flush()操作可能不會有效。在這種情況下，close()操作可能不會確保資料已經寫入到OSS。
JindoFuse 6.7.0及之後版本：
- 預設啟用了 fs.oss.fuse.flush.enable 配置（即預設為 true）。啟用後，寫入 OSS 也支援 flush() 操作，且不影響 OSS-HDFS。
- 啟用此配置後，無論是通過 open() 以 O_APPEND 方式開啟還是其他方式開啟，都不會再使用 appendObject 的方式寫入。而是通過通用的 PutObject 和 MPU（多部分上傳）操作寫入。調用 flush() 將已寫入的資料重新讀取並再次寫入 OSS，這可能導致額外的 I/O 開銷。特別是在以下情況下：
  - 對已存在的檔案執行 flush() 操作。
  - 對新寫的檔案執行兩次 flush()。
- 關閉此配置後，行為將迴歸至6.7.0之前版本的狀態，寫入OSS不支援 flush()。