From c28a4d1fb92187472c8722fae3b82b894cadaae6 Mon Sep 17 00:00:00 2001
From: zailon <zailon@bk.ru>
Date: Wed, 13 May 2026 21:17:36 +0500
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20docs/services/lxc203-media/navidrome.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/services/lxc203-media/navidrome.md | 229 ++++++++++++++++++++++++
 1 file changed, 229 insertions(+)
 create mode 100644 docs/services/lxc203-media/navidrome.md

diff --git a/docs/services/lxc203-media/navidrome.md b/docs/services/lxc203-media/navidrome.md
new file mode 100644
index 0000000..f34f971
--- /dev/null
+++ b/docs/services/lxc203-media/navidrome.md
@@ -0,0 +1,229 @@
+# Navidrome Music Server — LXC 203 (media)
+Контейнер: `media` (203) | Путь: `/mnt/service/navidrome` | Порты: `4533` (Web/API) | Тип: Self-hosted Subsonic-сервер + автоматическая разметка метаданных
+
+## 📋 Описание
+Лёгкий, быстрый и современный музыкальный сервер с полной поддержкой Subsonic API. Включает автоматическую нормализацию метаданных через `beets` + MusicBrainz, обход блокировок через Xray-туннель, исправление кодировки кириллицы и умные плейлисты через ListenBrainz.
+Особенности:
+✅ Полная локализация: интерфейс на русском языке (98%+ перевод)
+✅ Автоматическая разметка: `beets` + MusicBrainz для идеальных тегов и обложек
+✅ Обход блокировок: локальный SOCKS5-туннель через VPS для доступа к MusicBrainz
+✅ Кириллица: автоматическая конвертация тегов из CP1251 в UTF-8
+✅ Умные плейлисты: плагин ListenBrainz Daily Playlist («Моя волна»)
+✅ Клиенты: полная поддержка Subsonic-клиентов (Symfonium, Substreamer, Ultrasonic)
+
+## 🗂️ Структура файлов
+/mnt/service/navidrome/
+── docker-compose.yml      # Конфиг запуска сервера
+├── data/                   # База данных, настройки, кэш Navidrome
+├── plugins/                # Директория для плагинов (.ndp)
+└── navidrome.tar           # Архив для миграции между контейнерами
+/mnt/audio/                 # Точка монтирования музыкальной библиотеки
+
+## ⚙️ Установка и настройка
+### Шаг 1: Подготовка директорий и прав
+```bash
+sudo mkdir -p /mnt/service/navidrome/{data,plugins}
+sudo chown -R 1000:1000 /mnt/service/navidrome/data /mnt/service/navidrome/plugins
+sudo chmod -R a+rX /mnt/audio
+```
+
+### Шаг 2: Конфигурация Docker Compose
+Создайте файл `/mnt/service/navidrome/docker-compose.yml`:
+```yaml
+version: "3.8"
+services:
+  navidrome:
+    image: deluan/navidrome:latest
+    container_name: navidrome
+    user: "1000:1000"
+    ports:
+      - "4533:4533"
+    volumes:
+      - ./data:/data
+      - /mnt/audio:/music:ro
+      - ./plugins:/plugins:ro
+    environment:
+      - TZ=Asia/Yekaterinburg
+      - ND_MUSICFOLDER=/music
+      - ND_DATAFOLDER=/data
+      - ND_PORT=4533
+      - ND_LOGLEVEL=info
+      - ND_DEFAULTLANGUAGE=ru
+      # Система плагинов
+      - ND_PLUGINS_ENABLED=true
+      - ND_PLUGINS_FOLDER=/plugins
+      - ND_PLUGINS_AUTORELOAD=false
+      - ND_PLUGINS_LOGLEVEL=info
+      - ND_PLUGINS_CACHESIZE=200MB
+      # Плагин ListenBrainz Daily Playlist
+      - ND_PLUGINS_LISTENBRAINDAILYPLAYLIST_LISTENBRAINZTOKEN=ВАШ_ТОКЕН_ЗДЕСЬ
+      - ND_PLUGINS_LISTENBRAINDAILYPLAYLIST_PLAYLISTNAME=Моя волна
+      - ND_PLUGINS_LISTENBRAINDAILYPLAYLIST_MAXTRACKS=50
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+```
+
+### Шаг 3: Запуск и первоначальная настройка
+```bash
+cd /mnt/service/navidrome
+sudo docker compose up -d
+sudo docker compose logs -f --tail=20
+```
+Ожидаемый вывод: `INFO Starting HTTP server on :4533`. 
+Откройте `http://<IP>:4533`, создайте учётную запись администратора. Сервер автоматически просканирует `/mnt/audio`.
+
+## Автоматическая разметка метаданных (beets + MusicBrainz)
+Серверы не исправляют теги автоматически. Для чистоты библиотеки используется `beets`.
+
+### Шаг 1: Установка зависимостей
+```bash
+sudo apt update
+sudo apt install beets python3-pylast python3-requests python3-unidecode python3-mutagen
+mkdir -p ~/.config/beets
+```
+
+### Шаг 2: Конфигурация beets (`~/.config/beets/config.yaml`)
+```yaml
+directory: /mnt/audio/music
+library: ~/.config/beets/library.db
+
+import:
+  write: yes
+  copy: yes
+  move: yes
+  autotag: yes
+  group_albums: no
+
+paths:
+  default: $albumartist/$album%aunique{}/$track - $title
+  singleton: Non-Album/$artist - $title
+  comp: Various Artists/$album%aunique{}/$track - $title
+
+plugins: fetchart embedart
+
+fetchart:
+  auto: yes
+  minwidth: 500
+  maxwidth: 1000
+  enforce_ratio: yes
+  sources: [filesystem, coverart, itunes, amazon]
+
+embedart:
+  auto: yes
+  compare_threshold: 0
+  ifempty: no
+```
+
+### Шаг 3: Обход блокировок MusicBrainz (Xray-туннель)
+Если MusicBrainz недоступен из вашей сети, поднимите локальный SOCKS5-прокси через Xray (см. документацию `xray-client.md`). Запуск импорта через прокси:
+```bash
+https_proxy=socks5h://127.0.0.1:1080 http_proxy=socks5h://127.0.0.1:1080 beet import -q /mnt/audio/НоваяПапка
+```
+
+### Шаг 4: Исправление кириллицы (CP1251 → UTF-8)
+Старые сборники часто содержат теги в Windows-1251. Перед импортом конвертируйте:
+```bash
+find /mnt/audio/ЦелеваяПапка -type f -name "*.mp3" -print0 | xargs -0 mid3iconv -e cp1251
+```
+Проверка результата: `mid3v2 -l файл.mp3 | grep -E "TIT2|TPE1|TALB"`
+
+## 🧩 Плагины и умные плейлисты
+Навигроум поддерживает WASM-плагины. Для работы рекомендаций используется `listenbrainz-daily-playlist`.
+
+### Шаг 1: Установка плагина
+```bash
+cd /mnt/service/navidrome/plugins
+sudo curl -L -o listenbrainz-daily-playlist.ndp https://github.com/kgarner7/navidrome-listenbrainz-daily-playlist/releases/latest/download/listenbrainz-daily-playlist.ndp
+sudo chown 1000:1000 listenbrainz-daily-playlist.ndp
+```
+
+Шаг 2: Получение токена ListenBrainz
+1. Зарегистрируйтесь на https://listenbrainz.org
+2. Перейдите в `Profile Settings` → `User Token`
+3. Скопируйте токен и вставьте в `docker-compose.yml` в переменную `ND_PLUGINS_LISTENBRAINDAILYPLAYLIST_LISTENBRAINZTOKEN`
+4. Перезапустите контейнер: `sudo docker compose restart navidrome`
+
+### Шаг 3: Включение скробблинга в клиенте (Symfonium)
+Настройки → Интеграции → ListenBrainz → Включить → Вставить токен → Сохранить.
+Плейлист «Моя волна» появится в разделе «Плейлисты» после 5-10 прослушанных треков и автоматической генерации (раз в 24ч).
+
+## 📱 Подключение Android-клиента (Symfonium)
+1. Установите Symfonium из Google Play / F-Droid
+2. Настройки → Аккаунты → Добавить → Subsonic
+3. Заполните:
+   URL: `https://music.вашдомен.ru`
+   Логин/Пароль: от Navidrome
+   SSL/HTTPS: ✅ Включить
+   Транскодинг: ❌ Выключить
+4. Нажмите «Проверить подключение» → «Сохранить»
+5. Включите скробблинг в разделе Интеграции (см. выше)
+
+##  Полезные команды
+### Управление контейнером
+```bash
+sudo docker compose up -d          # Запуск
+sudo docker compose down           # Остановка
+sudo docker compose logs -f        # Логи в реальном времени
+sudo docker exec navidrome /navidrome --rescan  # Принудительное сканирование
+```
+
+### Работа с beets
+```bash
+beet import -q /mnt/audio/          # Тихий импорт всей библиотеки
+beet ls -f '$albumartist/$album/$title' | head -20  # Просмотр структуры в БД
+beet remove -d 'album:"Название"'   # Удалить из БД (файлы останутся)
+beet update                         # Обновить БД при изменении тегов на диске
+```
+
+### Миграция и бэкап
+```bash
+# Создание архива для переноса
+cd /mnt/service/navidrome
+sudo tar -cf navidrome.tar data docker-compose.yml plugins
+
+# Восстановление на новом сервере
+sudo tar -xf navidrome.tar
+sudo chown -R 1000:1000 data plugins
+```
+
+## 🚨 Решение проблем
+| Проблема | Причина | Решение |
+|----------|---------|---------|
+| `OCI runtime exec failed: navidrome not found` | Неверный путь к бинарнику в контейнере | Используйте `sudo docker exec navidrome /navidrome --rescan` |
+| Кракозябры вместо кириллицы | Теги в CP1251 | `find /mnt/audio -name "*.mp3" -print0 \| xargs -0 mid3iconv -e cp1251` |
+| `MusicBrainz not reachable` | Блокировка API или таймаут | Запускайте `beet` с `https_proxy=socks5h://127.0.0.1:1080` |
+| Плагин не грузится | Ошибка в конфиге или правах | Проверьте `sudo docker compose logs navidrome \| grep plugin`, убедитесь что `.ndp` читается пользователем 1000 |
+| Плейлист «Моя волна» пуст | Нет скробблов в ListenBrainz | Послушайте 5+ треков в Symfonium, проверьте ленту на listenbrainz.org, подождите 24ч |
+| Навидром не видит новые файлы | Отключено автосканирование или права | `sudo chmod -R a+rX /mnt/audio`, в UI: Настройки → Библиотека → Пересканировать |
+
+## 🔐 Безопасность
+Настройки для продакшена
+✅ Reverse Proxy: Всегда проксируйте порт 4533 через Nginx Proxy Manager с Let's Encrypt SSL
+✅ Subsonic API: Никогда не открывайте порт 4533 напрямую в интернет. Используйте только HTTPS
+✅ Xray-туннель: Прокси слушает только `127.0.0.1:1080`. Не меняйте на `0.0.0.0`
+✅ Права доступа: Контейнер работает от `1000:1000` с `no-new-privileges:true`
+✅ Пароли: Смените пароль администратора по умолчанию, используйте сложные токены для плагинов
+✅ Резервное копирование: Регулярно архивируйте папку `data/` — в ней хранится вся история прослушиваний и плейлисты
+
+## Обновление
+### Обновление ядра Navidrome
+```bash
+cd /mnt/service/navidrome
+sudo docker compose pull
+sudo docker compose up -d
+# Конфигурация и база данных сохраняются в томах, миграция происходит автоматически
+```
+
+### Обновление плагинов
+```bash
+cd /mnt/service/navidrome/plugins
+sudo curl -L -o plugin-name.ndp <новая_ссылка>
+sudo docker compose restart navidrome
+```
+
+## 💡 Рекомендации по поддержке
+• Проводите `mid3iconv` для всей библиотеки один раз при первичном развёртывании
+• Используйте флаг `-q` в `beet import` для больших библиотек (10k+ треков)
+• Включите `ND_PLUGINS_AUTORELOAD=true` только на время отладки плагинов
+• Для мониторинга используйте встроенные логи Navidrome и `htop` внутри контейнера
\ No newline at end of file