Initial commit: WBX Spring Framework Core

Spring Boot 3.5.0 + Java 21 기반 엔터프라이즈 프레임워크
- Auth: JWT, MFA/TOTP, OAuth2 SSO, PasswordPolicy, LoginHistory
- RBAC: Role-Permission, DeptScope, Redis 캐시
- Approval: Handler 패턴 결재 엔진
- Notification: SSE 실시간 알림
- File: Local/Azure Blob/AWS S3/GCP Storage
- DataSource: Multi-DB 라우팅 (MySQL/PG/Oracle/MSSQL)
- Admin: Thymeleaf 11화면 콘솔
- Compat: WBX FastAPI 호환 (에러/페이징)
- Flyway: 4종 DBMS 마이그레이션
- Scripts: install.bat/sh, deploy-prod.sh
- Docs: 설치가이드(OnPremise/Cloud), 개발자가이드 PDF

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
이 Commit은 다음에 포함되어 있습니다:
2026-03-25 10:27:18 +09:00
커밋 476f8a0565
121개의 변경된 파일7596개의 추가작업 그리고 0개의 파일을 삭제

215
scripts/deploy-prod.sh 일반 파일
파일 보기

@@ -0,0 +1,215 @@
#!/usr/bin/env bash
# ============================================================
# WBX Spring Core — 프로덕션 배포 스크립트 (Linux)
# 사용법: sudo ./scripts/deploy-prod.sh
# ============================================================
set -euo pipefail
# ---------- 색상 ----------
RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
ok() { echo -e " ${GREEN}[OK]${NC} $1"; }
warn() { echo -e " ${YELLOW}[WARN]${NC} $1"; }
fail() { echo -e " ${RED}[FAIL]${NC} $1"; exit 1; }
info() { echo -e " ${CYAN}[INFO]${NC} $1"; }
APP_DIR="/opt/wbx-app"
SERVICE_USER="wbxapp"
SERVICE_NAME="wbx-app"
JAR_NAME="app.jar"
echo ""
echo "=========================================="
echo " WBX Spring Core — 프로덕션 배포"
echo "=========================================="
echo ""
# ---------- Root 권한 ----------
if [ "$EUID" -ne 0 ]; then
fail "root 권한이 필요합니다: sudo $0"
fi
# ---------- 1. 서비스 계정 ----------
echo "1. 서비스 계정 (${SERVICE_USER})"
if id "$SERVICE_USER" &>/dev/null; then
ok "이미 존재"
else
useradd -r -m -s /bin/bash "$SERVICE_USER"
ok "생성 완료"
fi
# ---------- 2. 타임존/로케일 ----------
echo "2. 시스템 설정"
timedatectl set-timezone Asia/Seoul 2>/dev/null && ok "타임존: Asia/Seoul" || warn "타임존 설정 실패 — 수동 확인"
# ---------- 3. 디렉토리 ----------
echo "3. 디렉토리 구조"
mkdir -p "${APP_DIR}"/{logs,uploads,backup}
chown -R "${SERVICE_USER}:${SERVICE_USER}" "${APP_DIR}"
ok "${APP_DIR}/{logs,uploads,backup}"
# ---------- 4. 시스템 리밋 ----------
echo "4. 파일 디스크립터 리밋"
LIMITS_FILE="/etc/security/limits.d/${SERVICE_USER}.conf"
if [ ! -f "$LIMITS_FILE" ]; then
cat > "$LIMITS_FILE" << EOF
${SERVICE_USER} soft nofile 65535
${SERVICE_USER} hard nofile 65535
EOF
ok "${LIMITS_FILE} 생성"
else
ok "이미 존재"
fi
# ---------- 5. JAR 복사 ----------
echo "5. JAR 배포"
JAR_SOURCE="build/libs/wbx-spring-core-*.jar"
FOUND_JAR=$(ls $JAR_SOURCE 2>/dev/null | head -1)
if [ -z "$FOUND_JAR" ]; then
warn "JAR 파일 없음 — 먼저 ./gradlew bootJar 실행 필요"
else
# 이전 버전 백업
if [ -f "${APP_DIR}/${JAR_NAME}" ]; then
cp "${APP_DIR}/${JAR_NAME}" "${APP_DIR}/backup/${JAR_NAME}.$(date +%Y%m%d_%H%M%S)"
info "이전 JAR 백업 완료"
fi
cp "$FOUND_JAR" "${APP_DIR}/${JAR_NAME}"
chown "${SERVICE_USER}:${SERVICE_USER}" "${APP_DIR}/${JAR_NAME}"
ok "$(basename "$FOUND_JAR")${APP_DIR}/${JAR_NAME}"
fi
# ---------- 6. .env 템플릿 ----------
echo "6. 환경변수 파일"
if [ ! -f "${APP_DIR}/.env" ]; then
cat > "${APP_DIR}/.env" << 'ENVEOF'
# ===== WBX Spring Core — 프로덕션 환경변수 =====
SPRING_PROFILES_ACTIVE=prod,mysql
SERVER_CONTEXT_PATH=/
# JWT (필수 변경!)
JWT_SECRET=your-production-secret-key-minimum-256-bits-long
# DB
DB_HOST=localhost
DB_PORT=3306
DB_NAME=wbx_spring
DB_USER=wbxapp
DB_PASS=StrongP@ss
# Redis
SPRING_DATA_REDIS_HOST=localhost
# CORS
CORS_ORIGINS=https://app.company.com
# 로그
LOG_PATH=/opt/wbx-app/logs/app.log
ENVEOF
chown "${SERVICE_USER}:${SERVICE_USER}" "${APP_DIR}/.env"
chmod 600 "${APP_DIR}/.env"
ok "${APP_DIR}/.env 생성 (값을 반드시 수정하세요!)"
else
ok "이미 존재 — 건너뜀"
fi
# ---------- 7. systemd 서비스 ----------
echo "7. systemd 서비스"
SERVICE_FILE="/etc/systemd/system/${SERVICE_NAME}.service"
cat > "$SERVICE_FILE" << EOF
[Unit]
Description=WBX Spring Application
After=network.target
[Service]
Type=simple
User=${SERVICE_USER}
WorkingDirectory=${APP_DIR}
EnvironmentFile=${APP_DIR}/.env
ExecStart=/usr/bin/java \\
-XX:+UseG1GC \\
-XX:MaxRAMPercentage=75.0 \\
-Dspring.profiles.active=\${SPRING_PROFILES_ACTIVE} \\
-jar ${APP_DIR}/${JAR_NAME}
Restart=always
RestartSec=5
StandardOutput=append:${APP_DIR}/logs/app.log
StandardError=append:${APP_DIR}/logs/app.log
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable "$SERVICE_NAME" --quiet
ok "${SERVICE_FILE}"
# ---------- 8. 백업 cron ----------
echo "8. DB 백업 cron"
BACKUP_SCRIPT="${APP_DIR}/backup/db-backup.sh"
if [ ! -f "$BACKUP_SCRIPT" ]; then
cat > "$BACKUP_SCRIPT" << 'CRONEOF'
#!/usr/bin/env bash
# WBX Spring — DB 백업 (crontab: 0 2 * * *)
set -euo pipefail
source /opt/wbx-app/.env
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/opt/wbx-app/backup"
mysqldump -h"${DB_HOST}" -u"${DB_USER}" -p"${DB_PASS}" "${DB_NAME}" \
| gzip > "${BACKUP_DIR}/${DB_NAME}_${DATE}.sql.gz"
# 30일 이상 백업 삭제
find "${BACKUP_DIR}" -name '*.gz' -mtime +30 -delete
echo "[$(date)] backup done: ${DB_NAME}_${DATE}.sql.gz"
CRONEOF
chmod +x "$BACKUP_SCRIPT"
chown "${SERVICE_USER}:${SERVICE_USER}" "$BACKUP_SCRIPT"
ok "${BACKUP_SCRIPT} 생성"
# crontab 등록
CRON_LINE="0 2 * * * ${BACKUP_SCRIPT} >> ${APP_DIR}/logs/backup.log 2>&1"
(crontab -u "$SERVICE_USER" -l 2>/dev/null | grep -v "db-backup.sh"; echo "$CRON_LINE") \
| crontab -u "$SERVICE_USER" -
ok "crontab 등록 (매일 02:00)"
else
ok "이미 존재 — 건너뜀"
fi
# ---------- 9. 방화벽 ----------
echo "9. 방화벽"
if command -v firewall-cmd &>/dev/null; then
firewall-cmd --permanent --add-service=http --quiet 2>/dev/null || true
firewall-cmd --permanent --add-service=https --quiet 2>/dev/null || true
firewall-cmd --reload --quiet 2>/dev/null || true
ok "HTTP/HTTPS 허용"
else
warn "firewalld 없음 — 수동으로 방화벽 설정 필요"
fi
# ---------- 10. SELinux ----------
echo "10. SELinux"
if command -v setsebool &>/dev/null && getenforce 2>/dev/null | grep -qi enforcing; then
setsebool -P httpd_can_network_connect 1 2>/dev/null
ok "httpd_can_network_connect = 1"
else
info "SELinux 비활성 또는 미설치 — 건너뜀"
fi
# ---------- 결과 ----------
echo ""
echo "=========================================="
echo -e " ${GREEN}배포 준비 완료${NC}"
echo ""
echo " 체크리스트:"
echo " [ ] ${APP_DIR}/.env 값 수정 (JWT_SECRET, DB_PASS 필수!)"
echo " [ ] DB 생성 + 사용자 권한 부여"
echo " [ ] Redis 설치 + bind 127.0.0.1 + requirepass"
echo " [ ] JAR 빌드: ./gradlew bootJar"
echo " [ ] 서비스 시작: sudo systemctl start ${SERVICE_NAME}"
echo " [ ] 확인: curl http://localhost:8080/health"
echo " [ ] 리버스 프록시 설정 (Nginx/Caddy)"
echo " [ ] SSL 인증서 설치"
echo "=========================================="
echo ""

