From 34d48b914984131f55e11d56eba8b168dc9a3a2f Mon Sep 17 00:00:00 2001 From: zenn Date: Mon, 12 Oct 2026 18:39:06 +0900 Subject: [PATCH] Simplify routine NAS updates and separate optional data backups --- README.md | 4 ++-- deploy.md | 65 +++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 43 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 6cebbc8..db105ff 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Nginx Proxy Manager에는 실제 컨테이너/호스트 경로의 포트를 지 같은 네트워크 탐색은 기본 비활성입니다. `TRUSTED_PROXY_CIDRS`는 실제로 앱에 연결하는 검증된 프록시 IP/CIDR만 허용합니다. 임의 전달 헤더를 신뢰하지 않습니다. 검증된 클라이언트 IP를 얻지 못하면 네트워크 탐색을 하지 않습니다. 공인 IP가 정확히 같은 경우만 후보로 표시하고 IPv6 /64 통합은 하지 않습니다. 같은 공인 IP는 동일 Wi-Fi나 실제 근접의 증명이 아닙니다. -QR·8자리 코드는 기본 10분의 임시 공간 초대입니다. 최대 10대, 선택적 참여 승인, 내보내기와 공간 닫기를 지원합니다. 공간 참여와 자료 전송 수락은 별개입니다. QR 초대 토큰은 URL fragment에 넣어 서버 요청·리퍼러로 전달하지 않으며 참여 후 주소에서 지웁니다. +QR·4자리 코드는 기본 10분의 임시 공간 초대입니다. 초대 코드 길이는 설정으로 6자리까지 확장할 수 있습니다. 최대 10대, 선택적 참여 승인, 내보내기와 공간 닫기를 지원합니다. 공간 참여와 자료 전송 수락은 별개입니다. QR 초대 토큰은 URL fragment에 넣어 서버 요청·리퍼러로 전달하지 않으며 참여 후 주소에서 지웁니다. ## 익명 자료 @@ -55,7 +55,7 @@ QR·8자리 코드는 기본 10분의 임시 공간 초대입니다. 최대 10 ## 업데이트와 백업 -업데이트 전 앱을 정지하고 DB 볼륨(관련 WAL·SHM 포함)과 업로드 볼륨을 같은 시점에 백업합니다. SQLite 파일만 실행 중에 임의 복사하지 마세요. 복원은 별도 볼륨에서 DB integrity check와 실제 자료 접근을 확인한 뒤 적용합니다. 실제 Docker 백업·복원 검증은 Phase 5에서 수행합니다. +일반 코드·UI 업데이트는 `git pull --ff-only origin main` → Docker 이미지 재빌드 → 재배포로 진행합니다. Docker 구성과 환경변수가 바뀌지 않았다면 기존 YAML을 그대로 사용합니다. DB·업로드는 기존 볼륨에 유지되므로 매번 백업할 필요는 없습니다. DB 구조 변경에 대비하거나 데이터를 따로 보관하려면 앱을 정지한 뒤 DB 볼륨(WAL·SHM 포함), 업로드 볼륨, `.env`를 같은 시점에 백업합니다. 자세한 순서는 [deploy.md의 업데이트 절차](deploy.md#7-다음-버전으로-업데이트)를 참고하세요. 파일당 기본 2GiB, 익명 주체당 2GiB, 전체 익명 20GiB 제한과 최소 5GiB 여유 공간을 적용합니다. MB/KB 환경변수는 MiB/KiB 기준입니다. 파일은 수락 후 스트리밍 저장하고 중단 시 임시 파일·예약을 회수합니다. 파일은 8MiB 단위로 나누어 전송하고 서버가 받은 위치를 기록합니다. 중간 오류는 최대 3회 자동 재시도하며, 현재 화면에서 같은 파일로 ‘다시 전송’할 수 있습니다. 백그라운드 완료는 보장하지 않습니다. diff --git a/deploy.md b/deploy.md index 7f55bbf..faf1a16 100644 --- a/deploy.md +++ b/deploy.md @@ -211,14 +211,51 @@ https://hop.noname.company ## 7. 다음 버전으로 업데이트 -사용자가 확인한 NAS 경로에서 진행합니다. +**일반적인 코드·UI 업데이트는 아래 순서만 진행하세요. 기존 YAML·환경변수·볼륨은 그대로 사용합니다.** + +1. SSH에서 hop 폴더로 이동: ```sh cd /volume1/docker/projects/apps/hop ``` +2. 최신 코드 받기: + +```sh +git pull --ff-only origin main +``` + +3. Docker 앱 → **프로젝트 → hop → 재빌드 / 이미지 다시 빌드**. +4. 빌드 완료 후 **시작 / 재배포**. +5. `healthy` 확인 → 브라우저 새로고침. PWA는 앱을 닫고 다시 열기. + +앱의 재배포 버튼이 이미지 빌드까지 함께 실행한다면 그 버튼으로 진행해도 됩니다. 기존 이미지를 그대로 쓰는 단순 재시작은 새 코드를 반영하지 않습니다. + +**이번 업데이트도 이 순서로 진행하면 됩니다.** `sh scripts/configure-nas.sh`를 다시 실행하거나 YAML을 다시 불러올 필요가 없습니다. NPM·Cloudflare Tunnel 설정도 그대로 유지합니다. 위치 검색은 양쪽 브라우저에서 위치 권한을 허용하면 자동으로 동작합니다. + +DB와 파일은 `hop_hop_database`, `hop_hop_uploads` 볼륨에 있고 `.env`와 생성된 `compose.nas.yaml`은 Git에서 제외되어 있으므로 일반 코드 업데이트로 덮어쓰지 않습니다. 같은 볼륨을 사용하는 재배포에서 데이터는 유지됩니다. + +### 추가 작업이 필요한 업데이트 + +| 변경 내용 | 필요한 작업 | +| ------------------------------- | ------------------------------------------------------------------------------------------------------ | +| 코드·화면·CSS 변경 | Git pull → 이미지 재빌드 → 재배포 | +| Docker 구성·포트·볼륨 경로 변경 | Git pull → 설정/YAML 다시 생성 → Docker 앱에 새 YAML 불러오기 → 재빌드 → 재배포 | +| 환경변수 변경 | 필요한 값 수정 → 설정/YAML 다시 생성 → Docker 앱에 새 YAML 불러오기 → 재배포. 코드도 바뀌었다면 재빌드 | +| DB 구조·기존 데이터 변경 | 해당 버전의 변경 안내 확인 → 필요 시 아래 데이터 백업 → Git pull → 재빌드 → 재배포 | + +YAML이나 DB 변경이 필요한 버전은 업데이트 안내에서 별도로 표시합니다. 코드·CSS 수정 때마다 데이터 백업이나 YAML 재생성을 반복할 필요는 없습니다. + +### 필요한 경우에만 데이터 백업 + +백업 대상은 Git에 있는 코드가 아니라 **로그인 계정·설정이 들어 있는 DB, 임시 보관 파일, NAS의 `.env`**입니다. DB 변경 전 상태로 돌아갈 수 있게 준비하거나 현재 데이터를 별도로 보관하고 싶을 때 실행합니다. + 1. Docker 앱 → **프로젝트 → hop → 중지**. -2. SSH에서 데이터 백업: +2. SSH에서 순서대로 실행: + +```sh +cd /volume1/docker/projects/apps/hop +``` ```sh mkdir -p backups @@ -240,29 +277,9 @@ sudo docker run --rm -v hop_hop_database:/source/database:ro -v hop_hop_uploads: cp -p .env "backups/env-$(date +%Y%m%d-%H%M%S)" ``` -3. 최신 코드 받기: +3. 백업 후 위의 업데이트 순서로 진행하거나, 백업만 했다면 Docker 앱에서 **시작**. -```sh -git pull --ff-only origin main -``` - -4. 배포 YAML 다시 만들기. 기존 `.env`와 비밀값은 유지됩니다. - -```sh -sh scripts/configure-nas.sh -``` - -5. Docker 앱 → **프로젝트 → hop → 편집**. -6. 최신 **compose.nas.yaml**을 다시 불러오거나 편집기에 붙여넣기 → 저장. -7. **재빌드 / 이미지 다시 빌드** 선택 → **시작 / 재배포**. 단순 재시작만 하면 바뀐 코드가 이미지에 반영되지 않습니다. -8. `healthy` 확인. -9. 기존 같은 네트워크 자동 발견이 동작한다면 NPM·터널 설정은 그대로 유지합니다. 아직 설정하지 않았다면 **4단계 → 5-1단계 → 5-2단계** 순서로 진행합니다. -10. 브라우저 새로고침 → 양쪽 기기에서 사이트를 열고 브라우저의 **위치 권한을 허용**합니다. 약 100m 안이라면 자동으로 목록에 표시됩니다. 별도 검색 메뉴·거리 안내 문구는 표시하지 않습니다. 위치 권한은 각 기기에서 따로 허용해야 합니다. -11. 기기를 선택 → 링크·파일 전송 확인. 기존 PWA도 앱을 닫고 다시 열어 최신 화면을 확인합니다. - -기존 `.env`에 위치 설정이 없어도 `LOCATION_DISCOVERY_ENABLED=true`, 반경 100m가 적용됩니다. 새 도메인·외부 포트는 필요 없습니다. 실제 GPS 오차나 권한 문제로 검색되지 않으면 QR 연결을 이용하세요. [검색 동작과 기종 정보](docs/NEARBY_DISCOVERY.md)에 상세 동작을 기록했습니다. - -프로젝트를 삭제하거나 `docker compose down -v`를 실행하지 마세요. DB·파일은 `hop_hop_database`, `hop_hop_uploads` 볼륨에 남습니다. 업데이트 실패 시 중지하고 오류를 확인하세요. DB 마이그레이션이 적용됐을 수 있으므로 코드만 되돌리지 말고 같은 시점의 DB·업로드·환경파일 백업으로 함께 복구해야 합니다. +DB 구조가 바뀐 뒤 이전 상태로 복구하려면 같은 시점의 코드·DB·파일·환경설정을 함께 사용해야 합니다. 데이터 유지가 필요한 경우 프로젝트의 볼륨을 삭제하거나 `docker compose down -v`를 실행하지 않습니다. ## 8. 시작 / 중지 / 로그