Unify NAS operations on tracked docker-compose.yaml

This commit is contained in:
2026-10-14 11:08:42 +09:00
parent 46ad429cc7
commit ff89daac8c
10 changed files with 118 additions and 104 deletions

View File

@@ -28,15 +28,15 @@ API 테스트는 격리된 실제 SQLite DB와 임시 로컬 포트의 Socket.IO
## Docker 배포 준비
유그린 NAS에서 Docker 앱 버튼으로 배포하는 순서는 [deploy.md](deploy.md)를 따라 진행하세요. 현재 배포 경로는 Cloudflare Tunnel → 기존 NPM(8080) → NAS의 hop.(50189)입니다.
유그린 NAS의 Docker 앱과 터미널에서 같은 `docker-compose.yaml`로 배포하는 순서는 [deploy.md](deploy.md)를 따라 진행하세요. 현재 배포 경로는 Cloudflare Tunnel → 기존 NPM(8080) → NAS의 hop.(50189)입니다.
`.env.example`을 `.env`로 복사하고 비밀값을 설정합니다. `SESSION_SECRET`과 `DISCOVERY_SECRET`은 서로 다른 32자 이상의 무작위 비밀값이어야 합니다. 예를 들어 `openssl rand -hex 32`로 각각 생성합니다. Git에 실제 환경 파일·DB·파일을 넣지 않습니다.
이번 NAS 배포는 사용자가 지정한 **50189**를 호스트·컨테이너 포트로 사용합니다. `scripts/configure-nas.sh`가 실제 NAS 내부 IP를 물어보고 운영 `.env`와 배포 YAML을 준비합니다. 다른 환경에서는 충돌 없는 포트·바인딩 IP·프록시 경로를 따로 확인하세요. Compose는 필수 값이 비어 있으면 실행을 거절합니다. `.env`는 Node 서버 직접 실행 시 자동 로드되지 않으며 Compose 또는 실행 환경이 주입합니다.
이번 NAS 배포는 사용자가 지정한 **50189**를 호스트·컨테이너 포트로 사용합니다. `scripts/configure-nas.sh`가 실제 NAS 내부 IP를 물어보고 운영 `.env`와 저장 권한을 준비하고 Git의 `docker-compose.yaml`을 검사합니다. Compose 파일은 생성하거나 덮어쓰지 않습니다. 다른 환경에서는 충돌 없는 포트·바인딩 IP·프록시 경로를 따로 확인하세요. Compose는 필수 값이 비어 있으면 실행을 거절합니다. `.env`는 Node 서버 직접 실행 시 자동 로드되지 않으며 Compose 또는 실행 환경이 주입합니다.
```sh
docker compose config
docker compose up -d --build
sudo docker compose -f docker-compose.yaml config --quiet
sudo docker compose -f docker-compose.yaml up -d --build
```
앱 시작 시 버전 관리된 Drizzle 마이그레이션을 적용하며 실패하면 시작하지 않습니다. DB 볼륨과 프로젝트의 uploads 폴더는 재배포·재시작 후 유지됩니다. `docker compose down -v`는 데이터를 삭제하므로 사용하지 마세요.
@@ -55,11 +55,11 @@ QR·4자리 코드는 기본 10분의 임시 공간 초대입니다. 초대 코
## 파일 저장 위치
NAS의 파일 원본은 `/volume1/docker/projects/apps/hop/uploads/originals`에 저장합니다. 앱은 NAS 사용자의 UID/GID로 실행하며 업로드 폴더는 Git·Docker 빌드에서 제외합니다. DB는 `hop_hop_database` 영구 볼륨에 있습니다. 원본 수동 삭제는 조회·다운로드·전송과 1분 주기 정리 시 감지해 공유된 모든 항목과 용량 계산에 반영합니다. 권한 오류는 삭제로 오인하지 않습니다. 기존 설치의 최초 전환·테스트 자료 초기화는 [deploy.md](deploy.md)의 7-1단계를 진행하고, 이후 일반 업데이트에서는 초기화하지 않습니다.
NAS의 파일 원본은 `/volume1/docker/projects/apps/hop/uploads/originals`에 저장합니다. 앱은 NAS 사용자의 UID/GID로 실행하며 업로드 폴더는 Git·Docker 빌드에서 제외합니다. DB는 `hop_hop_database` 영구 볼륨에 있습니다. 원본 수동 삭제는 조회·다운로드·전송과 1분 주기 정리 시 감지해 공유된 모든 항목과 용량 계산에 반영합니다. 권한 오류는 삭제로 오인하지 않습니다. 단일 Compose 파일로 전환하는 순서는 [deploy.md](deploy.md)의 7-0단계를 따르며 기존 계정·DB·파일은 유지합니다.
## 업데이트와 백업
일반 코드·UI 업데이트는 `git pull --ff-only origin main` → Docker 이미지 재빌드 → 재배포로 진행합니다. Docker 구성과 환경변수가 바뀌지 않았다면 기존 YAML을 그대로 사용합니다. DB·업로드는 기존 볼륨에 유지되므로 매번 백업할 필요는 없습니다. DB 구조 변경에 대비하거나 데이터를 따로 보관하려면 앱을 정지한 뒤 DB 볼륨(WAL·SHM 포함), 업로드 볼륨, `.env`를 같은 시점에 백업합니다. 자세한 순서는 [deploy.md의 업데이트 절차](deploy.md#7-다음-버전으로-업데이트)를 참고하세요.
일반 업데이트는 `git pull --ff-only origin main` → `sudo docker compose -f docker-compose.yaml up -d --build`로 진행합니다. 소스와 운영 Compose 설정을 Git에서 함께 관리하며 UGREEN 앱도 동일한 파일을 사용합니다. DB·업로드는 기존 볼륨에 유지되므로 매번 백업할 필요는 없습니다. DB 구조 변경에 대비하거나 데이터를 따로 보관하려면 앱을 정지한 뒤 DB 볼륨(WAL·SHM 포함), 업로드 볼륨, `.env`를 같은 시점에 백업합니다. 자세한 순서는 [deploy.md의 업데이트 절차](deploy.md#7-다음-버전으로-업데이트)를 참고하세요.
파일당 기본 2GiB, 익명 주체당 2GiB, 전체 익명 20GiB 제한과 최소 5GiB 여유 공간을 적용합니다. MB/KB 환경변수는 MiB/KiB 기준입니다. 파일은 수락 후 스트리밍 저장하고 중단 시 임시 파일·예약을 회수합니다. 파일은 8MiB 단위로 나누어 전송하고 서버가 받은 위치를 기록합니다. 중간 오류는 최대 3회 자동 재시도하며, 현재 화면에서 같은 파일로 ‘다시 전송’할 수 있습니다. 백그라운드 완료는 보장하지 않습니다.