From d2d3d82f44bef0e10018c44f994da95a291115ad Mon Sep 17 00:00:00 2001 From: itms-merge-dev Date: Tue, 21 Jul 2026 19:06:17 +0900 Subject: [PATCH] =?UTF-8?q?docs(itms):=20DB=20=EB=8D=A4=ED=94=84(=EB=B0=B1?= =?UTF-8?q?=EC=97=85)=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=B6=94=EA=B0=80?= =?UTF-8?q?=20=E2=80=94=20kic=5Frel=20=EA=B8=B0=EC=A4=80=20=EC=95=B1/root?= =?UTF-8?q?=20=EA=B3=84=EC=A0=95=20mysqldump=C2=B7DBeaver?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/DB_DUMP_GUIDE.md | 112 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/DB_DUMP_GUIDE.md diff --git a/docs/DB_DUMP_GUIDE.md b/docs/DB_DUMP_GUIDE.md new file mode 100644 index 00000000..e215e088 --- /dev/null +++ b/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`로 붙이면 프로세스 목록/셸 히스토리에 노출되니 금지. + +--- + +## 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`에 **키 로테이션 권고** 기록됨 — 덤프와 별개로 자격증명 노출 관리 필요.