파일 분석부터 서버 폴더 관리까지, Python 기반 로컬 자체 호스팅, 파일 분석·정리 도구 - File Toolkit
File Toolkit은 Python + FastAPI + Uvicorn 기반의 로컬 자체 호스팅(Self-hosting) 파일 분석·정리 및 서버 폴더 관리 도구입니다.
Linux·Windows 환경에서 Docker, Nginx, Apache 또는 별도 데이터베이스 서버 없이 Python 가상환경과 필요한 라이브러리만으로 실행할 수 있도록 구성했습니다.
파일을 외부 클라우드 서비스에 전송하지 않고 자신의 PC나 서버에서 실행되는 FastAPI 애플리케이션으로 직접 처리하여 데이터 관리와 프라이버시를 중시합니다.
FastAPI + Uvicorn 기반으로 개발·실행 환경을 일원화하여, 사용자가 소스 코드를 직접 수정하고 기능을 확장하며 변경 사항을 즉시 반영해 사용할 수 있습니다.
일반적인 업로드 방식에서는 원본 파일을 변경하지 않고 분석·정리 결과를 생성하며, 필요할 때만 명시적으로 허용한 서버 폴더를 선택적으로 관리할 수 있습니다.
설치형 프로그램의 정해진 기능에 의존하기보다, 사용자가 직접 수정·확장하고 바로 적용하는 유연한 로컬 자체 호스팅을 지향합니다.
필요에 따라 Nginx·Apache 등 기존 웹 서버와 연동할 수도 있지만, 외부 서비스 운영이 아닌 로컬 자체 호스팅이 기본 목적입니다.
※ 주요 기능
-
파일 분석: 파일명, 크기, 확장자, MIME 유형 및 메타데이터 확인
-
체크섬·중복 탐지: SHA-256 해시 계산, 파일 크기와 해시를 기반으로 중복 후보 식별
-
파일명 일괄 변경: 접두사·접미사, 문자열 치환, 순차 번호 적용 및 변경 결과 미리보기
-
파일 분류·정리: 파일 유형별 분류, 정리 결과 미리보기 및 ZIP 다운로드
-
검색·비교·통계: 파일 필터링, 파일 크기 통계, 파일·인벤토리 비교 및 파일명 정규화
-
인벤토리 생성: 파일 목록을 CSV·JSON으로 내보내기
-
서버 폴더 관리: 명시적으로 허용한 폴더 탐색·검색·분석, 파일 미리보기·다운로드
-
웹 파일 관리자: 설정에 따라 파일 업로드, 파일·폴더 생성, 복사·이동·삭제, 휴지통 및 복원
-
원본 파일 변경: 서버 파일 이동·이름 변경 미리보기, 명시적 확인, 작업 이력 및 조건부 복원
-
백그라운드 처리: 작업 큐, 단계별 진행 상태, SSE 실시간 상태 전달, 작업 취소 및 결과 다운로드
-
스냅샷·비교 이력: 서버 폴더 상태 저장, 시점별 변경 비교, 비교 기록 및 변화 추세 확인
-
파일 처리 제한: 업로드 파일 크기·개수, 전체 처리량, 결과 파일 크기, 동시 작업 및 대기 작업 제한
-
사용자 인터페이스: 반응형 웹 화면, 한국어·영어·일본어·중국어 지원, System·Light·Dark 테마
※ 업로드 기반 파일명 변경과 분류는 원본을 수정하지 않고 결과 파일을 생성합니다.
※ 서버 폴더 접근과 원본 파일 변경 기능은 기본적으로 비활성화되어 있으며, 운영자의 명시적인 설정이 필요합니다.
※ 원본 파일 변경 후 복원은 파일 상태와 안전성 검사 결과에 따라 제한될 수 있습니다.
※ 기술 스택
Python, FastAPI, Uvicorn, Jinja2, Pydantic Settings, HTML5, CSS3, Vanilla JavaScript, REST API, SSE, SHA-256, ZIP, CSV, JSON, pytest, Ruff
※ 설치 및 운영 환경
-
Linux: Python 가상환경 기반 실행, 지원되는 파일시스템 기능을 이용한 서버 원본 파일 변경
-
Windows: Python 가상환경 기반 실행, 작업 스케줄러를 이용한 자동 시작 설정 안내
-
macOS: Python 및 프로젝트 의존성이 호환되는 환경에서 설치 가능 여부와 기능별 동작 확인 필요
-
공통: Python 3.11 또는 호환 버전, 프로젝트 의존성 설치, Docker 및 별도의 웹·데이터베이스 서버 설치 불필요
개발과 운영에 동일한 FastAPI 애플리케이션과 Uvicorn 실행 구조를 사용합니다.
기본 실행 주소는 127.0.0.1:8014이며, 백그라운드 작업 구조상 단일 Uvicorn 워커를 사용해야 합니다.
Windows·macOS에서는 Linux 전용 파일시스템 기능에 의존하는 일부 원본 파일 변경 기능의 지원 및 동작 검증이 필요합니다.
또한 File Toolkit v1.0.0에는 별도의 사용자 로그인·다중 사용자 권한 관리 기능이 없으므로, 외부 네트워크에 공개할 경우 접근 제한과 HTTPS 등 추가적인 보안 구성이 필요합니다.
※ AI 에이전트를 활용한 설치
Python이나 서버 실행 환경에 익숙하지 않은 사용자도 AI 에이전트의 도움을 받아 File Toolkit을 설치하고 실행할 수 있도록 운영체제에 종속되지 않는 공통 설치 요청 프롬프트를 제공합니다.
GitHub에 제공된 설치 프롬프트를 사용 중인 AI 에이전트에 전달하면, 로컬 운영체제와 시스템 환경을 먼저 확인하고 프로젝트 문서를 참고하여 가상환경 구성, 의존성 설치, 애플리케이션 실행 및 오류 해결을 안내받을 수 있습니다.
또한 확인된 운영체제에 맞는 자동 시작 설정 절차도 설치 요청에 포함되어 있습니다. Windows는 작업 스케줄러 기반 안내를 제공하며, Linux에서는 기존 운영 환경을 확인하고 사용자 승인 없이 시스템 서비스를 생성하지 않도록 구성했습니다.
AI 에이전트의 실행 권한과 환경에 따라 설치 및 설정을 직접 수행하거나 단계별 안내를 받아 진행할 수 있습니다.
※ 프로젝트 링크
라이선스: 프로젝트 자체 소스 코드 MIT License (종속 라이브러리는 개별 라이선스 적용)
File Toolkit v1.0.0은 첫 공개 안정 버전으로, 복잡한 서버 구성 없이 자신의 PC나 서버에서 파일 분석·정리 도구를 직접 실행하고 관리할 것을 지향합니다.
특히 업로드 사본을 이용한 비파괴 파일 처리와 허용된 서버 폴더에 대한 선택적 원본 파일 관리를 구분하여,
사용자가 자신의 파일과 실행 환경을 직접 통제할 수 있도록 구성했습니다.
로컬 자체 호스팅과 Python 기반 애플리케이션 개발에 관심 있는 분들께 도움이 되기를 바라며, 오류 및 개선 의견 환영합니다.
○ 참고 : 해당 포트폴리오
최신댓글
댓글을 불러오는 중입니다.
최신글
글을 불러오는 중입니다.