IPAM Backend

IP Address Management 시스템의 백엔드 서버입니다.

기술 스택

분류	기술
Language	Java 17
Framework	Spring Boot 3.5.x
Database	MySQL 8.x (FULLTEXT 검색)
Session	Redis 7.x (Spring Session, Sentinel HA)
Auth	Keycloak (OAuth2/OIDC)
Realtime	SSE (Server-Sent Events, Redis Pub/Sub)
Docs	Swagger (springdoc-openapi)

프로젝트 구조

src/main/java/com/nhn/ipambackend/
├── domain/
│   ├── address/       # IP 주소 관리 (13종 타입, TABLE_PER_CLASS 상속)
│   ├── subnet/        # 서브넷 관리 (계층 구조, 분할/병합/VLSM)
│   ├── region/        # Region 관리
│   ├── user/          # 사용자/역할 관리 (Keycloak 연동)
│   ├── favorite/      # 즐겨찾기 (복합키)
│   ├── log/           # 감사 로그 (스냅샷 방식)
│   ├── dashboard/     # 대시보드 통계
│   ├── search/        # 통합 검색 (FULLTEXT, 키워드 타입 자동 감지)
│   ├── manage/        # 마스터 데이터 관리 (Zone, SubnetType, DynamicAddressType, ESM, Service)
│   ├── alertpanel/    # 알림 패널 (CI번호 누락 감지)
│   └── sse/           # 실시간 이벤트 (SSE + Redis Pub/Sub)
└── global/
    ├── base/          # 공통 응답, 예외 처리, 상태 코드
    ├── config/        # 설정 (Security, Redis, Async, WebClient 등)
    └── util/          # 유틸리티 (IPConverter, JsonUtil)

도메인별 패키지 구조

각 도메인은 아래와 같은 패키지 구조를 따릅니다:

domain/{도메인명}/
├── controller/    # REST API 컨트롤러
├── service/       # 비즈니스 로직 (interface + impl)
├── repository/    # JPA Repository (+ Specification/QueryDSL)
├── dto/
│   ├── request/   # 요청 DTO
│   └── response/  # 응답 DTO
├── entity/        # JPA 엔티티
└── enums/         # Enum 정의 (필요 시)

---

로컬 개발 환경 설정

1. 사전 요구사항

• Java 17
• Docker & Docker Compose
• MySQL 8.x (로컬 또는 Docker)
• Frontend 프로젝트 (../ipam-frontend)

2. /etc/hosts 설정

Keycloak 인증이 도메인 기반으로 동작하므로 hosts 파일 수정이 필요합니다.

sudo vi /etc/hosts

아래 내용 추가:

127.0.0.1 ipam.nhn.com

3. 환경 변수 설정

.env.local 파일 확인 및 수정:

FRONTEND_URL=http://ipam.nhn.com      # Frontend URL (hosts 설정 필요)
MYSQL_HOST=host.docker.internal        # Docker 내에서 로컬 MySQL 접근
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USERNAME=root
MYSQL_PASSWORD=your_password
SPRING_PROFILES_ACTIVE=local          # local 프로필 (테스트 데이터 생성)

4. 서버 실행 (Docker Compose)

# Frontend + Backend + Redis 전체 실행
docker compose --env-file .env.local up -d --build

# 로그 확인
docker compose logs -f backend

5. 서버 실행 (IDE에서 직접)

IntelliJ/VSCode에서 직접 실행 시:

1. Run Configuration에 환경변수 설정
2. 또는 application-local.yml 사용

./gradlew bootRun --args='--spring.profiles.active=local'

6. 접속 확인

서비스	URL
Frontend	http://ipam.nhn.com
Backend API	http://ipam.nhn.com/api
Swagger UI	http://ipam.nhn.com/api/swagger-ui/index.html
Health Check	http://ipam.nhn.com/api/actuator/health

---

운영 배포(prod)

Primary 서버 (Server A)

# Git pull + 테스트 + 이미지 빌드 + 서비스 시작
./deploy.sh rebuild

# 테스트 건너뛰고 배포 (급할 때)
./deploy.sh rebuild --skip-test

# 테스트만 실행
./deploy.sh test

# 서비스 상태 확인
./deploy.sh status

# 로그 확인
./deploy.sh logs

# 서비스 중지
./deploy.sh down

Secondary 서버 (Server B) - 이중화

# 이중화 모드로 배포
./deploy.sh rebuild --secondary

# 이중화 서버 상태 확인
./deploy.sh status --secondary

---

API 문서

Swagger UI: /api/swagger-ui.html

주요 엔드포인트

