배포
코드 변경이 검사를 거쳐 운영 화면에 올라가기까지의 순서와 규칙을 정리합니다. 보안을 위해 서버 주소·경로·서비스 이름은 적지 않습니다.
운영 구성
| 항목 | 내용 |
|---|---|
| 실행 | 리눅스 서버 한 대에서 Next.js 독립 실행형 빌드로 돕니다. 앞단의 웹 서버가 kpi.dvsharp.com 요청을 넘깁니다. |
| 무중단 교체 | 같은 앱을 두 벌(블루·그린) 두고, 쉬는 쪽에 새 버전을 올린 뒤 전환합니다. |
| 데이터베이스 | 셀프호스팅 Supabase(PostgreSQL). 스키마 원본은 저장소의 prisma/schema.prisma입니다. |
| 자동 작업 | 정해진 시각의 작업은 서버의 작업 예약으로 돌립니다(데이터 반영과 자동 작업). |
| 오류 관측 | Sentry |
변경에서 배포까지
- 기본 브랜치에서 작업 브랜치를 만들어 고칩니다.
- 풀 리퀘스트를 엽니다. CircleCI가 형식 검사(
typecheck)와 시험(test)을 돌립니다. 저장소 규칙을 지키는 정적 시험도 함께 돕니다. - 검사를 통과하면 기본 브랜치에 병합합니다.
- 운영 배포는 오너가 요청할 때 한 번 합니다. 그때까지 병합된 변경을 한 번에 올립니다.
- 공용 배포 명령 하나로 배포합니다. 명령은 아래 순서로 돕니다.
| 순서 | 하는 일 |
|---|---|
| 1 | 병합된 기본 브랜치의 커밋을 고정합니다. 손으로 내려받거나 커밋을 고르지 않습니다. |
| 2 | 동시에 두 배포가 돌지 않게 잠급니다. |
| 3 | 배포 전 검사를 돌립니다. 적용하지 않은 DB 마이그레이션이 있거나 행 수준 보안(RLS) 감사가 실패하면 멈춥니다. |
| 4 | 빌드합니다. 빌드는 CPU 일부만 써서 운영 화면이 느려지지 않게 합니다. |
| 5 | 쉬는 쪽에 새 버전을 띄우고 상태 확인 요청이 성공하는지 봅니다. |
| 6 | 성공하면 요청을 새 버전으로 넘깁니다. 실패하면 이전 버전을 그대로 두고 실패 단계와 사유를 기록합니다. |
운영 서비스를 손으로 다시 시작하지 않습니다. 배포는 언제나 이 명령 하나로만 합니다.
DB 마이그레이션
배포 명령은 마이그레이션을 실행하지 않습니다. 스키마를 바꾼 변경은 아래 순서를 지킵니다.
- 운영 데이터베이스를 백업합니다.
pnpm exec prisma migrate deploy로 마이그레이션을 적용합니다.- 그 뒤에 배포합니다.
배포 전 검사는 pnpm run deploy:precheck이며, 적용하지 않은 마이그레이션이 남아 있으면 배포를 멈춥니다. 2026년 11월 마이그레이션 전에 배포해 약 5분 동안 운영 코드가 읽을 새 표가 아직 없었던 일이 있어 이 검사를 넣었습니다.
배포 직후
- 배포 전에 열어 둔 화면에서 서버 동작이 실패하면 새 버전이 배포됐습니다 안내와 새로고침 단추가 나옵니다. 사용자는 새로고침하면 됩니다.
- 운영 화면에서 바뀐 화면을 직접 열어 확인합니다.
- 새벽 작업처럼 자동 작업에 영향이 있는 변경이면 데이터 갱신 현황에서 다음 실행이 정상인지 봅니다.
개발자 명령
저장소 안에서 쓰는 명령입니다.
pnpm install # 의존성 설치
pnpm run dev # 로컬 개발 서버
pnpm run build # Prisma 생성 → Next.js 빌드
pnpm run test:integration # DB·외부 API를 쓰는 통합 시험
pnpm run deploy:precheck # 미적용 마이그레이션 확인 + RLS 감사
pnpm exec prisma migrate deploy # 마이그레이션 적용
비밀 값은 저장소에 두지 않고 서버의 환경 파일로만 관리합니다.
관련 쪽
- 배포 뒤 화면이 이상하면 문제 해결을 봅니다.