파일 분석부터 서버 폴더 관리까지, Python 기반 자체 호스팅 웹 도구 - File Toolkit
파일 분석·중복 탐지·일괄 정리부터 서버 폴더 관리까지 지원하는 Python 기반 오픈소스 자체 호스팅 웹 도구.
파일을 분석하고, 이름을 바꾸고, 중복을 확인하고, 폴더를 정리하는 일은 흔한 작업입니다. 하지만 파일 수가 많아지면 작업마다 별도의 프로그램을 실행하거나 명령어를 사용해야 하는 경우가 많습니다.
서버에 보관된 파일까지 관리하려면 상황은 더 복잡해집니다. 어떤 경로에 접근할 수 있는지, 원본 파일이 변경되는지, 작업을 되돌릴 수 있는지 등을 함께 고려해야 합니다.
이러한 작업을 하나의 웹 환경에서 처리하기 위해 개발한 프로젝트가 File Toolkit입니다.
File Toolkit은 Python + FastAPI + Uvicorn을 기반으로 만든 오픈소스 파일 관리 도구입니다. 사용자가 직접 설치하고 운영하는 자체 호스팅(Self-hosted) 방식을 채택했으며, 별도의 클라우드 계정이나 외부 데이터베이스 없이 실행할 수 있습니다.
2026년 11월 공개한 v1.0.0은 첫 번째 안정 릴리스로, 파일 분석과 결과 생성뿐 아니라 선택적으로 서버 폴더를 관리하는 기능까지 포함합니다.
1. 원본 파일을 보존하는 파일 작업
File Toolkit의 기본적인 파일 처리 방식은 원본을 직접 수정하지 않는 것입니다.
브라우저에서 파일을 선택하거나 끌어다 놓으면, 서버는 업로드된 사본을 분석하고 필요한 결과를 생성합니다.
주요 기능은 다음과 같습니다.
- 파일 정보 분석: 파일명, 크기, 확장자, MIME 유형 등 확인
- SHA-256 체크섬: 파일 무결성 확인 및 내용 비교
- 중복 파일 탐지: 파일 크기와 해시를 기반으로 중복 후보 식별
- 파일명 일괄 변경: 접두사, 접미사, 문자열 치환, 순차 번호 등을 적용한 변경 결과 미리보기
- 파일 유형별 정리: 문서, 이미지, 오디오 등 파일 종류에 따른 분류
- 인벤토리 생성: 파일 목록을 CSV 또는 JSON으로 내보내기
- 파일 비교와 통계: 파일 집합의 구성과 차이를 분석하기 위한 보조 기능
파일명 변경이나 유형별 정리는 먼저 예상 결과를 확인한 다음 ZIP 파일로 내려받을 수 있습니다.
이 과정에서 사용자의 컴퓨터에 저장된 원본 파일은 변경되지 않습니다.
즉, 파일을 먼저 분석하고 결과를 확인한 뒤 필요한 산출물만 가져가는 방식입니다.
2. 허용된 서버 폴더를 선택적으로 관리
File Toolkit은 일반적인 업로드 기반 파일 처리 외에도 서버에 저장된 파일을 관리하는 기능을 제공합니다.
다만 서버 전체의 파일시스템을 자유롭게 탐색하도록 설계하지 않았습니다.
서버 관리자가 환경 설정에서 접근 가능한 디렉터리를 명시적으로 등록하면, 애플리케이션은 해당 경로를 별칭과 상대 경로로 다룹니다.
설정에 따라 다음과 같은 작업을 수행할 수 있습니다.
- 허용된 서버 디렉터리 탐색 및 검색
- 파일 정보와 중복 후보 분석
- 폴더 인벤토리 생성
- 파일 미리보기 및 다운로드
- 파일과 폴더 생성, 업로드, 복사 및 이동
- 휴지통을 이용한 삭제와 복원
- 원본 파일 변경 이력 조회
서버 폴더 접근과 원본 파일 변경 기능은 기본적으로 비활성화되어 있습니다.
읽기, 쓰기, 삭제는 별도의 설정으로 구분되며, 실제 파일 변경에는 운영체제의 파일 접근 권한도 적용됩니다.
따라서 업로드 파일을 분석하는 일반 기능만 사용하고 서버 폴더 기능은 사용하지 않는 구성도 가능합니다.
3. 원본 파일 변경은 미리보기와 확인을 거쳐 진행
파일 분석과 실제 파일 변경은 서로 다른 작업입니다.
File Toolkit은 이 둘을 분리했습니다.
업로드 기반의 파일명 변경은 결과 ZIP을 생성할 뿐이지만, 서버 폴더에서 수행하는 파일 이동이나 이름 변경은 실제 파일시스템에 영향을 줄 수 있습니다.
이러한 원본 파일 변경에는 미리보기, 명시적 확인, 작업 만료 시간, 파일 상태 재검증, 충돌 방지 및 작업 저널 등의 보호 절차를 적용합니다.
지원되는 작업은 변경 이력을 조회하고 복원을 시도할 수 있도록 구성했습니다. 다만 파일 상태가 달라졌거나 안전성을 확인할 수 없는 경우에는 자동 복원이 제한될 수 있습니다.
이는 모든 변경을 되돌릴 수 있다는 의미가 아니라, 원본 파일에 영향을 주는 작업을 확인 가능한 절차로 관리한다는 의미입니다.
4. 백그라운드 처리와 스냅샷 비교
여러 파일을 분석하거나 폴더의 내용을 조사하는 작업은 처리 시간이 길어질 수 있습니다.
File Toolkit은 지원되는 작업을 백그라운드 작업 큐에 등록하고, 진행 상태를 확인할 수 있도록 했습니다.
Server-Sent Events(SSE)를 이용한 상태 전달, 단계별 진행 정보, 작업 취소, 완료 결과 다운로드 등을 제공합니다.
또한 서버 폴더의 상태를 시점별로 기록하는 스냅샷 기능이 있습니다.
스냅샷을 비교하면 파일의 추가, 삭제, 변경 여부를 확인할 수 있으며, 비교 이력과 변화 추세도 살펴볼 수 있습니다.
수집이 불완전하거나 판단할 근거가 부족한 항목은 확정적인 변경으로 단정하지 않고 불확실한 결과로 구분합니다.
이러한 기능은 파일 보관소의 변경 내역을 점검하거나, 서버 폴더의 상태를 주기적으로 비교하는 작업에 활용할 수 있습니다.
5. Python + FastAPI + Uvicorn을 선택한 이유
File Toolkit은 복잡한 외부 서비스를 추가하지 않고 파일 작업에 필요한 기능을 Python 애플리케이션 내부에 구성했습니다.
Python은 파일시스템 작업, 해시 계산, ZIP 생성, 경로 처리 등에 필요한 표준 라이브러리를 제공합니다.
FastAPI는 브라우저 인터페이스와 HTTP API를 연결하고, 파일 업로드와 작업 요청을 처리합니다.
Uvicorn은 FastAPI 애플리케이션을 실행하는 ASGI 서버입니다.
프런트엔드는 HTML, CSS, JavaScript를 사용하며, 화면 스타일과 스크립트를 별도 파일로 관리합니다.
또한 파일 분석, 관리 폴더, 백그라운드 작업, 파일 변경, 스냅샷 등을 서비스 모듈로 분리하여 기능별 유지보수가 가능하도록 구성했습니다.
이 구조의 특징은 다음과 같습니다.
- 별도의 외부 파일 처리 서비스가 필요하지 않음
- 별도의 데이터베이스 서버가 필요하지 않음
- 개발 환경과 운영 환경에서 동일한 Python 애플리케이션 구조를 활용할 수 있음
- 웹 인터페이스와 API를 함께 제공함
- 파일 처리 기능을 독립적인 서비스 모듈로 관리함
PHP 기반 파일 관리 도구와 어느 한쪽이 절대적으로 우수하다는 의미는 아닙니다.
File Toolkit의 차이는 Python의 파일 처리 생태계와 FastAPI의 API 구조, Uvicorn의 ASGI 실행 환경을 조합했다는 점에 있습니다.
6. 자체 호스팅과 보안의 경계
자체 호스팅은 사용자가 소프트웨어와 데이터를 보관할 환경을 직접 선택하고 관리한다는 의미입니다.
File Toolkit 역시 자신의 컴퓨터나 사설 서버에서 실행할 수 있으며, 일반적인 로컬 사용에는 별도의 클라우드 서비스가 필요하지 않습니다.
보안 측면에서는 관리 폴더 접근 범위 제한, 경로 탐색 및 심볼릭 링크 관련 검사, 파일 충돌 방지, Origin·CSRF 검증, 작업별 접근 토큰 등 여러 보호 장치를 적용하고 있습니다.
그러나 중요한 제한도 있습니다.
File Toolkit v1.0.0에는 애플리케이션 자체의 사용자 로그인 및 다중 사용자 권한 관리 시스템이 없습니다.
관리 폴더의 읽기·쓰기 설정은 파일시스템 접근 범위를 정하는 기능이며, 접속한 사용자를 인증하는 수단은 아닙니다.
따라서 외부 네트워크에서 접근할 수 있도록 배포한다면 HTTPS, 접근 제한, 리버스 프록시 보안 설정 등은 운영자가 별도로 구성해야 합니다.
특히 서버 파일 변경 기능을 사용할 때는 접근 권한을 최소화하고, 중요한 데이터를 별도로 백업하는 것이 좋습니다.
File Toolkit은 외부에 아무 제한 없이 공개하는 범용 파일 서버보다, 개인이나 신뢰할 수 있는 환경에서 직접 통제하며 사용하는 도구에 가깝습니다.
7. 웹 인터페이스와 다국어 지원
File Toolkit은 파일 작업을 명령어 없이 수행할 수 있도록 브라우저 인터페이스를 제공합니다.
파일 선택과 드래그 앤 드롭, 작업 진행 상태, 결과 테이블의 확장·축소, 파일 관리와 스냅샷 비교를 위한 작업 탭 등을 갖추고 있습니다.
화면 언어는 한국어, 영어, 일본어, 중국어 간체를 지원하며, 시스템 설정에 따른 자동 테마와 라이트·다크 테마를 선택할 수 있습니다.
데스크톱과 모바일 화면 크기를 고려한 반응형 레이아웃도 제공합니다.
8. 설치와 운영
File Toolkit은 Python 3.11 또는 프로젝트 의존성과 호환되는 Python 환경에서 실행할 수 있습니다.
기본 설치는 Python 가상환경을 준비하고, requirements.txt의 패키지를 설치한 뒤 .env.example을 참고하여 환경 설정을 구성하는 방식입니다.
기본 바인딩 주소는 127.0.0.1, 포트는 8014입니다.
현재 백그라운드 작업 관리 구조는 단일 Uvicorn 워커를 전제로 하므로, 워커 수를 임의로 늘려 운영해서는 안 됩니다.
Windows 자동 시작 방법도 문서로 제공하지만, 일부 원본 파일 변경 기능은 Linux 전용 파일시스템 기능에 의존합니다.
설치 절차와 운영 환경에 관한 자세한 내용은 GitHub 문서에서 확인할 수 있습니다.
9. AI를 활용한 로컬 설치 가이드
별도의 설치 지원 문서인 AI_INSTALL_GUIDE.md도 제공합니다.
이 문서는 AI 에이전트가 사용자의 운영체제와 Python 환경을 먼저 확인하고, 저장소의 실제 문서를 읽은 뒤 환경에 맞는 설치 및 검증 절차를 수행하도록 안내합니다.
기존 환경 설정과 파일을 보존하고, 서버 폴더 권한을 임의로 활성화하지 않으며, 시스템 수준의 변경에는 사용자의 승인을 받도록 하는 내용을 포함합니다.
AI가 설치 과정을 보조할 수 있도록 만든 안내서이지, 모든 환경에서 자동 설치가 보장된다는 의미는 아닙니다.
10. 오픈소스 공개
File Toolkit v1.0.0은 MIT 라이선스로 공개한 오픈소스 프로젝트입니다.
프로젝트 소스코드를 확인하고 수정하거나, 라이선스 조건에 따라 자신의 환경에 맞게 활용할 수 있습니다.
단, Python 의존성 패키지에는 각각의 라이선스가 별도로 적용됩니다.
File Toolkit이 지향하는 것은 거대한 파일 관리 플랫폼이 아닙니다.
자신의 파일을 분석하고, 정리하고, 필요한 경우 허용된 서버 폴더까지 관리하는 작업을 하나의 Python 웹 도구에서 처리하는 것.
그리고 원본을 보존하는 작업과 실제 원본을 변경하는 작업의 차이를 명확하게 유지하는 것입니다.
v1.0.0은 이러한 방향을 바탕으로 공개한 첫 안정 버전입니다.
프로젝트 및 관련 링크
- GitHub 저장소: File Toolkit
- README / 사용 설명서: README.md
- AI 설치 가이드: AI_INSTALL_GUIDE.md
- 개발 및 유지보수 지침: AGENTS.md
- 외부 소프트웨어 라이선스: THIRD_PARTY_LICENSES.md
- 라이선스: MIT
이 개발자의 다른 프로젝트