개발 환경 사전 요구사항
본 시스템을 구축하고 실행하기 위해 다음과 같은 런타임 환경 및 도구가 필수적입니다.
- 핵심 런타임 (Core Runtime):
- Java JDK 17 이상
- Apache Maven 3.8+
- MySQL Database 8.0+ (문자셋: utf8mb4)
- Redis Cache Server 5.0+
- Nacos 서버 2.2.x 버전
- 개발 도구 (Development Tools):
- IntelliJ IDEA 2022 또는 최신 버전
- 데이터베이스 클라이언트 (예: DBeaver, Navicat)
- 호스트 파일 관리 유틸리티 (예: SwitchHosts)
- Git 버전 관리 시스템
로컬 네트워크 호스트 설정
분산 시스템 아키텍처에서의 통신 안정성을 위해 로컬 호스트 파일을 수정하여 도메인 이름을 매핑해야 합니다. IP 주소를 직접 사용하는 경우 컨테이너화(Docker/K8s) 환경으로의 이관이 어려워지므로 도메인 네임을 활용하는 것을 권장합니다. VPN이나 프록시 도구는 DNS 해석을 방해할 수 있으므로 설정 과정에서는 비활성화하십시오.
# /etc/hosts (Linux/macOS) 또는 C:\Windows\System32\drivers\etc\hosts (Windows)
127.0.0.1 registry.nacos
127.0.0.1 db.mysql.primary
127.0.0.1 cache.redis
127.0.0.1 logs.kibana
소스 코드 가져오기 및 데이터베이스 초기화
프로젝트 저장소에서 소스 코드를 클론한 후 데이터베이스 스키마를 초기화해야 합니다.
# 저장소 복제
git clone https://gitee.com/elsfs/elsfs-cloud.git
# 데이터베이스 초기화 (MySQL 쉘 접속 후 실행)
# 1. 핵심 비즈니스 스키마 생성
source db/elsfs-mysql.sql;
# 2. 설정 관리 서버(Nacos)용 스키마 생성
source db/naocs-mysql.sql;
애플리케이션 설정 및 구성 수정
설정 파일 중앙화 관리를 위해 IP 주소 대신 위에서 설정한 호스트 이름을 사용합니다. 이는 서비스 간 결합도를 낮추고 환경(Dev/Staging/Prod) 간 설정 전환을 용이하게 만듭니다.
Nacos 서버 설정 (elsfs-optional-nacos 모듈)
# application.yml
db:
count: 1
user: ${DB_ACCOUNT:root} # 데이터베이스 사용자명
password: ${DB_CREDENTIAL:root} # 비밀번호 (특수문자 포함 시 반드시 따옴표 사용)
connect:
- url: jdbc:mysql://${DB_HOST:mysql}:3306/${DB_SCHEMA:nacos}?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=Asia/Shanghai
인프라 서비스 기동
설정 서버(Nacos)를 가장 먼저 시작하여 나머지 마이크로서비스들이 설정 정보를 조회할 수 있도록 합니다.
// 실행 경로: elsfs-optional/elsfs-optional-nacos/src/main/java/com/alibaba/nacos/
// 실행 클래스: NacosApplication.java
public static void main(String[] args) {
SpringApplication.run(NacosApplication.class, args);
}
미들웨어 및 보안 설정 구성
Nacos 콘솔(http://registry.nacos:8848/nacos, 기본 계정 nacos/nacos)에 접속하여 네임스페이스(elsfs-cloud) 내의 Redis 및 MySQL 연결 정보와 OAuth2 보안 설정을 갱신합니다.
Redis 및 JWT 설정 (application-dev.yml)
core:
security:
# JWT 키 쌍 설정
jwt:
keys:
- key-id: primary-key
issue-at: 2023-11-19T10:00:00.000Z
public-key-location: publicKey.pem
private-key-location: privateKey.pem
issuer-uri: http://localhost:7001
spring:
data:
redis:
index: 0
host: cache.redis
port: 6379
데이터소스 및 OAuth2 클라이언트 설정 (elsfs-cloud-starter-dev.yml)
spring:
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
username: ${DB_USER:root}
password: ${DB_PASS:root}
url: jdbc:mysql://${DB_HOST:mysql}:3306/${DB_NAME:elsfs-admin}?useUnicode=true&characterEncoding=UTF-8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
security:
oauth2:
client:
registration:
# GitHub OAuth2 연동
github-provider:
provider: github
client-id: YOUR_GITHUB_CLIENT_ID
client-secret: YOUR_GITHUB_CLIENT_SECRET
scope: user:email, read:user
# Gitee OAuth2 연동
gitee-provider:
provider: gitee
client-name: Gitee Login
client-id: YOUR_GITEE_CLIENT_ID
client-secret: YOUR_GITEE_CLIENT_SECRET
authorization-grant-type: authorization_code
redirect-uri: http://127.0.0.1:7001/login/oauth2/code/gitee
scope:
- user_info
- emails
# 내부 통신용 클라이언트
internal-client:
provider: auth-server
client-id: internal-service
client-secret: "{bcrypt}encrypted_secret_value"
client-authentication-method: client_secret_basic
authorization-grant-type: authorization_code
redirect-uri: http://admin.elsfs.test:7001/login/oauth2/code/internal
scope:
- message.read
- message.write
provider:
github:
user-name-attribute: login
gitee:
user-name-attribute: id
token-uri: https://gitee.com/oauth/token
user-info-uri: https://gitee.com/api/v5/user
authorization-uri: https://gitee.com/oauth/authorize
auth-server:
user-name-attribute: sub
issuer-uri: http://localhost:7002
시스템 시작 순서
의존성 순서를 준수하여 다음과 같은 순서로 애플리케이션을 기동합니다.
- 서비스 디스커버리:
NacosApplication.java - 인증 서버:
Oauth2ApplicationStarter.java - 관리자 포털:
AdminApplicationStarter.java