DOCS/troubleshooting/251014_skill-rag-file_sshfs_allow_other_해결.md

# skill-rag-file SSHFS allow_other 권한 문제 해결

**날짜**: 2025-10-14
**작성자**: Claude
**관련 파일**: `skill-rag-file/docker-compose.yml`

---

## 문제 상황

### 증상
- skill-rag-file 컨테이너가 `/mnt/51123data/documents/`에 파일 저장
- 컨테이너 내부에서만 파일 보임
- 호스트와 51123 서버 HDD에는 저장 안됨
- 컨테이너 재시작 시 파일 손실

### 근본 원인
1. **SSHFS 마운트**: `user_id=1001,group_id=1000` (admin:xusers)
2. **컨테이너 실행**: root (UID 0)
3. **권한 불일치**: FUSE는 기본적으로 마운트한 사용자만 접근 허용
4. **allow_other 미사용**: 다른 UID 접근 차단

### 검증
```bash
# 컨테이너 내부
docker exec skill-rag-file ls /mnt/51123data/documents/79441171.../2025-10/
# → 파일 보임

# 호스트
ls /mnt/51123data/documents/79441171.../2025-10/
# → No such file or directory
```

---

## 해결 과정

### 1단계: /etc/fuse.conf 수정

```bash
sudo sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf
```

**결과**:
```
user_allow_other
```

**의미**: 일반 사용자가 `allow_other` 옵션 사용 가능

### 2단계: SSHFS 재마운트

```bash
# 기존 마운트 해제
sudo fusermount -u /mnt/51123data

# allow_other 옵션 추가하여 재마운트
sshfs -o allow_other,default_permissions,IdentityFile=/home/admin/.ssh/id_rsa_deploy,reconnect,uid=1001,gid=1000 admin@192.168.219.45:/mnt/hdd/data /mnt/51123data -p 51123
```

**마운트 옵션 확인**:
```bash
mount | grep 51123data
# admin@192.168.219.45:/mnt/hdd/data on /mnt/51123data type fuse.sshfs (rw,nosuid,nodev,relatime,user_id=1001,group_id=1000,default_permissions,allow_other)
```

### 3단계: docker-compose.yml 볼륨 추가

**파일**: skill-rag-file/docker-compose.yml

```yaml
volumes:
  - ./chroma_db:/app/chroma_db
  - ./logs:/app/logs
  - ./.env:/app/.env:ro
  - /mnt/51123data:/mnt/51123data:rw  # 추가
```

### 4단계: 컨테이너 재시작

```bash
cd /home/admin/ivada_project/skill-rag-file
docker compose down
docker compose up -d
```

**결과**: 컨테이너 정상 시작 (DOCS/250915 문서의 "mkdir /mnt/51123data: file exists" 에러 발생 안함)

---

## 검증 결과

### 테스트 1: 파일 쓰기
```bash
docker exec skill-rag-file touch /mnt/51123data/documents/test_write_from_container.txt
ls -la /mnt/51123data/documents/ | grep test_write
# -rw-r--r-- 1 admin xusers 0 10월 14 01:01 test_write_from_container.txt
```

**결과**: ✅ 컨테이너 → 호스트 즉시 동기화

### 테스트 2: 디렉토리 생성
```bash
docker exec skill-rag-file mkdir -p /mnt/51123data/documents/test_team/2025-10
docker exec skill-rag-file touch /mnt/51123data/documents/test_team/2025-10/test.pdf
ls -la /mnt/51123data/documents/test_team/2025-10/
# total 8
# drwxr-xr-x 1 admin xusers 4096 10월 14 01:01 .
# -rw-r--r-- 1 admin xusers    0 10월 14 01:01 test.pdf
```

**결과**: ✅ 디렉토리 생성 및 권한 매핑 정상

### 테스트 3: 영속성
```bash
docker compose down && docker compose up -d
docker exec skill-rag-file ls /mnt/51123data/documents/ | grep test
# test.txt
# test_team
# test_write_from_container.txt
```

**결과**: ✅ 재시작 후에도 파일 유지

---

## 핵심 설정 요약

### /etc/fuse.conf
```
user_allow_other
```

### SSHFS 마운트 명령
```bash
sshfs -o allow_other,default_permissions,IdentityFile=/home/admin/.ssh/id_rsa_deploy,reconnect,uid=1001,gid=1000 admin@192.168.219.45:/mnt/hdd/data /mnt/51123data -p 51123
```

### docker-compose.yml
```yaml
volumes:
  - /mnt/51123data:/mnt/51123data:rw
```

---

## 교훈

### FUSE 기본 보안 정책
- FUSE는 기본적으로 마운트한 사용자만 접근 허용
- 컨테이너 내부 다른 UID 사용 시 접근 불가
- `allow_other` 옵션으로 해결 가능

### allow_other 사용 조건
- `/etc/fuse.conf`에 `user_allow_other` 필수
- `default_permissions` 옵션 권장 (일반 파일시스템 권한 체크)
- 보안 위험: 모든 사용자가 접근 가능하므로 신중히 사용

### Docker 볼륨 마운트
- SSHFS 마운트 포인트를 Docker 볼륨으로 사용 가능
- `allow_other` 없으면 컨테이너 내부에만 파일 존재 (휘발성)
- 볼륨 마운트 시 `/mnt/51123data:/mnt/51123data:rw` 형태로 전체 마운트 포인트 바인드

### 과거 문서 오류
- DOCS/250915: "볼륨 제거"가 해결책이 아님 → 임시 우회책
- DOCS/250731: "Docker SSHFS 충돌"로 롤백 → allow_other로 해결 가능
- 교훈: FUSE 권한 모델 이해 부족으로 잘못된 결론 도출

---

## 추가 발견 (2025-10-14 23:30)

### 문제: SSHFS 긴 파일명 처리 실패

**증상**:
- coldmail workflow 실행 시 PDF 업로드 500 에러
- 로그: `OSError: [Errno 74] Bad message`
- 파일명 예시: `1d8072302cf85eee...pdf` (150자 이상)

**원인**:
- upload.py:82: `f"{file_hash}_{file.filename}"` → 150자 초과
- SSHFS 파일시스템의 파일명 길이 제한

**구현 완료** (커밋 dfe6978):
- ✅ skill-rag-file/app/api/upload.py:73-87,106-107 수정 완료
- ✅ import uuid 추가 (upload.py:5)
- ✅ coldmail workflow PDF 첨부파일 재테스트 대기

---

## 관련 문서

- 250915_skill-rag-file_Docker_빌드_및_볼륨_마운트_문제.md
- 250915_skill-rag-file_초기_구축.md
- 250731_claude_SSHFS권한문제해결.md