152
scripts/install.bat 일반 파일
파일 보기

@@ -0,0 +1,152 @@
@echo off
chcp 65001 >nul 2>&1
setlocal EnableDelayedExpansion
:: ============================================================
:: WBX Spring Core — Windows 설치 스크립트
:: 사용법: scripts\install.bat
:: ============================================================
echo.
echo ==========================================
echo WBX Spring Core — 설치 점검
echo ==========================================
echo.
set ERRORS=0
:: ---------- 1. JDK 21 ----------
echo 1. JDK 확인
where java >nul 2>&1
if %ERRORLEVEL% equ 0 (
for /f "tokens=3" %%v in ('java -version 2^>^&1 ^| findstr /i "version"') do (
set "JAVA_FULL=%%~v"
)
for /f "tokens=1 delims=." %%m in ("!JAVA_FULL!") do set "JAVA_MAJOR=%%m"
if !JAVA_MAJOR! GEQ 21 (
echo [OK] JDK !JAVA_FULL!
) else (
echo [FAIL] JDK !JAVA_FULL! — 21 이상 필요
set /a ERRORS+=1
)
) else (
echo [FAIL] java 명령어 없음 — JDK 21 설치 필요
set /a ERRORS+=1
)
:: ---------- 2. Git ----------
echo 2. Git 확인
where git >nul 2>&1
if %ERRORLEVEL% equ 0 (
for /f "delims=" %%g in ('git --version') do echo [OK] %%g
) else (
echo [FAIL] git 없음
set /a ERRORS+=1
)
:: ---------- 3. Docker (선택) ----------
echo 3. Docker 확인 (선택)
where docker >nul 2>&1
if %ERRORLEVEL% equ 0 (
for /f "delims=" %%d in ('docker --version') do echo [OK] %%d
) else (
echo [WARN] Docker 미설치 — DB/Redis를 직접 설치해야 합니다
)
:: ---------- 4. 빌드 ----------
echo 4. Gradle 빌드
if !ERRORS! GTR 0 (
echo [FAIL] 사전 요구사항 미충족 — 빌드 건너뜀
) else (
call gradlew.bat build -x test --console=plain -q
if !ERRORLEVEL! equ 0 (
echo [OK] BUILD SUCCESSFUL
) else (
echo [FAIL] 빌드 실패
set /a ERRORS+=1
)
)
:: ---------- 5. .env 템플릿 ----------
echo 5. 환경변수 파일
if not exist .env (
(
echo # ===== WBX Spring Core — 환경변수 =====
echo # 이 파일을 환경에 맞게 수정하세요.
echo.
echo # --- 프로필 ---
echo SPRING_PROFILES_ACTIVE=prod,mysql
echo.
echo # --- 서버 ---
echo SERVER_CONTEXT_PATH=/
echo.
echo # --- JWT ^(필수 변경!^) ---
echo JWT_SECRET=your-production-secret-key-minimum-256-bits-long
echo.
echo # --- DB ---
echo DB_HOST=localhost
echo DB_PORT=3306
echo DB_NAME=wbx_spring
echo DB_USER=wbxapp
echo DB_PASS=StrongP@ss
echo.
echo # --- Redis ---
echo SPRING_DATA_REDIS_HOST=localhost
echo.
echo # --- CORS ---
echo CORS_ORIGINS=https://app.company.com
echo.
echo # --- 로그 경로 ---
echo LOG_PATH=D:\wbx-app\logs\app.log
echo.
echo # --- Azure SSO ^(azure 프로필 사용 시^) ---
echo # AZURE_CLIENT_ID=
echo # AZURE_CLIENT_SECRET=
echo # AZURE_TENANT_ID=
echo.
echo # --- Azure Blob Storage ---
echo # AZURE_STORAGE_ACCOUNT=
echo # AZURE_STORAGE_KEY=
echo # AZURE_CONTAINER=uploads
echo.
echo # --- AWS Cognito ^(aws 프로필 사용 시^) ---
echo # AWS_COGNITO_CLIENT_ID=
echo # AWS_COGNITO_CLIENT_SECRET=
echo # AWS_USER_POOL_ID=
echo # AWS_REGION=ap-northeast-2
echo.
echo # --- AWS S3 ---
echo # AWS_S3_BUCKET=
echo # AWS_ACCESS_KEY=
echo # AWS_SECRET_KEY=
) > .env
echo [OK] .env 생성 완료 (값을 수정하세요)
) else (
echo [WARN] .env 이미 존재 — 건너뜀
)
:: ---------- 6. 디렉토리 ----------
echo 6. 디렉토리 생성
if not exist logs mkdir logs
if not exist uploads mkdir uploads
if not exist backup mkdir backup
echo [OK] logs\ uploads\ backup\
:: ---------- 결과 ----------
echo.
echo ==========================================
if !ERRORS! equ 0 (
echo 설치 점검 완료
echo.
echo 다음 단계:
echo 1. .env 파일을 환경에 맞게 수정
echo 2. DB 생성 (또는 docker compose -f docker-compose-dev.yml up -d)
echo 3. gradlew.bat bootRun
echo 4. http://localhost:8080/health 확인
) else (
echo 오류 !ERRORS!건 — 위의 [FAIL] 항목을 해결하세요
)
echo ==========================================
echo.
endlocal

