TL;DR

  • File Browser는 단일 Go 바이너리와 내장 React 앱으로 제공되는 웹 파일 브라우저이며, 선택적 계정 기능을 통해 파일 관리와 비공개 폴더를 제공함
  • 누구나 파일을 탐색·업로드·다운로드할 수 있고, 계정 사용 시 생성·이름 변경·이동·삭제 기능이 추가됨
  • 계정 데이터는 SQLite 데이터베이스에 저장되고 파일은 일반 파일시스템에 유지됨
  • Docker Compose 또는 Go 1.26+와 Bun을 이용한 소스 빌드를 지원하며, 기본 접속 주소는 http://localhost:8080임
  • React 19·TypeScript·Vite·Tailwind CSS 프런트엔드와 표준 라이브러리 기반 Go 1.26+ 백엔드로 구성되고 BSD 3-Clause 라이선스를 적용함

File Browser

  • 단일 Go 바이너리와 내장 React 앱으로 제공되는 웹 파일 브라우저임
  • 누구나 파일을 탐색·업로드·다운로드할 수 있음
  • 선택적 계정 기능으로 파일 생성·이름 변경·이동·삭제와 비공개 폴더 관리가 가능함
  • 계정 데이터는 SQLite 데이터베이스에 저장되고 파일은 일반 파일시스템에 유지됨

빠른 시작

Docker Compose 권장

  • 다음 구성으로 ghcr.io/skidoodle/filebrowser:latest 이미지를 사용하고, 컨테이너 이름을 filebrowser로 지정하며, 중단 후 자동 재시작을 설정함
  • 호스트의 8080 포트를 컨테이너의 8080 포트에 연결함
  • ./data를 /data에, ./db를 /db에 연결함
  • docker compose up -d로 서비스를 시작함
  • 시작 후 http://localhost:8080을 열면 첫 방문 시 관리자 계정 생성 화면이 제공됨

사용자 ID·그룹 ID 지정

  • 컨테이너는 기본적으로 1000:1000으로 실행됨
  • 호스트 볼륨이 다른 사용자 소유인 경우 PUID와 PGID를 설정함
  • 예시 구성은 PUID=1001, PGID=1001을 사용하고 /mnt/nas/files를 /data에, ./db를 /db에 연결함
  • 엔트리포인트는 권한을 낮추기 전에 /data, /cache, /db의 소유권을 자동으로 수정함
  • /data 아래에 여러 파일시스템을 바인드 마운트하는 구성도 지원함
  • /mnt/ssd/documents를 /data/documents에 연결함
  • /mnt/hdd/media를 /data/media에 연결함
  • ./db를 /db에 연결함
  • Compose에서 PUID·PGID 대신 user: "1001:1001"을 사용하면 엔트리포인트가 소유권 수정을 건너뛰고 직접 실행함
  • 이 경우 볼륨이 해당 UID로 이미 쓰기 가능한 상태인지 확인해야 함

소스에서 빌드

  • Go 1.26+와 Bun이 필요함
  • just build로 빌드하고 FILEBROWSER_ROOT=./data ./bin/filebrowser로 실행함

구성

  • 모든 설정은 환경 변수에서 가져옴
  • PUID: 기본값 1000, 프로세스가 실행되는 사용자 ID이며 Docker에서만 적용됨
  • PGID: 기본값 1000, 프로세스가 실행되는 그룹 ID이며 Docker에서만 적용됨
  • FILEBROWSER_ROOT: 기본값 ./data, 방문자에게 제공하는 디렉터리임
  • FILEBROWSER_DATABASE: 기본값 ./filebrowser.db, SQLite 데이터베이스 경로임
  • FILEBROWSER_ADDRESS: 기본값 0.0.0.0:8080, 수신 대기 주소임
  • FILEBROWSER_BASEURL: 기본값 없음, 앱이 마운트되는 하위 경로임
  • FILEBROWSER_ACCESS_POLICY: 기본값 public, 접근 정책임
  • public은 익명 방문자의 업로드를 허용함
  • readonly는 탐색만 허용함
  • private는 모든 작업에 로그인을 요구함
  • FILEBROWSER_MAXUPLOAD: 기본값 10GiB, 단일 업로드의 최대 크기임
  • FILEBROWSER_CACHEDIR: 기본값 시스템 임시 디렉터리, 썸네일과 기타 폐기 가능한 데이터의 저장 디렉터리임
  • FILEBROWSER_MAXTEXTSIZE: 기본값 10MiB, 텍스트 유형 감지를 중단하는 기준 크기임
  • FILEBROWSER_GUARD: 기본값 true, 악용 방지 체인의 활성화 여부임
  • FILEBROWSER_TRUSTEDPROXIES: 기본값 없음, X-Forwarded-For에 사용할 쉼표로 구분된 프록시 CIDR 목록임
  • FILEBROWSER_REQUESTRATE: 기본값 60, IP별 초당 API 요청 수임
  • FILEBROWSER_DOWNLOADRATE: 기본값 200MiB, IP별 초당 다운로드 바이트 수임
  • FILEBROWSER_POWDIFFICULTY: 기본값 4, 작업 증명 난이도이며 0이면 비활성화됨
  • FILEBROWSER_SECRET: 기본값 없음, 기능 서명 키이며 기본적으로 캐시 디렉터리에 저장되는 키를 사용함
  • FILEBROWSER_INSECURE: 기본값 false, 인증을 비활성화하고 모든 방문자에게 전체 접근 권한을 부여하는 설정임
  • FILEBROWSER_ADMIN_PASSWORD: 기본값 없음, 관리자 비밀번호를 초기 설정하거나 재설정하는 값임
  • FILEBROWSER_DEBUG: 기본값 false, 상세 로깅 설정임

개발

  • just dev는 :8080에서 API를, :5173에서 Vite 개발 서버를 실행함
  • just test는 레이스 감지기를 사용해 Go 테스트를 실행함
  • just lint는 golangci-lint를 실행함
  • just fmt는 gofmt와 go vet를 실행함
  • just build는 SPA가 내장된 프로덕션 바이너리를 빌드함
  • 나머지 명령은 just --list로 확인함
  • 백엔드는 표준 라이브러리 기반 Go 1.26+로 구성됨
  • 프런트엔드는 React 19, TypeScript, Vite, Tailwind CSS로 구성되고 Bun으로 빌드됨

라이선스

  • BSD 3-Clause 라이선스를 적용함
  • 자세한 내용은 LICENSE에서 확인 가능함