Simple File Server

Spring Boot 기반의 간단한 파일 업로드/다운로드 서버입니다.

실행

필요한 환경변수는 프로젝트 루트의 .env 파일에 작성할 수 있습니다.

cp .env.example .env

./gradlew bootRun

웹 UI는 http://localhost:8080/files/에서 사용할 수 있습니다. API 가이드 화면은 http://localhost:8080/files/guide에서 확인할 수 있습니다. Swagger UI는 http://localhost:8080/files/api-guide, OpenAPI JSON은 http://localhost:8080/files/v3/api-docs에서 확인할 수 있습니다.

포트를 바꿔 실행하려면 .env의 FILE_SERVER_PORT 값을 수정합니다.

FILE_SERVER_PORT=8081
FILE_SERVER_CONTEXT_PATH=/files
FILE_SERVER_MAX_UPLOAD_SIZE=3GB

API

기본 최대 파일 크기는 3GB입니다. 이 값은 FILE_SERVER_MAX_UPLOAD_SIZE로 변경할 수 있으며, 서버의 multipart 업로드 제한과 웹 화면의 선택/업로드 검증이 같은 값을 사용합니다. nginx 같은 프록시를 앞단에 둘 경우 client_max_body_size도 같은 값으로 맞춰야 합니다.

Linux

업로드:

curl -F "file=@./sample.zip" http://localhost:8080/files/api

다운로드:

curl -L -o sample.zip http://localhost:8080/files/api/sample.zip

Windows PowerShell

업로드:

curl.exe -F "file=@C:\temp\sample.zip" http://localhost:8080/files/api

다운로드:

curl.exe -L -o sample.zip http://localhost:8080/files/api/sample.zip

요청 형식:

API	Method	Endpoint	Content-Type/Response	성공
업로드	POST	/files/api	multipart/form-data, field file	201 Created + FileResponse JSON
다운로드	GET	/files/api/{fileName}	attachment 응답	200 OK
파일 목록	GET	/files/api	JSON array	200 OK
파일 삭제	DELETE	/files/api/{fileName}	응답 본문 없음	204 No Content

업로드 성공 응답 예시:

{
  "name": "sample.zip",
  "size": 1048576,
  "sizeLabel": "1.0 MB",
  "lastModified": "2026-05-31T00:00:00Z",
  "downloadUrl": "http://localhost:8080/files/api/sample.zip"
}

업로드 한도를 넘으면 413 Payload Too Large와 아래 형식의 JSON을 반환합니다. multipart/form-data가 아닌 업로드 요청은 415 Unsupported Media Type과 같은 오류 JSON을 반환합니다.

{
  "message": "File size must be {configured limit} or less."
}

파일 목록:

curl http://localhost:8080/files/api

파일 삭제:

curl -X DELETE http://localhost:8080/files/api/sample.zip

기본 최대 파일 크기는 3GB이며, FILE_SERVER_MAX_UPLOAD_SIZE로 변경할 수 있습니다. 로컬 실행 시 저장 경로는 uploads/입니다. 로컬 실행에서 저장 경로를 바꾸려면 .env에 FILE_SERVER_STORAGE_LOCATION을 직접 추가합니다.

FILE_SERVER_STORAGE_LOCATION=/data/files

Docker 실행

Docker 실행은 compose.yml과 .env 파일을 사용합니다. 이미지는 JDK 21 기반으로 빌드하고 실행합니다.

cp .env.example .env

Docker 실행에서 서버의 업로드 파일 저장 위치는 .env의 FILE_SERVER_UPLOAD_DIR 값으로 지정합니다. 컨테이너 내부 경로는 /data/uploads로 고정되어 있습니다. FILE_SERVER_PORT는 호스트에 노출할 포트이며, 컨테이너 내부 포트는 8080으로 고정되어 있습니다.

FILE_SERVER_PORT=8081
FILE_SERVER_CONTEXT_PATH=/files
FILE_SERVER_UPLOAD_DIR=/srv/simple-file-server/uploads
FILE_SERVER_MAX_UPLOAD_SIZE=3GB

nginx에서 /files로 프록시할 때는 Spring 앱의 context path도 /files이므로 prefix를 제거하지 않도록 설정합니다.

location = /files {
    return 301 /files/;
}

location /files/ {
    proxy_pass http://127.0.0.1:8081;
    client_max_body_size 3g;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

서버에서는 Docker Hub에 push된 이미지를 받아 실행합니다.

docker login
docker compose pull
docker compose up -d

로컬에서 현재 소스로 이미지를 빌드해 실행하려면 compose.local.yml을 함께 사용합니다.

docker compose -f compose.yml -f compose.local.yml up -d --build

상태 확인:

docker compose ps
docker compose logs -f simple-file-server

중지:

docker compose down