Як розгорнути Navidrome на власному сервері у 2026 році: монтування музики, сканування та Subsonic-застосунки

Якщо ви вже намагалися розгорнути Navidrome на власному сервері, вам, імовірно, знайомий цей неприємний стан: UI відкривається, але під час сканування файли не знаходяться, тому що шлях до музики на хості змонтовано неправильно. Повторне створення контейнера рідко виправляє розбіжність між URL, станом і залежностями.

У цьому посібнику використовується один конкретний критерій готовності — просканувати музичну бібліотеку, змонтовану лише для читання, перевірити метадані й обкладинки, відтворити трек через Subsonic-клієнт і зберегти playlist. Кожне конфігураційне рішення оцінюється за цим критерієм, а не за green badge контейнера.

Створіть резервну копію стану, який Navidrome не може відновити самостійно

Визначте точку й час відновлення для Navidrome з урахуванням бази даних Navidrome, кешу обкладинок, playlist і оригінальної музичної бібліотеки. Змонтуйте /data до bootstrap, запишіть безпечні тестові дані та замініть контейнер, щоб підтвердити фактичну постійність цього шляху. Іменований volume забезпечує збереження даних під час redeploy, але не захищає від компрометації чи втрати сервера.

Підготуйте чисте середовище для відновлення, використайте ту саму зафіксовану версію застосунку та перевірте, що користувачі, playlist, історія відтворення й метадані відновилися, а той самий Subsonic-клієнт відтворює відомий трек. Запишіть команди, виправлення ownership і тривалість операцій. Посібник із резервного копіювання задає корисний стандарт: резервна копія вважається надійною після відновлення, а не після upload.

Запустіть Navidrome, не приховуючи важливих компонентів

Використовуйте контейнер як runtime, який можна замінити, а не як джерело істини.

docker run -d \
  --name navidrome \
  --restart unless-stopped \
  -p 127.0.0.1:4533:4533 \
  -v navidrome-data:/data \
  -v /srv/music:/music:ro \
  -e ND_BASEURL=/ \
  deluan/navidrome:latest

Перед відкриттям доступу підтвердьте локальну вимогу: монтування музичної бібліотеки лише для читання та доступний для запису application data. Перевірте користувача контейнера, шляхи, доступні для запису, і listener, прив’язаний до потрібної адреси, перш ніж відкривати до нього доступ. Виконайте повний сценарій — проскануйте музичну бібліотеку, змонтовану лише для читання, перевірте метадані й обкладинки, відтворіть трек через Subsonic-клієнт і збережіть playlist — та збережіть точне посилання на image, яке дало цей результат.

Оберіть мінімально достатню топологію Navidrome

Почніть із network namespace Navidrome: його web listener працює на порту 4533, а не на host port, скопійованому з tutorial для laptop. Локальна вимога runtime — монтування музичної бібліотеки лише для читання та доступний для запису application data. Зафіксуйте її поруч з image і портом, щоб replacement host отримав ті самі локальні можливості.

Після виконання вимоги запустіть повний сценарій — проскануйте музичну бібліотеку, змонтовану лише для читання, перевірте метадані й обкладинки, відтворіть трек через Subsonic-клієнт і збережіть playlist. Запишіть логи та вимірювання для часу сканування бібліотеки, CPU під час transcoding, кешу обкладинок, кількості одночасних потоків і пропускної здатності диска. Ці дані стануть першою відомою як справна архітектурою та зроблять подальші переміщення між Dockup compute і під’єднаним сервером тестованими.

TLS — це просто, а згенеровані URL — ні

Установіть ND_BASEURL, якщо сервіс працює з subpath; в інших випадках краще використовувати окремий HTTPS host. Передавайте вибраний hostname на порт контейнера 4533, прокидайте оригінальні host і HTTPS scheme та не публікуйте додатковий прямий origin.

Перевірте Navidrome із чистого зовнішнього клієнта. Відокремлюйте помилку ingress від відомої межі застосунку — файли не знаходяться під час сканування, тому що шлях до музики на хості змонтовано неправильно. Помилки certificate, DNS або 502 належать до routing; запит, який доходить до Navidrome, але згодом завершується помилкою, належить до стану застосунку, його capacity або допоміжної вимоги. Посібник із TLS для custom domain охоплює першу групу.

П’ять перевірок, які надійніші за health контейнера

До появи реальних користувачів створіть release worksheet для Navidrome. У ньому мають бути вказані зафіксовані image і порт 4533, canonical origin, постійні шляхи та власник монтування музичної бібліотеки лише для читання з доступним для запису application data. Додайте очікуваний результат цієї транзакції: просканувати музичну бібліотеку, змонтовану лише для читання, перевірити метадані й обкладинки, відтворити трек через Subsonic-клієнт і зберегти playlist.

Використовуйте worksheet після звичайної заміни та після чистого відновлення. Відновлення приймається лише тоді, коли користувачі, playlist, історія відтворення й метадані повернулися, а той самий Subsonic-клієнт відтворює відомий трек. Також зберіть короткий resource trace, що охоплює час сканування бібліотеки, CPU під час transcoding, кеш обкладинок, кількість одночасних потоків і пропускну здатність диска; зберігайте його поруч із release, щоб майбутні зміни capacity можна було порівнювати за тим самим workload.

