sdw086/api2

Fork 0

Files

T

sdw086 4b65caee2b [api] md 파일 갱신

2026-05-28 15:05:43 +09:00

9.4 KiB

Raw Blame History

alist API

Spring Boot 3 기반의 alist 백엔드 API 서버입니다.

프로젝트 개요

그룹: com.alist
Java: 21
Spring Boot: 3.5.10
기본 포트: 8106
실행 진입점: src/main/java/com/alist/api/ApiApplication.java
빌드 결과물: build/libs/api.jar

기술 스택

Spring Web
Spring Security
JWT (jjwt 0.11.5)
Spring Session + Redis
MyBatis (mapper/**/*.xml)
MariaDB
Swagger / OpenAPI (springdoc-openapi 2.8.0)
Validation
Actuator
Lombok
log4jdbc

주요 기능

사용자/관리자 JWT 발급 및 검증
Redis 기반 SSO 세션 관리와 쿠키 설정
Swagger UI Basic 인증 보호
DB 기반 허용 Origin 캐시를 사용하는 동적 CORS
TUS 기반 대용량 파일 업로드 초기화, 권한 검증, 상태 조회, hook 처리, 취소 처리
DB 기록 없는 단순 파일 업로드와 uploadPath 반환
SunEditor 이미지 업로드와 file-domain URL 반환
파일 view/download API
공통 응답 래퍼 ApiResponse<T> 및 ApiResponseCode 사용

디렉터리 구조

src/main/java/com/alist/api
├── common
│   ├── response          # ApiResponse, ApiResponseCode
│   └── utils             # 공통 유틸리티
├── config
│   ├── cache             # CORS 허용 Origin 캐시
│   ├── exception         # 전역 예외 처리
│   ├── filter            # DynamicCorsFilter
│   ├── jwt               # JWT 인증 관련 구성
│   ├── migration         # 마이그레이션 DB 설정
│   └── properties        # 설정 프로퍼티
└── modules
    ├── admin             # 관리자 인증/회원/스케줄/SSO 클라이언트 관리 API
    ├── cors              # DB 기반 허용 Origin 관리와 캐시 갱신 API
    ├── file              # 단순 업로드, SunEditor 업로드, path 기반 view/download
    ├── front             # 사용자 인증/SSO API와 사용자 관리 API
    ├── main              # 루트 응답
    ├── migration         # 레거시 사용자 조회
    ├── tusFile           # TUS 업로드 DB 기록, hook, 상태, 파일 목록/view/download/delete

리소스 파일은 아래 위치를 사용합니다.

