Airsonic в Docker Compose: готовый файл

MAATRIX

Если оригинальный Subsonic давно закрылся от бесплатных пользователей платной подпиской, а хочется по-прежнему слушать свою коллекцию FLAC и MP3 через привычный Subsonic-клиент на телефоне — Airsonic решает эту задачу. Это открытый форк Subsonic, который поднимается одним docker-compose.yml и работает с десятками уже существующих мобильных приложений безо всякой подписки. Ниже — рабочий конфиг, разбор нюансов с выбором актуального образа и то, на что стоит обратить внимание при развёртывании на VPS.

Что такое Airsonic и почему сейчас стоит смотреть на Airsonic-Advanced

Airsonic появился как community-форк Subsonic после того, как автор Subsonic перевёл проект на закрытую модель с обязательной подпиской для использования вне локальной сети. Идея была простая: сохранить открытый Subsonic API и функциональность без ограничений — многопользовательский доступ, транскодирование на лету, поддержку подкастов, скробблинг в Last.fm, LDAP-авторизацию.

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

Чем Airsonic отличается от более молодого Navidrome, который тоже совместим с Subsonic API:

• Airsonic написан на Java и работает поверх JVM — это заметно тяжелее по памяти, чем компилируемый в нативный бинарник Go-сервер Navidrome.
• У Airsonic из коробки есть встроенная поддержка подкастов с автозагрузкой по RSS-фиду — в Navidrome этой функции нет.
• Airsonic поддерживает LDAP-авторизацию — актуально, если на сервере уже есть централизованный каталог пользователей.
• Navidrome современнее по интерфейсу и легче по ресурсам, поэтому для чистого музыкального стриминга без подкастов многие сейчас выбирают его. Сравнение похожих сценариев разобрано в статье Navidrome в Docker Compose.

Если вам принципиально нужны подкасты в том же интерфейсе или вы уже привыкли к Subsonic-экосистеме — Airsonic-Advanced остаётся рабочим и живым выбором.

Требования к серверу

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

Точные цифры зависят от размера библиотеки и числа параллельных транскодирований — это ориентир, а не результат замеров на конкретном железе. На практике безопаснее сразу брать план с 4 ГБ RAM, чем экономить и потом переносить данные на более мощный тариф.

Docker и подготовка каталогов

Если Docker ещё не установлен на Ubuntu 24.04:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Создайте структуру каталогов — данные приложения, музыка, подкасты и плейлисты держим раздельно:

mkdir -p /opt/airsonic/{data,music,podcasts,playlists}

В /opt/airsonic/music заливается коллекция — через rsync, scp или rclone, если музыка синхронизируется из облака. Как и в большинстве Subsonic-совместимых серверов, точная структура папок не критична — Airsonic индексирует по тегам, но классическая раскладка Артист/Альбом/01 - Трек.flac даёт наиболее предсказуемую группировку в интерфейсе.

Готовый docker-compose.yml

Вот рабочий конфиг с актуальным образом Airsonic-Advanced, здоровым набором переменных и правильными правами на файлы:

services:
  airsonic:
    image: airsonicadvanced/airsonic-advanced:latest
    container_name: airsonic
    restart: unless-stopped
    ports:
      - "4040:4040"
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Europe/Moscow"
      CONTEXT_PATH: "/"
      JAVA_OPTS: "-Xms512m -Xmx1536m"
    volumes:
      - ./data:/airsonic/data
      - ./music:/airsonic/music
      - ./podcasts:/airsonic/podcasts
      - ./playlists:/airsonic/playlists
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:4040/index.view"]
      interval: 30s
      timeout: 10s
      retries: 3

Пояснения по ключевым параметрам:

• PUID / PGID — идентификаторы пользователя и группы, от имени которых процесс внутри контейнера пишет в тома. Выставляйте те же значения, что у пользователя, под которым вы работаете на хосте (id -u и id -g) — иначе получите проблемы с правами доступа к файлам музыки.
• JAVA_OPTS: "-Xms512m -Xmx1536m" — жёстко ограничивает heap JVM. Без явного лимита виртуальная машина Java может попытаться забрать память по своим внутренним эвристикам, что на небольшом VPS иногда приводит к OOM-killer. Значение -Xmx подбирайте исходя из объёма RAM на сервере — оставляйте системе минимум 30-40% памяти на файловый кэш и саму ОС.
• CONTEXT_PATH — путь, по которому сервис доступен внутри контейнера. Оставляйте /, если публикуете сервис на отдельном поддомене; меняйте, только если разворачиваете по под-пути вида example.com/airsonic.
• Том ./data — здесь хранится встроенная база (HSQLDB) с пользователями, плейлистами, статистикой прослушиваний и настройками транскодирования. Это единственное, что критично для регулярного бэкапа.

Запуск:

cd /opt/airsonic
docker compose up -d
docker compose logs -f airsonic

