자체 호스팅 이미지 변환·편집 도구 - Image Toolkit
Python + FastAPI + Uvicorn 기반으로 이미지 변환·편집·일괄 처리를 지원하는 로컬 자체 호스팅 웹 도구
Python + FastAPI + Uvicorn을 기반으로 개발한 웹 이미지 처리 도구 Image Toolkit의 첫 공개 버전 v0.1.0을 배포했습니다.
이미지 형식 변환이나 크기 조정, 간단한 편집을 위해 외부 서비스를 이용하는 대신, 자신의 PC나 서버에서 직접 실행할 수 있는 환경을 목표로 개발했습니다.
프로젝트: https://github.com/glitter-node/image-toolkit
온라인 데모: https://image-toolkit.glitter.kr/
1. 개발 목적
Image Toolkit은 로컬 자체 호스팅(Self-hosting)을 우선하는 이미지 처리 애플리케이션입니다.
특히 개발 환경과 운영 환경의 일관성에 중점을 두었습니다.
Python + FastAPI + Uvicorn 조합을 사용하면 개발 과정에서 사용한 애플리케이션 구조를 운영 환경에서도 그대로 유지할 수 있습니다.
별도의 웹 애플리케이션 프레임워크로 변환하거나 복잡한 인프라를 구성하지 않아도 됩니다.
Docker, WSL2, Nginx, Redis, 외부 데이터베이스 등은 기본 실행에 필요하지 않습니다.
Python 가상환경과 필요한 패키지만 설치하면 로컬에서 실행할 수 있도록 구성했습니다.
2. 주요 기능
이미지 형식 변환
- JPEG, PNG, WebP, AVIF 형식 출력
- HEIC 출력 지원(관련 코덱 사용 가능 시)
- JPEG, PNG, WebP, GIF, BMP, TIFF 등의 입력 형식 감지
- 이미지 품질 및 크기 조정
- EXIF 방향 정보 처리
지원 형식은 설치된 Pillow와 이미지 코덱 환경에 따라 달라질 수 있습니다.
이미지 편집
- 크기 조정(Resize)
- 자르기(Crop)
- 회전 및 좌우·상하 반전
- 밝기, 대비, 채도, 선명도 조정
- 텍스트 및 PNG 로고 워터마크
- 브라우저 편집 미리보기
일괄 처리
- 최대 10개 이미지 일괄 처리
- 비동기 작업 등록 및 진행 상태 조회
- 작업 취소
- 처리 결과 ZIP 다운로드
- 작업 만료 및 임시 파일 자동 정리
웹 인터페이스
- 반응형 UI
- 라이트·다크 테마
- 한국어, 영어, 일본어, 중국어 간체 지원
- 이미지 선택, 편집, 출력, 작업 이력 화면
3. 기술 구성
| 구분 | 기술 |
|---|---|
| Backend | Python + FastAPI |
| Application Server | Uvicorn |
| Image Processing | Pillow |
| Database | SQLite |
| Frontend | HTML + CSS + Vanilla JavaScript |
| API Documentation | OpenAPI / Swagger UI |
별도의 프런트엔드 빌드 시스템이나 외부 데이터베이스 서버 없이 동작하도록 구성했습니다.
이미지 편집 미리보기는 브라우저에서 제공하지만, 최종 이미지 변환은 서버의 Pillow에서 처리합니다.
자체 호스팅 환경에서는 업로드한 이미지와 작업 결과를 운영자가 관리하는 컴퓨터 또는 서버에서 처리할 수 있습니다.
4. 설치 및 실행
Python 3.11 이상을 기준으로 합니다.
Linux 환경에서는 다음과 같이 실행할 수 있습니다.
python3 -m venv venv
venv/bin/python -m pip install -r requirements.txt
venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 9781 --lifespan on --log-level info
브라우저에서 다음 주소로 접속합니다.
http://127.0.0.1:9781/
Windows와 macOS용 네이티브 설치 방법도 README에 정리했습니다.
Windows에서는 Task Scheduler를 이용한 사용자 로그인 시 자동 실행 방법도 별도로 제공합니다.
Windows·macOS의 설치 및 일부 이미지 코덱 동작은 환경별 확인이 필요합니다.
5. API 지원
FastAPI 기반의 REST API를 제공하므로 웹 UI 외에도 다른 애플리케이션이나 자동화 도구에서 이미지 변환 기능을 활용할 수 있습니다.
OpenAPI 기반 대화형 API 문서를 제공합니다.
API 문서: https://image-toolkit.glitter.kr/docs
6. 자체 호스팅 중심 설계
Image Toolkit은 공개 SaaS보다는 로컬 또는 직접 관리하는 서버에서 사용하는 것을 우선으로 설계했습니다.
SQLite로 작업 메타데이터를 관리하고, 작업에 필요한 입력 파일과 변환 결과는 로컬 파일 시스템에 저장합니다.
비동기 작업의 결과 파일은 설정된 보존 시간이 지나면 정리됩니다.
이미지 처리 작업은 서버 자원을 사용하므로, 공개 네트워크에 배포할 때는 별도의 접근 통제와 요청 제한 등을 고려해야 합니다.
7. v0.1.0 최초 공개
이번 버전은 기능 확장보다 기본 이미지 처리, 웹 UI, 비동기 작업 관리 및 자체 호스팅 환경을 구성하는 데 집중한 첫 공개 릴리스입니다.
기존 브라우저 수동 검증은 진행했으며, Python 및 Playwright 자동화 테스트는 이번 릴리스 준비 과정에서 실행하지 않았습니다.
HEIF/AVIF 지원 여부, 대용량 이미지의 메모리 사용, Windows·macOS 환경별 호환성 등은 추가 검증과 개선이 필요한 부분입니다.
8. GitHub 및 다운로드
- GitHub 저장소: https://github.com/glitter-node/image-toolkit
- v0.1.0 릴리스: https://github.com/glitter-node/image-toolkit/releases/tag/v0.1.0
- Linux/macOS용 tar.gz: https://github.com/glitter-node/image-toolkit/releases/download/v0.1.0/image-toolkit-v0.1.0.tar.gz
- ZIP 다운로드: https://github.com/glitter-node/image-toolkit/releases/download/v0.1.0/image-toolkit-v0.1.0.zip
- 설치 및 사용 문서: https://github.com/glitter-node/image-toolkit/blob/main/README.md
Image Toolkit은 기존 이미지 처리 서비스나 전문 편집 프로그램을 대체하려는 프로젝트라기보다, Python 기반 이미지 처리 기능을 웹 인터페이스와 API로 제공하고 이를 자신의 환경에서 직접 운영할 수 있도록 만든 도구입니다.
로컬 자체 호스팅을 위한 가벼운 이미지 처리 도구가 필요하거나 FastAPI 기반 웹 애플리케이션 구조에 관심 있는 분들께 참고가 되었으면 합니다.
사용해 보시고 발견한 오류나 개선 의견은 GitHub Issues를 통해 알려주시면 감사하겠습니다.
이 개발자의 다른 프로젝트