Трекер бюджета на своей инфраструктуре: открытый код, Docker и Postgres

Docker Compose не сможет обработать текущую конфигурацию, пока вы не выберете режим аутентификации. Для локальной установки без входа нужно явно указать его в команде:

AUTH_MODE=none make up

Эта мелочь многое говорит о самостоятельном размещении финансовых приложений. Запустить контейнеры легко. Настоящая работа — решить, кто получит к ним доступ, где будут храниться резервные копии и какие дополнительные сервисы смогут получать ваши финансовые данные.

Expense Budget Tracker — трекер бюджета с открытым исходным кодом под лицензией MIT, построенный на Next.js и Postgres. В этом руководстве описано текущее состояние репозитория: локальный запуск в Docker для одного технически подготовленного пользователя, задокументированное продакшен-развертывание в AWS через CDK и отдельные управляемые точки доступа к веб-интерфейсу, MCP и Agent API.

Сначала решите, какой контур вам нужен

«Разместить у себя» может означать несколько совершенно разных конфигураций. Они не взаимозаменяемы.

Вариант	Где хранятся финансовые данные	Что вы обслуживаете	Кому подходит
Локальный Docker Compose	Postgres в Docker-томе на вашем компьютере	Контейнеры, обновления, локальный доступ и резервные копии	Одному технически подготовленному пользователю, которому в основном нужен веб-интерфейс на одном компьютере
Ваш аккаунт AWS с описанным в документации стеком CDK	RDS и сервисы приложения в вашем аккаунте AWS	AWS, Cloudflare, домены, сертификаты, доставка писем, секреты, мониторинг и резервные копии	Публичное или многопользовательское развертывание, если вы готовы заниматься инфраструктурой
Управляемое веб-приложение	В облачной среде Expense Budget Tracker	Аккаунт и процесс ввода данных	Тем, кому нужен интерфейс без самостоятельной эксплуатации серверов
Облачный MCP-коннектор	В облачной рабочей области, доступной через сервис MCP	Разрешения OAuth и подключение клиента	Агенту с поддержкой MCP, которому нужен ограниченный доступ на чтение или запись
Облачный Agent API	В облачной рабочей области, доступной через сервис API	ApiKey с длительным сроком действия, выбор рабочей области и проверка SQL-запросов	Скриптам и агентам командной строки, которые могут напрямую обращаться по HTTP

Локальная команда Compose не создает api.your-domain.com или mcp.your-domain.com. Эти интерфейсы программного доступа относятся к архитектуре AWS и управляемому сервису. Подключая клиент к https://mcp.expense-budget-tracker.com/mcp, вы работаете с облачной рабочей областью, а не с контейнером Postgres на своем ноутбуке.

С этого и стоит начинать выбор трекера бюджета для своей инфраструктуры: вам нужен локальный контроль над веб-приложением и базой данных или удаленные интеграции, для которых потребуется более масштабное развертывание?

Как запустить трекер расходов локально в Docker

Понадобятся Git, Docker и Docker Compose. Клонируйте репозиторий и запустите стек из его корневой директории:

git clone https://github.com/kirill-markin/expense-budget-tracker.git
cd expense-budget-tracker
AUTH_MODE=none make up

Затем откройте http://localhost:3000.

AUTH_MODE — обязательная переменная Compose. Если вы не скопировали .env.example в .env, добавляйте этот префикс к каждой команде Compose. В примерах ниже он везде указан намеренно.

make up — короткий псевдоним для этой команды:

AUTH_MODE=none docker compose -f infra/docker/compose.yml up -d

Текущий файл Compose описывает Postgres 18, однократно запускаемый сервис миграций, веб-приложение на Next.js, сервис аутентификации и воркер курсов валют. При AUTH_MODE=none веб-приложение использует локальную учетную запись и не требует входа через Cognito. Это режим локального доступа для разработки, а не способ аутентификации на публичном сервере.

Проверить состояние контейнеров и следить за логами приложения можно обычными командами Compose:

