v1.12.31 불필요 파일 정리 및 업로드·배포 안정성 보강

docs/deploy-reference.md

@@ -34,6 +34,8 @@ Linux CI 이미지에서 브라우저 시스템 의존성도 함께 준비해야
 
 ### 운영 마이그레이션과 미디어 카탈로그 전환
 
+`migrate-production-db.sh`는 미적용 SQL 파일 하나와 해당 적용 이력을 같은 트랜잭션으로 실행한다. SQL 실패 시 해당 파일의 변경과 이력을 함께 취소하고 중단하며, 이미 완료된 이전 파일은 유지한다. `ENV_FILE`에는 상대·절대 경로를 사용할 수 있다.
+
 운영 PostgreSQL 볼륨은 Compose 프로젝트명 변화에 영향받지 않도록 `POSTGRES_VOLUME_NAME` 또는 기본값 `soristudio_sori-studio-postgres`로 실제 이름을 고정하고, 외부 볼륨(`external: true`)으로 선언한다. UGREEN Docker 앱에서 프로젝트 이름이 달라지면 `sori-studio_sori-studio-postgres`처럼 새 빈 볼륨이 붙고 PostgreSQL init 스크립트가 다시 실행될 수 있으므로, 배포 전후 아래 명령으로 DB 컨테이너가 기존 운영 볼륨을 물고 있는지 확인한다.
 
 ```bash
@@ -603,9 +605,9 @@ Homepage 위젯 연동은 `docs/homepage-widget.md`를 참고한다. Docker에
 - 게시물 Export ZIP 산출물은 `public/uploads/exports/YYYY/MM/{jobId}/` 아래 생성되며, 관리자 다운로드 API를 통해 내려받는다.
 - 완료·실패한 게시물 Export 작업을 관리자 화면에서 삭제하면 연결된 ZIP 파일도 함께 삭제된다.
 - `public/uploads/`는 Git에 포함하지 않는다.
-- NAS 운영에서는 `docker-compose.build.yml`의 `./public/uploads:/app/public/uploads` 볼륨으로 업로드 파일을 유지한다.
+- NAS 운영에서는 실행용 `docker-compose.yaml`과 CLI 빌드용 `docker-compose.build.yml`의 `./public/uploads:/app/public/uploads` 볼륨으로 업로드 파일을 유지한다. 업로드는 Docker 빌드 입력과 Nitro 정적 복사에서 제외하므로 새 이미지에 기존 파일을 넣지 않는다. 재배포 시 같은 업로드 폴더를 연결해야 하며 원본 폴더는 삭제하지 않는다.
 - 운영 빌드에서는 `/uploads/**` 서버 라우트가 `.output/public`이 아니라 `/app/public/uploads` 볼륨의 실제 파일을 직접 제공한다.
-- `/uploads/**` 응답은 `ETag`와 `Last-Modified`를 제공한다. 고유 URL로 저장되는 원본·시스템·회원 썸네일 파일은 1년 immutable 캐시를 사용하고, 같은 URL로 재생성될 수 있는 게시물 `thumbs` 파생 파일은 1시간 캐시와 `stale-while-revalidate`를 사용한다.
+- `/uploads/**` 응답은 `ETag`와 `Last-Modified`를 제공한다. 고유 URL로 저장되는 원본·시스템·회원 썸네일 파일은 1년 immutable 캐시를 사용하고, 같은 URL로 재생성될 수 있는 게시물 `thumbs` 파생 파일은 `no-cache`로 재검증한다.
 - `MAX_FILE_SIZE`, `MAX_VIDEO_FILE_SIZE`, `MAX_AUDIO_FILE_SIZE`, `MAX_DOCUMENT_FILE_SIZE` 환경 변수로 관리자 미디어 업로드 파일별 최대 크기를 제한한다. 1회 업로드 최대 파일 수와 전체 용량은 관리자 Settings > POST 설정 > 업로드 제한에서 조절한다. 리버스 프록시(Nginx 등)를 쓰면 `client_max_body_size`가 앱 한도보다 작지 않은지 함께 확인한다.
 - 관리자 미디어 화면은 현재 업로드 파일 시스템을 기준으로 목록, 파일명 변경, 삭제를 처리한다.