Airsonic на сервере: частые ошибки и решения

MAATRIX

Airsonic поднимают за вечер, а потом полдня разбираются, почему плеер на телефоне не видит сервер, библиотека не индексируется или транскодирование падает с невнятной ошибкой в логах. Проблема в том, что Airsonic — это не одна программа, а стек из Java-приложения, индекса Lucene, базы данных и (часто) ffmpeg за reverse proxy, и большинство ошибок рождается на стыках этих частей. Разберём типичные поломки по порядку и что с ними делать.

Airsonic и Airsonic-Advanced: с чем вы на самом деле имеете дело

Оригинальный проект Airsonic — форк Subsonic, сделанный после того, как Subsonic закрыл бесплатную версию. Сам Airsonic (репозиторий airsonic/airsonic) с 2023 года развивается вяло, его сопровождение фактически перешло к форку Airsonic-Advanced, который чинит баги, обновляет зависимости и добавляет поддержку внешних СУБД. Разворачивая новый сервер в конце 2026 года, разумнее ставить именно Advanced — у неё живее issue-трекер и новее Docker-образы.

Оба варианта — Java Spring-приложения:

• слушают HTTP на порту 4040 (или 4040/4443 в контейнерных образах);
• используют Lucene-индекс для быстрого поиска по библиотеке;
• хранят метаданные, плейлисты и пользователей в базе — встроенной HSQLDB (по умолчанию) либо внешней MySQL/MariaDB/PostgreSQL (только Advanced);
• отдают музыку клиентам по Subsonic API — это открытый протокол, который понимают DSub, Ultrasonic, Substreamer, Symfonium, play:Sub и десятки других приложений.

Именно универсальность по клиентам — главная причина держать Airsonic, а не самописный стриминг: мобильное приложение уже есть под любую платформу. Но она же добавляет точку отказа — несовместимость версий API между сервером и клиентом. Держите в голове три слоя, где что-то может сломаться: JVM и системные ресурсы, файловая система с медиатекой, сеть между сервером и клиентами.

Сервис не стартует или падает: Java, память, systemd

Первое, что стоит проверить при любой проблеме — жив ли процесс и что пишет в лог.

sudo systemctl status airsonic
sudo journalctl -u airsonic -n 100 --no-pager

Если сервис в failed сразу после старта, чаще всего это одна из трёх причин.

Не та версия Java. Airsonic и Airsonic-Advanced требуют JDK 11 (некоторые сборки Advanced уже собраны под 17). Если в системе стоит 8-я или 21-я без явного указания версии в unit-файле — сервис может не запуститься или запуститься с непредсказуемым поведением.

java -version
sudo apt install openjdk-11-jdk -y
sudo update-alternatives --config java

OutOfMemoryError. JVM по умолчанию берёт долю от доступной оперативной памяти. На VPS с 1–2 ГБ ОЗУ этого может не хватить, особенно при индексации большой библиотеки или параллельном транскодировании нескольких потоков. Задайте лимит явно через переменную окружения или ключ запуска:

# в systemd unit-файле airsonic.service
Environment="JAVA_OPTS=-Xms256m -Xmx768m"

После правки — sudo systemctl daemon-reload && sudo systemctl restart airsonic. Если память кончается регулярно при сканировании больших библиотек — не хватает VPS: лучше сразу брать конфигурацию с запасом, чем гонять сервис по кругу restart-crash-restart.

Занят порт. Если 4040 уже слушает другой процесс (например, старая версия Airsonic, поднятая вручную), новый инстанс не стартует. Проверка:

sudo ss -tulpn | grep 4040

Библиотека не сканируется: файлы есть, а треков нет

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

Права доступа. Airsonic обычно работает от отдельного системного пользователя (в пакетной установке — от airsonic, в Docker-образах linuxserver — управляется через PUID/PGID). Если медиатека лежит с правами, недоступными для чтения этому пользователю, сканер молча пропускает файлы без явной ошибки в UI — смотрите логи.

sudo chown -R airsonic:airsonic /var/music
sudo chmod -R a+rX /var/music

В Docker-Compose для образа linuxserver/airsonic-advanced укажите PUID/PGID хоста явно:

services:
  airsonic:
    image: lscr.io/linuxserver/airsonic-advanced:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Moscow
    volumes:
      - ./config:/config
      - /srv/music:/music:ro
      - /srv/podcasts:/podcasts
    ports:
      - "4040:4040"
    restart: unless-stopped

Симлинки внутри контейнера. Если реальные файлы лежат вне смонтированного тома (например, симлинк на другой раздел, не проброшенный в контейнер), Airsonic видит "битую" ссылку, и файл теряется. Решение — монтировать целевой путь тоже или использовать bind-mount реальной директории напрямую, без символических ссылок внутри контейнера.

Кодировка и спецсимволы в именах файлов. Кириллица, эмодзи в тегах, разная Unicode-нормализация имён (NFC/NFD) при копировании с Windows или macOS иногда ломают индексацию отдельных альбомов. Если пропадает конкретная папка — переименуйте её в латиницу и пересканируйте.

Неверный формат-фильтр. Список поддерживаемых расширений задаётся явно (Settings → General → Media file types). Если библиотека в .opus или .dsf, а формата нет в списке — файлы просто игнорируются, это настройка по умолчанию под mp3/flac/ogg/m4a, а не баг.

