GooseFS-Lite 도구는 COS(Cloud Object Storage, COS) 버킷을 로컬에 마운트하여 로컬 파일 시스템처럼 Tencent Cloud 객체 저장소의 객체를 직접 조작할 수 있도록 지원합니다. COSFS 도구에 비해 GooseFS-Lite는 대용량 파일 읽기/쓰기 속도를 더욱 향상시킬 수 있으며 로컬 디스크의 성능 제한을 받지 않습니다. GooseFS-Lite는 파일 순차 읽기, 무작위 읽기, 순차 쓰기, 디렉터리 작업 등 POSIX 파일 시스템의 주요 기능을 지원합니다.
사용 제한
GooseFS-Lite는 마운트 후 파일을 간단히 관리하는 용도에만 적합하며, 로컬 파일 시스템의 일부 기능 사용법은 지원하지 않습니다. 다음 사용 제한 사항에 유의하세요:
파일에 대한 무작위 쓰기 및 truncate 작업을 지원하지 않습니다.
여러 클라이언트가 동일한 COS 버킷을 마운트할 경우, 여러 클라이언트의 동작 조정은 사용자가 직접 수행해야 합니다. 예를 들어 여러 클라이언트가 동일한 파일에 쓰기를 수행하는 것을 피해야 합니다.
파일/폴더의 rename 작업은 원자적 작업이 아닙니다.
현재 마운트 지점에서 쓰기 작업 중인 파일의 읽기 및 rename을 지원하지 않습니다.
메타데이터 작업(예: 디렉터리 목록 표시)은 COS 서버에 원격으로 접근해야 하므로 성능이 낮습니다.
소프트/하드 링크를 지원하지 않습니다.
추가 쓰기 성능이 낮으며, 서버 측 데이터 복사 및 추가 대상 파일 다운로드 과정이 포함됩니다.
메모리가 부족한 환경(예: 컨테이너 메모리 또는 CVM 메모리가 2G 미만인 경우)에서의 사용은 권장하지 않습니다.
Java 환경을 보다 유연하게 설치하려면 수동 JDK 설치를 참조하십시오. 그리고 conf/goosefs-env.sh에서 환경 변수를 수정하여 적용되도록 합니다.
단계 4: 구성 파일 수정
goosefs-lite-<구체적 버전 번호> 디렉터리에서(예: 1.0.6 버전의 경우 goosefs-lite-1.0.6 디렉터리) 설정 파일을 수정하는 방법은 다음과 같이 두 가지가 있습니다:
sed를 사용하여 다음 세 가지 매개변수를 수정하십시오. 여기서 SECRET_ID, SECRET_KEY 및 REGION은 실제 정보로 작성합니다:
fs.cosn.userinfo.secretKey를 Tencent Cloud 비밀 키 Key로 구성합니다.
fs.cosn.userinfo.secretId를 Tencent Cloud 비밀 키 ID로 구성합니다.
fs.cosn.bucket.region을 버킷 리전으로 구성합니다.
sed -i '/<name>fs.cosn.userinfo.secretId<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$SECRET_ID<\\/value>/}' conf/core-site.xml
sed -i '/<name>fs.cosn.userinfo.secretKey<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$SECRET_KEY<\\/value>/}' conf/core-site.xml
sed -i '/<name>fs.cosn.bucket.region<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$REGION<\\/value>/}' conf/core-site.xml
vim을 사용하여 conf/core-site.xml 파일을 편집하고 매개변수를 수정할 수도 있습니다.
fs.cosn.userinfo.secretKey를 Tencent Cloud 비밀 키로 구성합니다.
fs.cosn.userinfo.secretId를 Tencent Cloud 비밀 키 ID로 구성합니다.
fs.cosn.bucket.region을 버킷 리전으로 구성합니다.
설정 파일 설명
goosefs-lite-<구체적 버전 번호>/conf 디렉터리에서(예: 1.0.6 버전의 경우 goosefs-lite-1.0.6/conf 디렉터리) 다음 파일을 볼 수 있습니다:
acl-site.properties:디렉터리의 권한, 사용자 이름, 그룹 이름, Linux POSIX 의미 체계와 유사한 0755, uid, gid 등을 지정합니다.
설명:
acl-site 구성 형식은 path=mode:user_name:group_name입니다. 예를 들어 /mnt/goosefs-lite/test_dir 경로에 755 mode, root 사용자, root 사용자 그룹을 구성하려면 구성 파일에 /mnt/goosefs-lite/test_dir=755:root:root를 추가하면 됩니다.
ACL 구성을 사용하려면 마운트 시 -o default_permissions 매개변수를 포함해야 합니다. 커널(VFS)이 파일 메타데이터의 mode/uid/gid를 기반으로 표준 Unix 권한 검사를 수행합니다. 동시에, 마운트 전에 goosefs-lite.properties 구성 파일에서 구성 항목 goosefs.lite.posix.acl.manager.enabled를 수정하거나 추가하여 true로 설정해야 합니다. 예를 들어 testbucket-1250000000을 /mnt/datadisk0/goosefs-lite-mnt에 마운트하는 명령은 다음과 같습니다:./bin/goosefs-lite mount -o "allow_other,default_permissions" /mnt/datadisk0/goosefs-lite-mnt cosn://testbucket-1250000000/
core-site.xml:Hadoop-COS의 구성 파일(goosefs-lite의 데이터 흐름은 Hadoop-COS를 기반으로 하므로 매개변수와 구성 파일이 거의 공용으로 사용됨)
goosefs-env.sh:JVM 매개변수 등 다양한 환경 변수.
goosefs-lite.properties:goosefs-lite 관련 구성.
log4j.properties:로그 구성. 디버그 로그를 활성화하려면 해당 파일의 마지막 줄 주석 처리를 해제한 후 다시 마운트하면 됩니다.
주의:
사용자는 구성에서 영구 키 사용을 피하고 서브 계정 키 또는 임시 키를 구성하는 방식으로 비즈니스 보안을 강화하는 것이 좋습니다. 서브 계정에 권한을 부여할 때는 필요한 작업 및 리소스에 대해서만 필요한 권한을 부여하여 예기치 않은 데이터 유출을 방지해야 합니다.
영구 키를 반드시 사용해야 하는 경우, 영구 키의 권한 범위를 제한하는 것이 좋습니다. 영구 키의 실행 가능 작업, 리소스 범위 및 조건(액세스 IP 등)을 제한함으로써 사용 보안을 강화할 수 있습니다.
단계 5: 버킷을 로컬 디렉터리에 마운트합니다
goosefs-lite-<구체적 버전 번호> 디렉터리에서(예: 1.0.6 버전의 경우 goosefs-lite-1.0.6 디렉터리) 다음 명령을 실행하여 키 파일에 구성된 버킷을 지정된 디렉터리에 마운트합니다:
명령줄에서 여러 개의 마운트 매개변수를 동시에 지정해야 하는 경우, 쉼표로 여러 매개변수를 구분하여 사용할 수 있습니다. 다음 명령어는 마운트 지점을 읽기 전용으로 설정하고 다른 사용자의 접근을 허용합니다:
./bin/goosefs-lite mount -o "ro,allow_other" mnt/ cosn://examplebucket-1250000000/
이 중:
-o allow_other: 다른 사용자가 마운트된 폴더에 접근할 수 있도록 허용하려면 GooseFS-Lite 실행 시 이 매개변수를 지정할 수 있습니다.
-o ro:마운트 지점을 읽기 전용으로 설정하여 쓰기 및 삭제 작업을 허용하지 않습니다.
설명:
단일 매개변수는 -o를 통해 지정할 수 있습니다(예: -o ro); 여러 매개변수는 쉼표로 구분하여 지정할 수 있습니다(예: -o "ro,allow_other").
단계 6: 마운트 지점 언마운트
설명:
GooseFS-Lite 마운트 지점을 언마운트할 경우 해당 경로를 통해 COS에 접근하는 모든 읽기/쓰기 작업이 즉시 중단됩니다. 작업 전에 현재 비즈니스 프로세스가 해당 마운트 디렉터리를 사용 중이지 않은지 확인해야 합니다.
goosefs-lite-<구체적 버전 번호> 디렉터리에서(예: 1.0.6 버전의 경우 goosefs-lite-1.0.6 디렉터리), 다음 명령을 실행하여 마운트 지점을 언마운트할 수 있습니다:
$ ./bin/goosefs-lite umount /mnt/goosefs-lite-mnt
Unmount fuse at /mnt/goosefs-lite-mnt/ (PID: 17206).
# 언마운트가 비정상적인 경우 다음 명령어를 사용하여 강제 언마운트할 수 있습니다
$ sudoumount -l /mnt/goosefs-lite-mnt
7단계: 매개변수 튜닝
GooseFS-Lite는 conf/core-site.xml 및 conf/goosefs-lite.properties 두 개의 구성 파일을 포함합니다.
conf/core-site.xml을 수정하여 업로드 및 다운로드 대역폭을 조정할 수 있습니다. 주요 매개변수는 다음과 같으며, 추가 매개변수는 Hadoop-COS 문서를 참조하십시오.
속성 키
설명
기본값
필수 항목
fs.cosn.useHttps
HTTPS를 COS 백엔드와의 전송 프로토콜로 사용할지 여부를 구성합니다.
true
아니요
fs.cosn.upload.part.size
멀티파트 업로드 시 각 part size의 크기입니다. COS의 멀티파트 업로드는 최대 10000개 블록만 지원하므로, 단일 파일로 사용 가능한 최대 크기를 예상해야 합니다. 예를 들어 part size가 8MB인 경우 최대 78GB 단일 파일 업로드를 지원할 수 있습니다. part size는 최대 2GB까지 지원 가능하므로, 단일 파일 최대 크기는 19TB까지 지원됩니다.
8388608(8MB)
아니요
fs.cosn.upload_thread_pool
COS로 파일을 스트리밍 업로드할 때 동시 업로드 스레드 수
32
아니요
fs.cosn.read.ahead.block.size
프리패치 블록 크기
1048576(1MB)
아니요
fs.cosn.read.ahead.queue.size
프리패치 큐의 길이
6
아니요
conf/goosefs-lite.properties를 수정하여 GooseFS-Lite의 동작을 조정할 수 있습니다. 주요 매개변수는 다음과 같습니다:
open 및 rename 작업 시 파일이 쓰여지고 있을 때 쓰기 작업 완료를 기다리는 시간 (단위: ms)
5000
아니요
goosefs.fuse.umount.timeout
파일 시스템을 언마운트할 때 완료되지 않은 작업을 기다리는 시간 (단위: ms)
120000
아니요
읽기 및 쓰기 동시성이 높은 경우 GooseFS-Lite의 최대 JVM 실행 메모리를 다음과 같이 조정하여 Full GC 및 OutOfMemoryError를 방지할 수 있습니다. JVM 기본값은 -Xmx512m -XX:MaxDirectMemorySize=512m -XX:+UseG1GC -XX:G1HeapRegionSize=32m이며, 조정 방법은 다음과 같습니다:
exportJAVA_OPTS="-Xms2G -Xmx2G"
./bin/goosefs-lite mount /mnt/goosefs-lite-mnt/ cosn://examplebucket-1250000000/
ps -ef|grep goosefs-lite|grep -v grep
자주 묻는 질문
libfuse 라이브러리 파일이 누락된 경우 어떻게 처리합니까?
libfuse 설치가 필요하며, 다음 방식을 참조하여 작업하십시오:
방법 1
1. 다음 명령을 실행하여 fuse-devel을 설치하십시오.
CentOS 또는 TencentOS 시스템인 경우 다음 명령을 실행하십시오:
yum install fuse-devel
Ubuntu 시스템인 경우 다음 명령을 실행하십시오:
aptinstall libfuse-dev
2. 설치가 완료된 후 다음 명령을 실행하여 설치가 성공적으로 완료되었는지 확인하십시오.
find / -name libfuse.so*
방법 2
이전 버전 libfuse.so.2.9.2 업데이트를 위한 설치 단계는 다음과 같습니다:
설명:
CentOS 7의 기본 설치 버전은 libfuse.so.2.9.2입니다.
1. libfuse 소스 코드를 다운로드하여 컴파일하여 libfuse.so.2.9.7을 생성합니다.
tar -zxvf fuse-2.9.7.tar.gz
cd fuse-2.9.7/ && ./configure &&make&&makeinstall
echo -e '\\n/usr/local/lib'>> /etc/ld.so.conf
ldconfig
2. libfuse.so.2.9.7 컴파일 및 생성 후 다음 단계에 따라 교체 작업을 수행하십시오:
2.1 다음 명령을 실행하여 이전 버전 libfuse.so.2.9.2 라이브러리 링크를 찾으십시오.
find / -name libfuse.so*
2.2 libfuse.so.2.9.7을 이전 버전 라이브러리 libfuse.so.2.9.2 위치에 복사하려면 다음 명령을 실행하십시오.
cp /usr/local/lib/libfuse.so.2.9.7 /usr/lib64/
2.3 다음 명령을 실행하여 이전 버전 libfuse.so 라이브러리의 모든 링크를 삭제하십시오.
rm -f /usr/lib64/libfuse.so
rm -f /usr/lib64/libfuse.so.2
2.4 다음 명령을 실행하여 삭제된 이전 버전 링크와 유사한 libfuse.so.2.9.7 라이브러리 링크를 생성하십시오.
1. /usr/lib/systemd/system/goosefs-lite.service 파일을 편집하여 다음 내용을 추가하십시오. examplebucket-1250000000을 사용자의 버킷으로 변경할 수 있습니다:주의: 다음 JAVA_OPTS에서 -Xms 및 -Xmx로 구성된 메모리 값은 해당 노드의 물리적 메모리 상한의 50%를 초과할 수 없습니다. 예를 들어 노드 물리적 메모리가 16GB인 경우 최대 -Xms8G -Xmx8G로 구성하는 것이 권장됩니다.
다음은 goosefs-lite-1.0.6 버전을 예시로 설명합니다:
[Unit]
Description=The Tencent Cloud GooseFS Lite for COS
2. 다음 명령을 실행하여 마운트 명령을 실행하고 백그라운드 데몬 프로세스 상태를 확인하십시오.
# goosefs-lite의 systemd 구성이 적용되도록 설정
systemctl daemon-reload
# 백그라운드 Fuse 프로세스 시작 설정
systemctl start goosefs-lite
# 백그라운드 데몬 프로세스 상태 확인
systemctl status goosefs-lite
# 마운트 포인트 목록 확인
/usr/local/goosefs-lite-1.0.6/bin/goosefs-lite stat
# systemd 구성을 수정한 경우 수정 후 reload 및 restart를 수행하십시오.
부팅 시 마운트를 시도하도록 설정:
systemctl enable goosefs-lite
3. 마운트 포인트 마운트 해제, 머신 재시작 및 Fuse 프로세스 상태 확인.
# 언마운트 실행. 주의: 데이터가 기록 중일 때 절대로 언마운트하지 마십시오. 그렇지 않으면 데이터 불완전이 발생할 수 있습니다
systemctl stop goosefs-lite
# 운영체제 재부팅 시 주의: 비즈니스에 영향을 미치지 않도록 신중하게 수행하십시오.
reboot -h now
# 백그라운드 데몬 프로세스 상태 확인
systemctl status goosefs-lite
# 마운트 포인트 목록 확인
/usr/local/goosefs-lite-1.0.6/bin/goosefs-lite stat
GooseFS-Lite가 매일 특정 시간대에 CPU 사용률이 높고, COS에 대량의 Head, List 요청을 발생시켜 요청 횟수 비용이 많이 발생하는 경우 어떻게 처리해야 할까요?
이는 일반적으로 사용자의 머신에 정기 디스크 스캔 작업이 존재하기 때문입니다. Linux 시스템에서 흔히 볼 수 있는 스캔 프로그램은 updatedb입니다. GooseFS-Lite 마운트 포인트 디렉터리를 updatedb 구성 파일인 /etc/updatedb.conf 파일의 PRUNEPATHS 구성 항목에 추가하여 해당 프로그램의 디스크 스캔 동작을 방지할 수 있습니다. 또한 Linux 도구 auditd를 통해 GooseFS-Lite 마운트 포인트에 액세스하는 프로그램을 찾을 수 있습니다.
goosefs-lite 1.0.3 버전 이상의 경우, 기본 로그 디렉터리는 /data/goosefs/logs/fuse 아래에 있습니다.
예: goosefs-lite를 마운트한 사용자가 root이고 마운트 포인트 경로가 /data1/data2인 경우, 로그 경로는 /data/goosefs/logs/fuse/root/data1/data2입니다.
goosefs-lite 1.0.0-1.0.2 버전의 경우, 기본 로그 디렉터리는 /data/goosefs/logs 아래에 있습니다.
마운트 포인트 로그 경로를 확인하는 또 다른 방법으로, 먼저 다시 마운트한 후 ps aux | grep ${MOUNT_POINT}를 실행합니다. 출력에서 Error_File 또는 goosefs.logs.dir을(를) 확인할 수 있으며, 이 경로의 상위 디렉터리가 해당 마운트 포인트의 모든 로그가 위치한 곳입니다.
시스템 로그: CentOS 또는 tlinux 시스템인 경우 /var/log/message*이고, Ubuntu인 경우 /var/log/syslog입니다.
디버그 로그를 활성화해야 하는 경우 conf/log4j.properties로 이동하여 가장 아래 줄의 내용을 주석 처리한 후 다시 마운트하십시오.
주의:
디버그 로그를 활성화하면 성능에 영향을 미칠 수 있으므로 정상적인 상황에서는 활성화할 필요가 없습니다.
마운트 실패 오류 "Name or service not known" 발생 시 어떻게 처리해야 합니까?
일반적으로 도메인을 해석할 수 없기 때문이며, 해당 도메인에 ping을 시도해 볼 수 있습니다. 아래 그림과 같은 오류가 발생하면 다음 명령을 실행하십시오:
ping VM-36-104-centos
동일하게 실패가 반환될 경우 /etc/hosts 파일을 수정하여 해당 IP를 구성할 수 있습니다. 일반적으로 127.0.0.1로 구성할 수 있습니다.
작업 단계:
1. /etc/hosts 파일에 한 줄을 추가하십시오. 여기서 VM-36-104-centos는 사용자의 호스트명으로 변경하십시오.
127.0.0.1 VM-36-104-centos
2. 이후 다시 ping 테스트를 수행하여 정상적으로 해석되는지 확인한 후 다시 마운트하면 됩니다.
2. konajdk에 있는 java 바이너리 프로그램의 절대 경로를 복사하십시오. 예를 들어, 압축 해제된 jdk는 /root/konajdk11 아래에 있습니다.
# java 버전 확인
/root/konajdk11/bin/java -version
# 현재 shell의 JAVA 환경 변수를 수정하여 다른 shell 및 프로세스에 영향을 미치지 않습니다.
exportJAVA=/root/konajdk11/bin/java
# 마운트
goosefs-lite mount /mnt cosn://bucket-appid
3. ps aux | grep goosefs-lite를 사용하면 프로세스 시작 부분에 /root/konajdk11/bin/java가 표시되어 지정한 java 버전이 사용 중임을 확인할 수 있으며 작업이 완료되었습니다.
마운트 포인트가 원래 정상이었는데 사용 중 갑자기 정상적으로 작동하지 않을 경우 어떻게 처리해야 합니까?
현재 문제가 있는 마운트 포인트가 /tmp/mount_point라고 가정합니다.
1. 먼저 ps aux | grep /tmp/mount_point를 사용하여 현재 이 마운트 지점을 사용 중인 프로세스가 있는지 확인하십시오. goosefs-lite 포함. 만약 있다면, kill 명령을 사용하여 해당 프로세스를 종료하십시오.
2. ls를 사용하여 마운트 포인트에 접근해 보십시오. 아무것도 반환되지 않으면 마운트 포인트가 성공적으로 해제된 것입니다. 이후 다시 마운트하면 됩니다.
ls /mount_point
3. transport is not connected 과 같은 오류가 발생하면 umount -l /mount_point 명령어로 강제 해제해야 합니다. (이 명령 실행에는 root 권한이 필요합니다)
일반적으로 이러한 상황은 프로세스가 kill -9 또는 시스템 oom-killer로 인해 종료되었을 때 발생합니다. 시스템 로그 또는 goosefs-lite 로그에서 확인할 수 있습니다.
4. 마운트 포인트 로그 디렉터리(/data/goosefs/logs/fuse/$USER/$MOUNT_POINT)에서 hs_error로 시작하는 로그가 있는지 확인하십시오(파일에는 프로그램 종료 전의 스택 및 원인이 기술되어 있음).
예외 발생: Unsupported or unrecognized SSL message, 처리 방법은 무엇입니까?
현재 환경에서는 https 모드를 비활성화하는 것을 지원하지 않으므로 구성을 수정해야 합니다. 해결 방법은 core-site.xml 구성 파일에 다음 내용을 추가하는 것입니다:
<property>
<name>fs.cosn.useHttps</name>
<value>false</value>
</property>
GooseFS-Lite에서 사설망 도메인을 사용하여 COS에 액세스하려면 어떻게 해야 합니까?
core-site.xml 구성 파일에서 fs.cosn.bucket.region 속성을 삭제하고 fs.cosn.bucket.endpoint_suffix 매개변수를 추가하십시오(goosefs-lite 1.0.12 이상 버전을 사용 중인 경우 fs.cosn.custom.endpoint_suffix 매개변수 추가).
마운트 시 또는 사용 중 403 Forbidden 오류가 발생하면 어떻게 처리해야 하나요?
일반적으로 로그에서 ERROR 유형의 로그는 어떤 권한이 누락되었는지 설명하므로 필요에 따라 추가하면 됩니다.
주의사항: head bucket 권한의 경우 경로 수준이 아닌 버킷 수준으로 설정해야 합니다. 예를 들어 cosn://bucket-appid/path는 적용되지 않으며, 반드시 cosn://bucket-appid 형태로 설정해야 합니다. 이 권한은 버킷 내 객체 목록이 노출되지 않습니다.
오류 "fuse: /dev/fuse 열기 실패, 허가되지 않은 작업(Operation not permitted)" 발생 시 처리 방법은?
1. root 권한이 있는지 확인하십시오.
2. 컨테이너 환경인 경우, 컨테이너 시작 시 --privileged 옵션이 있는지 확인하고 없으면 추가하십시오.
3. fuse 커널 모듈이 설치되었는지 확인하십시오: lsmod | grep fuse 명령어를 실행하여 반환 결과가 있는지 확인하십시오. 결과가 없으면 fuse 커널 모듈이 누락되었음을 의미합니다.
파일 쓰기 실패, 오류 "part num: 10001, the parameter partNumber is not valid."가 발생하는 경우 어떻게 처리해야 합니까?
이러한 상황은 멀티파트 업로드의 파트 수가 제한을 초과했음을 의미합니다. COS는 최대 10,000개의 파트 업로드만 지원합니다. 따라서 goosefs-lite는 기본적으로 8MB*10000(약 78GB) 크기의 파일을 최대 지원합니다. 더 큰 파일을 지원하려면 fs.cosn.upload.part.size 매개변수를 조정해야 합니다. 예를 들어 fs.cosn.upload.part.size를 16777216(16MB)로 수정할 경우 16MB*10000의 대용량 파일을 지원할 수 있습니다.
