Firefly III

Обзор

Firefly III

Firefly III — учёт личных финансов для тех, кто хочет хранить остатки по счетам, доходы, расходы, переводы, бюджеты, подписки и цели накопления на своём сервере. К операции можно прикрепить чек, разнести траты по категориям и проследить движение денег. Приложение заменяет учётную часть Quicken или Monarch Money, но не воспроизводит их готовые банковские подключения.

В отличие от Actual Budget, где основной сценарий — распределение доступных денег по конвертам, Firefly III строится вокруг счетов и операций, а бюджеты и правила дополняют этот журнал. Он удобен для подробной истории расходов и нескольких счетов. Для планирования каждой доступной денежной единицы лучше подходит инструмент с конвертами.

Рецепт запускает Firefly III 6.7.9, PostgreSQL 18.6 и cron в Alpine 3.22.2. Ежедневные задачи выполняются в 03:00 UTC, включая повторяющиеся операции и автоматические бюджеты. Отдельный Data Importer и внешние банковские сервисы не установлены. SMTP тоже не настроен: письма попадают в защищённый журнал приложения.

Основной клиент — браузер. Android и iOS поддерживают сторонние проекты, включая Waterfly III и Abacus из официального списка интеграций; настольного клиента в установке нет, мобильные приложения не проверялись. Интерфейс доступен на русском и английском. Приложение и логотип распространяются по AGPL-3.0-or-later, файлы установки — по MIT; уведомление о логотипе находится в assets/NOTICE.

Доступны локальный вход по email и паролю и встроенный TOTP. Второй фактор включается в профиле; коды восстановления нужно сохранить отдельно. Встроенных OIDC и SAML нет. Upstream поддерживает дополнительный remote-user guard, однако рецепт сохраняет вход по паролю: сам guard не проверяет подлинность переданной личности.

Стандартный однопользовательский режим закрывает публичную регистрацию после создания владельца. До этого первым владельцем может стать любой посетитель. Завершите регистрацию через loopback или SSH-туннель до открытия прокси и доступа из локальной сети.

Финансовые записи находятся в PostgreSQL; вложения и ключи подписи OAuth хранятся в постоянных томах. Рецепт сохраняет весь каталог Laravel storage и отдельный том загрузок, чтобы пересоздание контейнера или восстановление архива не лишало API-токены их ключей подписи. Защищайте все три тома и .env. Архив включает незашифрованные финансовые записи и ключи чтения зашифрованных вложений.

Smoke-тест на amd64 проверяет регистрацию, вход, персональный API-токен, счёт, расход, категорию и тег, настоящее вложение, endpoint cron и восстановление после удаления всех томов. arm64, ночное расписание, TOTP, почта, банки и мобильные клиенты не проверялись. В снимке безопасности сохранены восемь CRITICAL-находок в пакетах закреплённых образов. Функциональная проверка не является сертификатом безопасности.

Домашний и VPS-уровни поддерживаются после безопасного создания владельца. Надёжный уровень частичен: PostgreSQL и healthcheck есть, но лимиты ресурсов, внешний мониторинг и расписание резервирования настраивает оператор. Минимальный ориентир — 1 CPU, 1 ГиБ RAM и 5 ГиБ диска; 2 ГиБ RAM оставляют больше места для PHP и PostgreSQL. Большим вложениям и истории понадобится больше диска.

Официальные источники: установка Docker, резервирование, аутентификация, cron и изменения 6.7.9.

Пошаговая инструкция

Установка и обслуживание Firefly III

Ubuntu и Debian

Подойдут Ubuntu 24.04/26.04 LTS или Debian 12/13 с Docker Engine и Docker Compose от v2.24; установите их по инструкции Docker. Команды выполняются из каталога рецепта. Установите openssl; Python 3 и curl нужны только для smoke-теста. Доступ к Docker даёт административный контроль над хостом.

cp .env.example .env
chmod 600 .env
openssl rand -hex 16  # FIREFLY_APP_KEY: ровно 32 символа
openssl rand -hex 16  # FIREFLY_CRON_TOKEN: ровно 32 символа
openssl rand -hex 24  # FIREFLY_DB_PASSWORD

Вставьте три разных результата в .env, задайте FIREFLY_SITE_OWNER и оставьте привязку к loopback до первой регистрации. Entrypoint отклоняет шаблонный ключ, шаблонный пароль БД и неверную длину ключа или токена до запуска HTTP. Пароль администратора создаётся в браузере, а не в .env.

