Actual Budget

Обзор

Actual Budget — это конвертное бюджетирование, которое целиком живёт на ваших машинах. Каждый клиент — браузер, настольное приложение, телефон, открывший тот же адрес, — держит полную локальную копию бюджета и работает офлайн; сервер из этого рецепта нужен как точка синхронизации: он сводит копии и хранит файл. Деньги распределяются по категориям на месяц вперёд, операции импортируются из файлов или через банковские интеграции, которые вы настраиваете сами, а отчёты и расписания считаются на стороне клиента.

Рецепт поднимает зафиксированный Actual 26.9.0 одним контейнером с SQLite в одном volume: server-files для базы учётной записи и user-files для файлов бюджета. Web-порт привязан к localhost, разрешён только вход по паролю — способы через заголовок и OpenID остаются закрытыми, пока оператор не включит их сам.

Безопасность и границы рецепта

Полный прикладной smoke-тест прошёл на amd64 и arm64, практическая проверка backup и restore — на amd64. Пароль сервера задаётся в браузере при первом открытии, поэтому собственных секретов у рецепта нет — но это же означает, что незащищённый инстанс достанется тому, кто откроет его первым. Поставьте HTTPS перед первым визитом и не публикуйте порт напрямую. По умолчанию Actual принимает сразу три способа входа — пароль, заголовок и OpenID; рецепт сужает ACTUAL_ALLOWED_LOGIN_METHODS до password, потому что вход по доверенному заголовку за прокси, который этот заголовок не вырезает, — это открытая дверь. Сквозное шифрование включается для каждого бюджета отдельно внутри приложения: без него файлы лежат на сервере в открытом виде и в таком же виде попадают в резервные копии.

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

1. Проверьте сервер на Ubuntu или Debian

Подойдёт Ubuntu 22.04+ или Debian 12+ с Docker Engine и Compose v2.24+. Хватит одного ядра, 512 МБ RAM и 2 ГБ диска: бюджет занимает несколько мегабайт, а основная работа идёт в клиенте. Официальный образ заявляет amd64 и arm64.

docker --version
docker compose version

2. Подготовьте рецепт

mkdir -p ~/services/actual-budget
cd ~/services/actual-budget
cp .env.example .env
chmod 600 .env

Генерировать секреты не нужно: Actual спрашивает пароль сервера в браузере при первом визите и хранит его хеш в server-files. Сохраните пароль в менеджере паролей — это единственное, что стоит между интернетом и бюджетом.

Все переменные .env:

• ACTUAL_PORT — локальный web-порт, по умолчанию 5006;
• ACTUAL_LOGIN_METHOD — способ входа: password, openid или header;
• ACTUAL_ALLOWED_LOGIN_METHODS — какие способы сервер принимает вообще; в этом рецепте только password;
• ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB, ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB и ACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB ограничивают размеры синхронизации и загрузок;
• ACTUAL_TIME_ZONE — часовой пояс IANA;
• ACTUAL_DATA_VOLUME — имя volume с server-files и user-files;
• ACTUAL_BACKUP_DIR — каталог резервных копий на хосте.

3. Запустите и задайте пароль сервера

docker compose config
docker compose pull
docker compose up -d --wait --wait-timeout 600
docker compose ps
curl --fail http://127.0.0.1:5006/health

/health отвечает {"status":"UP"}, когда API и хранилище SQLite готовы. Откройте внешний адрес и задайте пароль сервера на экране первичной настройки раньше, чем это сделает кто-то другой, затем создайте или импортируйте файл бюджета. Браузер, открывший бюджет, держит его полную локальную копию, поэтому первая синхронизация загружает файл целиком.

Развёртывание на VPS

Оставьте 127.0.0.1:${ACTUAL_PORT}:5006: до сервера доберётся только HTTPS-прокси на этом же хосте. В файрволе откройте SSH, HTTP и HTTPS и больше ничего. Пароль сервера задавайте сразу после первого запуска: доступный, но ещё не настроенный инстанс отдаёт бюджет тому, кто его нашёл. Банковская синхронизация через GoCardless или SimpleFIN настраивается внутри приложения и требует исходящего HTTPS.

Доступ из доверенной локальной сети

Лучше ssh -L 5006:127.0.0.1:5006 user@server и адрес http://localhost:5006. Для постоянного доступа по локальной сети замените привязку к localhost одним конкретным приватным IP и ограничьте порт файрволом. Учтите: устанавливаемому PWA и Web Crypto для сквозного шифрования нужен защищённый контекст, поэтому обычный HTTP по локальной сети ограничивает и то, и другое — считайте такой маршрут временным.

Домен и HTTPS

Направьте budget.example.com на сервер, замените хост в примере для Caddy, Nginx или Traefik и один раз откройте адрес, чтобы задать пароль. Прокси должен пропускать загрузки размером с файл бюджета — в примере для Nginx client_max_body_size поднят до 100 МБ — и передавать WebSocket-апгрейды для синхронизации. Абсолютных ссылок Actual не строит, поэтому переменной с базовым адресом, которую нужно согласовывать с доменом, здесь нет.

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

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает сервер, архивирует весь volume /data и складывает рядом .env и compose.yaml. Остановка важна: живой файл SQLite можно поймать в момент записи. В архиве лежат все файлы бюджета и хеш пароля сервера — шифруйте его и увозите за пределы сервера. Actual делает и собственные периодические копии внутри volume, а настольный клиент — локальные копии; ни то, ни другое не заменяет архив за пределами сервера.