Первый старт JVM-приложения занимает заметно больше времени, чем у лёгких Go-сервисов — дождитесь в логах строки о старте Tomcat, прежде чем открывать веб-интерфейс. По умолчанию логин и пароль администратора — admin / admin, обязательно смените пароль сразу после первого входа через Settings → Users.

Первая настройка: пользователи, транскодирование, подкасты

После входа под admin первым делом запускается сканирование медиатеки: Settings → Media Folders покажет путь /airsonic/music, который нужно добавить как источник, если он не подхватился автоматически. Полное сканирование крупной коллекции на JVM ощутимо медленнее, чем на нативных серверах — для нескольких десятков тысяч треков это может занять от нескольких минут до пары десятков, в зависимости от CPU.

Транскодирование настраивается в Settings → Transcoding. В образе уже установлен ffmpeg, дополнительно ставить ничего не нужно — достаточно указать битрейт по умолчанию для мобильных клиентов, например MP3 192-320 kbps или Opus для более эффективного сжатия у клиентов, которые его поддерживают.

Подкасты — то, чего нет у большинства альтернатив: в Podcast Receiver добавляется RSS-ссылка, и Airsonic сам скачивает новые эпизоды в /airsonic/podcasts по расписанию. Это удобно, если хочется держать музыку и подкасты в одном интерфейсе и слушать их из одного и того же мобильного клиента.

Дополнительных пользователей создавайте в Settings → Users — можно ограничивать доступ к папкам или разрешать/запрещать транскодирование для конкретной учётной записи. Удобно, если сервер общий на семью или небольшую команду.

HTTPS и доступ извне

Порт 4040 без TLS в открытый интернет выпускать не стоит — логин и пароль будут уходить в открытом виде при каждой авторизации мобильного клиента. Если на сервере уже есть Traefik, добавьте Airsonic ещё одним сервисом через лейблы:

services:
  airsonic:
    image: airsonicadvanced/airsonic-advanced:latest
    container_name: airsonic
    restart: unless-stopped
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Europe/Moscow"
      JAVA_OPTS: "-Xms512m -Xmx1536m"
    volumes:
      - ./data:/airsonic/data
      - ./music:/airsonic/music
      - ./podcasts:/airsonic/podcasts
      - ./playlists:/airsonic/playlists
    networks:
      - traefik-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.airsonic.rule=Host(`music.example.com`)"
      - "traefik.http.routers.airsonic.entrypoints=websecure"
      - "traefik.http.routers.airsonic.tls.certresolver=letsencrypt"
      - "traefik.http.services.airsonic.loadbalancer.server.port=4040"

networks:
  traefik-net:
    external: true

Если Traefik ещё не развёрнут, есть отдельный разбор — Traefik на VPS. Тем, кто не хочет разбираться с лейблами, проще поднять обычный nginx с reverse-proxy блоком на порт 4040 и получить сертификат через Certbot — вариант ничуть не хуже, просто требует отдельной конфигурации веб-сервера на хосте, а не внутри Compose-стека.

При работе через reverse proxy важно правильно передавать заголовки X-Forwarded-*, иначе Airsonic может неверно определять протокол запроса. Для Traefik это работает из коробки, для nginx заголовки нужно проставить явно (proxy_set_header X-Forwarded-Proto $scheme; и аналогично для X-Forwarded-For).

Резервное копирование и перенос данных

Вся конфигурация — пользователи, плейлисты, настройки транскодирования, история прослушиваний, подписки на подкасты — хранится в /opt/airsonic/data в виде базы HSQLDB. Именно этот каталог нужно бэкапить регулярно; саму музыкальную коллекцию можно не дублировать в бэкапах VPS, если она уже надёжно хранится в другом месте.

Простой скрипт для ежедневного бэкапа с остановкой контейнера на время архивации:

#!/bin/bash
DATE=$(date +%Y%m%d)
mkdir -p /opt/backups/airsonic
docker compose -f /opt/airsonic/docker-compose.yml stop airsonic
tar -czf /opt/backups/airsonic/data-$DATE.tar.gz -C /opt/airsonic data
docker compose -f /opt/airsonic/docker-compose.yml start airsonic
find /opt/backups/airsonic -name "*.tar.gz" -mtime +14 -delete

Остановка контейнера перед архивацией базы — не строгая необходимость для HSQLDB (в отличие от файловых БД, которые пишутся построчно), но так надёжнее гарантированно получить консистентный снимок без незакрытых транзакций. Для комплексного подхода к бэкапам всего сервера, а не только одного контейнера, стоит посмотреть, какие тома вообще стоит бэкапить и как в разных сценариях.

Перенос на новый сервер сводится к копированию каталогов data, music, podcasts, playlists и повторному запуску того же docker-compose.yml на новом хосте. Отдельной миграции базы делать не нужно — HSQLDB переезжает как обычные файлы вместе с остальными данными.

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