AUTH_MODE=none docker compose -f infra/docker/compose.yml ps
AUTH_MODE=none docker compose -f infra/docker/compose.yml logs -f web

Чтобы остановить стек, выполните:

AUTH_MODE=none make down

Makefile вызывает docker compose down без -v. Данные Postgres остаются в именованном томе pgdata, и стек подхватывает их при следующем запуске.

Такое хранение удобно, но резервной копией его назвать нельзя. Сбой хоста, повреждение диска, случайное удаление тома или явный вызов docker compose down -v по-прежнему могут уничтожить единственную копию данных.

Оставьте эту конфигурацию локальной

Конфигурация Compose открывает на хосте порт 3000 для веб-приложения, 5432 для Postgres и 8081 для сервиса аутентификации. В ней также заданы учетные данные базы для разработки. Не размещайте такую конфигурацию на доступном из интернета сервере в расчете на то, что Docker сам закрыл доступ.

Для установки на рабочем компьютере:

• ограничьте сетевой доступ с помощью файрвола хоста;
• не перенаправляйте порты 3000, 5432 и 8081 на роутере;
• не выводите систему с AUTH_MODE=none в публичный доступ через обратный прокси;
• не храните репозиторий, файлы .env и дампы базы данных в публичных папках или каталогах с широким доступом.

Для продакшена в репозитории описано развертывание в AWS через CDK. Готовой защищенной конфигурации для любого VPS, NAS, кластера Kubernetes или домашнего сервера репозиторий не обещает, хотя опытный специалист сможет адаптировать код.

Какие сервисы работают и что остается в Postgres

Локальная архитектура достаточно компактна, чтобы разобраться в ней целиком:

• Веб-приложение на Next.js: предоставляет интерфейсы бюджета, транзакций, остатков, дашборда, демо-режима и чата.
• Postgres: хранит журнал операций, бюджетные планы, настройки рабочих областей, метаданные счетов и состояние приложения.
• Контейнер миграций: применяет SQL-миграции из репозитория перед запуском веб-сервиса.
• Воркер курсов валют: получает общедоступные данные о курсах и записывает их через роль базы данных с ограниченными правами.
• Сервис аутентификации: поддерживает архитектуру развертывания с аутентификацией; при AUTH_MODE=none локальный веб-интерфейс не использует Cognito.

Postgres служит источником истины. Для разработчика это практичное приложение для учета бюджета на Postgres: можно изучать миграции, разбираться в связях между таблицами, выполнять запросы к своей базе и экспортировать ее стандартными средствами Postgres. Защита на уровне строк (row-level security) и отдельные роли приложения по-прежнему важны внутри системы, но не заменяют защиту хоста и резервные копии.

Воркер курсов валют отправляет внешние запросы, чтобы получить данные о курсах. Для получения этих общедоступных данных ему не нужно отправлять записи из вашего финансового реестра. У дополнительных функций с ИИ другой контур передачи данных, и его стоит рассмотреть отдельно.

Создайте настоящую резервную копию, прежде чем считать данные защищенными

Для базы Postgres из локальной Compose-конфигурации по умолчанию эта команда создает на хосте сжатый архив:

AUTH_MODE=none docker compose -f infra/docker/compose.yml exec -T postgres \
  pg_dump -U tracker -d tracker --format=custom \
  > expense-budget-tracker.dump

Обращайтесь с этим файлом как с банковской выпиской. Он может содержать описания транзакций, остатки, категории, заметки и другие идентифицирующие сведения.

Для надежного резервного копирования нужно принять четыре решения:

1. Частота: определите, сколько последних изменений вы готовы потерять.
2. Второе место хранения: храните еще одну копию дампа за пределами Docker-хоста, чтобы отказ одного диска не уничтожил обе копии.
3. Шифрование и доступ: зашифруйте хранящийся архив и ограничьте круг тех, кто может его прочитать.
4. Проверка восстановления: периодически восстанавливайте архив в отдельном совместимом экземпляре Postgres и проверяйте транзакции, бюджеты и остатки.

