MediaFlowZ

MediaFlowZ — самостоятельная медиаплатформа для домашнего сервера, команды или организации. Она объединяет файловый каталог, просмотр и чтение медиа, совместный доступ и офисное редактирование, сохраняя пользовательские файлы в каталогах владельца, а метаданные — в PostgreSQL.

Возможности

• каталог файлов и папок, поиск, фильтры, избранное и плейлисты;
• просмотр изображений, аудио, видео, PDF, текста и поддерживаемых документов;
• thumbnails, preview и HLS-транскодирование через CPU, AMD или NVIDIA;
• загрузки с возобновлением, версии файлов, корзина и восстановление;
• ACL, shares, публичные ссылки и персональные настройки;
• совместное редактирование через ONLYOFFICE и открытие в локальном Office;
• опциональные WebDAV и explicit FTPS gateways;
• защищённое хранение credentials внешних подключений;
• административные индексация, диагностика, задачи и системная статистика.

Архитектура и данные

Production deployment запускается Docker Compose и включает Web, Worker, PostgreSQL, Keycloak, ONLYOFFICE, FFmpeg, Secret Store и External Storage connector. WebDAV и FTPS включаются профилем file-access. PostgreSQL доступен только во внутренней сети Compose; Web выполняет migrations под advisory lock. Worker управляет отдельным FFmpeg-контейнером через Docker socket.

Медиатека, PostgreSQL, thumbnails/conversion cache, версии, transfers, user data и data-protection keys размещаются в отдельных bind-каталогах. Секреты находятся только в защищённой папке deployment. docker-compose.generated.yml содержит host-specific пути и GPU-устройства, но не значения секретов.

Требования

• Windows 10/11 или современный x64/arm64 Linux;
• PowerShell 7.4 или новее (pwsh);
• Docker Desktop с WSL2 backend на Windows либо Docker Engine на Linux;
• Docker Compose plugin (docker compose);
• свободные порты 8070 (Web), 8071 (Keycloak) и 8082 (ONLYOFFICE);
• доверенные DNS/TLS endpoints для публичного production-доступа;
• достаточно места для медиатеки, PostgreSQL, thumbnails, версий и временных transfers.

CPU работает без GPU runtime. NVIDIA требует исправный драйвер и NVIDIA Container Toolkit. AMD на native Linux требует доступный DRM render node и VA-API driver. AMD в Docker Desktop/WSL2 использует /dev/dxg, /dev/dri и библиотеки WSL; установщик восстанавливает vgem перед каждым запуском.

Быстрый старт

Клонировать репозиторий не нужно. Скачайте единственный standalone-скрипт:

Invoke-WebRequest `
  https://git.zaharatot.ru/Zaharatot/MediaFlowZ/raw/branch/main/Install-MediaFlowZ.ps1 `
  -OutFile Install-MediaFlowZ.ps1
./Install-MediaFlowZ.ps1 -Action Install

На Linux:

curl -fLO https://git.zaharatot.ru/Zaharatot/MediaFlowZ/raw/branch/main/Install-MediaFlowZ.ps1
pwsh ./Install-MediaFlowZ.ps1 -Action Install

Скрипт сам проверит Docker, предложит его установку, обнаружит GPU, задаст несколько вопросов, создаст секреты, скачает актуальный deployment contract и запустит контейнеры. Другие файлы из репозитория рядом со скриптом не нужны.

Обычный интерактивный запуск:

./Install-MediaFlowZ.ps1 -Action Install

Для автоматизации все обязательные несекретные значения задаются явно:

