Сложность: ★★☆☆☆ | Время: 15 минут | Итог: освоение развертывания и основных функций self-hosted приложения для ИИ-бухгалтерии
Целевая аудитория: Индивидуальные разработчики, фрилансеры, владельцы малого бизнеса и энтузиасты технологий, заинтересованные в автоматизации финансового управления.
Основные зависимости: Docker, Docker Compose, LLM API (OpenAI/Gemini/Mistral)
1. О проекте
Давайте сначала поговорим о проекте TaxHacker.
TaxHacker — это ИИ-приложение для бухгалтерского учета с открытым исходным кодом и возможностью самохостинга (self-hosted), разработанное специально для фрилансеров, малого бизнеса и индивидуальных разработчиков. Его главная особенность: использование ИИ для автоматического распознавания и извлечения финансовых данных из счетов и квитанций, что превращает утомительную ручную работу по ведению учета в процесс «в один клик».
Вы можете спросить, зачем использовать это решение, когда на рынке так много финансового ПО? Вот несколько причин:
- Интеллектуальное распознавание ИИ: загрузите фото чека, и ИИ автоматически извлечет название товара, сумму, дату, продавца и другую информацию, распознавая даже рукописные квитанции.
- Мультивалютная поддержка: поддержка более 170 фиатных валют и 14 криптовалют с автоматической конвертацией по историческому курсу на дату транзакции.
- 100% Self-hosted: данные хранятся на вашем собственном сервере, конфиденциальность полностью под вашим контролем, не нужно беспокоиться об утечке финансовых данных.
- Бесплатно и открыто: лицензия MIT, отсутствие платы за лицензирование.
Проект построен на Next.js 15 + Prisma + PostgreSQL, развертывание через Docker очень простое и занимает около 15 минут.
2. Подготовка окружения
Прежде чем начать развертывание, проверьте ваше окружение.
2.1 Требования к оборудованию
- Память: минимум 4 ГБ RAM (рекомендуется 8 ГБ)
- Хранилище: минимум 10 ГБ свободного места (для хранения загруженных изображений счетов)
- Система: 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
Вам понадобится API-ключ, чтобы ИИ мог распознавать счета. Если вы хотите сэкономить, рассмотрите платформу Defapi — она предоставляет API основных LLM по цене вдвое дешевле официальной, поддерживает OpenAI, Claude, Gemini и полностью совместима с протоколом OpenAI API.
3. Структура проекта
Перед развертыванием взглянем на общую структуру проекта:
TaxHacker/
├── app/ # Приложение Next.js
│ ├── (app)/ # Роуты основного приложения
│ │ ├── dashboard/ # Панель управления
│ │ ├── transactions/ # Записи транзакций
│ │ ├── settings/ # Страница настроек
│ │ └── ...
│ └── api/ # API роуты
├── ai/ # Ядро логики ИИ
│ ├── analyze.ts # Анализ чеков
│ ├── prompt.ts # Шаблоны промптов
│ └── providers/ # Провайдеры LLM
├── prisma/ # Модели базы данных
├── docker-compose.yml # Конфигурация Docker Compose
├── 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
# Настройка БД (используется PostgreSQL из docker-compose)
DATABASE_URL=postgresql://postgres:postgres@db:5432/taxhacker
# Путь для хранения файлов
UPLOAD_PATH=/app/data/uploads
# Секретный ключ аутентификации (минимум 16 символов)
BETTER_AUTH_SECRET=ваш-супер-секретный-ключ
# Отключение регистрации (рекомендуется для self-hosted)
DISABLE_SIGNUP=true
# Настройка LLM (на примере OpenAI)
OPENAI_MODEL_NAME=gpt-4o
OPENAI_API_KEY=ваш-openai-api-key
# Или использование Google Gemini
# GOOGLE_MODEL_NAME=gemini-2.0-flash
# GOOGLE_API_KEY=ваш-gemini-api-key
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 автоматически создает учетную запись администратора. Данные для входа по умолчанию:
- Email: admin@localhost
- Пароль: admin
WARNING
Пожалуйста, измените пароль по умолчанию сразу после первого входа!
5.2 Настройка LLM
Нажмите Settings (Настройки) в левом нижнем углу → LLM, убедитесь, что ваш API-ключ настроен правильно. На этой странице можно протестировать работу ИИ:
Test AI Connection: [Нажать для теста]
Если тест пройден успешно, значит LLM настроена.
5.3 Установка базовой валюты
В разделе Settings → Currencies установите вашу базовую валюту (например, RUB, USD или CNY).
5.4 Создание категорий
В Settings → Categories создайте нужные категории расходов/доходов, например:
- Питание
- Транспорт
- Офисные принадлежности
- ПО и сервисы
- Прочие доходы
6. Использование основных функций
Теперь посмотрим, как использовать ИИ для распознавания счетов.
6.1 Загрузка первого чека
Перейдите в раздел Unsorted (Неразобранное) на главной странице, нажмите кнопку Upload и загрузите изображение чека или PDF-счет.
Поддерживаемые форматы: JPG, PNG, PDF.
После загрузки вы увидите превью файла.
6.2 Автоматическое распознавание ИИ
Нажмите кнопку Analyze рядом с файлом, ИИ начнет анализ. Через несколько секунд вы увидите результат извлечения:
{
"date": "2026-03-15",
"merchant": "Starbucks Coffee",
"amount": 350.00,
"currency": "RUB",
"items": [
{ "name": "Латте", "quantity": 1, "price": 300.00 },
{ "name": "Салфетки", "quantity": 1, "price": 50.00 }
],
"category": "Питание"
}
Если в данных есть ошибка, вы можете отредактировать их вручную.
6.3 Подтверждение и сохранение
После подтверждения данных нажмите Confirm, и транзакция попадет в вашу книгу учета.
6.4 Автоматическая конвертация валют
Если вы загружаете счет в иностранной валюте (например, в долларах или евро), TaxHacker автоматически:
- Распознает тип валюты.
- Получит исторический курс на дату транзакции.
- Конвертирует сумму в базовую валюту.
Список поддерживаемых валют (включая BTC, ETH и др.) можно посмотреть в Settings → Currencies.
6.5 Пользовательские поля
Если у вас есть особые требования к извлечению данных, вы можете создать пользовательские поля в Settings → Fields. Например, если нужно извлекать ИНН из счета:
- Нажмите Add Field.
- Название поля: ИНН.
- Укажите промпт для ИИ:
Пожалуйста, извлеки идентификационный номер налогоплательщика (ИНН) из счета. - Сохраните.
При следующем анализе ИИ попытается извлечь это поле.
7. Экспорт и резервное копирование данных
Важнейшим аспектом учета является возможность экспорта данных, и TaxHacker отлично с этим справляется.
7.1 Фильтрация и экспорт
На странице Transactions вы можете фильтровать записи по дате, категории, проекту и другим критериям:
- Диапазон дат: с 2026-01-01 по 2026-03-21
- Категории: Питание, Транспорт
- Сумма: > 1000
После фильтрации нажмите Export CSV, чтобы выгрузить историю транзакций вместе со всеми вложениями.
7.2 Полное резервное копирование
В Settings → Backups можно создать полную резервную копию данных, включая:
- Снапшот базы данных
- Все загруженные файлы
- Информацию о конфигурации
Файл бэкапа можно скачать локально для обеспечения безопасности данных.
8. Устранение неисправностей
В процессе развертывания и использования могут возникнуть следующие проблемы:
Q1: Контейнер не запускается, ошибка подключения к БД
Проверьте правильность DATABASE_URL в docker-compose.yml. По умолчанию используется db в качестве имени хоста (внутренняя сеть Docker). Если вы используете внешнюю БД, скорректируйте настройки.
Q2: Анализ ИИ завис в статусе "Processing"
Сначала проверьте правильность API-ключа LLM. Затем просмотрите логи контейнера:
docker compose logs app | grep -i error
Если вы видите ошибку rate limit, значит превышен лимит вызовов API.
Q3: Ошибка "File too large" при загрузке
По умолчанию лимит файла составляет 10 МБ. Чтобы увеличить его, измените .env:
MAX_FILE_SIZE=20971520 # 20 МБ
Затем перезапустите сервис: docker compose restart.
Q4: Неточное распознавание чеков
Вы можете настроить системный промпт в Settings → LLM, чтобы дать ИИ больше контекста. Например, если вы работаете в общепите, добавьте:
Ты — профессиональный бухгалтер в сфере общественного питания, эксперт в распознавании форматов чеков различных ресторанов и кафе.
Q5: Как изменить пароль для входа
После входа нажмите на аватар в правом верхнем углу → Profile, там можно сменить пароль и email.
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 Кастомизация ИИ-промптов
TaxHacker позволяет глубоко настраивать поведение ИИ. Измените системный промпт в Settings → LLM, чтобы ИИ извлекал данные в соответствии с вашими отраслевыми стандартами.
9.2 Управление несколькими проектами
Создавайте разные проекты (например, «Проект А», «Проект Б») в Settings → Projects. Это позволяет вести раздельный учет доходов и расходов, что идеально подходит для фрилансеров с несколькими направлениями деятельности.
9.3 Автоматизация с OpenClaw
Если вы также развернули OpenClaw, можно настроить его на периодический вызов API TaxHacker для автоматической обработки неразобранных чеков, реализуя полностью автономный учет.
9.4 Автоматические бэкапы по расписанию
Используйте cronjob для вызова API бэкапа:
0 2 * * * curl -X POST http://localhost:7331/api/backups
Это будет создавать резервную копию каждую ночь в 02:00.