Перед обновлением приложения создайте свежий дамп. Затем получите новый код, пересоберите образы и снова запустите стек:

git pull
AUTH_MODE=none make build
AUTH_MODE=none make up

Контейнер миграций запускается при старте. Перед обновлением прочитайте описание изменений. Не удаляйте дамп, сделанный до обновления, пока не проверите приложение и не выполните тестовое восстановление.

Самостоятельное размещение не означает, что каждый байт останется локальным

Основной веб-интерфейс и базу Postgres можно запустить локально на своем компьютере. Данные покидают этот контур, когда вы включаете функцию или обращаетесь к точке доступа, которая передает их наружу.

Встроенный чат с ИИ

Встроенный чат использует OPENAI_API_KEY. Когда вы работаете с чатом, OpenAI может получать промпты, прикрепленное или извлеченное содержимое и финансовый контекст, необходимый для вызова модели. В текущей цепочке обработки запроса указано store: false, но провайдеру все равно нужно обработать запрос. Остальные правила хранения зависят от настроек вашей организации OpenAI API. Прежде чем отправлять банковские выписки или данные из финансового реестра, изучите актуальные правила OpenAI по управлению данными API.

Трассировка Langfuse необязательна. Она включается, только когда одновременно заданы параметры подключения и значение релиза. После включения трейсы чата экспортируются по выбранному вами адресу LANGFUSE_BASE_URL. Адрес Langfuse Cloud добавляет еще одного внешнего обработчика данных; при самостоятельном размещении Langfuse данные отправляются в инфраструктуру под вашим управлением.

Если ваше требование звучит как «строки с финансовыми данными никогда не передаются провайдеру LLM», не настраивайте интеграцию с ИИ и не используйте чат. Размещение базы данных на своей инфраструктуре не отменяет исходящий запрос к модели, который вы включили сами.

Собственное развертывание в AWS

При описанном в документации развертывании в AWS сервисы приложения и RDS находятся в вашем аккаунте AWS. Но появляются и другие системы, которым приходится доверять: Cloudflare для DNS и обработки внешнего трафика, Cognito для аутентификации, Resend для писем при входе, сертификаты для публичных доменов, Secrets Manager, мониторинг и необязательные подключения OpenAI и Langfuse.

Стек CDK включает управляемые средства резервного копирования базы. Вам по-прежнему нужно решить, подходит ли срок хранения копий, следить за сбоями, проверять восстановление, менять секреты, устанавливать обновления и реагировать на инциденты. «Мой аккаунт AWS» — полезная граница контроля, но не то же самое, что «никаких сторонних сервисов».

Управляемый интерфейс, облачный MCP и облачный Agent API

Управляемый веб-интерфейс доступен по адресу app.expense-budget-tracker.com. Этот вариант требует меньше всего эксплуатационной работы, однако оператор сервиса и провайдеры хостинга входят в контур обработки данных. Прежде чем загружать туда реальные финансовые сведения, прочитайте политику конфиденциальности.

Клиент с поддержкой MCP может подключиться к:

https://mcp.expense-budget-tracker.com/mcp

Облачный MCP-коннектор использует авторизацию OAuth через браузер. Обязательная область доступа expenses:read разрешает просматривать список рабочих областей, изучать схему и выполнять запросы на чтение. Область expenses:write выдается отдельно и необходима для sql_execute. Начните с доступа только на чтение и выдавайте права на запись лишь тогда, когда клиенту действительно нужно создавать, изменять или удалять финансовые записи. MCP-клиент также может получить данные, возвращенные инструментами, поэтому его собственная политика конфиденциальности тоже имеет значение. Полный процесс описан в руководстве по MCP-коннектору.

Облачный Agent API — другой интерфейс с отдельными учетными данными. Начните с запроса:

curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/

После завершения настройки по коду из письма вы получите ключ с длительным сроком действия. Добавляйте в прямые запросы:

Authorization: ApiKey <key>

