sdw086/api2

Fork 0

Files

T

sdw086 9da2585f29 [API] SSO 다중 도메인 로그인 작업 커밋

2026-03-31 17:46:33 +09:00

8.7 KiB

Raw Blame History

alist API

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

프로젝트 개요

그룹: com.alist
Java: 21
Spring Boot: 3.5.10
포트: 8106
빌드 결과물: 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 기반 세션 관리와 쿠키 설정
Swagger UI Basic 인증 보호
DB 기반 허용 Origin 캐시를 사용하는 동적 CORS
TUS 업로드 초기화, 권한 검증, 상태 조회, 완료 처리, 취소 처리
파일 조회/다운로드 API
공통 응답 래퍼 ApiResponse<T> 및 ApiResponseCode 사용

디렉터리 구조

src/main/java/com/alist/api
├── common
│   ├── modules/file      # 공통 파일 업로드/다운로드 모듈
│   ├── response          # ApiResponse, ApiResponseCode
│   └── utils             # 공통 유틸리티
├── config
│   ├── cache             # CORS 허용 Origin 캐시
│   ├── exception         # 전역 예외 처리
│   ├── filter            # DynamicCorsFilter
│   ├── jwt               # JWT 인증 관련 구성
│   └── properties        # 설정 프로퍼티
└── modules
    ├── auth              # 인증/세션 관련 API
    ├── main              # 루트 리다이렉트

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

설정: src/main/resources/application*.yaml
Mapper XML: src/main/resources/mapper/**/*.xml
로그 설정: src/main/resources/logback-*.xml

실행 방법

빌드

./gradlew bootJar

로컬 실행

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

JAR 실행

java -jar build/libs/api.jar --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

파일 업로드

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

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

보안 구조

Swagger

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

API

기본 인증 방식: JWT Bearer
세션 저장소: Redis
세션 쿠키: RedisSessionConfig에서 도메인, Secure, SameSite 제어

공개 경로

/
/actuator/health
/auth/**
/files/tusHook

루트 / 요청은 /swagger-ui/index.html로 리다이렉트됩니다.

CORS

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

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

파일 업로드/다운로드

이 프로젝트는 대용량 업로드를 위해 TUS 서버(tusd)와 연동합니다. API는 업로드 메타데이터 관리, 업로드 권한 검증, 상태 저장, 완료/취소 처리를 담당합니다.

주요 업로드 엔드포인트

POST /files/uploadInit
GET /files/uploadAuth
POST /files/uploadStatus
POST /files/tusHook
POST /files/uploadCancel

파일 조회 엔드포인트

GET /files/list/{fileMasterIdx}
GET /files/view/{fileUuid}
GET /files/download/{fileUuid}

운영 메모

TUS 업로드 엔드포인트: https://file-alist.pjt.kr/tus/files/
업로드 임시 경로: /srv/project/alist/uploads/tmp
업로드 최종 경로: /srv/project/alist/uploads
정적 파일 도메인: https://file-alist.pjt.kr

주요 인증 엔드포인트

POST /auth/token
POST /auth/refresh
GET /auth/loginChecked
POST /auth/logout
POST /user/signup

API 예시 요청/응답

아래 예시는 실제 컨트롤러의 요청 필드와 ApiResponse<T> 응답 구조를 기준으로 정리했습니다.

1. 토큰 발급

요청:

POST /auth/token
Content-Type: application/json

{
  "id": "test"
}

응답 예시:

{
  "data": {
    "id": null,
    "accessToken": "eyJhbGciOiJI..."
  },
  "code": "CODE_2001",
  "message": "임시 토큰 정보 조회에 성공하였습니다."
}

2. 테스트 회원가입

요청:

POST /test/testSignup
Content-Type: application/json

{
  "id": "testuser01",
  "password": "pass1234"
}

응답 예시:

{
  "data": {
    "userIdx": 101,
    "id": "testuser01"
  },
  "code": "CODE_2002",
  "message": "아이디 등록 되었습니다."
}

중복일 경우 예시:

{
  "data": {
    "userIdx": null,
    "id": null
  },
  "code": "CODE_2004",
  "message": "중복된 아이디 정보 입니다."
}

3. 파일 업로드 초기화

요청:

POST /files/uploadInit
Content-Type: application/json
Cookie: ALIST_SESSION=...

{
  "fileCategory": "notice",
  "folderPath": "/2026/03",
  "itemList": [
    {
      "originName": "guide.pdf",
      "sizeBytes": 102400,
      "contentType": "application/pdf"
    }
  ]
}

응답 예시:

{
  "data": {
    "fileMasterIdx": 55,
    "tusEndpoint": "https://file-alist.pjt.kr/tus/files/",
    "itemList": [
      {
        "fileSeq": 1,
        "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111",
        "uploadToken": "upload-token-sample",
        "originName": "guide.pdf",
        "sizeBytes": 102400,
        "contentType": "application/pdf"
      }
    ]
  },
  "code": "CODE_200",
  "message": "성공"
}

4. 업로드 상태 조회

요청:

POST /files/uploadStatus
Content-Type: application/json

{
  "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111"
}

응답 예시:

{
  "data": {
    "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111",
    "status": "UPLOADING",
    "uploadedBytes": 51200,
    "totalBytes": 102400,
    "percent": 50,
    "updatedAt": "2026-03-11T09:30:00"
  },
  "code": "CODE_200",
  "message": "성공"
}

조회 결과가 없을 경우 예시:

{
  "data": {
    "fileUuid": null,
    "status": null,
    "uploadedBytes": null,
    "totalBytes": null,
    "percent": null,
    "updatedAt": null
  },
  "code": "CODE_2003",
  "message": "조회된 정보가 없습니다."
}

Actuator

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

health
info
metrics

헬스체크 기본 경로:

GET /actuator/health

응답 규칙

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

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

코드	HTTP Status	의미
`CODE_200`	`200 OK`	일반 성공
`CODE_204`	`204 No Contnet`	일반 성공
`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`	서버 오류

배포 관련

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

참고

Swagger 로컬 접속: http://localhost:8106/swagger-ui.html
운영 환경에서는 application-pjt.yaml의 환경변수 주입 방식 사용을 권장합니다.

라이선스

Proprietary

8.7 KiB Raw Blame History

alist API

프로젝트 개요

기술 스택

주요 기능

디렉터리 구조

실행 방법

빌드

로컬 실행

JAR 실행

프로파일

필수 설정 항목

데이터 저장소

인증/보안

파일 업로드

보안 구조

Swagger

API

공개 경로

CORS

파일 업로드/다운로드

주요 업로드 엔드포인트

파일 조회 엔드포인트

운영 메모

주요 인증 엔드포인트

API 예시 요청/응답

1. 토큰 발급

2. 테스트 회원가입

3. 파일 업로드 초기화

4. 업로드 상태 조회

Actuator

응답 규칙

배포 관련

참고

라이선스

8.7 KiB

Raw Blame History