admin/front 분리

2026-07-20 17:49:24 +09:00
parent 9269278e40
commit ed41ef24cb
673 changed files with 16782 additions and 11277 deletions
@@ -1,43 +1,80 @@
 # 설정 및 실행 가이드

-## 설정 규칙
- 공통 설정은 `application.yaml`, 환경별 차이는 `application-local.yaml`, `application-pjt.yaml` 에 둔다.
- `pjt` 프로파일은 DB/Redis/JWT/Swagger 계정을 환경변수 치환으로 받으므로 새 민감정보는 하드코딩하지 않는다.
- 로깅 설정은 프로파일별 `logback-local.xml`, `logback-pjt.xml` 을 사용하므로 로그 정책 변경 시 함께 본다.
- MyBatis 설정은 `application.yaml` 기준으로 관리하므로 mapper location, alias package, camel case 옵션을 중복 정의하지 않는다.
- Redis 는 세션 저장소와 업로드 상태 캐시 용도를 함께 가지므로 키 prefix 충돌 여부를 확인한다.
+## 설정 위치
+
+- 환경값은 각 실행 모듈의 `src/main/resources`에 둡니다.
+- 공통 설정은 `application.yaml`, 환경별 차이는 `application-local.yaml`, `application-pjt.yaml`에 둡니다.
+- admin과 front는 서로 다른 포트, 도메인, JWT 쿠키 정책, Swagger 정보, 로그 설정을 가질 수 있습니다.
+- core에는 실행 환경별 YAML을 두지 않고, 환경값을 사용하는 공통 구현과 인프라 설정만 둡니다.
+- 단순 설정값은 사용하는 클래스에서 `@Value` 필드 주입으로 읽습니다. 목록·Map·중첩 구조처럼 구조화된 설정만 `@ConfigurationProperties` 클래스로 관리합니다.

 ## 프로파일
+
 | 프로파일 | 설명 |
-|---------|------|
+|---|---|
 | `local` | 로컬 개발 환경 |
-| `pjt` | 프로젝트(개발) 환경 |
-
-## Swagger 접속
- URL: `http://localhost:8106/swagger-ui.html`
- 인증: `swagger.login.id` / `swagger.login.password` (환경별 yaml에 설정)
-
-## 파일 업로드 설정
- `tus-file.upload.final-root` 는 TUS 완료 파일과 단순 업로드 파일이 공유하는 최종 저장 루트다.
- `tus-file.upload.tmp-root` 는 tusd 임시 업로드 루트다. file-domain nginx 에서는 `/uploads/tmp/` 접근을 404로 막는다.
- `file.upload.root-path` 는 보통 `${tus-file.upload.final-root}` 를 사용해 단순 업로드와 TUS 완료 파일의 마운트 루트를 맞춘다.
- `file.upload.view.file-domain` 은 SunEditor 이미지 응답 URL 생성에 사용한다. 예: `https://file-alist.pjt.kr`.
- `file.upload.max-size` 는 단순 업로드 전역 최대 용량이다. `file.upload.types.{folder}.max-size` 가 있으면 폴더별 설정이 우선한다.
- `file.upload.allowed-extensions` 는 단순 업로드 전역 확장자 허용 목록이다.
- `file.upload.types.{key}.folder` 는 실제 저장 폴더명이다. 설정되지 않은 folder 값도 전역 정책을 통과하면 동적 폴더로 저장할 수 있다.
- `file.upload.types.{key}.image-only` 가 `true` 이면 이미지 확장자만 허용한다.
- `file.upload.types.{key}.resize.enabled` 가 `true` 이고 업로드 파일이 이미지이면 resize 함수를 거친다. `width` 와 `height` 가 모두 있으면 중앙 crop 후 고정 크기로 저장하고, `max-width` 만 있으면 비율을 유지해 축소한다.
- `spring.servlet.multipart.max-file-size` 와 `max-request-size` 는 `-1` 로 두고, 실제 제한은 업로드 서비스 정책에서 처리한다.
-
-## file-domain nginx 기준
- `/tus/file/` 는 tusd 로 프록시하며 `auth_request /_upload_auth` 로 API의 `/tus/file/upload/auth` 를 호출한다.
- `/_upload_auth` 는 내부 location 으로만 열고 `Authorization`, `X-File-Uuid`, 필요 시 `Upload-Metadata`, `Upload-Length` 헤더를 API 로 전달한다.
- `/uploads/` 는 `/srv/project/alist/uploads/` 를 정적 파일로 제공한다.
- `/uploads/tmp/` 는 tusd 임시 파일 노출을 막기 위해 404 처리한다.
- 그 외 경로는 `location /` fallback 에서 차단한다.
+| `pjt` | 프로젝트 개발 환경 |

 ## 실행 명령
- 로컬 실행: `./gradlew bootRun`
- 테스트 실행: `./gradlew test`
- jar 생성: `./gradlew bootJar`
- Windows 명령: `.\gradlew.bat bootRun`, `.\gradlew.bat test`, `.\gradlew.bat bootJar`
+
+```bash
+./gradlew :02-api-admin:bootRun --args='--spring.profiles.active=local'
+./gradlew :03-api-front:bootRun --args='--spring.profiles.active=local'
+```
+
+```bash
+./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/` 아래에서 서버별로 분리합니다.
+
+```bash
+./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/**` 경로, 최종 저장 루트, 임시 저장 루트가 일치하는지 함께 확인합니다.