Додайте одну контрольовану помилку: передайте безпечні тестові дані поблизу resource або format limit, пов’язаного з цією межею: файли не знаходяться під час сканування, тому що шлях до музики на хості змонтовано неправильно. Переконайтеся, що Navidrome повідомляє про проблему на правильній межі, відновіть коректну умову та повторно запустіть транзакцію. Так ви перевірите видимість помилки, а не лише успішне виконання, і не дозволите інтерфейсу, який виглядає справним, приховати зламаний worker, callback або database connection.

Логи, які відповідають на наступне запитання

Використовуйте сканування музичної бібліотеки лише для читання, перевірку метаданих і обкладинок, відтворення треку через Subsonic-клієнт і збереження playlist як smoke test Navidrome після кожного deployment. Супровідні метрики — час сканування бібліотеки, CPU під час transcoding, кеш обкладинок, кількість одночасних потоків і пропускна здатність диска; налаштуйте alert там, де ці ресурси наближаються до рівня, який погіршує користувацьку дію.

Основний ризик змін полягає в тому, що міграції бази даних Navidrome та поведінку scanner потрібно тестувати, поки оригінальні музичні файли залишаються недоторканими. Безпечний release починається з snapshot, який можна відновити, і перевіряє будь-яку односторонню зміну стану до перемикання traffic. Якщо під час сканування файли не знаходяться, тому що шлях до музики на хості змонтовано неправильно, не видаляйте невдалий контейнер, доки не прочитаєте його конфігурацію та першу помилку.

Не надавайте Navidrome доступ до всього хоста

Завершіть bootstrap window одразу після створення першого довіреного адміністратора. Конкретна пастка Navidrome — монтування музичної бібліотеки з доступом на запис без обґрунтованої причини; безпечніша межа — монтувати музику лише для читання, захистити облікові записи та відкривати доступ тільки до streaming service, а не до бібліотеки хоста.

ND_BASEURL — це конфігурація, а не secret; зберігайте його значення явним, захищаючи окремі credentials, які використовує Navidrome. Для передавання credentials залежностей використовуйте private networking, а ролям усередині Navidrome надавайте лише мінімально необхідні дії. Не записуйте чутливі request body та відповіді provider у звичайні логи.

Зберігайте конфігурацію Navidrome явною, а routing доручіть Dockup

Routing, certificates, заміна сервісів і під’єднане storage — цілком доречні цілі для automation. Dockup обробляє це для Navidrome і може provision-ити пов’язану managed database або підключатися до сервісів на власному сервері клієнта.

Водночас Dockup не має вигадувати trust policy Navidrome. Після deployment установіть ND_BASEURL, якщо сервіс працює з subpath; в інших випадках краще використовувати окремий HTTPS host, забезпечте дотримання цієї межі — монтуйте музику лише для читання, захищайте облікові записи та відкривайте доступ тільки до streaming service, а не до бібліотеки хоста — і перевірте результат цього сценарію: проскануйте музичну бібліотеку, змонтовану лише для читання, перевірте метадані й обкладинки, відтворіть трек через Subsonic-клієнт і збережіть playlist. У результаті ви отримуєте infrastructure в один клік із acceptance test, специфічним для застосунку.

Поширені запитання

Що потрібно Navidrome для production deployment?

Маршрутизуйте контейнер Navidrome на порту 4533 через один HTTPS origin. Локальна вимога runtime — монтування музичної бібліотеки лише для читання та доступний для запису application data. Не вважайте Navidrome готовим, доки не зможете просканувати музичну бібліотеку, змонтовану лише для читання, перевірити метадані й обкладинки, відтворити трек через Subsonic-клієнт і зберегти playlist.

Які дані Navidrome потрібно включити до резервної копії?

Забезпечте постійне зберігання /data і додайте базу даних Navidrome, кеш обкладинок, playlist та оригінальну музичну бібліотеку до одного recovery manifest. Чисте відновлення Navidrome вважається успішним лише тоді, коли користувачі, playlist, історія відтворення й метадані повернулися, а той самий Subsonic-клієнт відтворює відомий трек.

Чи потрібен Navidrome HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin Navidrome, а порт 4533 залиште у внутрішньому route. Правильно застосуйте налаштування Navidrome: установіть ND_BASEURL, якщо сервіс працює з subpath; в інших випадках краще використовувати окремий HTTPS host. Для Navidrome HTTPS захищає credentials або користувацький контент під час передавання та забезпечує узгоджену поведінку клієнтів, чутливу до origin.

Як тестувати upgrade Navidrome?

Відновіть поточний стан Navidrome в ізольованому deployment, застосуйте candidate version і повторіть acceptance transaction. Зверніть особливу увагу на те, що міграції бази даних Navidrome та поведінку scanner потрібно тестувати, поки оригінальні музичні файли залишаються недоторканими. Зберігайте попередню Navidrome image, доки не зрозумієте межі міграції даних і rollback.