Перенос проекта: Docker-развёртывание Lampac NextGen

- Заменена структура старого деплоя (immisterio/lampac) на lampac-nextgen/lampac - docker-compose.yaml: образ ghcr.io/lampac-nextgen/lampac, тома конфига/данных/override-файлов - init.conf: SkipModules, TorrServer (LAN-only), TelegramBot, LampaWeb.initPlugins.dlna - Override-файлы: manifest (Tracks, Music, Tg-notify.bot, AdminPanel), extensions.json (магазин +DLNA) - README.md, AGENT.md, .gitignore
2026-10-01 16:22:51 +03:00
parent 3832c00cc9
commit 89267427ae
16 changed files with 787 additions and 1226 deletions
@@ -0,0 +1,81 @@
+# AGENT.md — инструкции для AI-агента
+
+## О проекте
+
+Это **deployment-репозиторий** для локального развёртывания Lampac NextGen (активный форк заброшенного Lampac) в Docker на этой машине. Исходники форка сюда не клонируются — используется официальный образ `ghcr.io/lampac-nextgen/lampac`.
+
+- Форк: https://github.com/lampac-nextgen/lampac (347+ звёзд, ежедневные коммиты, релизы)
+- Документация: https://docs.lampac.dev
+- Образ: `ghcr.io/lampac-nextgen/lampac:latest` (multi-arch: amd64/arm64)
+- Порт: **9118**, рабочая директория в контейнере: `/lampac`
+- Последняя задеплоенная версия: `1.61.2` (при установке 01.10.2026)
+
+## Файлы
+
+| Файл | Назначение | Правила |
+| --- | --- | --- |
+| `docker-compose.yaml` | Единственный compose-файл | тома обязательны; фиксированной сети/subnet нет (дефолтная сеть compose) |
+| `lampac-docker/config/init.conf` | Конфиг сервера (JSON) | hot-reload для большинства ключей (кроме `BaseModule.SkipModules` — нужен рестарт); строго валидный JSON |
+| `lampac-docker/config/passwd` | Пароль root, **секрет** | не выводить в чат/логи/коммиты, в `.gitignore` |
+| `lampac-docker/modules/*/manifest.json` | Manifest-оверрайды (`enable: true`) | монтируются поверх `/lampac/module/<Name>/manifest.json`; для модулей, у которых в образе `enable: false` (сейчас: `Tracks`, `Music`, `Tg-notify.bot`, `AdminPanel`) |
+| `lampac-docker/modules/LampaWeb/plugins/extensions.json` | Каталог магазина плагинов (`/extensions`) | override образного файла, добавлена секция «Lampac» (DLNA); после правки сбросить кеш `lampac-docker/cache/static/63/` |
+| `lampac-docker/cache/` | Кеш | монтируется в `/lampac/cache` |
+| `lampac-docker/database/` | SQLite-БД (Sync, TimeCode, SISI) | монтируется в `/lampac/database`, не удалять |
+| `dlna/` | Медиа/превью DLNA | монтируется в `/lampac/data/dlna`, не удалять |
+| `.gitignore` | Игнорируемые пути | в игноре: `config/passwd` (секрет), `cache/`, `database/`, `dlna/`, `.DS_Store`; остальное (init.conf, modules/, compose, доки) — переносимое |
+| `README.md` / `AGENT.md` | Документация | обновлять при любых изменениях развёртывания |
+
+## Основные команды
+
+```bash
+docker compose up -d                    # запуск
+docker compose pull && docker compose up -d   # обновление
+docker compose restart lampac           # рестарт (нужен только для passwd)
+docker compose logs -f --tail 100 lampac      # логи
+docker compose ps                       # статус
+curl -fsS "http://localhost:9118/version?type=hash"   # health-check (ожидается 200 + hash)
+curl -fsS -o /dev/null -w '%{http_code}\n' http://localhost:9118/online.js  # ожидается 200
+```
+
+Проверка работоспособности после любых изменений: health-check выше + контейнер в статусе `healthy`.
+
+## Правила работы
+
+1. **Отвечать по-русски.**
+2. После любых изменений в проекте — дополнять `README.md` и `AGENT.md`.
+3. Конфиг менять только в `lampac-docker/config/init.conf`; валидность проверять: `python3 -m json.tool lampac-docker/config/init.conf`.
+4. Включение/выключение модулей — через `BaseModule.SkipModules` в `init.conf` (добавить имя = выключить; имя = имя папки в `/lampac/module/`, группы вроде `OnlineAnime` выключаются целиком). `SkipModules` **не hot-reload** — после правки нужен `docker compose restart lampac`. Модули, у которых в образе `manifest.json: enable: false` (`Tracks`, `Music`, `Tg-notify.bot`, `AdminPanel`), включаются только manifest-оверрайдом: копия манифеста с `enable: true` в `lampac-docker/modules/<Name>/manifest.json` + монтирование в compose. Список модулей: https://docs.lampac.dev/modules/overview
+   - Текущее состояние: выключены `OnlineAnime`, `OnlineUKR`, `OnlinePaid`, `OnlineGEO`, `Transcoding`, `WebLog`; включены все остальные (TorrServer, Sync/TimeCode/Storage/SyncEvents, Catalog, JacRed, DLNA, SISI, Tracks, Music, Tg-notify.bot, AdminPanel).
+   - Плагины Lampa: `/online.js`, `/sisi.js`, `/dlna.js` и т.д. Большинство Lampac сам подключает клиенту через `/lampainit.js` (см. ниже про `initPlugins`); при необходимости плагин можно добавить вручную по URL.
+   - **Два уровня включения модуля:** (1) `SkipModules`/manifest — модуль скомпилирован и работает на сервере; (2) `LampaWeb.initPlugins.<name>` в `init.conf` — плагин попадает в список, который `/lampainit.js` добавляет клиенту Lampa (`Lampa.Plugins.add`). Без второго флага сервер отвечает, но пункт в Lampa не появится (так было с `dlna` — флаг `initPlugins.dlna` добавлен в init.conf). Дефолты флагов — в `current.conf` секция `LampaWeb.initPlugins`.
+   - **Магазин плагинов** в Lampa (Настройки → Плагины) читает `/extensions` → `LampaWeb/plugins/extensions.json` (каталог образа). Свои записи добавляются через override-файл в `lampac-docker/modules/LampaWeb/plugins/extensions.json` (монтирован в compose). Ответ кешируется `Staticache` на диске: `lampac-docker/cache/static/<bucket>/` — после правки удалить соответствующий файл (`grep -rl secuses lampac-docker/cache/static/`) или весь каталог static, затем перезапросить.
+5. Новые пользовательские модули класть в `lampac-docker/mods/<Name>/` (монтировать в `/lampac/mods/<Name>`), переопределения плагинов — `lampac-docker/plugins/lampainit.js` → `/lampac/plugins/override/lampainit.js`.
+6. Не раскрывать пароль из `passwd`, не коммитить его, не выводить в логи.
+7. Не открывать порт 9118 в интернет без файрвола/reverse proxy; модули `DLNA`, `Tracks`, `Transcoding`, `GStreamer`, `Catalog` не предназначены для публичного доступа.
+8. Образ пиннить по тегу при необходимости воспроизводимости (в compose сейчас `:latest`).
+
+## Структура контейнера (важные пути)
+
+```text
+/lampac/
+├── init.conf          # конфиг (смонтирован с хоста)
+├── passwd             # пароль root (смонтирован с хоста)
+├── cache/             # кеш (смонтирован)
+├── database/          # SQLite и бэкапы конфига (смонтирован)
+├── mods/              # пользовательские модули (Roslyn компилирует .cs на лету)
+├── module/            # встроенные модули образа
+├── plugins/override/  # переопределения JS-плагинов
+└── wwwroot/           # статика Lampa UI
+```
+
+Горячая перезагрузка: `init.conf` watcher каждую секунду; `mods/*.cs` перекомпилируются при изменении.
+
+## Troubleshooting
+
+- **Контейнер нестабилен / Chromium падает** — проверить `shm_size: 1024mb` в compose (обязательно для Playwright).
+- **Не стартует после правки init.conf** — проверить JSON: `python3 -m json.tool lampac-docker/config/init.conf`; бэкапы в `/lampac/database/backup/init/`.
+- **Модуль не загрузился** — смотреть `docker compose logs lampac | grep -E "skip compilation|loaded module"`; для модулей с `enable: false` в образе проверить manifest-оверрайд и его монтирование в compose.
+- **Tg-notify молчит** — нужен `bot_token` в секции `TelegramBot` init.conf (без него long polling не стартует, в логе предупреждение).
+- **Занят порт 9118** — `lsof -i :9118` или сменить порт в `init.conf` (`listen.port`) и в `ports` compose-файла одновременно.
+- **Сеть** — в compose нет фиксированной сети/subnet; используется дефолтная сеть проекта (`lampac_default`).
+- **Обновление сломало конфиг** — свериться с https://github.com/lampac-nextgen/lampac/blob/main/config/example.init.conf (новые ключи добавляются в стартовый конфиг).