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 접속 정보(계정 `nestpay_app`). live/sandbox 는 강한 비밀번호 필수(기본 `nestpay` 사용 시 부팅 거부).
DB_MIGRATION_USER / DB_MIGRATION_PASSWORD	표를 만들고 바꿀 때만 쓰는 별도 계정(`nestpay_mig`). Flyway 가 이 계정으로 접속합니다. 넣지 않으면 `DB_USER` 를 그대로 사용(로컬 개발 기본). 운영은 반드시 분리 — 서비스 계정에 표 삭제 권한이 남으면 프로그램 실수 하나로 장부가 사라질 수 있습니다.
APP_CRYPTO_KEY	민감정보(_enc) 암호화 키. 운영 필수(기본값 사용 시 부팅 거부). 환경마다 다르게, 절대 유출 금지·분실 시 복호화 불가.*
ADMIN_TOKEN_SECRET	토큰(관리자·회원·매장·pinPass) 서명 키. 운영 필수(기본값 사용 시 부팅 거부).
INTERNAL_API_KEY	입금 웹훅 인증 키. 운영 필수(기본값 사용 시 부팅 거부).
`STORAGE_DIR`	파일·이미지 실물을 두는 폴더. 두 WAS 가 같은 폴더를 바라봐야 합니다(WAS #1 의 폴더를 WAS #2 가 마운트 — 발주사 확정 2026-08-11). 기본 `/data/uploads`. 서버가 켜질 때 이 폴더에 쓸 수 있는지 확인하고, 못 쓰면 부팅을 멈춥니다 (마운트가 빠진 채 서비스가 열려 파일이 사라지는 사고 방지).
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. 하나라도 기본값이면 서버가 켜지지 않습니다.

3. 새 서버 최초 구축 (데이터베이스 초기 배포)

테스트·운영 서버에 DB 를 처음 올릴 때의 절차입니다. 스크립트는 저장소 paynest-v1/db/deploy/ 에 있으며, 상세 설명은 같은 폴더의 README.md 를 보세요.

실행 순서

순서	작업	내용
①	01_create_database_and_accounts.sql	데이터베이스(utf8mb4 · utf8mb4_unicode_ci)와 계정 3개를 만들고 DB 단위 권한을 줍니다. 앱을 켜기 전, DB 관리자(root)로 실행.
②	my.cnf 설정 후 DB 재시작	`event_scheduler=ON`(보존기간 자동 정리) · `default_time_zone='+09:00'`(KST 단일 기준).
③	환경변수 주입 후 앱 기동	Flyway 가 V1 부터 순서대로 표를 전부 만들고, 기초 데이터(은행 목록·시스템 지갑·약관·정책 등)까지 넣습니다.
④	02_grant_table_privileges.sql	표별 권한(고치기·지우기)을 줍니다. 표가 생긴 뒤라야 줄 수 있습니다(없는 표에 GRANT 하면 ERROR 1146). 표가 늘어나는 배포마다 다시 실행.
⑤	03_post_deploy_check.sql	11개 항목을 자동 점검해 OK / 확인필요로 보여 줍니다. 전부 OK 여야 서비스를 엽니다.

표를 만드는 큰 SQL 파일을 따로 두지 않습니다. 마이그레이션 파일이 유일한 정본이며, 같은 내용을 두 곳에 두면 한쪽을 잊는 순간 서버마다 구조가 달라집니다. 새 서버도 같은 마이그레이션을 처음부터 돌려 만듭니다.

계정 3개와 권한 설계

계정	할 수 있는 일	못 하는 일
nestpay_mig	표 만들기·바꾸기, 트리거·이벤트 등록 (Flyway 전용)	—
nestpay_app	모든 표 읽기·추가, 업무 표 60개 고치기, 지정된 표 20개 지우기	표 만들기·지우기(DDL), 증거 표 9개 고치기, 그 밖의 표 지우기
nestpay_ro	모든 표 읽기 (조사·통계·감사)	그 외 전부

증거 표 9개 — ledger_entries · audit_logs · pii_access_logs · login_histories · reject_logs · external_api_logs · app_error_logs · lot_allocations · policy_agreements. 이 중 6개는 DB 안의 방어 트리거로도 막혀 두 겹입니다.

접속 주소는 '%'(어디서든)가 아니라 API 서버 2대의 IP로 묶습니다. 비밀번호가 새어도 그 두 곳에서만 붙을 수 있습니다.

실측 검증 결과

순정 MariaDB 10.3(기본 문자셋 latin1)에 ① 을 돌리고 앱을 켠 결과 V1~V70 이 70/70 성공(1.7초), 표 70개 전부 utf8mb4_unicode_ci.
제한 계정으로 앱을 띄워 실제 QR 결제 1,000원이 정상 처리되고 차변=대변이 맞음을 확인.
방어 동작 확인 — UPDATE ledger_entries · DELETE audit_logs · DELETE transactions · CREATE TABLE 은 모두 ERROR 1142 로 거부, 업무 표 수정은 정상.
③ 점검 결과: 트리거 14개 · 자동 정리 작업 2개 · 기초 데이터 10종 전부 OK.
※ V71 적용 후에는 트리거 15개(pg_api_logs append-only 추가).

운영 전 필수 초기 관리자(root·admin) 비밀번호는 소스에 공개된 123456 입니다. 관리자 화면을 방화벽으로 막아 둔 상태에서 담당자가 첫 로그인·OTP 등록·비밀번호 변경을 끝낸 뒤 외부에 여세요. 또한 입금 통장은 예시 값, 출금 통장은 비어 있습니다 — 실제 운영 계좌로 등록해야 합니다.

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

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

위치·규칙

파일: apps/api/src/main/resources/db/migration/V{번호}__{설명}.sql (예: V35__xxx.sql)
번호는 이어지는 정수로만 증가(건너뛰기·재사용 금지). 현재 최신 버전은 저장소의 db/migration/ 마지막 파일 또는 아래 확인 쿼리로 봅니다(문서에 숫자를 고정하지 않음 — 계속 늘어남).
이미 적용된 파일은 절대 수정하지 않습니다(체크섬 불일치로 기동 실패). 바꾸려면 새 번호로 추가.
시스템 버전 테이블(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 에서 먼저 재현·해결하세요.

5. 배포 절차

확정 대기 물리 서버 분리로 접속 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) 심사 후 배포. 강제 업데이트는 관리자 전역설정의 최소버전으로 통제.

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