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

MAATRIX

Ampache — один из самых старых self-hosted музыкальных серверов, и это его сила: за годы он оброс поддержкой Subsonic API, DAAP, UPnP/DLNA, WebDAV и десятков клиентов, которые под капотом умеют говорить хотя бы на одном из этих протоколов. Обратная сторона возраста — классический PHP+MySQL стек с собственной логикой конфигурации, которая не всегда очевидна, если вы привыкли к современным Go- или Node-сервисам с одним бинарником. Ниже — разбор ошибок, с которыми реально сталкиваются на проде: от неверной версии PHP до зависаний транскодирования и отказов Subsonic-клиентов, по схеме «симптом — причина — решение».

С чего начинать диагностику

Ampache работает поверх обычного веб-стека, поэтому первый источник правды — логи веб-сервера и PHP, а не что-то специфичное для самого приложения:

tail -f /var/log/nginx/error.log
tail -f /var/log/php8.3-fpm.log
systemctl status php8.3-fpm nginx mariadb

Если используете Apache с mod_php, логи будут в /var/log/apache2/error.log. Второй источник — сама админка Ampache: раздел Admin → System («System Update» или «Config Check» в разных версиях) показывает версию PHP, статус подключения к базе и наличие обязательных расширений — это первое, что стоит открыть при странной проблеме, часто причина видна прямо там, без похода в логи.

Третий источник — журнал каталогов внутри самого Ampache: при сканировании библиотеки он пишет построчный отчёт о том, какие файлы добавлены, какие пропущены и почему; этот лог доступен прямо в интерфейсе после запуска Add/Update catalog и обычно информативнее общего error-лога, когда проблема именно в файлах библиотеки. Если страница вместо ошибки просто белая (white screen of death для PHP), временно включите display_errors в php.ini или посмотрите PHP error log — по умолчанию Ampache в проде эти ошибки пользователю не показывает.

Ошибки установки: версия PHP и недостающие расширения

Ampache требователен к набору PHP-расширений, и именно это чаще всего ломает установку на свежем сервере. Минимальный практический набор, который стоит поставить заранее:

apt install php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd \
  php8.3-mbstring php8.3-xml php8.3-intl php8.3-gettext php8.3-zip

Точный список расширений и поддерживаемых версий PHP уточняйте в документации к вашей версии Ampache перед установкой — проект поддерживает конкретный диапазон версий PHP, и слишком новая или слишком старая версия интерпретатора — частая причина ошибок уже на этапе установочного мастера («Requirements not met» или похожая формулировка). Если ставите Ampache из исходников с GitHub, потребуется ещё и Composer (composer install --no-dev --optimize-autoloader) — без этого шага получите Class 'X' not found при первом открытии страницы, поскольку часть зависимостей не входит в репозиторий и подтягивается отдельно. Отдельно проверьте права на директорию config/: веб-сервер (www-data или nginx) должен иметь право туда писать при первичной настройке через мастер, иначе он не сможет сохранить ampache.cfg.php.

Каталог не сканируется или новые треки не появляются

Симптом такой же, как у любого self-hosted музыкального сервера: добавили каталог, запустили сканирование, а часть (или все) треки не появились. Причин обычно три.

Первая — права доступа. Каталог добавляется в Admin → Catalogs → Add a New Catalog с указанием абсолютного пути на диске сервера; если этот путь принадлежит другому пользователю или закрыт правами 700, процесс PHP-FPM/веб-сервера его просто не прочитает:

ls -la /srv/music
chown -R www-data:www-data /srv/music
chmod -R a+rX /srv/music

Вторая — ограничение open_basedir в php.ini. Это специфика LAMP-стека, о которой часто забывают: если директива не включает путь к музыкальной библиотеке, PHP тихо откажется читать файлы за её пределами, и в интерфейсе будет пустой результат скана без явной ошибки. Проверьте php -i | grep open_basedir и при необходимости добавьте нужный путь в конфиге PHP-FPM пула.

Третья причина всплывает на больших библиотеках — таймаут. Веб-запрос на сканирование ограничен max_execution_time и memory_limit, и на библиотеке в десятки тысяч треков скан через браузер может не успеть завершиться. Увеличьте лимиты для CLI/веб-пула:

max_execution_time = 3600
memory_limit = 512M

Ещё надёжнее — использовать консольные скрипты Ampache (обычно лежат в директории bin/ дистрибутива) для запуска обновления каталога из cron, минуя ограничения веб-запроса вовсе:

php /var/www/ampache/bin/catalog_update.inc --update

Название скрипта и флаги могут отличаться между релизами — сверьтесь со списком в вашей поставке (ls bin/) и справкой --help. Файлы с повреждёнными или отсутствующими тегами (ID3/Vorbis Comments) по умолчанию тихо пропускаются с записью в лог каталога; почините теги внешним редактором и запустите скан повторно.

Транскодирование не работает или лагает

Транскодирование в Ampache завязано на внешний бинарник ffmpeg (или альтернативу вроде avconv в старых версиях), которого может не быть в системе или который недоступен пользователю веб-сервера:

sudo -u www-data ffmpeg -version

Если команда падает с ошибкой доступа или command not found — веб-интерфейс будет тормозить или обрывать поток, даже если сам Ampache вроде бы работает. Установите ffmpeg (apt install ffmpeg) и убедитесь, что PATH процесса PHP-FPM его видит — иногда веб-сервер запускается в окружении без обычного $PATH пользователя, и бинарник, который прекрасно находится из-под ssh, не находится из-под www-data.