설정: src/main/resources/application*.yaml
Mapper XML: src/main/resources/mapper/**/*.xml
로그 설정: src/main/resources/logback-*.xml
상세 문서: docs/*.md

실행 방법

빌드

./gradlew bootJar

로컬 실행

./gradlew bootRun --args='--spring.profiles.active=local'

JAR 실행

java -jar build/libs/api.jar --spring.profiles.active=local

Windows:

.\gradlew.bat bootRun --args='--spring.profiles.active=local'

프로파일

프로파일	설명	설정 파일
`local`	로컬 개발 환경	`src/main/resources/application-local.yaml`
`pjt`	프로젝트 개발 서버 환경	`src/main/resources/application-pjt.yaml`

공통 설정은 src/main/resources/application.yaml에 있습니다.

필수 설정 항목

데이터 저장소

spring.datasource.*
spring.data.redis.*
spring.session.*

인증/보안

jwt.secret
jwt.access-token-validity-seconds
jwt.refresh-token-validity-seconds
cookie.secure
cookie.domain
cookie.name
cookie.same-site
swagger.login.id
swagger.login.password

TUS 업로드

tus-file.upload.tus-endpoint
tus-file.upload.public-base-url
tus-file.upload.tmp-root
tus-file.upload.final-root
tus-file.upload.interrupt-seconds
tus-file.upload.auth-cache.ttl-seconds

단순 업로드 / 에디터 이미지

file.upload.root-path
file.upload.view.file-domain
file.upload.max-size
file.upload.allowed-extensions
file.upload.types.*

pjt 프로파일은 DB/Redis/JWT/Swagger 값을 환경변수로 주입받도록 작성되어 있습니다.

보안 구조

Swagger

보호 경로: /v3/api-docs/**, /swagger-ui/**, /swagger-ui.html
인증 방식: HTTP Basic
계정 정보: swagger.login.id, swagger.login.password

Admin API

/admin/** 는 별도 SecurityFilterChain을 사용합니다.
/admin/auth/**, /admin/user/add 는 공개하고, 그 외 /admin/** 는 ADMIN 권한을 요구합니다.
GET /admin/auth/loginChecked 는 토큰 재발급 없이 현재 관리자 로그인 상태만 확인합니다.

API

기본 인증 방식: JWT Bearer 또는 HttpOnly 쿠키 fallback
세션 저장소: Redis
쿠키 속성: cookie.* 설정으로 제어

공개 경로

/
/actuator/health
/sso/**
/auth/**
/user/add
/user/migration/list
/tus/file/upload/auth
/tus/file/hook
/file/**

TUS 업로드 토큰은 일반 access token이 아니므로 /tus/file/upload/auth, /tus/file/hook 은 file-domain nginx auth_request 설정과 Spring Security 공개 경로를 함께 맞춰야 합니다.

CORS

DynamicCorsFilter가 최우선 필터로 동작하며, 허용 Origin 목록은 CorsCache에서 조회합니다.

허용된 Origin에만 Access-Control-Allow-Origin 설정
Credential 허용
OPTIONS preflight 요청은 200 OK로 즉시 응답
DB를 직접 매 요청마다 조회하지 않고 캐시된 목록을 사용

file-domain nginx 의 TUS 업로드 경로는 별도 map $http_origin $cors_allow_origin 설정으로 허용 Origin을 제한합니다.

파일 업로드

파일 업로드는 두 흐름으로 분리되어 있습니다.

단순 업로드

DB에 기록하지 않고 파일만 저장한 뒤 업무 테이블에 저장하기 좋은 값을 반환합니다.

POST /file/upload
GET /file/view?path=/uploads/...
GET /file/download?path=/uploads/...

응답 데이터 예시:

{
  "uploadPath": "/uploads/notice/2026/05/08/abc.png",
  "originalFileName": "sample.png",
  "storedFileName": "abc.png",
  "fileExtension": "png",
  "contentType": "image/png",
  "fileSize": 12345,
  "width": 800,
  "height": 600
}

SunEditor 이미지 업로드

SunEditor 업로드는 API로 저장하되, 에디터 본문에는 token이 필요 없는 file-domain URL을 저장합니다.

POST /file/suneditor/upload

응답 예시:

{
  "result": [
    {
      "url": "https://file-alist.pjt.kr/uploads/editor/2026/05/08/abc.png",
      "name": "sample.png",
      "size": 12345
    }
  ]
}

TUS 업로드

대용량 업로드는 tusd와 연동하며 API는 DB 기록, 토큰 발급, 권한 검증, hook 반영을 담당합니다.

POST /tus/file/upload/init
GET /tus/file/upload/auth
POST /tus/file/upload/status
POST /tus/file/hook
POST /tus/file/upload/cancel
GET /tus/file/list/{fileMasterIdx}
GET /tus/file/view/{fileUuid}
GET /tus/file/download/{fileUuid}
POST /tus/file/delete

운영 TUS 엔드포인트:

https://file-alist.pjt.kr/tus/file/

file-domain 운영 메모

업로드 최종 경로: /srv/project/alist/uploads
tusd 임시 경로: /srv/project/alist/uploads/tmp
파일 도메인: https://file-alist.pjt.kr
nginx /uploads/ 는 /srv/project/alist/uploads/ 를 정적 파일로 제공합니다.
nginx /uploads/tmp/ 는 임시 파일 노출 방지를 위해 404 처리합니다.
nginx /tus/file/ 는 tusd로 프록시하고 auth_request /_upload_auth 로 /tus/file/upload/auth 를 호출합니다.

주요 인증 엔드포인트

POST /auth/token
POST /auth/access
POST /auth/refresh
POST /auth/apiKeyLogin
GET /sso/loginChecked
POST /sso/login
POST /sso/exchange
POST /sso/logout
POST /admin/auth/login
POST /admin/auth/refresh
GET /admin/auth/loginChecked
POST /admin/auth/logout
POST /user/add
POST /user/migration/list

Actuator

외부 노출 대상은 아래와 같습니다.

health
info
metrics

헬스체크 기본 경로:

GET /actuator/health

응답 규칙

모든 API 응답은 ApiResponse<T> 래퍼를 우선 사용하며, 상태/메시지는 ApiResponseCode enum으로 관리합니다.

자주 사용하는 코드 예시는 아래와 같습니다.

코드	HTTP Status	의미
`CODE_200`	`200 OK`	일반 성공
`CODE_204`	`204 No Content`	일반 성공
`CODE_2001`	`200 OK`	단건 조회 성공
`CODE_2002`	`201 Created`	등록 성공
`CODE_2003`	`200 OK`	조회 결과 없음
`CODE_2004`	`409 Conflict`	중복 데이터
`CODE_4001`	`400 Bad Request`	입력값/바인딩 오류
`CODE_4003`	`400 Bad Request`	필수 파라미터 누락
`CODE_401`	`401 Unauthorized`	인증 필요
`CODE_403`	`403 Forbidden`	권한 없음
`CODE_500`	`500 Internal Server Error`	서버 오류

파일 binary view/download 응답은 ResponseEntity<Resource> 로 직접 내려줄 수 있습니다.

배포 관련

Dockerfile: Dockerfile
Jenkins 파이프라인: Jenkinsfile.pjt
배포 스크립트: deploy/
개발 서버 API 도메인: https://api-alist.pjt.kr
파일 도메인: https://file-alist.pjt.kr
Swagger: https://api-alist.pjt.kr/swagger-ui/index.html

상세 문서

라이선스

Proprietary

9.4 KiB Raw Blame History

alist API

프로젝트 개요

기술 스택

주요 기능

디렉터리 구조

실행 방법

빌드

로컬 실행

JAR 실행

프로파일

필수 설정 항목

데이터 저장소

인증/보안

TUS 업로드

단순 업로드 / 에디터 이미지

보안 구조

Swagger

Admin API

API

공개 경로

CORS

파일 업로드

단순 업로드

SunEditor 이미지 업로드

TUS 업로드

file-domain 운영 메모

주요 인증 엔드포인트

Actuator

응답 규칙

배포 관련

상세 문서

라이선스

9.4 KiB

Raw Blame History