From b792cdb8d5c2540dd34dbce577cf19c4ed609ce5 Mon Sep 17 00:00:00 2001
From: gahusb <bgg8988@gmail.com>
Date: Mon, 11 May 2026 04:02:36 +0900
Subject: [PATCH] =?UTF-8?q?docs(packs-lab):=20=EC=9A=B4=EC=98=81=20?=
 =?UTF-8?q?=EA=B2=80=EC=A6=9D=20=EA=B2=B0=EA=B3=BC=20=EB=B0=98=EC=98=81=20?=
 =?UTF-8?q?=E2=80=94=20DSM=20API=20path=20=ED=98=95=EC=8B=9D=20+=20DSM=5FV?=
 =?UTF-8?q?ERIFY=5FSSL=20=EB=AA=85=EC=8B=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

5/11 운영 첫 호출 검증 중 발견된 사항을 spec/CLAUDE.md에 반영:

1. DSM API path 형식 차이: Synology DSM은 일반 사용자 권한일 때
   /<shared_folder>/... 형식만 인식, /volume1/... 거부 (error 408).
   PACK_HOST_DIR 운영 예시값 /docker/webpage/media/packs로 변경.

2. DSM_VERIFY_SSL env 명시: LAN IP + self-signed cert 환경에서 SSL 검증
   끄기 위한 환경변수. .env.example 7+3 path로 갱신.

3. DSM 사용자 권한 가이드: File Station + Sharing 둘 다 ON 필요.

4. NAS 디렉토리 준비 명령에서 호스트 OS path와 DSM API path 차이 명시.

운영 검증: HTTP 200 + DSM 공유 URL (gofile.me/...) 발급 확인.
---
 CLAUDE.md                                          |  7 ++++---
 ...026-05-05-packs-lab-infra-integration-design.md | 14 ++++++++++----
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 239f4db..f7cfbd7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -642,7 +642,8 @@ docker compose up -d
 - 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`(컨테이너 내부, upload 저장 target) ↔ `PACK_HOST_DIR`(NAS 호스트 절대경로, Supabase에 저장 + DSM 호출 시 사용). 운영 NAS에서 `PACK_HOST_DIR` 미설정 시 sign-link가 컨테이너 경로를 DSM에 전달해 파일을 못 찾음.
+- 경로 3분리: `PACK_DATA_PATH`(호스트 OS path, docker volume 좌측) → `PACK_BASE_DIR`(컨테이너 내부, upload 저장 target) → `PACK_HOST_DIR`(DSM API path, Supabase에 저장). 운영 NAS에서 `PACK_HOST_DIR` 미설정 시 sign-link가 컨테이너 경로를 DSM에 전달해 파일을 못 찾음.
+- ⚠️ **DSM API path 형식**: Synology DSM API는 일반 사용자 권한일 때 `/<shared_folder>/...` 형식만 인식하고 `/volume1/...` 절대경로는 거부(error 408). 운영 NAS는 반드시 `PACK_HOST_DIR=/docker/webpage/media/packs` (shared folder 시점) 설정. admin 사용자만 `/volume1/...` 사용 가능하나 보안상 권장 안 함.
 
 **환경변수**
 - `DSM_HOST` / `DSM_USER` / `DSM_PASS`: Synology DSM 7.x 인증 (공유 링크 발급용)
@@ -651,8 +652,8 @@ docker compose up -d
 - `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_HOST_DIR`: NAS 호스트 절대경로 (운영 `/volume1/docker/webpage/media/packs`, 미설정 시 PACK_BASE_DIR로 fallback)
-- `PACK_DATA_PATH`: docker-compose volume 마운트의 호스트 측 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
+- `PACK_HOST_DIR`: DSM API용 path. **운영 NAS는 `/docker/webpage/media/packs` (shared folder 시점)**. 미설정 시 `PACK_BASE_DIR`로 fallback (DSM 호출 X 환경에서만 안전)
+- `PACK_DATA_PATH`: docker-compose volume 마운트의 호스트 측 OS 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
 
 **HMAC 인증 패턴**
 - Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret))
diff --git a/docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md b/docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md
index 545c831..cd95f67 100644
--- a/docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md
+++ b/docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md
@@ -292,7 +292,7 @@ location /api/packs/ {
 | `proxy_request_buffering off` | 5GB 파일을 nginx가 모두 받고 backend에 forward하면 ~5GB 디스크 buffer 발생 |
 | `proxy_read/send_timeout 1800s` | 30분 — 업로드 토큰 TTL과 일치, 느린 업링크에서 5GB 전송 여유 |
 
-### 5.3 `.env.example` — 신규 환경변수 (6 + 3 path)
+### 5.3 `.env.example` — 신규 환경변수 (7 + 3 path)
 
 ```bash
 # ─── packs-lab — NAS 자료 다운로드 자동화 ────────────────────────────
@@ -300,6 +300,8 @@ location /api/packs/ {
 DSM_HOST=https://gahusb.synology.me:5001
 DSM_USER=
 DSM_PASS=
+# LAN IP + self-signed cert 환경에서 IP mismatch 시 false (LAN 내부 통신이라 허용)
+DSM_VERIFY_SSL=false
 
 # Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값)
 BACKEND_HMAC_SECRET=
@@ -317,8 +319,10 @@ PACK_DATA_PATH=./data/packs
 # 컨테이너 내부 저장 경로 (routes.py upload target. docker-compose volume 우측)
 PACK_BASE_DIR=/app/data/packs
 
-# DSM·Supabase에 노출되는 NAS 호스트 절대경로. 운영에서 반드시 설정 — 미설정 시 sign-link 시 DSM에 컨테이너 경로 전달돼 파일 못 찾음.
-PACK_HOST_DIR=/volume1/docker/webpage/media/packs
+# DSM API용 path. Synology DSM API는 일반 사용자 권한일 때 /<shared_folder>/... 형식만 인식하고 /volume1/... 절대경로는 거부(error 408).
+# 운영 NAS는 반드시 shared folder 시점 — /docker/webpage/media/packs.
+# admin 사용자는 /volume1/... 도 가능하지만 보안상 별도 packs-bot user 권장.
+PACK_HOST_DIR=/docker/webpage/media/packs
 ```
 
 ### 5.4 NAS 디렉토리 준비
@@ -326,12 +330,14 @@ PACK_HOST_DIR=/volume1/docker/webpage/media/packs
 운영 첫 배포 시 SSH로 1회. 파일은 `PACK_HOST_DIR` 평면에 직접 저장 — tier 디렉토리 분기는 만들지 않음(tier 구분은 filename 규칙으로 admin이 관리):
 
 ```bash
-mkdir -p /volume1/docker/webpage/media/packs
+mkdir -p /volume1/docker/webpage/media/packs    # 호스트 OS path (volume 마운트용)
 chown -R PUID:PGID /volume1/docker/webpage/media/packs
 ```
 
 PUID/PGID는 `.env`의 기존 값 사용.
 
+> ⚠️ **DSM 사용자 권한 — File Station + Sharing 둘 다 필요**: Control Panel → User → packs-bot(또는 admin) → Permissions → File Station에서 `docker` shared folder Read 권한 + Applications → Sharing 권한 ON.
+
 ### 5.5 `scripts/deploy-nas.sh` SERVICES 화이트리스트
 
 webhook 자동 배포(deployer)가 호출하는 sync 스크립트는 화이트리스트로 동기화 대상 디렉토리를 명시한다. 신규 서비스 추가 시 반드시 함께 수정해야 NAS 운영 디렉토리에 소스 sync + docker compose 빌드가 동작한다.