RepoThread Logo
RepoThread
요금제

빠른 시작

관련 소스 파일

이 페이지의 내용은 다음 소스 파일을 기반으로 생성되었습니다:

환경 요구사항

nbcio-boot 프로젝트를 실행하기 위해서는 다음 환경이 필요합니다.

필수 요구사항:

구성 요소버전용도
Docker20.10+컨테이너 실행 환경
Docker Compose2.0+멀티 컨테이너 오케스트레이션
MySQL8.0+메인 데이터베이스 (UTF8MB4 지원)
Redis5.0+캐시 및 세션 저장소
JDK1.8+Java 애플리케이션 실행

포트 요구사항:

애플리케이션은 다음 포트를 사용합니다 (docker-compose.yml:20-26, application-dev.yml:1-2):

  • 8080: 메인 애플리케이션 포트
  • 3306: MySQL 데이터베이스
  • 6379: Redis 캐시 서버

데이터베이스 문자셋 요구사항:

MySQL은 UTF8MB4 문자셋으로 구성되어야 합니다 (docker-compose.yml:13-15):

yaml
1--character-set-server=utf8mb4
2--collation-server=utf8mb4_general_ci

설치 단계

Docker Compose를 이용한 설치 (권장)

프로젝트는 로컬 개발 환경과 서버 배포 환경에 대해 서로 다른 Docker Compose 구성을 제공합니다.

1단계: 저장소 클론

bash
1git clone https://github.com/nbacheng/nbcio-boot.git
2cd nbcio-boot

2단계: 로컬 개발 환경 실행

로컬 개발용 구성은 MySQL, Redis, System 모듈을 포함합니다 (docker-compose.yml:1-42):

bash
1docker-compose up -d

이 명령은 다음 세 개의 컨테이너를 시작합니다:

컨테이너명이미지포트 매핑
nbcio-boot-mysqlnbcio-boot-mysql3306:3306
nbcio-boot-redisredis:5.06379:6379
nbcio-boot-systemnbcio-boot-system8080:8080

3단계: 서버 배포 환경 실행 (선택사항)

운영 서버 배포 시 사전 빌드된 이미지를 사용합니다 (docker-compose-server.yml:1-51):

bash
1docker-compose -f docker-compose-server.yml up -d

서버 구성에는 Nginx 리버스 프록시가 추가로 포함됩니다 (docker-compose-server.yml:46-51):

yaml
1jeecg-boot-nginx:
2  image: 81.70.17.111:5000/nginxhtml
3  ports:
4    - 80:80

수동 설치 (대안)

Docker를 사용하지 않는 경우, 각 구성 요소를 수동으로 설치할 수 있습니다.

데이터베이스 설정:

MySQL에 데이터베이스를 생성하고 초기화 스크립트를 실행합니다:

bash
1mysql -u root -p < db/nbcio-boot.sql

초기화 스크립트는 Flowable CMMN 관련 테이블을 자동으로 생성합니다 (db/nbcio-boot.sql:111-191).

애플리케이션 설정:

설정 파일에서 데이터베이스 연결 정보를 확인합니다 (application-dev.yml:1-14):

yaml
1server:
2  port: 8080
3  servlet:
4    context-path: /nbcio-boot

최소 실행 경로

가장 빠르게 애플리케이션을 실행하는 방법입니다.

bash
1# 1. Docker Compose로 모든 서비스 시작
2docker-compose up -d
3
4# 2. 서비스 상태 확인
5docker-compose ps
6
7# 3. 로그 확인
8docker-compose logs -f nbcio-boot-system

예상 결과:

모든 컨테이너가 Up 상태로 표시되어야 합니다:

NAME                  STATUS    PORTS
nbcio-boot-mysql      Up        0.0.0.0:3306->3306/tcp
nbcio-boot-redis      Up        0.0.0.0:6379->6379/tcp
nbcio-boot-system     Up        0.0.0.0:8080->8080/tcp

실행 검증

서비스 상태 확인

1단계: 컨테이너 실행 확인

bash
1docker-compose ps

