Operations & Deployment

NestPay 운영·배포 가이드

개발(dev) → 테스트(sandbox) → 운영(live) 3단계 환경 운영과 데이터베이스 동기화(Flyway) 절차입니다. 담당자가 이 문서만 따라 하면 각 환경을 안전하게 올리고, DB 변경을 순서대로 반영할 수 있습니다.

1. 환경 3단계 구조

환경은 NESTPAY_ENV 값으로 구분합니다. dev 가 아니면(sandbox·live) 개발용 기본 시크릿으로는 서버가 기동되지 않습니다(SecretsGuard, 보안).

환경	NESTPAY_ENV	용도 / 특징
local (dev)	dev	개발자 PC. 도커 컴포즈(API+MariaDB). 개발용 기본 시크릿 허용, 스텁 외부연동. 실데이터 없음.
sandbox	sandbox	테스트 서버. 운영과 동일 구성이되 테스트 시크릿·테스트 인증사(테스트베드). 발주사·QA 검증용. 실데이터 아님.
live	live	운영 서버. 운영 시크릿·실 인증사·실계좌. 실데이터. 접속·배포 제한(물리 분리).

코드는 환경별로 분기하지 않습니다. 같은 산출물(jar·앱·admin)에 환경변수만 달리 주입해 동작을 바꿉니다(도메인·DB·시크릿·인증사).

2. 환경변수 (환경별 주입)

변수	설명 · dev 기본값
NESTPAY_ENV	dev \| sandbox \| live. 기본 `dev`. live/sandbox 는 반드시 지정.
SERVICE_DOMAIN	서비스 도메인. 기본 `nestpay.co.kr`. api.·admin.·www. 서브도메인이 자동 파생.
DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD	DB 접속. live/sandbox 는 강한 비밀번호 필수(기본 `nestpay` 사용 시 부팅 거부).
APP_CRYPTO_KEY	민감정보(_enc) 암호화 키. 운영 필수(기본값 사용 시 부팅 거부). 환경마다 다르게, 절대 유출 금지·분실 시 복호화 불가.*
ADMIN_TOKEN_SECRET	토큰(관리자·회원·매장·pinPass) 서명 키. 운영 필수(기본값 사용 시 부팅 거부).
INTERNAL_API_KEY	입금 웹훅 인증 키. 운영 필수(기본값 사용 시 부팅 거부).
STORAGE_ENDPOINT	파일/이미지 전용 오브젝트 스토리지(S3 호환) 주소. 운영은 `https://storages.nestpay.co.kr`. 로컬 기본 `http://nestpay-storage:9000`(MinIO 컨테이너).
STORAGE_ACCESS_KEY / STORAGE_SECRET_KEY	스토리지 접근 키/비밀 키. STORAGE_SECRET_KEY 는 운영 필수(기본값 `nestpay-secret` 사용 시 부팅 거부) — 남으면 모든 파일 열람·교체·삭제 가능.
STORAGE_BUCKET	파일을 담을 버킷 이름. 기본 `nestpay-files`. 없으면 최초 업로드 때 자동 생성.
SWAGGER_ENABLED	API 문서(/swagger-ui, /v3/api-docs) 노출 여부. 기본 `true`. 운영은 반드시 `false`(내부 API 은닉).
TRUSTED_PROXIES / ADMIN_BOOTSTRAP_ALLOW	신뢰 프록시(nginx) IP, 관리자 화이트 IP 미등록 시 초기 허용 대역(첫 IP 등록 후 자동 무시).
SERVER_PORT / TZ	서버 포트(기본 `8080`), 시간대(`Asia/Seoul`).

주의 APP_CRYPTO_KEY는 환경별로 고정해야 합니다. live 키가 바뀌면 기존 암호화 데이터(카드·계좌·OTP)를 복호화할 수 없습니다. 안전한 비밀 보관소(Vault/KMS/환경파일)로 관리하세요.

운영(sandbox·live)에서 부팅 가드(SecretsGuard)가 개발 기본값을 거부하는 시크릿: DB_PASSWORD · APP_CRYPTO_KEY · ADMIN_TOKEN_SECRET · INTERNAL_API_KEY · STORAGE_SECRET_KEY. 하나라도 기본값이면 서버가 켜지지 않습니다.

