NAS DB 초기화 배포 절차를 문서화

docs/history.md

@@ -1,5 +1,9 @@
 # 의사결정 이력
 
+## 2026-04-03 v1.4.62
+- 운영 서버를 새 DB로 다시 시작하는 절차는 “일반 업데이트 재빌드”와 “볼륨까지 삭제하는 완전 초기화”가 같은 문서 안에 섞이면 실수로 데이터를 날릴 위험이 크므로, 배포 문서에서 두 흐름을 별도 섹션으로 나누는 편이 맞다고 판단했다.
+- DB만 비우고 업로드 볼륨을 남기는 방식도 가능하지만, 현재 서비스는 DB 레코드와 업로드 파일 참조가 강하게 연결되어 있으므로 이 방법 역시 “운영 데이터를 전부 버리는 전제”라는 경고를 같이 적어두는 쪽으로 정리했다.
+
 ## 2026-04-03 v1.4.61
 - 운영자가 쓰는 템플릿 주소를 `topics.id` 자체로 두면 나중에 이름/URL을 다듬고 싶을 때 참조 FK와 기존 링크까지 같이 흔들릴 수 있으므로, 내부 참조용 랜덤 `id`와 공개/관리용 `slug`를 분리하는 구조가 더 안전하다고 판단했다.
 - 운영 DB와 로컬 DB를 모두 새로 시작할 수 있는 상황이라면 예전 `id -> slug` 백필이나 레거시 호환 코드를 남기는 편이 오히려 유지보수 비용만 늘리므로, 이번 변경은 새 스키마 기준으로 깔끔하게 정리하고 기존 데이터 호환 마이그레이션은 두지 않기로 했다.

docs/todo.md

@@ -1,6 +1,8 @@
 # 할 일 및 이슈
 
 ## 단기 확인
+- `v1.4.62`에서 NAS 배포 문서에 운영 DB 완전 초기화 절차를 추가했으므로, 실제 NAS에서 `git pull → docker compose ... down -v → up -d --build` 순서로 재배포했을 때 빈 DB가 현재 스키마로 다시 올라오고 `freeform`만 생성되는지 확인한다.
+- `docker volume rm tier-maker_tmaker_mariadb_data` 방식은 프로젝트 디렉터리명에 따라 실제 볼륨 이름이 달라질 수 있으므로, 운영 NAS에서는 먼저 `docker volume ls | grep tmaker`로 이름을 확인한 뒤 문서 명령이 그대로 맞는지 점검한다.
 - `v1.4.61`에서 템플릿 공개 주소를 `slug`로 분리했으므로, 홈 카드/주제 상세/나의 티어표/즐겨찾기/검색 결과/팔로우 피드/사용자 프로필에서 열리는 URL이 `/topics/:slug`, `/editor/:slug/...` 형태로 바뀌고, 실제 화면 내용도 같은 주제 템플릿으로 정확히 열리는지 QA한다.
 - 관리자 템플릿 생성/설정은 이제 내부 ID가 아니라 `slug + 이름`만 입력하므로, 새 템플릿 생성, 기존 템플릿 이름/slug 저장, 중복 slug 입력, 대문자/특수문자 slug 입력, 공개/비공개 토글, 썸네일/기본 아이템 관리가 모두 같은 템플릿에 정상 반영되는지 확인한다.
 - 신규 빈 DB 초기화 시 `topics`에 `freeform` 한 건만 생성되고 `example-topic`, `another-topic` 같은 예시 템플릿이 더 이상 자동으로 생기지 않는지 운영/로컬 재배포 후 확인한다.

docs/ugreen-nas-deploy.md

@@ -93,7 +93,41 @@ docker compose --env-file .env.production -f docker-compose.prod.yml up -d --bui
 - Dockerfile, Nginx 설정, 프런트 소스, 백엔드 소스가 바뀐 경우에는 `--build`를 유지한다.
 - 단순 재시작만 필요할 때도 있지만, 운영에서는 실수 방지를 위해 `up -d --build`를 기본값으로 두는 편이 안전하다.
 
