gahusb/web-page-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(packs-lab): 운영 검증 결과 반영 — DSM API path 형식 + DSM_VERIFY_SSL 명시

Browse Source 
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/...) 발급 확인.
This commit is contained in:
gahusb
2026-05-11 04:02:36 +09:00
parent 1d4bff31c4
commit b792cdb8d5
2 changed files with 14 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
CLAUDE.md
View File

@@ -642,7 +642,8 @@ docker compose up -d
- Vercel SaaS와 HMAC 인증으로 통신, 사용자 인증은 Vercel이 Supabase로 처리 (본 서비스는 외부 인증 없음) - Vercel SaaS와 HMAC 인증으로 통신, 사용자 인증은 Vercel이 Supabase로 처리 (본 서비스는 외부 인증 없음)
- DB: 외부 Supabase `pack_files` 테이블 (DDL: `packs-lab/supabase/pack_files.sql`) - 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` - 파일 구조: `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 인증 (공유 링크 발급용) - `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 우회) - `SUPABASE_URL` / `SUPABASE_SERVICE_KEY`: Supabase pack_files 테이블 접근 (service_role, RLS 우회)
- `UPLOAD_TOKEN_TTL_SEC`: admin upload 토큰 TTL (기본 1800초 = 30분) - `UPLOAD_TOKEN_TTL_SEC`: admin upload 토큰 TTL (기본 1800초 = 30분)
- `PACK_BASE_DIR`: 컨테이너 내부 저장 경로 (기본 `/app/data/packs`) - `PACK_BASE_DIR`: 컨테이너 내부 저장 경로 (기본 `/app/data/packs`)
- `PACK_HOST_DIR`: NAS 호스트 절대경로 (운영 `/volume1/docker/webpage/media/packs`, 미설정 시 PACK_BASE_DIR로 fallback) - `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 마운트의 호스트 측 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`) - `PACK_DATA_PATH`: docker-compose volume 마운트의 호스트 측 OS 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
**HMAC 인증 패턴** **HMAC 인증 패턴**
- Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret)) - Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret))

14
docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md
View File

@@ -292,7 +292,7 @@ location /api/packs/ {
| `proxy_request_buffering off` | 5GB 파일을 nginx가 모두 받고 backend에 forward하면 ~5GB 디스크 buffer 발생 | | `proxy_request_buffering off` | 5GB 파일을 nginx가 모두 받고 backend에 forward하면 ~5GB 디스크 buffer 발생 |
| `proxy_read/send_timeout 1800s` | 30분 — 업로드 토큰 TTL과 일치, 느린 업링크에서 5GB 전송 여유 | | `proxy_read/send_timeout 1800s` | 30분 — 업로드 토큰 TTL과 일치, 느린 업링크에서 5GB 전송 여유 |
### 5.3 `.env.example` — 신규 환경변수 (6 + 3 path) ### 5.3 `.env.example` — 신규 환경변수 (7 + 3 path)
```bash ```bash
# ─── packs-lab — NAS 자료 다운로드 자동화 ──────────────────────────── # ─── packs-lab — NAS 자료 다운로드 자동화 ────────────────────────────
@@ -300,6 +300,8 @@ location /api/packs/ {
DSM_HOST=https://gahusb.synology.me:5001 DSM_HOST=https://gahusb.synology.me:5001
DSM_USER= DSM_USER=
DSM_PASS= DSM_PASS=
# LAN IP + self-signed cert 환경에서 IP mismatch 시 false (LAN 내부 통신이라 허용)
DSM_VERIFY_SSL=false
# Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값) # Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값)
BACKEND_HMAC_SECRET= BACKEND_HMAC_SECRET=
@@ -317,8 +319,10 @@ PACK_DATA_PATH=./data/packs
# 컨테이너 내부 저장 경로 (routes.py upload target. docker-compose volume 우측) # 컨테이너 내부 저장 경로 (routes.py upload target. docker-compose volume 우측)
PACK_BASE_DIR=/app/data/packs PACK_BASE_DIR=/app/data/packs
# DSM·Supabase에 노출되는 NAS 호스트 절대경로. 운영에서 반드시 설정 — 미설정 시 sign-link 시 DSM에 컨테이너 경로 전달돼 파일 못 찾음. # DSM API용 path. Synology DSM API는 일반 사용자 권한일 때 /<shared_folder>/... 형식만 인식하고 /volume1/... 절대경로는 거부(error 408).
PACK_HOST_DIR=/volume1/docker/webpage/media/packs # 운영 NAS는 반드시 shared folder 시점 — /docker/webpage/media/packs.
# admin 사용자는 /volume1/... 도 가능하지만 보안상 별도 packs-bot user 권장.
PACK_HOST_DIR=/docker/webpage/media/packs
``` ```
### 5.4 NAS 디렉토리 준비 ### 5.4 NAS 디렉토리 준비
@@ -326,12 +330,14 @@ PACK_HOST_DIR=/volume1/docker/webpage/media/packs
운영 첫 배포 시 SSH로 1회. 파일은 `PACK_HOST_DIR` 평면에 직접 저장 — tier 디렉토리 분기는 만들지 않음(tier 구분은 filename 규칙으로 admin이 관리): 운영 첫 배포 시 SSH로 1회. 파일은 `PACK_HOST_DIR` 평면에 직접 저장 — tier 디렉토리 분기는 만들지 않음(tier 구분은 filename 규칙으로 admin이 관리):
```bash ```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 chown -R PUID:PGID /volume1/docker/webpage/media/packs
``` ```
PUID/PGID는 `.env`의 기존 값 사용. 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 화이트리스트 ### 5.5 `scripts/deploy-nas.sh` SERVICES 화이트리스트
webhook 자동 배포(deployer)가 호출하는 sync 스크립트는 화이트리스트로 동기화 대상 디렉토리를 명시한다. 신규 서비스 추가 시 반드시 함께 수정해야 NAS 운영 디렉토리에 소스 sync + docker compose 빌드가 동작한다. webhook 자동 배포(deployer)가 호출하는 sync 스크립트는 화이트리스트로 동기화 대상 디렉토리를 명시한다. 신규 서비스 추가 시 반드시 함께 수정해야 NAS 운영 디렉토리에 소스 sync + docker compose 빌드가 동작한다.