docker compose --env-file .env config --quiet
docker compose --env-file .env pull
docker compose --env-file .env up -d --wait --wait-timeout 600
docker compose ps

VPS и первый владелец

Создайте владельца до публикации через прокси. Для удалённого сервера откройте туннель со своего компьютера:

ssh -L 8088:127.0.0.1:8088 user@server

Откройте http://localhost:8088, зарегистрируйтесь с уникальным паролем от 16 символов и завершите настройку счетов и валюты. Стандартный однопользовательский режим закрывает регистрацию после первого аккаунта. Включите TOTP в профиле и сохраните коды восстановления отдельно. Затем открывайте публичный HTTPS. Не публикуйте порты PostgreSQL и cron; настройте firewall, обновления и зашифрованные внешние копии.

Доверенная локальная сеть или VPN

Для первого входа используйте тот же туннель. После регистрации замените 127.0.0.1 в пробросе веб-порта на частный адрес сервера, задайте FIREFLY_URL=http://<частный-адрес>:8088 и пересоздайте сервисы. Разрешайте доступ только доверенным клиентам или через VPN. Частный адрес без HTTPS всё равно передаёт сессии входа и финансовую информацию открытым текстом.

Домен и HTTPS

Направьте money.example.com на сервер и задайте FIREFLY_URL=https://money.example.com. Укажите в FIREFLY_TRUSTED_PROXIES точный адрес или CIDR прокси, видимый приложению, затем выполните docker compose up -d --wait --wait-timeout 600. Не используйте **, если не контролируете весь прямой доступ. Сохраняйте AUTHENTICATION_GUARD=web: заголовки протокола от прокси не включают единый вход.

Caddy, Nginx и Traefik

proxy/Caddyfile направляет HTTPS-домен на loopback-порт. Для proxy/nginx.conf укажите пути сертификатов; перед перезагрузкой выполните nginx -t. proxy/traefik.yaml — динамическая конфигурация file provider для уже установленного Traefik с указанным certificate resolver. Примеры предполагают прокси на Docker-хосте. Контейнерному прокси нужна контролируемая общая сеть или доступный адрес хоста: его 127.0.0.1 указывает на него самого.

Данные и все параметры

Compose создаёт тома проекта database, storage и uploads. PostgreSQL 18 хранит данные в /var/lib/postgresql; Laravel storage — в /var/www/html/storage; отдельный том загрузок перекрывает /var/www/html/storage/upload. В storage находятся ключи подписи OAuth. .env содержит ключ шифрования вложений и сессий; потеря FIREFLY_APP_KEY может сделать зашифрованные данные нечитаемыми.

Скрипты также принимают необязательные FOSSARY_ENV_FILE, COMPOSE_PROJECT_NAME и FIREFLY_BACKUP_DIR. По умолчанию это .env, проект firefly-iii и backups/. Если запускали docker compose -p с другим именем, экспортируйте тот же COMPOSE_PROJECT_NAME для каждого резервирования и восстановления. Ежедневный cron обслуживает повторяющиеся операции и автоматические бюджеты; импорт из банка и расписание резервирования настраиваются отдельно. SMTP не настроен; почтовые ссылки попадают в журналы, которые нужно защищать.

Резервирование

bash backup.sh

Скрипт останавливает cron и приложение, делает логический дамп PostgreSQL и два архива хранилищ, добавляет .env и Compose, затем запускает только ранее работавшие сервисы. Архивы имеют режим 600 и уникальные имена. Зашифруйте копию на другой машине и регулярно проверяйте восстановление. Экспорт операций не является полной резервной копией.

Восстановление — заменяет финансовые данные

Используйте только доверенные архивы. Сохраните старый .env, особенно FIREFLY_APP_KEY, и совпадающие версии приложения и базы. На новом сервере запустите только БД и создайте контейнеры приложения без запуска:

docker compose up -d --wait database
docker compose create --no-deps firefly cron

Затем восстановите архив:

bash restore.sh /absolute/path/firefly-iii-<timestamp>.tar

Скрипт проверяет состав архива, создаёт страховочную копию, останавливает запись, пересоздаёт базу приложения, заменяет оба тома хранилища и ждёт healthcheck. Архивный .env автоматически не активируется. Проверьте остатки по счетам, операции, вложения и API-токены до открытия доступа. При сбое сервисы записи остаются остановленными; изучите журналы и устраните причину до запуска. Для другой машины нужны архивные секреты и исправленный внешний URL.

Обновление