Основные точки доступа SQL намеренно разделяют один запрос на чтение и одну разрешенную операцию записи:

• POST /v1/sql/query принимает один ограниченный запрос SELECT или WITH ... SELECT.
• POST /v1/sql/execute принимает один разрешенный запрос INSERT, UPDATE или DELETE.

Выбор рабочей области и защита Postgres на уровне строк применяются на сервере. Они не превращают запрос к управляемому сервису в локальный, а OAuth-точка доступа MCP не принимает ApiKey. Справочник API описывает получение сведений о сервисе, выбор рабочей области, просмотр схемы, ограничения запросов и точные правила SQL. Подробнее о подтверждении операций и сверке данных рассказано в руководстве по API для учета расходов.

Что вы берете на себя при самостоятельном размещении

Со стороны приложения личные финансы для разработчика могут выглядеть приятно просто: один репозиторий, одна команда Compose, одна база данных. Но эксплуатационная работа не заканчивается после первой успешно загруженной страницы.

При локальном запуске в Docker вы отвечаете за:

• обновления Docker и операционной системы хоста;
• обновления приложения и проверку миграций;
• дампы базы данных, зашифрованные копии на другом устройстве, сроки хранения и проверки восстановления;
• свободное место на диске и состояние контейнеров;
• правила межсетевого экрана и физический доступ к компьютеру;
• защиту файлов .env, ключей API, ключей моделей и резервных копий.

Для публичного развертывания добавьте:

• домен и настройку DNS;
• TLS-сертификаты и механизмы их продления;
• аутентифицированный доступ вместо AUTH_MODE=none;
• доставку писем с одноразовыми кодами и учетные данные для нее;
• мониторинг базы данных и сервисов;
• обработку оповещений, реагирование на инциденты и восстановление;
• расходы на облако и защиту аккаунта провайдера.

Руководство по самостоятельному размещению — краткая инструкция по настройке. Документация по развертыванию в исходном репозитории остается главным источником по поддерживаемой архитектуре AWS.

Практический список для принятия решения

Трекер расходов на своей инфраструктуре вам подходит, если верно большинство пунктов:

• Вы готовы администрировать Docker и Postgres, а не просто один раз ими воспользоваться.
• Вы готовы автоматизировать резервное копирование и проверять восстановление, а не слепо полагаться на Docker-том.
• Вам нужен прямой доступ к стандартной базе данных и исходному коду, который можно проверить или изменить.
• Вам достаточно локального доступа из браузера либо вы готовы эксплуатировать документированный стек AWS.
• Вы можете не открывать систему с AUTH_MODE=none в публичную сеть.
• Вы будете проверять каждый необязательный исходящий канал, особенно чат с ИИ и телеметрию.

Используйте управляемое приложение или другой облачный вариант, если следующие пункты больше похожи на ваш случай:

• Вы хотите вносить и проверять финансовые данные, не обслуживая инфраструктуру.
• Вам нужен надежный удаленный доступ, но вы не хотите управлять доменами, TLS, аутентификацией, электронной почтой, секретами и мониторингом.
• Вы, скорее всего, не заметите сбой резервного копирования или несвоевременное обновление безопасности.
• MCP с разграничением доступа по областям OAuth или облачный Agent API решает задачу интеграции без эксплуатации полного стека.

Есть и полезный промежуточный вариант: запустить локальную систему без ключей ИИ, не открывать к ней доступ из интернета и выгружать зашифрованные резервные копии Postgres в подконтрольное вам хранилище. Так вы получите главное преимущество трекера бюджета на своей инфраструктуре, не делая вид, что конфигурация Compose на ноутбуке — полноценная платформа для продакшена.

Начните с AUTH_MODE=none make up, внесите несколько тестовых транзакций без конфиденциальных данных, остановите и снова запустите стек, а затем создайте и проверьте дамп базы данных. Если такой короткий эксплуатационный цикл кажется разумным, переносите реальные данные. Если уже на этом этапе он кажется лишней работой, управляемый сервис, вероятно, будет более честным выбором.