세 개의 컨테이너가 모두 실행 중인지 확인합니다 (docker-compose.yml:31-42).

2단계: 애플리케이션 엔드포인트 접근

애플리케이션은 컨텍스트 경로 /nbcio-boot에서 실행됩니다 (application-dev.yml:9-10):

bash
1curl http://localhost:8080/nbcio-boot/

3단계: 데이터베이스 연결 확인

MySQL 컨테이너에 접속하여 테이블 생성을 확인합니다:

bash
1docker exec -it nbcio-boot-mysql mysql -uroot -proot

Flowable 관련 테이블이 생성되었는지 확인합니다 (db/nbcio-boot.sql:127-146):

sql
1SHOW TABLES LIKE 'act_%';

헬스 체크 (제안)

참고: 헬스 체크 엔드포인트는 소스 코드에서 명시적으로 확인되지 않았습니다. 다음은 Spring Boot 일반적인 관행입니다.

bash
1curl http://localhost:8080/nbcio-boot/actuator/health

예상 출력 (일반적인 Spring Boot 응답):

json
1{"status":"UP"}

환경 설정 및 구성

애플리케이션 포트 및 컨텍스트 경로

애플리케이션은 기본적으로 8080 포트에서 실행되며, 컨텍스트 경로는 /nbcio-boot로 설정됩니다 (application-dev.yml:1-14):

yaml
1server:
2  port: 8080
3  tomcat:
4    max-swallow-size: -1
5  servlet:
6    context-path: /nbcio-boot
7  compression:
8    enabled: true
9    min-response-size: 1024

활성 프로필은 dev로 설정되어 있습니다 (application.yml:1-6):

yaml
1spring:
2  application:
3    name: jeecg-system
4  profiles:
5    active: ${env:dev}

데이터베이스 연결 구성

MySQL 데이터베이스는 다음 설정으로 구성됩니다 (docker-compose.yml:6-19):

설정 항목값
루트 비밀번호root
문자셋utf8mb4
Collationutf8mb4_general_ci
타임존Asia/Shanghai
최대 패킷 크기128M

Redis는 인증 없이 기본 포트로 실행됩니다 (docker-compose.yml:23-29):

yaml
1nbcio-boot-redis:
2  image: redis:5.0
3  ports:
4    - 6379:6379

Docker 컨테이너 구성

로컬 개발용 구조

로컬 개발 환경은 세 개의 주요 서비스로 구성됩니다 (docker-compose.yml:1-42):

正在加载图表渲染器...

시스템 모듈은 MySQL과 Redis에 의존성을 가집니다 (docker-compose.yml:35-37):

yaml
1depends_on:
2  - nbcio-boot-mysql
3  - nbcio-boot-redis

서버 배포용 구성

서버 배포 구성은 사전 빌드된 Docker 이미지를 사용합니다 (docker-compose-server.yml:1-51):

서비스이미지 위치포트
MySQL81.70.17.111:5000/jeecg-boot-mysql:1.03306
Redisredis:5.06379
System81.70.17.111:5000/jeecg-boot-system:1.08080
Nginx81.70.17.111:5000/nginxhtml80

서버 구성에서는 설정 파일을 볼륨으로 마운트합니다 (docker-compose-server.yml:41-42):

yaml
1volumes:
2  - /data/config:/jeecg-boot/config

데이터베이스 초기화

Flowable 테이블 스키마 생성

초기화 스크립트는 Flowable CMMN(Case Management) 관련 테이블을 생성합니다 (db/nbcio-boot.sql:111-191):

주요 테이블 구조:

테이블명용도
act_app_deployment_resource앱 배포 리소스 저장
act_cmmn_casedef케이스 정의
act_cmmn_databasechangelog데이터베이스 변경 로그
act_cmmn_deploymentCMMN 배포 정보

act_cmmn_casedef 테이블은 케이스 정의의 메타데이터를 저장합니다 (db/nbcio-boot.sql:128-146):