Прочитайте release notes и инструкцию обновления. Сохраните .env, Compose и проверенный архив. Остановите cron и приложение, измените только FIREFLY_VERSION на изученную закреплённую версию, загрузите и запустите её:

bash backup.sh
docker compose stop cron firefly
# Измените FIREFLY_VERSION в .env; сохраняйте мажорную версию БД.
docker compose pull firefly
docker compose up -d --wait --wait-timeout 600
docker compose logs --tail=100 firefly

Миграции базы выполняются при запуске автоматически. Проверьте остатки, скачивание чеков, плановые задачи и API. Для мажорного обновления PostgreSQL нужен отдельный план экспорта и импорта; не подключайте существующий каталог к другой мажорной версии.

Откат

1. Закройте внешний доступ, остановите cron и firefly.
2. Верните предыдущие Compose и .env, сохраняя правильный ключ шифрования и ту же мажорную версию БД. Укажите прежний FIREFLY_VERSION.
3. Загрузите прежний образ, выполните docker compose up -d --wait database, затем docker compose create --no-deps firefly cron. Оставьте приложение остановленным, чтобы старый код не мигрировал текущую базу.
4. Запустите bash restore.sh /path/to/pre-upgrade.tar. Страховочная копия сохранит текущее состояние, затем прежние база и хранилища заменят его.
5. Проверьте вход, остатки, операции, вложения и API, затем откройте прокси. Не считайте простую смену образа на старый поверх мигрировавшей базы безопасным откатом.

Остановка и удаление

docker compose down сохраняет тома. Для полного удаления после проверки внешней копии выполните docker compose down --volumes --remove-orphans. Команда уничтожает финансовые записи, вложения и ключи OAuth. .env и локальные архивы удаляйте отдельно, когда они больше не нужны.

Перед изменением модели безопасности изучите официальные руководства по резервированию и по аутентификации.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Диагностика Firefly III

Начните с docker compose ps --all, docker compose logs --tail=200 firefly database cron, docker compose --env-file .env config --quiet и curl -i http://127.0.0.1:8088/health. Не публикуйте разрешённую конфигурацию, токены, финансовые записи и ссылки сброса пароля в issue.

• Приложение сразу перезапускается: проверьте сообщение проверки секретов. FIREFLY_APP_KEY и FIREFLY_CRON_TOKEN должны быть разными 32-символьными значениями; замените шаблонный пароль БД. Не меняйте существующий ключ шифрования ради устранения ошибки запуска.
• Не проходит вход в БД: изменение .env не меняет пароль в инициализированном томе PostgreSQL. Верните исходный секрет или осознанно измените пароль роли базы; не удаляйте тома с финансовыми данными.
• Первым зарегистрировался посторонний: немедленно закройте доступ. Для действительно пустой, ненужной установки удалите тома и создайте владельца заново через loopback. При наличии записей сохраните архив и используйте upstream-процедуру восстановления аккаунта вместо сброса данных.
• Регистрация недоступна: после первого аккаунта это ожидаемо в однопользовательском режиме. Используйте приглашения владельца или осознанно изучите многопользовательские настройки; не отключайте защиту ради прохождения теста.
• Ошибки HTTPS, сессий или CSRF: сравните FIREFLY_URL с адресом браузера, передавайте исходные host/protocol и доверяйте только адресу прокси. После правки env пересоздайте сервис. Проверьте, что прокси не направляет запросы на свой loopback.
• Не создаются повторяющиеся операции и автоматические бюджеты: проверьте контейнер cron и расписание через docker compose exec cron crontab -l. Задача запускается в 03:00 UTC независимо от TZ. Для ручной проверки выполните docker compose exec firefly php artisan firefly-iii:cron; ежедневная задача может сообщить, что уже выполнялась. Считайте статический HTTP-токен и журналы доступа секретными.
• После восстановления не работают вложения или API-токены: восстанавливайте совпадающий FIREFLY_APP_KEY, дамп PostgreSQL, ключи storage и uploads вместе. Одной базы недостаточно. До новой попытки сохраните копию текущих томов.
• Обновление завершилось ошибкой: оставьте доступ закрытым, изучите журнал миграций и восстановите архив до обновления с совпадающим образом. Не удаляйте таблицы и не запускайте старый образ поверх обновлённой схемы.
• Нет банковской ленты или почты: Data Importer и SMTP не настроены. Экспорт файлов в браузере не является резервной копией. Перед включением интеграций прочитайте официальные инструкции установки и почты.

Источники: Docker FAQ, резервирование, cron и upstream issues.