난이도: ★★☆☆☆ | 소요 시간: 15분 | 기대 효과: 셀프 호스팅 AI 회계 앱의 배포 및 핵심 기능 사용법 숙달
대상 독자: 개인 개발자, 프리랜서, 소규모 기업 운영자 및 재무 관리 자동화에 관심이 있는 기술 애호가.
핵심 의존성: Docker, Docker Compose, LLM API (OpenAI/Gemini/Mistral)
1 프로젝트 소개
먼저 TaxHacker 프로젝트에 대해 알아보겠습니다.
TaxHacker는 프리랜서, 소규모 기업 및 개인 개발자를 위해 설계된 오픈 소스 셀프 호스팅 AI 회계 애플리케이션입니다. 이 프로젝트의 핵심 셀링 포인트는 AI를 통해 영수증 및 인보이스에서 재무 데이터를 자동으로 식별하고 추출하여, 번거로운 수동 기입 작업을 클릭 한 번으로 해결하는 것입니다.
시중에 많은 재무 소프트웨어가 있는데 왜 이것을 사용해야 할까요? 몇 가지 이유를 들어보겠습니다:
- AI 스마트 식별: 영수증 사진을 업로드하면 AI가 상품명, 금액, 날짜, 업체 등의 정보를 자동으로 추출하며, 손글씨 영수증까지 인식합니다.
- 다중 통화 지원: 170개 이상의 법정 화폐와 14종의 암호화폐를 지원하며, 거래일 기준의 과거 환율로 자동 변환됩니다.
- 100% 셀프 호스팅: 데이터가 본인의 서버에 저장되므로 프라이버시를 완벽하게 제어할 수 있으며 재무 데이터 유출 걱정이 없습니다.
- 무료 오픈 소스: MIT 라이선스로 라이선스 비용이 전혀 없습니다.
이 프로젝트는 Next.js 15 + Prisma + PostgreSQL로 구축되었으며, Docker 배포가 매우 간단하여 15분이면 실행할 수 있습니다.
2 환경 준비
배포를 시작하기 전에 환경을 확인해 주세요.
2.1 하드웨어 요구 사양
- 메모리: 최소 4GB RAM (8GB 권장)
- 스토리지: 최소 10GB 여유 공간 (업로드된 영수증 이미지 저장용)
- 시스템: Linux/macOS/Windows (Docker 지원 필요)
2.2 소프트웨어 요구 사양
다음 소프트웨어를 설치해야 합니다:
- Docker Engine 20.10+
- Docker Compose 2.0+
TIP
Windows 사용자는 WSL2 + Docker Desktop 조합을 권장합니다. 가장 안정적입니다.
2.3 LLM API 준비
TaxHacker는 세 가지 LLM 제공업체를 지원합니다:
- OpenAI (GPT-4o 권장)
- Google Gemini
- Mistral
AI가 영수증을 인식하려면 API 키가 필요합니다. 비용을 절약하고 싶다면 Defapi 플랫폼을 고려해 보세요. 주요 LLM API를 공식 가격의 절반 수준으로 제공하며, OpenAI, Claude, Gemini 등 다양한 모델을 지원하고 OpenAI API 프로토콜과 완벽히 호환됩니다.
3 프로젝트 구조
배포 전, 프로젝트의 전체 구조를 살펴보겠습니다:
TaxHacker/
├── app/ # Next.js 애플리케이션
│ ├── (app)/ # 메인 앱 라우트
│ │ ├── dashboard/ # 대시보드
│ │ ├── transactions/ # 거래 기록
│ │ ├── settings/ # 설정 페이지
│ │ └── ...
│ └── api/ # API 라우트
├── ai/ # AI 핵심 로직
│ ├── analyze.ts # 영수증 분석
│ ├── prompt.ts # 프롬프트 템플릿
│ └── providers/ # LLM 제공업체
├── prisma/ # 데이터베이스 모델
├── docker-compose.yml # Docker 오케스트레이션 설정
├── Dockerfile # Docker 이미지 정의
└── .env.example # 환경 변수 예시
4 Docker 원클릭 배포
이제 본격적으로 배포를 시작합니다. Docker 방식이 가장 간단하며, 명령어 한 줄로 실행할 수 있습니다.
4.1 설정 파일 다운로드
# 프로젝트 디렉토리 생성
mkdir -p taxhacker && cd taxhacker
# docker-compose.yml 다운로드
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml
# 환경 변수 템플릿 다운로드
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/.env.example
4.2 환경 변수 설정
# 환경 변수 파일 복사
cp .env.example .env
선호하는 편집기로 .env를 열고 다음 주요 설정을 입력합니다:
# 기본 설정
PORT=7331
BASE_URL=http://localhost:7331
SELF_HOSTED_MODE=true
# 데이터베이스 설정 (docker-compose에 포함된 PostgreSQL 사용)
DATABASE_URL=postgresql://postgres:postgres@db:5432/taxhacker
# 파일 저장 경로
UPLOAD_PATH=/app/data/uploads
# 인증 키 (최소 16자 이상)
BETTER_AUTH_SECRET=your-super-secret-key-change-this
# 회원가입 비활성화 (셀프 호스팅 모드 권장)
DISABLE_SIGNUP=true
# LLM 설정 (OpenAI 예시)
OPENAI_MODEL_NAME=gpt-4o
OPENAI_API_KEY=your-openai-api-key-here
# 또는 Google Gemini 사용 시
# GOOGLE_MODEL_NAME=gemini-2.0-flash
# GOOGLE_API_KEY=your-gemini-api-key-here
WARNING
BETTER_AUTH_SECRET은 반드시 복잡한 무작위 문자열로 변경해야 보안이 유지됩니다.
4.3 서비스 시작
# 모든 서비스 시작
docker compose up -d
처음 시작 시 PostgreSQL 데이터베이스가 자동으로 생성되고 마이그레이션이 실행됩니다. 약 1~2분 정도 소요됩니다.
4.4 배포 확인
# 컨테이너 상태 확인
docker compose ps
# 로그 확인
docker compose logs -f app
모든 것이 정상이라면 http://localhost:7331 접속 시 로그인 페이지가 나타납니다.
5 기본 설정
서비스가 실행된 후 몇 가지 기초 설정을 완료해야 합니다.
5.1 첫 로그인
셀프 호스팅 모드에서 TaxHacker는 관리자 계정을 자동으로 생성합니다. 기본 로그인 정보는 다음과 같습니다:
- 이메일: admin@localhost
- 비밀번호: admin
WARNING
첫 로그인 후 즉시 기본 비밀번호를 변경하세요!
5.2 LLM 설정
왼쪽 하단의 Settings → LLM을 클릭하여 API 키가 올바르게 설정되었는지 확인합니다. 이 페이지에서 AI 작동 여부를 테스트할 수 있습니다:
Test AI Connection: [테스트 클릭]
성공 메시지가 뜨면 LLM 설정이 완료된 것입니다.
5.3 기준 통화 설정
Settings → Currencies에서 기준 통화를 설정합니다. 한국 원화(KRW) 또는 주로 사용하는 통화로 설정하는 것을 추천합니다.
5.4 카테고리 생성
Settings → Categories에서 필요한 지출/수입 카테고리를 생성합니다. 예:
- 식비
- 교통비
- 사무용품
- 소프트웨어 서비스
- 기타 수입
6 핵심 기능 실전 활용
환경 설정이 끝났으니 AI로 영수증을 인식하는 방법을 살펴보겠습니다.
6.1 첫 영수증 업로드
홈페이지의 Unsorted(미분류) 영역으로 이동하여 Upload 버튼을 클릭하고 영수증 이미지나 PDF 인보이스를 업로드합니다.
지원 파일 형식: JPG, PNG, PDF
업로드가 성공하면 파일 미리보기가 표시됩니다.
6.2 AI 자동 식별
파일 옆의 Analyze 버튼을 클릭하면 AI가 영수증 분석을 시작합니다. 몇 초 후 다음과 같은 추출 결과를 확인할 수 있습니다:
{
"date": "2026-03-15",
"merchant": "스타벅스",
"amount": 35.00,
"currency": "CNY",
"items": [
{ "name": "라떼", "quantity": 1, "price": 30.00 },
{ "name": "냅킨", "quantity": 1, "price": 5.00 }
],
"category": "식비"
}
결과에 오류가 있다면 수동으로 편집하여 교정할 수 있습니다.
6.3 확인 및 저장
데이터가 정확하다면 Confirm을 클릭하세요. 해당 거래가 장부에 기록됩니다.
6.4 다중 통화 자동 변환
달러(USD)나 유로(EUR) 같은 외화 영수증을 업로드하면 TaxHacker가 자동으로 다음을 수행합니다:
- 통화 유형 식별
- 거래일의 과거 환율 조회
- 기준 통화로 변환
Settings → Currencies에서 BTC, ETH 등 암호화폐를 포함한 지원 통화 목록을 확인할 수 있습니다.
6.5 사용자 정의 필드
특수한 추출 요구사항이 있다면 Settings → Fields에서 사용자 정의 필드를 생성할 수 있습니다. 예를 들어 영수증의 사업자 등록 번호를 추출하고 싶다면:
- Add Field 클릭
- 필드 이름: 사업자번호
- AI 추출 프롬프트 입력:
영수증에서 사업자 등록 번호를 추출해 주세요 - 저장
다음 번 영수증 분석 시, AI가 자동으로 이 필드의 추출을 시도합니다.
7 데이터 내보내기 및 백업
가계부에서 가장 중요한 것은 데이터 내보내기입니다. TaxHacker는 이 기능을 잘 지원합니다.
7.1 필터링 후 내보내기
Transactions 페이지에서 날짜, 카테고리, 프로젝트별로 필터링할 수 있습니다:
- 날짜 범위: 2026-01-01 ~ 2026-03-21
- 카테고리: 식비, 교통비
- 금액: > 100
필터링 후 Export CSV를 클릭하면 모든 첨부 파일이 포함된 거래 기록을 내보낼 수 있습니다.
7.2 전체 백업
Settings → Backups에서 다음을 포함한 전체 데이터 백업을 생성할 수 있습니다:
- 데이터베이스 스냅샷
- 업로드된 모든 파일
- 설정 정보
백업 파일을 로컬로 다운로드하여 데이터 안전을 보장하세요.
8 자주 묻는 질문(FAQ)
배포 및 사용 과정에서 발생할 수 있는 문제들입니다:
Q1: 컨테이너 시작 실패, 데이터베이스 연결 오류 메시지
docker-compose.yml의 DATABASE_URL이 올바른지 확인하세요. 기본 설정은 db를 호스트 이름으로 사용합니다(Docker 내부 네트워크). 데이터베이스를 커스텀했다면 그에 맞게 수정해야 합니다.
Q2: AI 분석이 계속 "처리 중"으로 표시됨
먼저 LLM API 키가 올바른지 확인하세요. 그 다음 컨테이너 로그를 확인합니다:
docker compose logs app | grep -i error
rate limit 오류가 보인다면 API 호출 횟수 제한에 걸린 것입니다.
Q3: 파일 업로드 시 "파일이 너무 큼" 오류
기본 최대 파일 크기 제한은 10MB입니다. 더 큰 파일을 업로드해야 한다면 .env를 수정하세요:
MAX_FILE_SIZE=20971520 # 20MB
그 후 서비스를 재시작합니다: docker compose restart
Q4: 영수증 인식이 부정확함
Settings → LLM에서 시스템 프롬프트를 커스텀하여 AI에게 더 많은 컨텍스트를 줄 수 있습니다. 예를 들어 외식업 종사자라면 다음과 같이 추가할 수 있습니다:
당신은 전문적인 외식 산업 회계사입니다. 다양한 레스토랑과 분식점의 영수증 형식을 식별하는 데 능숙합니다.
Q5: 로그인 비밀번호 변경 방법
로그인 후 우측 상단 아바타 → Profile에서 비밀번호와 이메일을 수정할 수 있습니다.
Q6: 관리자 비밀번호를 잊어버린 경우
데이터베이스를 통해 재설정해야 합니다. PostgreSQL 컨테이너에 접속합니다:
docker exec -it taxhacker-db-1 psql -U postgres -d taxhacker
그 후 다음을 실행합니다:
UPDATE users SET password_hash = 'new_password_hash' WHERE email = 'admin@localhost';
9 심화 활용 방향
기본 기능을 익혔다면 다음과 같은 심화 활용법을 탐색해 보세요:
9.1 AI 프롬프트 커스터마이징
TaxHacker는 AI의 행동을 깊이 있게 제어할 수 있게 해줍니다. Settings → LLM에서 시스템 프롬프트를 수정하여 업종 규범에 맞춰 데이터를 추출하도록 만드세요.
9.2 다중 프로젝트 관리
Settings → Projects에서 "프로젝트 A", "프로젝트 B"와 같이 프로젝트를 생성하면 프로젝트별로 수지 통계를 낼 수 있어 여러 사업선을 가진 프리랜서에게 매우 유용합니다.
9.3 OpenClaw와 결합한 자동화
OpenClaw를 함께 배포한 경우, 정기적으로 TaxHacker API를 호출하여 미분류 영수증을 자동으로 처리하도록 설정해 진정한 무인 회계를 구현할 수 있습니다.
9.4 예약 자동 백업
cronjob을 사용하여 백업 API를 정기적으로 호출하세요:
0 2 * * * curl -X POST http://localhost:7331/api/backups
매일 새벽 자동으로 백업이 생성됩니다.