Восстановление

Восстановление необратимо заменяет volume с данными. Используйте ту же версию Actual и текущий .env:

./restore.sh ./backups/actual-budget-YYYYMMDDTHHMMSSZ.tar
curl --fail http://127.0.0.1:5006/health

Скрипт сначала делает резервную копию заменяемого состояния, затем пересоздаёт volume, распаковывает архив и поднимает сервер. После этого каждый клиент окажется «новее» восстановленного сервера: откройте каждый браузер и настольное приложение, а если клиент отказывается синхронизироваться — удалите его локальный файл и заново скачайте бюджет с сервера. Практическую проверку восстановления процедура не проходила: отрепетируйте её на отдельном сервере.

Обновление Actual

Сделайте резервную копию и прочитайте release notes — релизы выходят почти каждый месяц и иногда мигрируют формат бюджета:

./backup.sh
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:5006/health
docker compose logs --tail=200 actual

Заменяйте точный тег actualbudget/actual-server:26.9.0 на проверенную версию; latest, edge и nightly использовать нельзя. После миграции формата клиенты обновят свои локальные копии при следующей синхронизации, поэтому обновляйте настольные приложения в том же окне обслуживания.

Откат

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

docker compose down --timeout 60
./restore.sh ./backups/actual-budget-BEFORE-UPDATE.tar

Клиенты, успевшие мигрировать локальную копию, должны заново скачать бюджет с восстановленного сервера.

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

docker compose down сохраняет volume с данными. После проверки резервной копии за пределами сервера удалите всё безвозвратно:

docker compose down
docker volume rm actual-data
rm -rf ~/services/actual-budget

Если ACTUAL_DATA_VOLUME изменён, подставьте фактическое имя. Копии бюджета остаются в каждом браузере и настольном клиенте — если данные должны исчезнуть везде, очистите их отдельно.

Источники: установка в Docker, конфигурация сервера, резервное копирование и релиз v26.9.0.

Диагностика

Контейнер не становится healthy

docker compose ps
docker compose logs --tail=200 actual
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q actual)"

Проверка здоровья запускает внутри контейнера node scripts/health-check.js, который обращается к /health. Если контейнер стартовал, но проверку не проходит, почти всегда дело в правах на volume или в значении ACTUAL_LOGIN_METHOD, отличном от password, openid и header.

Экран первичной настройки снова просит пароль

/account/needs-bootstrap показывает, задан ли пароль:

curl --fail http://127.0.0.1:5006/account/needs-bootstrap

"bootstrapped":false на уже настроенном инстансе означает, что сервер смотрит в пустой server-files — обычно из-за переименованного или пересозданного volume. Прежде чем задавать новый пароль, проверьте ACTUAL_DATA_VOLUME и docker volume ls: бюджет остался в старом volume.

Пароль сервера потерян

Команды сброса нет. Остановите сервер, удалите account.sqlite из server-files и пройдите первичную настройку заново — файлы бюджета в user-files сохранятся:

docker compose stop actual
docker run --rm -v actual-data:/data alpine:3.22 rm -f /data/server-files/account.sqlite
docker compose start actual

Сначала сделайте резервную копию. Если для бюджета включено сквозное шифрование, его пароль — отдельный и таким способом не восстанавливается.

Клиент не синхронизируется или сообщает о конфликте

У каждого клиента полная локальная копия, поэтому восстановленный из архива сервер отстаёт от клиентов. Откройте бюджет в клиенте и выполните «Reset sync» в настройках файла либо удалите локальный файл и скачайте бюджет с сервера заново. Делайте это по одному устройству за раз, иначе два клиента зальют расходящиеся копии.

Синхронизация падает на большом бюджете

Ограничения заданы явно: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB, ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB и ACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB. Поднимайте их вместе с лимитом тела запроса на прокси — в примере для Nginx это client_max_body_size — и пересоздавайте контейнер.

Банковская синхронизация ничего не делает

GoCardless и SimpleFIN настраиваются внутри приложения, а не в рецепте, и обоим нужен исходящий HTTPS из контейнера. Посмотрите ошибку провайдера в журнале, затем проверьте исходящий доступ:

docker compose exec actual node -e "fetch('https://bankaccountdata.gocardless.com/api/v2/').then(r=>console.log(r.status)).catch(e=>{console.error(e.message);process.exit(1)})"

Обратный прокси отвечает 502 или страница открывается, но не синхронизируется

На хосте выполните curl -I http://127.0.0.1:5006/. Если ответ есть, проблема в прокси: внутри контейнера прокси 127.0.0.1 — это он сам, поэтому используйте адрес host gateway или общую сеть Docker. Если страница грузится, но синхронизации нет, прокси обычно режет WebSocket-апгрейды — оба примера их пропускают.