./Install-MediaFlowZ.ps1 -Action Install `
  -DeploymentPath D:\MediaFlowZ `
  -MediaPath D:\Media `
  -PostgreSqlPath C:\mediaflowz-pgsql `
  -PublicUrl https://media.example.com `
  -KeycloakPublicUrl https://auth.example.com `
  -HardwareMode CPU `
  -NonInteractive

На Linux используйте те же параметры и абсолютные POSIX-пути. Отсутствующий параметр в -NonInteractive завершает установку безопасной ошибкой.

Действия установщика

./Install-MediaFlowZ.ps1 -Action Install   # создаёт или дополняет deployment
./Install-MediaFlowZ.ps1 -Action Start     # проверяет конфигурацию и запускает контейнеры
./Install-MediaFlowZ.ps1 -Action Update    # проверяет, получает образы и перезапускает deployment
./Install-MediaFlowZ.ps1 -Action Diagnose  # создаёт sanitized-отчёт без изменения host
./Install-MediaFlowZ.ps1 -Action Repair    # восстанавливает только каталоги и generated state

Укажите -DeploymentPath, если используется не стандартный C:\MediaFlowZ или /opt/mediaflowz. На Windows мастер отдельно предлагает путь PostgreSQL с целевым значением C:\mediaflowz-pgsql; его можно изменить параметром -PostgreSqlPath. На Linux по умолчанию используется <DeploymentPath>/data/postgres. Выбранный путь сохраняется в installation-state.json, и повторный Install не меняет существующие секреты и persistent paths.

Выбор GPU

Режим задаётся -HardwareMode CPU, AMD или NVIDIA. При нескольких GPU укажите индекс нужного адаптера через -GpuDeviceIndex. Установщик сохраняет его стабильный hardware ID и проверяет backend внутри FFmpeg-контейнера до запуска основных сервисов. При недоступном GPU выберите CPU явно; неуспешный аппаратный probe не скрывается автоматическим запуском.

Внутри deployment скрипт создаёт:

• docker-compose.yml — скачанный production contract всех сервисов;
• docker-compose.generated.yml в deployment — выбранный CPU/GPU backend, конкретные устройства и host-specific параметры.

docker-compose.dev.yml нужен только разработчикам в клоне репозитория. Установщик его не скачивает и не использует.

Windows + AMD + WSL2

Перед Install, Start, Update и Repair установщик выполняет modprobe vgem внутри docker-desktop, заново перечисляет /dev/dri и строит override с фактическими устройствами. Старый Start-MediaFlowZ-AMD.ps1 сохранён только как forwarding wrapper к общей команде.

Что запрашивает мастер

• deployment directory;
• абсолютный путь медиатеки;
• публичные MediaFlowZ и Keycloak URL;
• CPU/GPU backend и конкретный адаптер;
• при необходимости — включение WebDAV/FTPS.

В deployment создаются mediaflowz.env, docker-compose.generated.yml, installation-state.json, logs/, secrets/ и отдельные каталоги данных. Database passwords, Keycloak clients, ONLYOFFICE JWT, service credentials, Secret Store KEK и временный пароль первого администратора создаются криптографически стойко. Пароль первого входа хранится в secrets/mediaflowz-initial-admin-password.txt; после входа его нужно немедленно сменить.

Установщик не может безопасно придумать production DNS и доверенный TLS-сертификат. Для профиля file-access заранее подготовьте PFX и защищённый файл пароля, затем задайте их пути согласно документации gateways. Порты WebDAV и FTPS по умолчанию — 7443 и 2121; passive FTPS использует 50000–50009.

Обновление, backup и восстановление

Перед Update, обновлением major PostgreSQL и значимыми migrations сделайте согласованный backup. PostgreSQL dump не содержит медиатеку, thumbnails, версии, transfers, user data, data-protection keys, Secret Store key ring и сертификаты — их требуется сохранять отдельно из одного остановленного состояния.

• PostgreSQL: backup и restore
• Keycloak: эксплуатация и согласованный backup
• Secret Store: bootstrap, escrow и recovery
• WebDAV и FTPS
• Сборка и публикация образов

Обычные Install, Start, Update, Diagnose и Repair никогда не удаляют пользовательские данные, базы или существующие secrets.

Диагностика

./Install-MediaFlowZ.ps1 -Action Diagnose -DeploymentPath D:\MediaFlowZ -NonInteractive

Команда выводит JSON с ОС, версиями, выбранным профилем, наличием каталогов, endpoints и состояниями контейнеров. Для сохранения перенаправьте stdout в нужный защищённый файл. Diagnose сам ничего не записывает и не изменяет; secret values в отчёт не включаются.

Если запуск не проходит:

1. Проверьте docker version и docker compose version.
2. Запустите Diagnose и проверьте доступность persistent paths.
3. Для GPU проверьте host driver/runtime; для Windows AMD — доступность docker-desktop WSL.
4. Выполните Repair, если удалён только generated-файл или производный каталог.
5. Проверьте /health/live и /health/database Web, health PostgreSQL, Keycloak, Secret Store и Worker.

Не публикуйте runtime.env, secrets/, diagnostics с частными host paths или installation state. Не открывайте PostgreSQL и внутренние service endpoints в Internet. Docker socket монтируется только Worker и должен оставаться недоступным Web.

Разработка

Для разработчиков после клонирования репозитория development Compose остаётся отдельным контрактом и не участвует в пользовательской установке:

docker compose -f docker-compose.dev.yml up -d
dotnet run --project src/MediaFlowZ.Web/MediaFlowZ.Web.csproj

Мобильная MAUI-обёртка не входит в серверную установку. Правила структуры и сопровождения находятся в AGENTS.md, а текущий план рефакторинга — в Docs/info.md.

Лицензия

Проект распространяется по лицензии MIT. Лицензии контейнерных образов и внешних компонентов проверяйте отдельно перед публичным или коммерческим deployment.