sql
1CREATE TABLE `act_cmmn_casedef` (
2  `ID_` varchar(255) NOT NULL,
3  `REV_` int(11) NOT NULL,
4  `NAME_` varchar(255) DEFAULT NULL,
5  `KEY_` varchar(255) NOT NULL,
6  `VERSION_` int(11) NOT NULL,
7  ...
8  PRIMARY KEY (`ID_`),
9  UNIQUE KEY `ACT_IDX_CASE_DEF_UNIQ` (`KEY_`,`VERSION_`,`TENANT_ID_`)
10) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

변경 로그 및 잠금 관리

Liquibase 기반의 변경 로그 테이블이 생성됩니다 (db/nbcio-boot.sql:155-191):

sql
1CREATE TABLE `act_cmmn_databasechangelog` (
2  `ID` varchar(255) NOT NULL,
3  `AUTHOR` varchar(255) NOT NULL,
4  `FILENAME` varchar(255) NOT NULL,
5  `DATEEXECUTED` datetime NOT NULL,
6  ...
7) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

배포 잠금 테이블은 동시 배포를 방지합니다 (db/nbcio-boot.sql:195-207):

sql
1CREATE TABLE `act_cmmn_databasechangeloglock` (
2  `ID` int(11) NOT NULL,
3  `LOCKED` bit(1) NOT NULL,
4  `LOCKGRANTED` datetime DEFAULT NULL,
5  `LOCKEDBY` varchar(255) DEFAULT NULL,
6  PRIMARY KEY (`ID`)
7) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

일반적인 문제 및 해결 방법

문제 1: MySQL 연결 실패

증상: 애플리케이션 시작 시 데이터베이스 연결 오류 발생

원인: MySQL 컨테이너가 완전히 시작되기 전에 시스템 모듈이 연결을 시도

해결 방법:

  1. 컨테이너 시작 순서 확인 (docker-compose.yml:35-37):
bash
1docker-compose up -d nbcio-boot-mysql nbcio-boot-redis
2sleep 30
3docker-compose up -d nbcio-boot-system
  1. MySQL 로그 확인:
bash
1docker-compose logs nbcio-boot-mysql

문제 2: 포트 충돌

증상: port is already allocated 오류 발생

원인: 3306, 6379, 8080 포트가 이미 사용 중

해결 방법:

  1. 사용 중인 포트 확인:
bash
1# Linux/macOS
2lsof -i :8080
3lsof -i :3306
4lsof -i :6379
5
6# Windows
7netstat -ano | findstr :8080
  1. 기존 서비스 중지 또는 docker-compose.yml에서 포트 변경

문제 3: 문자셋 인코딩 오류

증상: 한글 또는 이모지 데이터 저장 시 깨짐 현상

원인: MySQL 문자셋 설정이 UTF8MB4로 구성되지 않음

해결 방법:

MySQL 컨테이너의 문자셋 설정 확인 (docker-compose.yml:13-15):

bash
1docker exec -it nbcio-boot-mysql mysql -uroot -proot -e "SHOW VARIABLES LIKE 'character%';"

올바른 출력:

character_set_server    | utf8mb4
collation_server        | utf8mb4_general_ci

문제 4: Redis 연결 타임아웃

증상: 캐시 연결 실패 메시지

원인: Redis 컨테이너가 준비되지 않음

해결 방법:

Redis 연결 테스트:

bash
1docker exec -it nbcio-boot-redis redis-cli ping

예상 응답: PONG

다음 단계

빠른 시작을 완료한 후, 다음 단계를 권장합니다:

  1. 사용자 가이드 확인: 애플리케이션의 주요 기능과 워크플로우 사용법 학습
  2. API 문서 검토: REST API 엔드포인트 및 요청/응답 구조 이해
  3. Flowable 워크플로우 설정: 비즈니스 프로세스 자동화를 위한 워크플로우 정의
  4. 보안 설정 강화: 운영 환경 배포 전 데이터베이스 비밀번호 및 Redis 인증 설정 변경

참고: 운영 환경 배포 시 docker-compose-server.yml 구성을 사용하며, 이미지를 프라이빗 레지스트리에 업로드해야 합니다 (docker-compose-server.yml:1-10).