From e0c29955186601b6254b643ffe5198264def111d Mon Sep 17 00:00:00 2001 From: zenn Date: Thu, 26 Mar 2026 17:33:47 +0900 Subject: [PATCH] =?UTF-8?q?=EB=A6=B4=EB=A6=AC=EC=8A=A4:=20v0.1.35=20NAS=20?= =?UTF-8?q?Git=20=EB=B0=B0=ED=8F=AC=20=EC=A0=88=EC=B0=A8=20=EC=A0=95?= =?UTF-8?q?=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/history.md | 4 ++ docs/ugreen-nas-deploy.md | 84 ++++++++++++++++++++++++++++++++++++++- docs/update.md | 4 ++ 3 files changed, 91 insertions(+), 1 deletion(-) diff --git a/docs/history.md b/docs/history.md index c5bc1db..186d873 100644 --- a/docs/history.md +++ b/docs/history.md @@ -1,5 +1,9 @@ # 의사결정 이력 +## 2026-03-26 v0.1.35 +- NAS 운영 경로는 수동 파일 복사보다 Git clone 기반이 로컬 개발 흐름과 더 잘 맞고, 실수로 누락되는 파일을 줄일 수 있으므로 기본 배포 방식으로 권장하기로 결정했다. +- 운영 환경 변수와 Docker 볼륨은 Git 저장소 바깥의 NAS 자산으로 유지하고, 코드는 `git pull`로만 반영하는 역할 분리를 명확히 하기로 했다. + ## 2026-03-26 v0.1.34 - 일부 NAS 환경에서 `favicon.svg` 정적 응답이 `403`으로 차단될 수 있으므로, 운영 안정성을 위해 별도 파일 요청이 필요 없는 인라인 데이터 URL 파비콘으로 전환하기로 결정했다. - 관리자 기본 아이템 등록은 단일 파일 업로드만으로는 운영 부담이 크므로, 다중 선택과 드래그 앤 드롭을 지원하고 라벨은 파일명으로 자동 생성하는 방향을 채택했다. diff --git a/docs/ugreen-nas-deploy.md b/docs/ugreen-nas-deploy.md index 18509ce..7646e8c 100644 --- a/docs/ugreen-nas-deploy.md +++ b/docs/ugreen-nas-deploy.md @@ -17,6 +17,37 @@ - NAS 작업 폴더에 현재 프로젝트를 그대로 업로드한다. - 기존 로컬 MariaDB 내용은 무시하고 새 운영 DB로 시작해도 된다. +## 1-1. 권장 방식: Git clone 기반 운영 +- 수동 복사는 처음 1회에는 가능하지만, 이후부터는 로컬과 NAS가 쉽게 어긋난다. +- 권장 방식은 NAS 작업 폴더를 Git 저장소로 두고, 로컬에서 작업 후 `push`, NAS에서는 `pull`만 하는 구조다. +- 추천 흐름: + - 로컬: 개발 → 테스트 → 커밋 → `git push` + - NAS: `git pull` → `docker compose up -d --build` + +처음부터 Git으로 시작하려면 NAS에서: + +```bash +cd /volume1/docker/projects/apps +git clone https://git.sori.studio/zenn/tier-maker.git +cd tier-maker +cp .env.production.example .env.production +``` + +- 이미 같은 경로에 수동 복사본이 있다면, 가장 깔끔한 방법은 기존 폴더를 다른 이름으로 잠시 옮기고 새로 `clone`하는 것이다. +- `.env.production`은 Git에 올리지 않고 NAS에만 유지한다. + +예시: + +```bash +cd /volume1/docker/projects/apps +mv tier-maker tier-maker-manual-backup +git clone https://git.sori.studio/zenn/tier-maker.git +cd tier-maker +cp .env.production.example .env.production +``` + +- 이후 기존 수동 복사본의 `.env.production` 값을 새 clone 폴더의 `.env.production`에 그대로 옮기면 된다. + ## 2. 환경변수 파일 준비 - 루트에서 `.env.production.example`를 복사해 `.env.production`으로 만든다. - 최소 변경값: @@ -46,6 +77,43 @@ docker compose --env-file .env.production -f docker-compose.prod.yml up -d --bui docker compose --env-file .env.production -f docker-compose.prod.yml --profile admin up -d --build ``` +- MariaDB 첫 초기화는 NAS 환경에서 2분 이상 걸릴 수 있다. +- 현재 프로덕션 컴포즈는 이를 고려해 `start_period: 150s`, `retries: 20` healthcheck를 사용한다. +- 로그상 DB가 정상 기동했는데도 `unhealthy`가 뜬 적이 있다면 최신 `docker-compose.prod.yml`로 다시 올리는 것이 좋다. + +## 3-1. 이후 업데이트 방식 +- Git clone 기반으로 전환한 뒤에는 파일을 하나씩 NAS에 덮어쓰지 않는다. +- 로컬에서 커밋과 푸시가 끝난 뒤, NAS에서는 아래 두 줄이 기본 배포 절차다. + +```bash +git pull origin main +docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +``` + +- Dockerfile, Nginx 설정, 프런트 소스, 백엔드 소스가 바뀐 경우에는 `--build`를 유지한다. +- 단순 재시작만 필요할 때도 있지만, 운영에서는 실수 방지를 위해 `up -d --build`를 기본값으로 두는 편이 안전하다. + +## 3-2. 이번 v0.1.34까지 적용하는 예시 +- 이미 NAS 폴더가 Git clone 상태라면: + +```bash +cd /volume1/docker/projects/apps/tier-maker +git pull origin main +docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +``` + +- 아직 수동 복사 폴더만 있다면: + +```bash +cd /volume1/docker/projects/apps +mv tier-maker tier-maker-manual-backup +git clone https://git.sori.studio/zenn/tier-maker.git +cd tier-maker +cp .env.production.example .env.production +# 여기서 기존 .env.production 값을 새 파일에 옮긴다. +docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +``` + ## 4. NAS 리버스 프록시 - 외부 도메인: `tmaker.sori.studio` - 내부 대상 프로토콜: `http` @@ -58,6 +126,7 @@ docker compose --env-file .env.production -f docker-compose.prod.yml --profile a - 현재 프로덕션 컴포즈는 `SESSION_COOKIE_SECURE=true`를 사용한다. - 따라서 `tmaker.sori.studio`에는 HTTPS 인증서가 연결되어 있어야 한다. - NAS 리버스 프록시가 HTTPS 종료를 하고 내부는 `http://frontend:80` 또는 `localhost:8080`으로 전달하면 된다. +- 최신 프런트 Nginx 설정은 백엔드로 `X-Forwarded-Proto: https`를 넘기므로, 로그인 직후 세션이 바로 풀리는 경우에는 프런트 이미지를 다시 빌드해 최신 설정이 반영됐는지 먼저 확인한다. ## 6. 데이터 위치 - MariaDB 데이터: Docker volume `tmaker_mariadb_data` @@ -67,12 +136,25 @@ docker compose --env-file .env.production -f docker-compose.prod.yml --profile a ## 7. 점검 포인트 - 메인 접속: `https://tmaker.sori.studio` - 헬스체크: `https://tmaker.sori.studio/health` +- 로그인 후 새로고침 또는 `내 티어표` 진입 시 세션이 유지되는지 확인 - 관리자 로그인 후: - 게임 생성 - 썸네일 업로드 - 티어표 저장 - 이미지 다운로드 -## 8. 참고 +## 8. MariaDB가 unhealthy일 때 +- 로그에 `ready for connections`가 보이면 DB 자체는 정상일 가능성이 높다. +- 이 경우는 대부분 healthcheck 시간이 짧아서 생기는 문제다. +- 최신 컴포즈 파일 반영 후 아래 순서로 다시 시작한다: + +```bash +docker compose --env-file .env.production -f docker-compose.prod.yml down -v +docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +``` + +## 9. 참고 - 현재 업로드 이미지는 서버 저장 전에 리사이즈/압축하지 않는다. - 운영 중 원본 이미지가 많이 쌓이면 이후 `sharp` 기반 최적화 단계를 추가하는 것이 좋다. +- 프런트/백엔드/Nginx 설정을 바꿨다면 NAS에서 `docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build`로 이미지를 다시 빌드해 반영한다. +- 운영 중 `.env.production`, 업로드 파일 볼륨, MariaDB 볼륨은 Git과 별개로 NAS 로컬 자산이므로 백업 정책을 따로 잡아야 한다. diff --git a/docs/update.md b/docs/update.md index 224cf8a..31f8166 100644 --- a/docs/update.md +++ b/docs/update.md @@ -1,5 +1,9 @@ # 업데이트 로그 +## 2026-03-26 v0.1.35 +- **NAS Git 배포 절차 추가**: UGREEN NAS에서 수동 복사 대신 `git clone`과 `git pull` 기반으로 운영 배포를 관리하는 절차를 배포 가이드에 정리 +- **v0.1.34 반영 명령 정리**: 이미 수동 복사본이 있는 경우 새 clone으로 전환한 뒤 최신 이미지를 다시 빌드하는 순서를 문서화 + ## 2026-03-26 v0.1.34 - **파비콘 정적 요청 제거**: 운영 환경에서 `/favicon.svg`가 `403`으로 막히는 경우를 피하기 위해, 별도 파일 대신 `index.html` 인라인 데이터 URL 파비콘으로 전환 - **관리자 기본 아이템 다중 업로드 추가**: 게임 관리 화면에서 기본 아이템을 여러 장 드래그 앤 드롭 또는 다중 파일 선택으로 한 번에 추가할 수 있도록 변경하고, 기본 라벨은 파일명 기준으로 자동 생성