-## 3-2. 이번 v0.1.34까지 적용하는 예시
+## 3-2. 운영 DB/업로드/세션까지 완전 초기화하고 새로 빌드하기
+- 운영 데이터를 전부 버리고 새 DB로 다시 시작할 때만 사용한다.
+- 아래 명령은 MariaDB 데이터, 업로드 이미지, 세션 파일 볼륨까지 같이 삭제하므로 실행 전에 정말 초기화해도 되는지 반드시 확인한다.
+- `.env.production`은 프로젝트 폴더에 그대로 남고, Docker volume 데이터만 제거된다.
+
+```bash
+cd /volume1/docker/projects/apps/tier-maker
+git pull origin main
+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
+```
+
+- 이렇게 올리면 백엔드가 빈 MariaDB에 현재 스키마를 새로 만들고, 초기 템플릿은 시스템용 `freeform` 한 건만 생성한다.
+- `down -v` 후 첫 기동은 MariaDB 초기화 때문에 조금 더 오래 걸릴 수 있으니, 아래 명령으로 상태를 확인한다.
+
+```bash
+docker compose --env-file .env.production -f docker-compose.prod.yml ps
+docker compose --env-file .env.production -f docker-compose.prod.yml logs -f mariadb
+docker compose --env-file .env.production -f docker-compose.prod.yml logs -f backend
+```
+
+## 3-3. DB만 비우고 업로드/세션 볼륨은 유지하기
+- 이미지 파일과 세션 볼륨은 유지하고 MariaDB 데이터만 새로 시작하고 싶다면 `tmaker_mariadb_data` 볼륨만 지운다.
+- 이 경우에도 기존 티어표/유저 DB 레코드와 업로드 파일 참조가 끊길 수 있으므로, 현재 운영 데이터를 전부 버리는 전제에서만 사용한다.
+
+```bash
+cd /volume1/docker/projects/apps/tier-maker
+docker compose --env-file .env.production -f docker-compose.prod.yml down
+docker volume rm tier-maker_tmaker_mariadb_data
+docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
+```
+
+- 만약 볼륨 이름이 다르게 잡혀 있는지 확인하고 싶다면 먼저 `docker volume ls | grep tmaker`로 실제 이름을 확인한 뒤 지운다.
+
+## 3-4. 이번 최신 main까지 적용하는 예시
 - 이미 NAS 폴더가 Git clone 상태라면:
 
 ```bash
@@ -153,6 +187,8 @@ 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
 ```
 
+- 이 명령도 `down -v` 때문에 DB/업로드/세션 볼륨을 모두 삭제한다. 데이터를 유지해야 하는 상황이면 `-v`를 빼고 다시 올린다.
+
 ## 9. 참고
 - 현재 업로드 이미지는 서버 저장 전에 리사이즈/압축하지 않는다.
 - 운영 중 원본 이미지가 많이 쌓이면 이후 `sharp` 기반 최적화 단계를 추가하는 것이 좋다.

docs/update.md

@@ -1,5 +1,10 @@
 # 업데이트 로그
 
+## 2026-04-03 v1.4.62
+- UGREEN NAS 운영 배포 문서에 `git pull origin main` 후 일반 재빌드하는 절차와, 운영 데이터를 전부 버리고 `docker compose ... down -v`로 MariaDB/업로드/세션 볼륨까지 초기화한 뒤 새로 `up -d --build` 하는 절차를 분리해서 추가했다.
+- DB만 비우고 싶을 때 `tmaker_mariadb_data` 볼륨만 삭제하는 방법과, 실제 볼륨 이름이 다를 수 있으니 `docker volume ls | grep tmaker`로 먼저 확인하는 안내도 함께 적었다.
+- 새로 초기화한 운영 DB로 올리면 현재 스키마가 다시 생성되고 시스템 템플릿은 `freeform` 한 건만 들어간다는 점을 배포 문서에 명시했다.
+
 ## 2026-04-03 v1.4.61
 - 템플릿 공개 URL과 내부 참조를 분리해, `topics.id`는 서버가 자동 생성하는 랜덤 내부 ID로 두고 운영자가 직접 관리하는 공개 주소는 `topics.slug`로 저장하도록 바꿨다.
 - 공개 주제/에디터 경로는 `slug`를 우선 사용하고, 백엔드는 `/api/topics/:topicId`, `/api/tierlists/public?topicId=...`, 티어표 저장/템플릿 요청의 `topicId` 입력을 `slug` 또는 내부 ID에서 실제 템플릿 레코드로 해석한 뒤 내부 `topic_id`를 저장하도록 정리했다.