관리자 글쓰기 화면과 개발 환경 문서 정리

2026-05-07 10:36:01 +09:00
parent e506a343bc
commit 1ef50c111b
13 changed files with 276 additions and 115 deletions
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -9,7 +9,7 @@
 | 개발 | `npm run dev` | 로컬 테스트, 개발 서버 |
 | 프로덕션 | `npm run build` | NAS 배포, 운영 서버 |

-> `npm run dev`는 프로젝트 전용 실행 스크립트를 통해 Localhost, Local IP, Admin, Tailwind Viewer 링크만 요약 출력한다.
+> `npm run dev`는 프로젝트 전용 실행 스크립트를 통해 개발 서버, Admin, Tailwind Viewer 링크만 요약 출력한다.

 ---

@@ -50,6 +50,8 @@ npm run dev

 ```bash
 # Docker daemon 시작
+# Docker Desktop을 사용하면 Docker.app을 먼저 실행
+# Colima를 사용하면 아래 명령 실행
 colima start

 # 개발 DB 컨테이너 실행
@@ -71,6 +73,33 @@ docker exec sori-studio-db psql -U sori_studio -d sori_studio -c 'SELECT count(*
 - 관리자: http://127.0.0.1:43117/admin
 - Tailwind Viewer: http://127.0.0.1:43117/_tailwind/

+### 로컬 DB 확인 방법
+
+로컬 개발 DB는 PostgreSQL이며 호스트에서는 `127.0.0.1:43119`로 접근한다. 접속 정보는 Git에 포함하지 않는 `.env.development` 값을 사용한다.
+
+| 항목 | 값 |
+|------|----|
+| Host | `127.0.0.1` |
+| Port | `43119` |
+| Database | `.env.development`의 `POSTGRES_DB` |
+| User | `.env.development`의 `POSTGRES_USER` |
+| Password | `.env.development`의 `POSTGRES_PASSWORD` |
+
+터미널에서 바로 확인할 때는 컨테이너 내부 `psql`을 사용한다.
+
+```bash
+# DB 준비 상태 확인
+docker exec sori-studio-db pg_isready -U sori_studio -d sori_studio
+
+# 게시물 개수 확인
+docker exec sori-studio-db psql -U sori_studio -d sori_studio -c 'SELECT count(*) AS posts_count FROM posts;'
+
+# psql 콘솔 접속
+docker exec -it sori-studio-db psql -U sori_studio -d sori_studio
+```
+
+GUI로 확인할 때는 DBeaver, TablePlus, DataGrip, CloudBeaver 같은 PostgreSQL 클라이언트에서 위 접속 정보를 입력한다. phpMyAdmin은 MySQL/MariaDB용 도구라 이 프로젝트의 PostgreSQL DB 확인 용도로는 사용하지 않는다.
+
 ---

 ## UGREEN NAS Docker 배포
@@ -141,6 +170,76 @@ docker run -d -p 3000:3000 sori.studio:latest
 - 로컬 개발 Docker Compose 실행 시 `ENV_FILE=.env.development`와 `--env-file .env.development`를 함께 사용
 - 로컬 개발 DB 마이그레이션은 `npm run db:migrate:dev`로 실행

+### 개발/운영 DB 분리 검증 절차
+
+검증 전제는 실제 비밀번호나 전체 `DATABASE_URL`을 화면 공유, 문서, 커밋 메시지에 노출하지 않는 것이다. 확인할 때는 호스트, 포트, DB 이름, 파일명만 대조한다.
+
+1. `.env.development` 확인.
+
+```bash
+# 로컬 개발 DB는 호스트 기준 127.0.0.1:43119를 사용해야 한다.
+# DATABASE_URL 전체 값은 공유하지 않는다.
+rg -n "^(DATABASE_URL|POSTGRES_DB|POSTGRES_USER|DB_PORT)=" .env.development
+```
+
+기준:
+
+- `DATABASE_URL` 호스트가 `127.0.0.1`
+- `DATABASE_URL` 포트가 `43119`
+- `DB_PORT=43119`
+- 운영 NAS 호스트명, 운영 IP, 운영 DB 이름이 포함되지 않음
+
+2. `.env.production` 확인.
+
+```bash
+# 운영 파일은 Git에 올리지 않는 운영 전용 파일이다.
+# 값이 없으면 NAS 배포 전 작성해야 한다.
+test -f .env.production && rg -n "^(DATABASE_URL|POSTGRES_DB|POSTGRES_USER|APP_PORT)=" .env.production
+```
+
+기준:
+
+- NAS Docker 내부 실행 기준이면 `DATABASE_URL` 호스트가 `sori-studio-db`
+- NAS 외부 DB를 별도 인스턴스로 쓰는 경우에도 로컬 개발 DB(`127.0.0.1:43119`)를 가리키지 않음
+- `APP_PORT=43118`
+- `.env.development`와 DB 비밀번호, 관리자 비밀번호가 서로 다름
+
+3. 로컬 개발 DB 연결 확인.
+
+```bash
+docker exec sori-studio-db pg_isready -U sori_studio -d sori_studio
+docker exec sori-studio-db psql -U sori_studio -d sori_studio -c 'SELECT current_database(), current_user;'
+```
+
+기준:
+
+- `accepting connections` 표시
+- `current_database`가 로컬 개발 DB 이름
+- `current_user`가 로컬 개발 DB 계정
+
+4. 로컬 개발 서버 연결 확인.
+
+```bash
+npm run dev
+```
+
+기준:
+
+- 출력 주소가 `http://127.0.0.1:43117`
+- 관리자 API 요청에서 `127.0.0.1:43119` 연결 오류가 발생하지 않음
+
+5. 커밋 전 민감 정보 확인.
+
+```bash
+git status --short
+git diff -- . ':!package-lock.json'
+```
+
+기준:
+
+- `.env.development`, `.env.production`이 변경 목록에 포함되지 않음
+- 문서와 코드 diff에 실제 DB 비밀번호, 관리자 비밀번호, 운영 접속 주소가 포함되지 않음
+
 ## 업로드 파일

 - 관리자 글쓰기에서 업로드한 이미지는 `/uploads/posts/YYYY/MM/` URL로 제공한다.