From 5e9a51c9e845a2cc356b8c5f540687bc1d021a51 Mon Sep 17 00:00:00 2001 From: gahusb Date: Wed, 6 May 2026 01:42:15 +0900 Subject: [PATCH] =?UTF-8?q?docs(claude):=20packs-lab=2010=EB=B2=88?= =?UTF-8?q?=EC=A7=B8=20=EC=84=9C=EB=B9=84=EC=8A=A4=EB=A1=9C=20=EB=93=B1?= =?UTF-8?q?=EB=A1=9D=20(=ED=8F=AC=ED=8A=B8/=EB=9D=BC=EC=9A=B0=ED=8C=85/API?= =?UTF-8?q?=20=ED=91=9C=20+=20=EC=8B=A0=EA=B7=9C=20=EC=84=B9=EC=85=98)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 51ab67b..ced1191 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,9 @@ ## 1. 프로젝트 개요 Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포. -- **서비스**: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, deployer (9개) +- **서비스**: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, packs-lab, deployer (10개) - **프론트엔드**: 별도 레포 (React + Vite SPA), 빌드 산출물만 NAS에 배포 -- **인프라**: Docker Compose (9컨테이너) + Nginx(리버스 프록시) + Gitea Webhook 자동 배포 +- **인프라**: Docker Compose (10컨테이너) + Nginx(리버스 프록시) + Gitea Webhook 자동 배포 --- @@ -59,6 +59,7 @@ Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포. | `blog-lab` | 18700 | 블로그 마케팅 수익화 API | | `realestate-lab` | 18800 | 부동산 청약 자동 수집·매칭 API | | `agent-office` | 18900 | AI 에이전트 오피스 (실시간 WebSocket + 텔레그램 연동) | +| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (DSM 공유 링크 + 5GB 업로드, Vercel SaaS와 HMAC 통신) | | `personal` | 18850 | 개인 서비스 (포트폴리오·블로그·투두 통합) | | `travel-proxy` | 19000 | 여행 사진 API + 썸네일 생성 | | `frontend` (nginx) | 8080 | 정적 SPA 서빙 + API 리버스 프록시 | @@ -82,6 +83,7 @@ Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포. | `/api/blog/` | `personal:8000` | 블로그 API | | `/api/profile/` | `personal:8000` | 포트폴리오 API | | `/api/agent-office/` | `agent-office:8000` | AI 에이전트 오피스 API + WebSocket | +| `/api/packs/` | `packs-lab:8000` | 5GB 업로드 대응 (`client_max_body_size 5G`, `proxy_request_buffering off`, 1800s timeout) | | `/webhook`, `/webhook/` | `deployer:9000` | Gitea Webhook | | `/media/music/` | `/data/music/` (파일 직접 서빙) | 생성된 오디오 파일 | | `/media/videos/` | `/data/videos/` (파일 직접 서빙) | YouTube 영상 MP4 | @@ -135,6 +137,7 @@ docker compose up -d | Stock Lab | http://localhost:18500 | | Blog Lab | http://localhost:18700 | | Realestate Lab | http://localhost:18800 | +| Packs Lab | http://localhost:18950 | --- @@ -634,6 +637,36 @@ docker compose up -d | PUT | `/api/blog/posts/{id}` | 블로그 글 수정 | | DELETE | `/api/blog/posts/{id}` | 블로그 글 삭제 | +### packs-lab (packs-lab/) +- NAS 자료 다운로드 자동화 — Synology DSM 공유링크 발급 + 5GB 멀티파트 업로드 수신 +- Vercel SaaS와 HMAC 인증으로 통신, 사용자 인증은 Vercel이 Supabase로 처리 (본 서비스는 외부 인증 없음) +- DB: 외부 Supabase `pack_files` 테이블 (DDL: `packs-lab/supabase/pack_files.sql`) +- 파일 구조: `app/main.py`, `app/auth.py`, `app/dsm_client.py`, `app/routes.py`, `app/models.py` +- 컨테이너 저장 경로: `PACK_BASE_DIR` env (default `/app/data/packs`). docker-compose volume 마운트와 일치 필수. + +**환경변수** +- `DSM_HOST` / `DSM_USER` / `DSM_PASS`: Synology DSM 7.x 인증 (공유 링크 발급용) +- `BACKEND_HMAC_SECRET`: Vercel SaaS와 양쪽 공유 시크릿 (HMAC SHA256) +- `SUPABASE_URL` / `SUPABASE_SERVICE_KEY`: Supabase pack_files 테이블 접근 (service_role, RLS 우회) +- `UPLOAD_TOKEN_TTL_SEC`: admin upload 토큰 TTL (기본 1800초 = 30분) +- `PACK_BASE_DIR`: 컨테이너 내부 저장 경로 (기본 `/app/data/packs`) +- `PACK_DATA_PATH`: 호스트 마운트 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`) + +**HMAC 인증 패턴** +- Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret)) +- Replay 방어: 타임스탬프 ±5분 윈도우 +- admin browser → backend upload: `Authorization: Bearer ` (jti 단발성) + +**packs-lab API 목록** + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| POST | `/api/packs/sign-link` | Vercel HMAC → DSM Sharing.create로 4시간 유효 다운로드 URL 발급 | +| POST | `/api/packs/admin/mint-token` | Vercel HMAC → 일회성 upload 토큰 발급 (기본 30분 TTL) | +| POST | `/api/packs/upload` | Bearer token → multipart 5GB 저장 + Supabase INSERT | +| GET | `/api/packs/list` | Vercel HMAC → 활성 pack_files 목록 (deleted_at IS NULL) | +| DELETE | `/api/packs/{file_id}` | Vercel HMAC → soft delete (DSM 공유는 자동 만료) | + ### deployer (deployer/) - Webhook 검증: `X-Gitea-Signature` (HMAC SHA256, `compare_digest` 사용) - `WEBHOOK_SECRET` 환경변수로 시크릿 관리