Дальше нужно явно настроить команду транскодирования в Preferences → Streaming (или в конфиге, в зависимости от версии) — по умолчанию профиль может быть не задан, и клиент получает исходный файл без изменений. Шаблон обычно строится вокруг плейсхолдера %FILE% и целевого кодека, например транскодирование в MP3 192 kbps для мобильной сети:

ffmpeg -i %FILE% -c:a libmp3lame -b:a 192k -f mp3 -

Перед тем как считать проблему в Ampache, прогоните похожую команду вручную из-под www-data — так сразу видно, упирается ли дело в отсутствующий кодек в сборке ffmpeg, в права на файл или в саму логику приложения. Если лагает не один поток, а транскодирование при нескольких слушателях — это обычно вопрос CPU: реальное транскодирование нагружает процессор заметно сильнее простой раздачи файлов, и на бюджетном VPS с 1 vCPU три-четыре параллельных потока — уже потолок.

Subsonic API и мобильные клиенты не подключаются

Значительная часть мобильных клиентов (DSub, Ultrasonic, Symfonium, play:Sub) ходят в Ampache через встроенный Subsonic-совместимый API, а не нативный протокол. Если клиент пишет «неверный логин» или «сервер не отвечает» при правильных данных — проверяйте по порядку.

Во-первых, сам Subsonic-бэкенд должен быть включён на сервере — в части версий Ampache это отдельный модуль/плагин, который активируется явно в настройках API, а не работает «из коробки» сразу после установки. У конкретного пользователя, под которым логинится приложение, тоже должен быть разрешён доступ по API — это отдельный флаг в правах, независимый от обычного веб-логина. Во-вторых, обратите внимание на путь эндпоинта — некоторые старые клиенты жёстко ожидают /server/xml.server.php, тогда как более новые версии Ampache используют другую схему роутинга; при разночтении подключение будет молча отваливаться. В-третьих, если сервер работает по HTTPS с самоподписанным сертификатом, часть клиентов откажется подключаться без явного разрешения на недоверенный сертификат в настройках самого приложения — для внешнего доступа проще сразу оформить нормальный сертификат, чем разбираться с доверием в каждом клиенте.

Полезно проверить работу API отдельно от мобильного приложения — прямым запросом curl с валидными учётными данными:

curl "https://music.example.com/server/subsonic/rest/ping.view?u=USER&p=PASS&v=1.16.1&c=test"

Если этот запрос возвращает <subsonic-response status="ok">, проблема на стороне конкретного клиента (не тот путь, не та версия API); если возвращает ошибку авторизации или таймаут — проблема на сервере.

Доступ через реверс-прокси, SSL и большие файлы

При выносе Ampache наружу через nginx стриминг и загрузка файлов — два места, где стандартный конфиг реверс-прокси спотыкается. Рабочий блок:

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

    client_max_body_size 512M;
    proxy_read_timeout 3600s;
    proxy_buffering off;

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

client_max_body_size нужно поднять, если планируете загружать треки через веб-интерфейс, а не только сканировать локальный каталог — стандартный лимит nginx в 1 МБ обрежет любой аудиофайл почти мгновенно. proxy_buffering off и увеличенный proxy_read_timeout решают обрывы при перемотке и долгом стриминге больших FLAC-файлов — без этого nginx пытается сначала полностью забуферить ответ, и клиент упирается в таймаут раньше, чем получит первые байты. Не забудьте зеркально поднять лимиты и на стороне PHP-FPM — upload_max_filesize, post_max_size и request_terminate_timeout, иначе даже пропущенный через nginx запрос оборвётся уже на уровне PHP. Подробный разбор настройки самого прокси-слоя — в статье про nginx как реверс-прокси на сервере.

Проблемы с базой данных MySQL/MariaDB

Ampache хранит всю метаинформацию — треки, плейлисты, теги, права пользователей — в MySQL или MariaDB, и большинство «странных» глюков интерфейса на самом деле упирается в кодировку или лимиты базы. Самая частая ошибка — Incorrect string value при импорте треков с эмодзи или нестандартными символами в названии альбома или исполнителя. Причина — таблицы созданы не в utf8mb4, а в устаревшей utf8 (который на деле хранит только 3 байта на символ и не умеет в 4-байтовые emoji-последовательности):

ALTER DATABASE ampache CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Для уже созданных таблиц потребуется ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4 по каждой таблице — при первичной установке проще сразу указать utf8mb4 в мастере, чем чинить это постфактум.

Вторая частая проблема — max_allowed_packet слишком мал для крупных операций (импорт большого плейлиста, бэкап/восстановление дампа), что даёт обрыв соединения с MySQL посреди операции:

[mysqld]
max_allowed_packet = 256M

Третье — деградация интерфейса на библиотеках от сотен тысяч треков: без регулярного ANALYZE TABLE и правильных индексов запросы на поиск и построение списков альбомов начинают заметно тормозить. Общие принципы диагностики и оптимизации MySQL/MariaDB не специфичны для Ampache и разобраны в статье про MariaDB на сервере: частые ошибки и решения. А поскольку вся ценность Ampache — в базе, а не в файлах на диске (файлы можно перекачать заново, историю прослушиваний и плейлисты — нет), регулярный дамп обязателен: план настройки — в статье про бэкап MySQL на сервере.

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