Бэкап и восстановление Airsonic

MAATRIX

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

Что нужно бэкапить в Airsonic

Airsonic — форк Subsonic, работающий как Java-приложение (обычно в Docker, реже как WAR под Tomcat) с поддержкой десятков клиентов по Subsonic API: DSub, Substreamer, Symfonium, play:Sub и другие. У сервиса три независимых слоя данных, и относиться к ним нужно по-разному:

• База данных — пользователи, пароли, плейлисты, история прослушиваний, рейтинги, теги «избранное», подписки на подкасты, настройки транскодирования. Это самое критичное и самое маленькое по объёму — обычно десятки мегабайт.
• Конфигурация (airsonic.properties, ключи, настройки LDAP/OAuth если включены) — небольшая, но без неё сервер не поднимется в прежнем виде.
• Медиатека — сами файлы музыки и подкастов. Как правило, это отдельное хранилище (NAS, отдельный диск, смонтированный volume), и её бэкап — отдельная задача с другой периодичностью: аудиофайлы не меняются каждый день, а метаданные — постоянно.

Кэш обложек и транскодированных файлов бэкапить не нужно — Airsonic пересоздаст их сам при следующем запуске.

Где лежат данные: структура airsonic home

Всё критичное живёт в одном каталоге — AIRSONIC_DIR, по умолчанию /var/airsonic. Если вы ставили Airsonic через Docker (официальный образ airsonic/airsonic или форк airsonic-advanced), это смонтированный volume:

/var/airsonic/
├── airsonic.properties      # основной конфиг
├── db/                      # embedded HSQLDB (по умолчанию)
│   ├── db.script
│   ├── db.properties
│   └── db.log
├── cifs/                    # креды для сетевых шар, если используются
├── podcasts/                # скачанные эпизоды подкастов
├── thumbs/                  # кэш обложек — можно не бэкапить
└── transcode/                # временные транскоды — не бэкапить

Проверить актуальный путь легко:

docker inspect airsonic --format '{{json .Mounts}}' | python3 -m json.tool

или, если Airsonic развёрнут без Docker, посмотреть переменную окружения AIRSONIC_DIR в systemd-юните / скрипте запуска.

Бэкап встроенной базы HSQLDB и конфигурации

По умолчанию Airsonic использует embedded HSQLDB — файловую базу, которая пишется прямо в db/db.script. У HSQLDB нет фонового WAL-режима как у Postgres, поэтому копировать файлы «на живую» рискованно: можно поймать базу в момент записи и получить битый дамп.

Правильный минимальный сценарий — короткая остановка контейнера на бэкап:

#!/usr/bin/env bash
set -euo pipefail

AIRSONIC_DIR=/var/airsonic
BACKUP_DIR=/srv/backups/airsonic
DATE=$(date +%Y-%m-%d_%H%M)

mkdir -p "$BACKUP_DIR"

docker stop airsonic
tar czf "$BACKUP_DIR/airsonic-$DATE.tar.gz" \
  --exclude="$AIRSONIC_DIR/thumbs" \
  --exclude="$AIRSONIC_DIR/transcode" \
  -C / "${AIRSONIC_DIR#/}"
docker start airsonic

# ротация: хранить последние 14 архивов
find "$BACKUP_DIR" -name 'airsonic-*.tar.gz' -mtime +14 -delete

Простой у Airsonic — сервис перечитывает базу целиком при старте, так что остановка на несколько секунд для tar незаметна для пользователей, слушающих музыку через клиенты (соединение просто на секунду прервётся). Если для вас критична нулевая пауза, единственный надёжный вариант — перейти на внешнюю СУБД (следующий раздел), где есть нормальный online-бэкап.

Перенос на внешнюю СУБД для надёжности

Embedded HSQLDB хорош для домашнего сервера с парой пользователей, но у него есть ограничение: он не переживает параллельный доступ и плохо ведёт себя при внезапном обрыве питания — файл базы может повредиться без возможности восстановления. Если Airsonic обслуживает несколько человек или вы просто хотите нормальный бэкап без остановки сервиса, стоит перевести его на MariaDB или MySQL.

В airsonic.properties (или через переменные окружения контейнера) задаются JDBC-параметры:

DatabaseConfigType=external
DatabaseConfigEmbedDriver=
DatabaseConfigEmbedUrl=
DatabaseUsername=airsonic
DatabasePassword=change_me
DatabaseConfigType=external
JWTKey=сгенерированный_ключ

# JDBC для MariaDB
spring.datasource.url=jdbc:mariadb://db-host:3306/airsonic?useUnicode=true&characterEncoding=UTF-8
spring.datasource.username=airsonic
spring.datasource.password=change_me
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver

Точные имена ключей отличаются между версиями Airsonic и Airsonic-Advanced — сверьтесь с airsonic.properties.default в вашем образе перед правкой. После миграции на внешнюю базу бэкап становится тривиальным и не требует остановки контейнера:

mysqldump -u airsonic -p --single-transaction airsonic > airsonic-db-$(date +%F).sql

Флаг --single-transaction даёт консистентный снимок без блокировки таблиц — Airsonic продолжает работать, пока идёт дамп.

Автоматизация бэкапа: скрипт + cron + restic

Голый tar в cron работает, но не даёт дедупликации и шифрования. Для боевого сервера удобнее restic — он инкрементально дедуплицирует бэкапы (повторный бэкап конфига весит копейки) и умеет писать сразу в S3-совместимое хранилище.

Инициализация репозитория (один раз):

export RESTIC_REPOSITORY=s3:https://s3.example.com/my-backups/airsonic
export RESTIC_PASSWORD=надёжный-пароль-репозитория
restic init

Скрипт бэкапа, который останавливает контейнер только на копирование базы (или пропускает остановку, если вы уже на внешней СУБД):

#!/usr/bin/env bash
set -euo pipefail

AIRSONIC_DIR=/var/airsonic
export RESTIC_REPOSITORY=s3:https://s3.example.com/my-backups/airsonic
export RESTIC_PASSWORD_FILE=/etc/restic/airsonic.pass

docker stop airsonic
restic backup "$AIRSONIC_DIR" \
  --exclude "$AIRSONIC_DIR/thumbs" \
  --exclude "$AIRSONIC_DIR/transcode" \
  --tag airsonic-config
docker start airsonic

# отдельно, без остановки — дамп внешней СУБД, если она используется
# mysqldump ... | restic backup --stdin --stdin-filename airsonic-db.sql

restic forget --tag airsonic-config \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

Задача в cron (бэкап конфига раз в сутки ночью, когда меньше слушателей):

0 4 * * * /usr/local/bin/backup-airsonic.sh >> /var/log/airsonic-backup.log 2>&1

Подробно про сам restic — установку, ключи шифрования и работу с разными бэкендами — есть отдельный разбор в статье про пошаговую установку restic на Ubuntu 24.04, а если сомневаетесь между restic и альтернативой — сравнение в статье restic или Borgbackup: что выгоднее и когда.

Восстановление из бэкапа

Порядок действий при восстановлении на новом или пересобранном сервере:

1. Поднимите тот же образ Airsonic — версия должна совпадать или быть не старше той, что делала бэкап. Миграции схемы БД идут только вперёд, откатить версию с новой базой на старый Airsonic не получится.
2. Остановите контейнер, если он уже успел создать пустой /var/airsonic.
3. Разверните архив (или restore из restic) поверх целевого каталога:

docker stop airsonic
rm -rf /var/airsonic/*
tar xzf airsonic-2026-08-20_0400.tar.gz -C /

# или из restic
restic restore latest --target / --tag airsonic-config

1. Проверьте права: контейнер Airsonic обычно работает от непривилегированного пользователя (uid 1000 или отдельный airsonic), а после tar/restic восстановления файлы могут принадлежать root:

chown -R 1000:1000 /var/airsonic

1. Запустите контейнер и проверьте логи первого старта:

docker start airsonic
docker logs -f airsonic

Если использовалась внешняя СУБД — восстановите дамп до старта Airsonic:

mysql -u airsonic -p airsonic < airsonic-db-2026-08-20.sql

1. Перепривяжите медиатеку — смонтируйте те же пути к музыке, что были на исходном сервере (или пропишите новые в настройках Media Folders через веб-интерфейс, если пути изменились).

После старта зайдите под своим пользователем и проверьте плейлисты, рейтинги и подписки на подкасты — если они на месте, восстановление прошло успешно. Если музыкальная библиотека бэкапилась отдельно (как и рекомендовано в разделе выше), её нужно восстановить тем же способом, каким она резервировалась — обычно rsync или тот же restic с отдельным тегом, чтобы не смешивать с конфигом.

Что касается инфраструктуры для самого Airsonic — сервису достаточно 1-2 vCPU и 2 ГБ RAM при небольшом числе одновременных стримов; основная нагрузка появляется при транскодировании на лету для клиентов с плохим каналом. Если держите библиотеку в несколько тысяч альбомов и хотите держать бэкапы на отдельном диске от рабочих данных — конфигурация VPS с отдельным SSD под бэкапы решает это без лишних плясок с сетевыми хранилищами.

Частые вопросы