도메인	Base URL	주요 기능
Subnet	/api/subnets	CRUD, 분할(균등/VLSM), 병합, Supernet, Import, 맵, 사용량, 공인IP 대시보드
Address	/api/addresses	조회, 예약/취소(개별/범위), 예약 가능 여부, 동적 주소 생성
Region	/api/regions	Region CRUD
User	/api/users	역할 관리, 속성 관리, 벌크 역할 변경
Favorite	/api/favorites	서브넷 즐겨찾기 추가/제거/조회
Log	/api/logs	감사 로그 조회, CSV 내보내기
Search	/api/search	통합 검색, IP Range, ESM, 검색 기록, 메타데이터
Dashboard	/api/dashboard	대시보드 통계
Manage	/api/zones, /api/subnet-types, /api/dynamic-address-types	마스터 데이터 관리
Alert Panel	/api/alert-panel	ci_no 누락 알림
SSE	/api/sse	실시간 이벤트 스트림

테스트

# 전체 테스트
./gradlew test

# 도메인별 테스트
./gradlew test --tests "com.nhn.ipambackend.domain.subnet.*"
./gradlew test --tests "com.nhn.ipambackend.domain.address.*"
./gradlew test --tests "com.nhn.ipambackend.domain.search.*"
./gradlew test --tests "com.nhn.ipambackend.domain.favorite.*"
./gradlew test --tests "com.nhn.ipambackend.domain.region.*"
./gradlew test --tests "com.nhn.ipambackend.domain.log.*"
./gradlew test --tests "com.nhn.ipambackend.domain.dashboard.*"
./gradlew test --tests "com.nhn.ipambackend.domain.user.*"
./gradlew test --tests "com.nhn.ipambackend.domain.manage.*"

테스트 파일 목록

도메인	테스트 파일
Subnet	SubnetServiceTest, SubnetEntityTest
Address	AddressServiceTest, AddressEntityTest
Search	SearchServiceTest
Favorite	FavoriteServiceTest
Region	RegionServiceTest
Log	LogServiceTest, AuditLogServiceTest
Dashboard	DashboardServiceTest
User	UserServiceTest, RoleTest
Manage	DynamicAddressTypeServiceTest

---

Cursor 개발 규칙

.cursor/rules/ 디렉토리에 도메인별 개발 가이드가 있습니다.

파일	설명
.overview.mdc	프로젝트 전체 구조, 코딩 컨벤션
subnets.mdc	서브넷 도메인 (계층 구조, 분할/병합/VLSM, Import)
addresses.mdc	주소 도메인 (13종 타입, TABLE_PER_CLASS, 예약/취소)
search.mdc	검색 도메인 (FULLTEXT, 키워드 자동 감지, ESM)
regions.mdc	Region 도메인
logs.mdc	감사 로그 (스냅샷 방식)
favorites.mdc	즐겨찾기 (복합키)

Cursor에서 해당 도메인 파일 작업 시 자동으로 규칙이 적용됩니다.

---

환경별 프로필

프로필	용도	특징
local	로컬 개발	테스트 데이터 자동 생성, SQL 로깅
prod	운영 (Primary)	SQL 로깅 비활성화, Redis Sentinel

---

주요 설정 파일

파일	설명
.env.local	로컬 개발 환경변수
.env.prod	운영 환경변수 (Primary)
.env.secondary	운영 환경변수 (Secondary, 이중화)
docker-compose.yml	Primary: Frontend + Backend + Redis Master + Sentinel
docker-compose.secondary.yml	Secondary: 이중화 구성
deploy.sh	통합 배포 스크립트 (up, down, restart, rebuild, logs, status, test)

---

DB 마이그레이션

파일	설명
db/init.sql	초기 스키마/데이터
db/init-logs.sql	로그 테이블 초기화
db/alias.sql	검색 Alias 데이터
db/preset.sql	검색 Preset 데이터
db/migration-fulltext-search.sql	FULLTEXT 검색 인덱스 마이그레이션
db/migration-roles.sql	역할(Roles) 마이그레이션
db/migration-log-server-ip.sql	로그 서버 IP 마이그레이션
db/migration-dynamic-address-type.sql	동적 주소 타입 마이그레이션

---

문제 해결

Keycloak 인증 실패

1. /etc/hosts에 ipam.nhn.com 설정 확인
2. FRONTEND_URL이 http://ipam.nhn.com인지 확인
3. Keycloak 클라이언트 설정에서 Redirect URI 확인

Docker에서 로컬 MySQL 접근 불가

MYSQL_HOST를 host.docker.internal로 설정 (Mac/Windows)

테스트 데이터가 생성되지 않음

SPRING_PROFILES_ACTIVE=local 설정 확인