3. 데이터베이스 동기화 (Flyway 마이그레이션)

DB 변경은 항상 마이그레이션 파일로만 합니다. 운영 DB를 직접 손대지 않습니다. 서버가 기동될 때 Flyway 가 밀린 마이그레이션을 순서대로 자동 적용합니다.

위치·규칙

파일: apps/api/src/main/resources/db/migration/V{번호}__{설명}.sql (예: V35__xxx.sql)
번호는 이어지는 정수로만 증가(건너뛰기·재사용 금지). 현재 최신 = V34.
이미 적용된 파일은 절대 수정하지 않습니다(체크섬 불일치로 기동 실패). 바꾸려면 새 번호로 추가.
시스템 버전 테이블(users·merchants 등) ALTER 시 파일 첫 줄에 SET @@system_versioning_alter_history = KEEP;.

승격 절차 (dev → sandbox → live)

dev 작성·검증: 로컬에서 새 V{n} 작성 → 서버 기동 → 적용·회귀검증. (스키마 정본 db/schema.dbml·db/queries.sql도 함께 갱신)
커밋·동기화: git.madeitup.kr 에 커밋(추후 페이네스트 git 으로 미러링).
sandbox 반영: sandbox 서버가 새 코드로 재기동되면 Flyway 가 자동 적용. 적용 여부 확인:
```
SELECT version, description, success, installed_on
FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;
```
QA·발주사 검증.
live 반영: 배포 전 DB 백업(mysqldump) → 운영 서버 재기동 → Flyway 자동 적용 → 위 쿼리로 success=1 확인 → 헬스체크(/health).

롤백

Flyway Community 는 자동 다운 마이그레이션이 없습니다. 되돌리는 변경은 새 마이그레이션(V{n+1})으로 앞으로 감기(forward fix).
파괴적 변경(컬럼 삭제 등)은 live 반영 전 반드시 백업. 데이터 이전이 필요한 변경은 2단계(추가→이행→제거)로 나눠 배포.

실패한 마이그레이션이 남으면(success=0) 다음 기동이 막힙니다. 원인 수정 후 실패 행 정리(DELETE FROM flyway_schema_history WHERE success=0) → 재기동. sandbox 에서 먼저 재현·해결하세요.

4. 배포 절차

확정 대기 물리 서버 분리로 접속 PC가 제한적이며, 구체 배포 방식은 계약 후 확정합니다. 아래는 현재 로컬 구성 기준의 표준 절차(확정 시 갱신).

운영 토폴로지(제공 인프라 기준)

L4(로드밸런서) 뒤에 동일 코드 2대가 붙고, DB(MariaDB) 1대와 파일 스토리지(오브젝트)를 공유합니다. 세션 어피니티는 없다고 가정 → 앱 서버는 무상태(stateless)여야 합니다.
무상태 요건은 구현으로 충족: 세션은 서버측 저장 없는 HMAC 토큰, 파일은 공유 오브젝트 스토리지(로컬 디스크 금지), 이용제한 카운터는 공유 DB, 주기 워커는 집기표식(claim token)·원자적 상태전이로 2대 동시 실행에도 중복이 없습니다.
Flyway 는 2대가 각자 실행해도 DB 락으로 안전하나, 배포는 1대 선(先)기동 후 나머지를 권장합니다.

산출물 빌드: API ./gradlew build(jar), 앱 flutter build, admin 정적 파일.
서버 이미지/컨테이너 갱신(도커 컴포즈) — docker compose up -d --build. 환경변수는 서버측 .env/시크릿으로 주입.
기동 시 Flyway 자동 적용 → /health 200 확인 → 관리자·앱 스모크 테스트.
앱은 스토어(App Store·Play) 심사 후 배포. 강제 업데이트는 관리자 전역설정의 최소버전으로 통제.

환경·배포 세부는 발주사 인프라 확정에 따라 갱신됩니다. 관련: 구현 현황 · 마이그레이션 · 요청자료.