Полное пересканирование: Settings → General → "Rescan media folders now". Если индекс повреждён — остановите сервис, удалите содержимое ~/.airsonic/db (только для HSQLDB, как крайняя мера и после бэкапа) и перезапустите.

Транскодирование падает или не запускается

Транскодирование нужно, когда клиент просит поток в формате/битрейте, отличном от исходного файла — типичный случай для мобильного плеера на 3G/LTE. За это отвечает внешний бинарник ffmpeg, который Airsonic сам не устанавливает.

which ffmpeg || sudo apt install ffmpeg -y

Если ffmpeg не найден, транскодирование в интерфейсе недоступно, а при стриме с ограничением битрейта клиент получает обрыв или ошибку 500. Проверьте путь к бинарнику в Settings → Transcoding — там должен стоять реальный /usr/bin/ffmpeg, а не путь из коробочной конфигурации. В Docker-образах ffmpeg обычно уже вшит — проверить можно так:

docker exec -it airsonic which ffmpeg && docker exec -it airsonic ffmpeg -version

Частая причина обрывов и заиканий именно в контейнере — исчерпание CPU: транскодирование "на лету" нескольких потоков разом на 1 vCPU перегружает процессор, даже если сам ffmpeg исправен. Снижайте целевой битрейт транскода в настройках плеера либо переносите библиотеку на сервер с запасом по CPU — транскодирование заметно прожорливее по вычислениям, чем прямая раздача файлов. Если исходники уже в удобном формате (mp3/aac невысокого битрейта), проще отключить транскодирование для Wi-Fi-подключений в клиенте — это снимает нагрузку и убирает целый класс ошибок.

Клиенты не подключаются: Subsonic API, HTTPS, reverse proxy

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

Требование HTTPS у клиента. Часть приложений (в первую очередь на iOS) по умолчанию отказывается логиниться по обычному HTTP без явной галочки "allow insecure connection" — это ограничение самого приложения, не Airsonic. Решение — включить эту опцию в клиенте (если она есть) либо, что правильнее, поставить сервер за reverse proxy с TLS.

Минимальный конфиг Nginx для Airsonic с проксированием на 4040 и поддержкой длинных запросов на стриминг:

server {
    listen 443 ssl http2;
    server_name music.example.com;

    ssl_certificate     /etc/letsencrypt/live/music.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/music.example.com/privkey.pem;

    client_max_body_size 0;
    proxy_read_timeout 3600;

    location / {
        proxy_pass http://127.0.0.1:4040;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Про выпуск и обновление сертификата — в отдельной статье про Let's Encrypt на VPS, там же разбор типичных ошибок валидации.

Несовпадение версии Subsonic API. Клиент присылает серверу заголовок с версией API, которую понимает. Если клиент старый, а сервер новее (или наоборот) — авторизация может проходить, но часть функций (плейлисты, обложки, подкасты) не работает. Обычно лечится обновлением клиента до актуальной версии из стора.

Проверка API вручную. Прежде чем винить клиент, проверьте, что сам Subsonic API отвечает — это сразу исключает половину гипотез:

curl "https://music.example.com/rest/ping.view?u=admin&p=ВАШ_ПАРОЛЬ&v=1.16.1&c=curltest&f=json"

Ответ "status":"ok" значит, что сервер и авторизация работают, а проблема — в конкретном клиенте или в сети между ним и сервером (например, файрвол блокирует порт 443 наружу или VPN клиента режет длинные keep-alive соединения на стриминг).

База данных: HSQLDB, MariaDB и что с ними делать

Встроенная HSQLDB (файловая база в ~/.airsonic/db) удобна для старта, но плохо переживает нештатное выключение сервера (kill -9, обрыв питания) и заметно проседает на десятках тысяч треков.

Если библиотека уже за 20–30 тысяч треков или сервис живёт на VPS без гарантированного чистого shutdown — стоит перейти на внешнюю СУБД. В Airsonic-Advanced это настраивается через application.properties:

DatabaseConfigType=external
DatabaseConfigEmbedDriver=org.mariadb.jdbc.Driver
DatabaseConfigEmbedUrl=jdbc:mariadb://127.0.0.1:3306/airsonic
DatabaseConfigEmbedUsername=airsonic
DatabaseConfigEmbedPassword=ВАШ_ПАРОЛЬ

Перед первым запуском создайте пустую базу и пользователя в MariaDB — схему Airsonic накатит сам при старте. Обратный перенос с HSQLDB "на лету" штатными средствами не поддерживается: переезд практически всегда означает пересоздание сервера с повторным добавлением библиотеки и плейлистов, поэтому вопрос с базой лучше решать на старте. Бэкапы обязательны в любом случае — файл HSQLDB или дамп MariaDB через cron, плюс сама медиатека, если она не на отдельном хранилище.

Отдельный класс проблем — не ошибки, а тормоза при больших библиотеках: индексация Lucene на 30–50 тысяч треков может идти десятки минут, это нормально и упирается в дисковый I/O, особенно на медленном сетевом диске. Обложки кешируются на диск при первом обращении — если в Docker кеш живёт в эфемерном слое без persistent-тома под /config, он перегенерируется на каждый рестарт. Для комфортной работы с библиотекой в несколько десятков тысяч треков закладывайте от 2 ГБ ОЗУ — это ориентир, точная цифра зависит от размера библиотеки и числа слушателей.

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