docs(itms): DB 덤프(백업) 가이드 추가 — kic_rel 기준 앱/root 계정 mysqldump·DBeaver

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/DB_DUMP_GUIDE.md

@@ -0,0 +1,112 @@
+# ITMS DB 덤프(백업) 가이드
+
+> 최종 갱신: 2026-07-21 | 분류: **대외비** — 무단 배포 금지
+> **보안 불변**: 이 문서에 **비밀번호·AES 암호문·DB root 비번을 기재하지 않는다.** 실값은 서버 시크릿·키스토어·DBA에게서만 조달.
+> 대상 예시는 **KIC 운영 프로파일(`application-kic_rel.yml`)** 기준. 다른 프로파일은 호스트/DB명만 바꿔 동일 적용.
+
+---
+
+## 0. 대상 DB 요약
+
+| 항목 | 값 | 출처 |
+|------|-----|------|
+| 엔진 | MariaDB | `application-kic_rel.yml` |
+| Host / Port | `192.10.10.203` / `3306` | (KIC **기관 내부망**) |
+| DB명 | `ur_itms_rel_db` | primarydb.jdbcUrl |
+| 앱 계정 | yml에 AES-256-CBC 암호문 | `primarydb.username` / `primarydb.password` |
+| 복호 키 | `api/src/main/resources/secrets/UrpSystem.keystore` 의 `aes256.key` (IV=키 앞 16바이트) | `Aes256Cipher` |
+
+- `192.10.10.203`은 **KIC 기관 내부망** 주소 → **KIC 망에 VPN/터널로 접근 가능한 위치에서만** 덤프 가능.
+- 개발서버 로컬 DB(`ur_itms_db`@101.79.17.164)와는 **다른 DB**임에 주의.
+- ⚠ front 모듈만 키스토어가 다름(`UrpSysKeyMng.keystore`). api/batch/datatrans는 공용 `UrpSystem.keystore`.
+
+---
+
+## 1. 앱 계정으로 덤프
+
+### 1-A. DBeaver
+
+1. 새 연결 → **MariaDB**
+2. **Main 탭**: Host `192.10.10.203`, Port `3306`, Database `ur_itms_rel_db`, User/Password = 복호화한 앱 계정 값
+   - KIC 망 직접 접근 불가 시 **SSH 탭**에서 경유 점프 호스트를 터널로 지정
+3. **Test Connection** 으로 확인
+4. 좌측 트리 `ur_itms_rel_db` 우클릭 → **Tools → Dump database**
+5. 옵션: **Add routines / Add triggers 체크** (레거시에 `PROC_APPROVAL`·`FUNC_HOLIDAYS` 등 존재) → 출력 파일 지정 → **Start**
+
+> DBeaver는 로컬 PC에 설치된 `mysqldump`(또는 MariaDB `mariadb-dump`) 실행 파일을 호출한다. 없으면 MariaDB 클라이언트 설치 후 연결 설정의 **Local Client** 경로 지정.
+
+### 1-B. 서버/CLI (KIC 망 접근 가능한 호스트)
+
+```bash
+mysqldump -h 192.10.10.203 -P 3306 -u <앱계정> -p \
+  --single-transaction --routines --triggers --events \
+  --default-character-set=utf8mb4 \
+  ur_itms_rel_db | gzip > ur_itms_rel_db_$(date +%Y%m%d).sql.gz
+```
+
+- `-p` **프롬프트**에 비번 입력. `-p<pw>`로 붙이면 프로세스 목록/셸 히스토리에 노출되니 금지.
+
+---
+
+## 2. root 계정으로 덤프
+
+앱 계정은 특정 DB에만 권한이 있을 수 있으나 **MariaDB root**는 전권이라 프로시저·트리거·이벤트까지 확실히 받는다.
+
+### 2-A. DB 서버에 SSH 로그인 후 로컬 실행 (권장·가장 확실)
+
+```bash
+# DB 서버 안에서 (localhost 접속 → 네트워크 이슈 없음)
+mysqldump -u root -p \
+  --single-transaction --routines --triggers --events \
+  --default-character-set=utf8mb4 \
+  ur_itms_rel_db | gzip > /tmp/ur_itms_rel_db_$(date +%Y%m%d).sql.gz
+```
+
+로컬로 가져오기:
+
+```bash
+scp <계정>@192.10.10.203:/tmp/ur_itms_rel_db_20260721.sql.gz .
+```
+
+### 2-B. 원격에서 root로 직접 접속
+
+```bash
+mysqldump -h 192.10.10.203 -P 3306 -u root -p \
+  --single-transaction --routines --triggers --events \
+  --default-character-set=utf8mb4 \
+  ur_itms_rel_db | gzip > ur_itms_rel_db_$(date +%Y%m%d).sql.gz
+```
+
+- ⚠ MariaDB root는 보통 `root@localhost`(unix_socket/localhost 한정)로만 열려 원격 접속이 막힌 경우가 많다. `Access denied for user 'root'@'<내IP>'` 발생 시 **2-A(서버 로컬 실행)** 또는 **앱 계정**으로 전환.
+
+### 2-C. DBeaver에서 root
+
+1. 연결 편집 → User `root`, Password = **MariaDB root 비번**
+2. `ur_itms_rel_db` 우클릭 → **Tools → Dump database** → Add routines/triggers 체크 → **Start**
+
+---
+
+## 3. 자주 쓰는 변형 옵션
+
+| 목적 | 옵션 |
+|------|------|
+| 스키마만(데이터 제외) | `--no-data` |
+| 데이터만(DDL 제외) | `--no-create-info` |
+| 특정 테이블만 | `... ur_itms_rel_db TABLE1 TABLE2` |
+| 특정 테이블 제외 | `--ignore-table=ur_itms_rel_db.TABLE` |
+| MyISAM 정합성 | `--single-transaction`은 InnoDB 전용. MyISAM 섞이면 서비스 정지 또는 `--lock-tables` 검토 |
+
+**복원(참고)**
+
+```bash
+gunzip < ur_itms_rel_db_20260721.sql.gz | mysql -u root -p ur_itms_rel_db
+```
+
+---
+
+## 4. 비밀번호/자격증명 조달
+
+- **앱 계정 비번**: `application-kic_rel.yml`의 AES-256-CBC 암호문 → `UrpSystem.keystore`의 `aes256.key`로 복호. **이 문서·커밋·로그에 평문 기재 금지.**
+- **MariaDB root 비번**: yml/키스토어에 없음 → **KIC DB 서버 관리자(DBA) 또는 서버 시크릿**에서 조달.
+- **OS root SSH**: DB root(계정)와 별개. GUARDiA 보안 규칙상 기관 서버는 root SSH 직접 접속 금지(opsagent 계정 사용) — KIC 서버 정책 준수.
+- 참고: 이 프로파일에는 Gmail 발송 계정 비번도 암호문으로 포함. `DB_CONNECTIONS.md`에 **키 로테이션 권고** 기록됨 — 덤프와 별개로 자격증명 노출 관리 필요.