api2/docs/runtime-config.md

설정 및 실행 가이드

설정 위치

• 환경값은 각 실행 모듈의 src/main/resources에 둡니다.
• 공통 설정은 application.yaml, 환경별 차이는 application-local.yaml, application-pjt.yaml에 둡니다.
• admin과 front는 서로 다른 포트, 도메인, JWT 쿠키 정책, Swagger 정보, 로그 설정을 가질 수 있습니다.
• core에는 실행 환경별 YAML을 두지 않고, 환경값을 사용하는 공통 구현과 인프라 설정만 둡니다.
• 단순 설정값은 사용하는 클래스에서 @Value 필드 주입으로 읽습니다. 목록·Map·중첩 구조처럼 구조화된 설정만 @ConfigurationProperties 클래스로 관리합니다.

프로파일

프로파일	설명
local	로컬 개발 환경
pjt	프로젝트 개발 환경

실행 명령

./gradlew :02-api-admin:bootRun --args='--spring.profiles.active=local'
./gradlew :03-api-front:bootRun --args='--spring.profiles.active=local'

./gradlew :02-api-admin:bootJar
./gradlew :03-api-front:bootJar

Docker 배포

• admin과 front는 각각 독립 JAR와 Docker 이미지를 사용합니다.
• admin Dockerfile은 02-api-admin/Dockerfile, front Dockerfile은 03-api-front/Dockerfile에 둡니다.
• Compose는 deploy/pjt/compose/ 아래에서 서버별로 분리합니다.

./gradlew :02-api-admin:bootJar
docker build -t registry.pjt.kr/alist/api-admin:${IMAGE_TAG} 02-api-admin

./gradlew :03-api-front:bootJar
docker build -t registry.pjt.kr/alist/api-front:${IMAGE_TAG} 03-api-front

구분	Admin	Front
Compose	api-admin-compose.pjt.yml	api-front-compose.pjt.yml
컨테이너 포트	8111	8112
환경파일	/srv/project/alist/env/api-admin/.env	/srv/project/alist/env/api-front/.env
로그 파일	/srv/project/alist/logs/api-admin/app/api-admin.log	/srv/project/alist/logs/api-front/app/api-front.log

두 서버 모두 파일 저장 경로를 공유해야 하므로 /srv/project/alist/uploads를 같은 컨테이너 경로로 마운트합니다.

Jenkins 배포

• 루트 Jenkinsfile.pjt는 프로젝트 환경 배포용이며, TARGET 파라미터로 admin, front, all을 선택합니다.
• 선택한 대상만 Gradle bootJar, Docker image build/push, 원격 Compose 배포를 수행합니다.
• admin과 front는 서로 다른 Compose project(alist-api-admin, alist-api-front)로 실행하므로 한쪽 배포가 다른 서버 컨테이너를 내리지 않습니다.
• Jenkins 서버에는 registry-pjt, ssh-pjt credential이 필요합니다.

Swagger

• admin: http://localhost:8111/swagger-ui.html
• front: http://localhost:8112/swagger-ui.html
• 인증 정보는 각 모듈 환경 설정의 swagger.login.id, swagger.login.password를 사용합니다.

MyBatis와 리소스

• main Mapper XML은 01-api-core/src/main/resources/mapper/standard/**/*.xml 또는 mapper/bespoke/**/*.xml에 둡니다.
• MainDataSourceConfig가 위 두 경로만 명시적으로 스캔합니다. admin/front YAML의 MyBatis 공통 속성보다 core의 MainDataSourceConfig 설정을 기준으로 확인합니다.
• migration Mapper XML은 01-api-core/src/main/resources/mapper/migration/**에 두며, migration 전용 SqlSessionFactory가 classpath*: 기준으로 로드합니다. main DataSource 스캔 대상은 아닙니다.
• migration DataSource는 front의 migration.datasource.alist.enabled, migration.datasource.eltown.enabled가 true인 경우에만 활성화합니다. admin YAML에는 migration 설정을 두지 않습니다.
• Mapper Java 인터페이스, 내부 DTO/VO, XML namespace와 XML id는 core 업무 모듈 이관 시 함께 이동합니다.

파일 업로드와 TUS

• 공통 저장 루트와 파일 조회 도메인은 file.storage.root-path, file.storage.view-domain으로 관리하며 admin/front 양쪽에 둡니다.
• 단순 파일 업로드의 확장자, 크기, 타입별 정책은 file.upload.*으로 관리합니다.
• TUS 설정(tus-file.upload.*)은 TUS를 실행하는 admin 서버에만 둡니다. Front YAML에는 두지 않습니다.
• TUS 완료 파일은 file.storage.root-path 아래로 이동하고, tusd 임시 파일은 tus-file.upload.tmp-root 아래에 둡니다.
• file-domain nginx와 tusd 설정은 /tus/file/** 경로, 최종 저장 루트, 임시 저장 루트가 일치하는지 함께 확인합니다.