zenn/sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.3.6: 운영 DB 마이그레이션 적용 이력 및 NAS 명령 추가

Browse Source 
schema_migrations로 적용 파일을 추적하고, 기존 운영 DB는 001부터 자동 실행하지 않도록 baseline 흐름을 둔다.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zenn
2026-05-20 14:33:13 +09:00
parent c43873ce5f
commit 0e70d4482d
9 changed files with 372 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/deploy.md
View File

@@ -137,16 +137,14 @@ cp .env.example .env.production
# Docker 빌드 및 실행
docker compose --env-file .env.production up -d --build
# 기존 운영 DB를 유지한 채 새 버전을 올릴 때 추천 글·네비 location 마이그레이션 적용
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/023_add_post_featured.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/024_navigation_recommended_location.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/025_posts_status_no_private.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/026_site_settings_show_post_updated_at.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/027_site_settings_home_cover.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/028_site_settings_announcement.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/029_site_settings_signup_blocked_usernames.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/030_analytics_daily_stats.sql
docker compose --env-file .env.production exec sori-studio-db psql -U sori_studio -d sori_studio -f /docker-entrypoint-initdb.d/031_analytics_engagement_and_realtime.sql
# 운영 DB 마이그레이션 상태 확인
npm run db:migrate:prod:status
# schema_migrations 도입 전 운영 DB가 이미 최신이면 최초 1회 기준점 기록(실제 SQL 실행 없음)
npm run db:migrate:prod:baseline
# 이후 배포에서는 아직 적용되지 않은 SQL만 순서대로 실행
npm run db:migrate:prod
```
### Docker 네트워크 충돌 대응
@@ -200,6 +198,8 @@ docker compose --env-file .env.production up -d --build
- NAS Docker 배포 시 PostgreSQL 초기 스키마는 `db/migrations/`의 SQL로 생성
- 로컬 개발 Docker Compose 실행 시 `ENV_FILE=.env.development`와 `--env-file .env.development`를 함께 사용
- 로컬 개발 DB 마이그레이션은 `npm run db:migrate:dev`로 실행
- NAS 운영 DB 마이그레이션은 `npm run db:migrate:prod:status`로 적용 상태를 확인하고, `npm run db:migrate:prod`로 미적용 파일만 실행한다.
- `schema_migrations`가 없는 기존 운영 DB에서 `posts` 테이블이 감지되면 `db:migrate:prod`는 001부터 자동 실행하지 않는다. 현재 코드 기준 최신 DB라면 최초 1회 `npm run db:migrate:prod:baseline`으로 기존 파일을 적용 완료로 기록한다. 특정 번호까지만 기록하려면 예: `npm run db:migrate:prod:baseline -- --to=031`.
- 네비게이션 계층(`parent_id`, `is_folder`)은 `017_navigation_hierarchy.sql` 적용 후 저장 API가 정상 동작한다(미적용 시 `INSERT` 컬럼 불일치).
- 회원 마지막 로그인 표시(`previous_last_seen_at`, `previous_last_seen_ip`)는 `021_add_member_previous_login.sql` 적용 후 정상 동작한다.
- 사이트 로고와 파비콘 저장(`logo_url`, `favicon_url`)은 `022_add_site_logo_urls.sql` 적용 후 정상 동작한다.

6
docs/history.md
View File

@@ -1,5 +1,11 @@
# 의사결정 이력
## 2026-05-20 v1.3.6
### NAS 운영 마이그레이션 적용 이력 도입
운영 NAS에서 몇 번 SQL까지 적용했는지 파일명만으로 추적하면 누락과 중복 실행을 사람이 기억해야 한다. `schema_migrations` 테이블에 적용 완료 파일을 기록하고, 운영용 `db:migrate:prod`는 기록이 없는 파일만 실행하도록 했다. 이미 운영 중인 DB에는 과거 적용 기록이 없으므로, 기존 스키마가 감지되면 001부터 자동 실행하지 않고 baseline 기록을 요구해 데이터 변경 SQL의 의도치 않은 재실행을 막는다.
## 2026-05-20 v1.3.5
### 관리자 로그인·대시보드 차트·통계 보관 후속

3
docs/map.md
View File

@@ -291,7 +291,8 @@
| composables/useThemeMode.js | 사용자 화면 라이트/다크 테마 상태 관리 |
| middleware/admin-auth.global.js | 관리자 페이지 접근 인증 |
| scripts/dev-server.js | 로컬 개발 서버 링크 요약 출력 |
| scripts/migrate-development-db.js | 로컬 개발 DB 마이그레이션 실행 |
| scripts/migrate-database.js | 로컬·NAS DB 마이그레이션 적용/상태/baseline 실행 |
| scripts/migrate-development-db.js | 기존 로컬 개발 DB 마이그레이션 명령 호환 래퍼 |
| .env.example | 환경 변수 예시 |
| Dockerfile | NAS 운영 이미지 빌드 |
| docker-compose.yml | NAS 컨테이너 실행 초안 |

8
docs/spec.md
View File

@@ -213,6 +213,14 @@ components/content/
- 운영 DB 접속 정보는 로컬 기본 `.env`에 기록하지 않음
- DB 관리 도구는 CloudBeaver 등을 사용할 수 있도록 접속 정보를 환경별로 분리
### 마이그레이션 적용 이력
- `schema_migrations` 테이블은 적용 완료된 SQL 파일명을 `file_name` 기준으로 기록한다.
- `npm run db:migrate:dev`와 `npm run db:migrate:prod`는 `db/migrations/*.sql` 중 `schema_migrations`에 없는 파일만 순서대로 실행한다.
- `npm run db:migrate:prod:status`는 NAS 운영 DB의 적용/대기 파일 목록을 출력한다.
- 기존 운영 DB에 `posts` 테이블은 있지만 `schema_migrations`가 없으면 `npm run db:migrate:prod`는 데이터 보호를 위해 001부터 자동 실행하지 않고 중단한다.
- 기존 운영 DB가 현재 코드 기준으로 이미 최신이면 `npm run db:migrate:prod:baseline`으로 현재 마이그레이션 파일들을 실행 없이 적용 완료로 기록한 뒤 이후 새 파일만 적용한다.
### Posts (블로그 글)
| 필드 | 타입 | 설명 |

5
docs/update.md
View File

@@ -1,5 +1,10 @@
# 업데이트 이력
## v1.3.6
- DB 마이그레이션: `schema_migrations` 적용 이력 관리와 `db:migrate:prod`, `db:migrate:prod:status`, `db:migrate:prod:baseline` 명령 추가.
- 운영 보호: 기존 운영 스키마가 있는데 적용 이력이 없으면 001부터 자동 실행하지 않고 baseline 안내 후 중단.
## v1.3.5
- 관리자 로그인: 자동완성 값 동기화·제출 중만 버튼 비활성. 운영 HTTP에서 Secure 쿠키 미저장으로 로그인 루프되던 문제 수정. `server/utils/session-cookie.js`로 path `/`·`x-forwarded-proto` Secure 통일.