v1.12.27 NAS 실행 yaml 및 명시적 이미지 빌드 분리

docs/spec.md

@@ -1115,8 +1115,15 @@ APP_PORT=43080
 - 접속자 대표 페이지는 포커스 여부가 아닌 마지막 확인 시각 기준. 현재 API의 회원별·익명 IP별 묶음은 유지. 인원 표시는 반환된 목록 수와 전체 접속자 수를 구분.
 - 열린 페이지 팝오버는 hover 시 일시 표시, 클릭/Enter로 고정 전환. 포인터를 목록으로 이동해도 링크 접근을 유지하며, 화면 범위에 맞춰 위/아래 배치하고 긴 목록은 내부 스크롤 제공.
 
-## 운영 Compose 식별 (v1.12.26)
+## 운영 Compose 식별 (v1.12.27)
 
-- 기본 프로젝트명은 `COMPOSE_PROJECT_NAME` 또는 `sori-studio`. Compose 최상위 `name`으로 선언하고 운영 명령은 `-p sori-studio -f docker-compose.yml` 사용.
-- 운영 마이그레이션·썸네일 백필 스크립트는 루트의 `docker-compose.yml`을 명시적으로 선택한다. 환경 파일 선택 및 DB 외부 볼륨 설정은 유지.
-- 운영 업데이트 기본 경로는 Git 소스 동기화 후 UGREEN Docker 앱의 기존 `sori-studio` 프로젝트에서 Compose 구성 확인·재배포. CLI는 보조 경로이며 GUI의 별도 Compose 사본과 원본 `.yml` 차이를 확인한다.
+- 기본 프로젝트명은 `COMPOSE_PROJECT_NAME` 또는 `sori-studio`. Compose 최상위 `name`으로 선언하고 실행 명령은 `-p sori-studio -f docker-compose.yaml`, 빌드 명령은 `-f docker-compose.build.yml` 사용.
+- 운영 마이그레이션·썸네일 백필 스크립트는 루트의 실행용 `docker-compose.yaml`을 명시적으로 선택한다. 환경 파일 선택 및 DB 외부 볼륨 설정은 유지.
+- v1.12.27부터 운영 업데이트 기본 경로는 Git 소스 동기화 → 터미널 이미지 빌드 → UGREEN Docker 앱의 기존 `sori-studio` 프로젝트 재배포. 제공된 재배포 로그에 빌드가 없어 앱 단독 소스 빌드를 전제하지 않는다.
+
+## 로컬 이미지 사전 빌드·NAS 앱 실행 (v1.12.27)
+
+- `sh scripts/build-production-image.sh`: `ENV_FILE` 또는 `.env.production`을 선택한 뒤 `docker-compose.build.yml`의 앱 서비스만 `build`. 운영 환경 파일 누락/읽기 실패는 종료 코드 1, Docker 빌드 오류는 그대로 반환. 컨테이너 시작·삭제·네트워크·DB 변경 명령은 실행하지 않는다.
+- `docker-compose.yaml`: GUI에 독립 구성으로 적용. 앱은 기본 빌드 이미지와 동일한 `sori-studio:latest`, `pull_policy: never`, `build` 없음. 프로젝트명·네트워크·외부 DB 볼륨·포트·업로드/마이그레이션 경로는 기본 Compose와 동일.
+- GUI가 pull 정책을 덮어쓰는 실제 동작은 NAS에서 확인해야 하며 이미지 다운로드/업데이트 옵션이 있으면 앱 이미지에 대해 해제. `docker-compose.build.yml`은 CLI 빌드·배포용으로 유지.
+- NAS에 기존 비추적 `docker-compose.yaml`이 있으면 첫 git pull 전에 이름을 바꿔 백업한다. 두 구성을 모두 저장소에서 관리하며 실행용 기본 파일과 빌드용 파일의 이름을 구분한다.