lampac/AGENT.md

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)
• Git: ssh://git@gitea.prodik.ru:222/prodik/lampac.git, основная ветка main (ветка synology — старая, не трогать); remote настроен как origin
• Коммиты: git add -A && git commit && git push origin main — секреты/данные отсекает .gitignore; в git идут только compose, init.conf, modules/, доки, .gitignore

Файлы

Файл	Назначение	Правила
docker-compose.yaml	Единственный compose-файл	тома обязательны; фиксированной сети/subnet нет (дефолтная сеть compose)
config/init.conf	Конфиг сервера (JSON)	hot-reload для большинства ключей (кроме BaseModule.SkipModules — нужен рестарт); строго валидный JSON
config/passwd	Пароль root, секрет	не выводить в чат/логи/коммиты, в .gitignore
modules/*/manifest.json	Manifest-оверрайды (enable: true)	монтируются поверх /lampac/module/<Name>/manifest.json; для модулей, у которых в образе enable: false (сейчас: Tracks, Music, Tg-notify.bot, AdminPanel)
modules/LampaWeb/plugins/extensions.json	Каталог магазина плагинов (/extensions)	override образного файла, добавлена секция «Lampac» (DLNA); после правки сбросить кеш cache/static/63/
cache/	Кеш	монтируется в /lampac/cache
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	Документация	обновлять при любых изменениях развёртывания

Основные команды

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. Конфиг менять только в config/init.conf; валидность проверять: python3 -m json.tool 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 в 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-файл в modules/LampaWeb/plugins/extensions.json (монтирован в compose). Ответ кешируется Staticache на диске: cache/static/<bucket>/ — после правки удалить соответствующий файл (grep -rl secuses cache/static/) или весь каталог static, затем перезапросить.
5. Новые пользовательские модули класть в mods/<Name>/ (монтировать в /lampac/mods/<Name>), переопределения плагинов — plugins/lampainit.js → /lampac/plugins/override/lampainit.js.
6. Не раскрывать пароль из passwd, не коммитить его, не выводить в логи.
7. Не открывать порт 9118 в интернет без файрвола/reverse proxy; модули DLNA, Tracks, Transcoding, GStreamer, Catalog не предназначены для публичного доступа.
8. Образ пиннить по тегу при необходимости воспроизводимости (в compose сейчас :latest).

Структура контейнера (важные пути)

/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 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 (новые ключи добавляются в стартовый конфиг).