148
scripts/install.sh 일반 파일
파일 보기

@@ -0,0 +1,148 @@
#!/usr/bin/env bash
# ============================================================
# WBX Spring Core — Linux/macOS 설치 스크립트
# 사용법: chmod +x scripts/install.sh && ./scripts/install.sh
# ============================================================
set -euo pipefail
# ---------- 색상 ----------
RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
ok() { echo -e " ${GREEN}[OK]${NC} $1"; }
warn() { echo -e " ${YELLOW}[WARN]${NC} $1"; }
fail() { echo -e " ${RED}[FAIL]${NC} $1"; }
info() { echo -e " ${CYAN}[INFO]${NC} $1"; }
ERRORS=0
echo ""
echo "=========================================="
echo " WBX Spring Core — 설치 점검"
echo "=========================================="
echo ""
# ---------- 1. JDK 21 ----------
echo "1. JDK 확인"
if command -v java &>/dev/null; then
JAVA_VER=$(java -version 2>&1 | head -1 | awk -F '"' '{print $2}' | cut -d. -f1)
if [ "$JAVA_VER" -ge 21 ] 2>/dev/null; then
ok "JDK $JAVA_VER"
else
fail "JDK $JAVA_VER (21 이상 필요)"
ERRORS=$((ERRORS + 1))
fi
else
fail "java 명령어 없음 — JDK 21 설치 필요"
ERRORS=$((ERRORS + 1))
fi
# ---------- 2. Git ----------
echo "2. Git 확인"
if command -v git &>/dev/null; then
ok "$(git --version)"
else
fail "git 없음"
ERRORS=$((ERRORS + 1))
fi
# ---------- 3. Docker (선택) ----------
echo "3. Docker 확인 (선택)"
if command -v docker &>/dev/null; then
ok "$(docker --version | head -1)"
else
warn "Docker 미설치 — DB/Redis를 직접 설치해야 합니다"
fi
# ---------- 4. 빌드 ----------
echo "4. Gradle 빌드"
if [ $ERRORS -gt 0 ]; then
fail "사전 요구사항 미충족 — 빌드 건너뜀"
else
chmod +x gradlew
if ./gradlew build -x test --console=plain -q; then
ok "BUILD SUCCESSFUL"
else
fail "빌드 실패"
ERRORS=$((ERRORS + 1))
fi
fi
# ---------- 5. .env 템플릿 ----------
echo "5. 환경변수 파일"
if [ ! -f .env ]; then
cat > .env << 'ENVEOF'
# ===== WBX Spring Core — 환경변수 =====
# 이 파일을 환경에 맞게 수정하세요.
# --- 프로필 ---
SPRING_PROFILES_ACTIVE=prod,mysql
# --- 서버 ---
SERVER_CONTEXT_PATH=/
# --- JWT (필수 변경!) ---
JWT_SECRET=your-production-secret-key-minimum-256-bits-long
# --- DB ---
DB_HOST=localhost
DB_PORT=3306
DB_NAME=wbx_spring
DB_USER=wbxapp
DB_PASS=StrongP@ss
# --- Redis ---
SPRING_DATA_REDIS_HOST=localhost
# --- CORS ---
CORS_ORIGINS=https://app.company.com
# --- 로그 경로 ---
LOG_PATH=/opt/wbx-app/logs/app.log
# --- Azure SSO (azure 프로필 사용 시) ---
# AZURE_CLIENT_ID=
# AZURE_CLIENT_SECRET=
# AZURE_TENANT_ID=
# --- Azure Blob Storage ---
# AZURE_STORAGE_ACCOUNT=
# AZURE_STORAGE_KEY=
# AZURE_CONTAINER=uploads
# --- AWS Cognito (aws 프로필 사용 시) ---
# AWS_COGNITO_CLIENT_ID=
# AWS_COGNITO_CLIENT_SECRET=
# AWS_USER_POOL_ID=
# AWS_REGION=ap-northeast-2
# --- AWS S3 ---
# AWS_S3_BUCKET=
# AWS_ACCESS_KEY=
# AWS_SECRET_KEY=
ENVEOF
chmod 600 .env
ok ".env 생성 완료 (값을 수정하세요)"
else
warn ".env 이미 존재 — 건너뜀"
fi
# ---------- 6. 디렉토리 ----------
echo "6. 디렉토리 생성"
mkdir -p logs uploads backup
ok "logs/ uploads/ backup/"
# ---------- 결과 ----------
echo ""
echo "=========================================="
if [ $ERRORS -eq 0 ]; then
echo -e " ${GREEN}설치 점검 완료${NC}"
echo ""
echo " 다음 단계:"
echo " 1. .env 파일을 환경에 맞게 수정"
echo " 2. DB 생성 (또는 docker compose -f docker-compose-dev.yml up -d)"
echo " 3. ./gradlew bootRun"
echo " 4. http://localhost:8080/health 확인"
else
echo -e " ${RED}오류 ${ERRORS}건 — 위의 [FAIL] 항목을 해결하세요${NC}"
fi
echo "=========================================="
echo ""