204 lines
6.5 KiB
Markdown
204 lines
6.5 KiB
Markdown
# Travel-Proxy 성능 개선 설계
|
|
|
|
## 목표
|
|
|
|
travel-proxy의 파일 스캔 기반 아키텍처를 SQLite 인덱스 DB로 전환하여 수천 장의 사진을 무난하게 처리하고, 앨범 커버 지정 + 썸네일 사전 생성을 지원한다.
|
|
|
|
## 배경
|
|
|
|
현재 travel-proxy는 `os.scandir`으로 NAS 폴더를 매번 스캔하고, 메모리 캐시(TTL 300초)로 결과를 보관한다. 사진 수백 장에서는 문제없지만, 수천 장이면:
|
|
- 캐시 만료 시 1~2초 스캔 지연
|
|
- 콜드 스타트(컨테이너 재시작) 시 첫 요청 느림
|
|
- 전체 리스트를 메모리에 상주
|
|
- 썸네일이 첫 요청 시 동기 생성되어 초기 로딩 지연
|
|
|
|
## 아키텍처
|
|
|
|
### 변경 전
|
|
|
|
```
|
|
API 요청 → os.scandir(폴더) → 메모리 캐시 → 슬라이싱 페이지네이션
|
|
↓
|
|
썸네일 온디맨드 생성 (Pillow)
|
|
```
|
|
|
|
### 변경 후
|
|
|
|
```
|
|
수동 sync 버튼 → 폴더 스캔 → travel.db 동기화 + 썸네일 사전 생성
|
|
↓
|
|
API 요청 → SQLite 쿼리 (인덱스) → 페이지네이션
|
|
```
|
|
|
|
### 파일 구조
|
|
|
|
| 파일 | 역할 |
|
|
|------|------|
|
|
| `main.py` | FastAPI 라우트 (기존 + 신규) |
|
|
| `db.py` (신규) | SQLite 스키마 정의, 쿼리 헬퍼 |
|
|
| `indexer.py` (신규) | 폴더 스캔 → DB 동기화 + 썸네일 생성 |
|
|
|
|
기존 `main.py`의 `scan_album`, `ensure_thumb`, 메모리 캐시 로직이 `indexer.py`와 `db.py`로 이동하고, `main.py`는 라우트만 남는다.
|
|
|
|
## DB 스키마
|
|
|
|
```sql
|
|
CREATE TABLE photos (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
album TEXT NOT NULL,
|
|
filename TEXT NOT NULL,
|
|
mtime REAL NOT NULL,
|
|
has_thumb INTEGER DEFAULT 0,
|
|
indexed_at TEXT NOT NULL,
|
|
UNIQUE(album, filename)
|
|
);
|
|
|
|
CREATE INDEX idx_photos_album ON photos(album);
|
|
|
|
CREATE TABLE album_covers (
|
|
album TEXT PRIMARY KEY,
|
|
filename TEXT NOT NULL,
|
|
updated_at TEXT NOT NULL
|
|
);
|
|
```
|
|
|
|
### 설계 포인트
|
|
|
|
- `photos` 테이블에 URL/thumb 경로를 저장하지 않음 — 런타임에 `MEDIA_BASE` + album + filename으로 조합 (환경변수 변경에 유연)
|
|
- `mtime`으로 변경 감지 — 동기화 시 파일이 삭제됐거나 mtime이 바뀌면 갱신
|
|
- `album_covers`가 비어있으면 해당 앨범의 첫 번째 사진이 자동 커버
|
|
|
|
## API 설계
|
|
|
|
### 기존 API 변경
|
|
|
|
| 엔드포인트 | 변경 내용 |
|
|
|-----------|----------|
|
|
| `GET /api/travel/photos` | 내부 로직만 변경 (os.scandir → DB 쿼리). 응답 형식 동일 |
|
|
| `GET /api/travel/regions` | 변경 없음 |
|
|
| `POST /api/travel/reload` | 제거 (sync로 대체) |
|
|
| `GET /media/travel/.thumb/{album}/{filename}` | 유지 — 동기화 시 이미 썸네일 생성되므로 Pillow 호출 빈도 대폭 감소. 미생성 분 폴백으로 온디맨드 생성 유지 |
|
|
|
|
### 신규 API
|
|
|
|
| 메서드 | 경로 | 설명 |
|
|
|--------|------|------|
|
|
| `POST` | `/api/travel/sync` | 폴더 스캔 → DB 동기화 + 썸네일 생성 |
|
|
| `GET` | `/api/travel/albums` | 앨범 목록 + 사진 수 + 커버 정보 |
|
|
| `PUT` | `/api/travel/albums/{album}/cover` | 앨범 커버 지정 |
|
|
|
|
### POST /api/travel/sync
|
|
|
|
폴더를 스캔하여 DB와 동기화하고, 미생성 썸네일을 일괄 생성한다.
|
|
|
|
**요청**: 바디 없음
|
|
|
|
**응답**:
|
|
```json
|
|
{
|
|
"added": 42,
|
|
"removed": 3,
|
|
"thumbs_generated": 42,
|
|
"duration_sec": 12.5
|
|
}
|
|
```
|
|
|
|
**동기 실행** — 수동 트리거이므로 BackgroundTask 불필요, 응답에 결과 포함.
|
|
|
|
### GET /api/travel/albums
|
|
|
|
앨범 목록과 각 앨범의 사진 수, 커버 정보를 반환한다.
|
|
|
|
**응답**:
|
|
```json
|
|
[
|
|
{
|
|
"album": "오사카",
|
|
"count": 342,
|
|
"cover_url": "/media/travel/오사카/IMG_3281.jpg",
|
|
"cover_thumb": "/media/travel/.thumb/오사카/IMG_3281.jpg"
|
|
}
|
|
]
|
|
```
|
|
|
|
커버가 지정되지 않은 앨범은 첫 번째 사진(album + filename 정렬 기준)이 자동 커버.
|
|
|
|
### PUT /api/travel/albums/{album}/cover
|
|
|
|
특정 사진을 앨범 커버로 지정한다.
|
|
|
|
**요청**:
|
|
```json
|
|
{
|
|
"filename": "IMG_3281.jpg"
|
|
}
|
|
```
|
|
|
|
**응답**:
|
|
```json
|
|
{
|
|
"album": "오사카",
|
|
"filename": "IMG_3281.jpg",
|
|
"cover_url": "/media/travel/오사카/IMG_3281.jpg",
|
|
"cover_thumb": "/media/travel/.thumb/오사카/IMG_3281.jpg"
|
|
}
|
|
```
|
|
|
|
**검증**: 해당 album + filename 조합이 photos 테이블에 존재하는지 확인. 없으면 404.
|
|
|
|
## 동기화 로직 (indexer.py)
|
|
|
|
### sync 프로세스
|
|
|
|
1. `region_map.json`에서 전체 앨범 폴더 목록 수집
|
|
2. 각 폴더 `os.scandir` → `{album, filename, mtime}` 세트 수집
|
|
3. DB와 비교:
|
|
- DB에 없는 파일 → INSERT (`added`)
|
|
- DB에 있지만 폴더에 없는 파일 → DELETE (`removed`)
|
|
- mtime이 다른 파일 → UPDATE + `has_thumb=0` (변경됨)
|
|
4. `has_thumb=0`인 파일 → 썸네일 생성 → `has_thumb=1`로 갱신
|
|
5. 결과 반환: `{added, removed, thumbs_generated, duration_sec}`
|
|
|
|
### 삭제된 커버 처리
|
|
|
|
커버로 지정된 사진이 폴더에서 삭제되면 `album_covers`에서도 제거 → 자동으로 첫 번째 사진 폴백.
|
|
|
|
### 성능
|
|
|
|
- NAS Celeron J4025 기준, 2,000장 최초 동기화 + 썸네일 생성 예상: 3~5분
|
|
- 이후 동기화는 변경분만 처리 → 수초 이내
|
|
|
|
## 앨범 커버 지정 UX
|
|
|
|
프론트엔드 앨범 상세 페이지에서 사진을 길게 누르거나 우클릭 → "커버로 설정" 메뉴. `PUT /api/travel/albums/{album}/cover` 호출.
|
|
|
|
프론트엔드 변경은 이 스펙 범위 밖 — 백엔드 API만 제공하고, 프론트 연동은 별도 작업.
|
|
|
|
## 기존 API 호환성
|
|
|
|
- `GET /api/travel/photos` 응답 형식 (`items`, `total`, `has_next`, `matched_albums`) 완전히 유지
|
|
- 프론트엔드 `useTravelData` 훅은 수정 없이 동작
|
|
- `GET /api/travel/albums`는 선택적 개선용 — 프론트가 앨범 카드 커버를 표시할 때 활용
|
|
|
|
## Docker 변경
|
|
|
|
- `travel.db` 저장 위치: 썸네일 볼륨 내 `/data/thumbs/travel.db` (추가 볼륨 불필요)
|
|
- `requirements.txt`에 `aiosqlite` 추가 불필요 — 동기 sqlite3 표준 라이브러리 사용
|
|
- Dockerfile 변경 없음
|
|
|
|
### docker-compose.yml 변경
|
|
|
|
기존 볼륨에 DB를 함께 저장하므로 추가 볼륨 불필요:
|
|
```yaml
|
|
volumes:
|
|
- ${PHOTO_PATH}:/data/travel:ro
|
|
- ${RUNTIME_PATH}\travel-thumbs:/data/thumbs:rw # travel.db도 여기에 저장
|
|
```
|
|
|
|
## 제거되는 코드
|
|
|
|
- `main.py`의 `CACHE`, `CACHE_TTL`, `META_MTIME_CACHE` 딕셔너리 및 관련 로직
|
|
- `main.py`의 `scan_album()` 함수 (indexer.py로 이동)
|
|
- `main.py`의 `ensure_thumb()` 함수 (indexer.py로 이동, 온디맨드 폴백은 유지)
|
|
- `POST /api/travel/reload` 엔드포인트 (sync로 대체)
|