Home/lampac
0
0
Fork 0
Code Pull Requests Activity
Files
7b8e28b3bfd9e46ff14b4bd62094274441d74368
lampac/AGENT.md
T

15 KiB
Raw Blame History

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 — тот же код с абсолютными путями томов Synology NAS; remote настроен как origin
  • Коммиты: git add -A && git commit && git push origin main — секреты/данные отсекает .gitignore; в git идут только compose, init.conf, mods/ (включённые модули), modules/ (резерв, не монтируется), доки, .gitignore

Продакшн: Proxmox LXC

Постоянное развёртывание — LXC 121 (lampac) на Proxmox root@192.168.88.254, контейнер root@192.168.88.23 (DHCP на vmbr0), SSH по ключу ~/.ssh/id_rsa_prodik. Проект лежит в /opt/lampac (rsync с рабочей машины, без .git).

  • Unprivileged LXC + features: nesting=1,keyctl=1 (без этого Docker не стартует), onboot: 1, 2 core / 4 GB / 32 GB.
  • SMB \\10.6.0.1\Torrents для DLNA: монтируется на хосте Proxmox в /mnt/torrents (fstab + креды /root/.smb_cred, chmod 600) и пробрасывается в контейнер mp0. Unprivileged LXC монтировать cifs не может (нет CAP_SYS_ADMIN в init userns — mount error: Operation not permitted, и это не AppArmor). В fstab обязателен uid=101000,gid=101000: маппинг LXC 0→100000, иначе в контейнере файлы видны как root и приложение (uid 1000) не пишет превью (Access to the path '/lampac/data/dlna/thumbs/' is denied).
  • Том заменён через docker-compose.override.yml (в контейнере, не в git): services.lampac.volumes: - /mnt/torrents:/lampac/data/dlna. Базовый compose хранит ./dlna — rsync-обновления его не трогают.
  • Обновление на сервере: rsync проекта → cd /opt/lampac && docker compose up -d.
  • Проверки: docker ps → healthy; эндпоинты /version?type=hash, /online.js, /ts/, /dlna, /extensions → 200; в логах нет denied|SqliteException.

Файлы

Файл Назначение Правила
docker-compose.yaml Единственный compose-файл тома обязательны; фиксированной сети/subnet нет (дефолтная сеть compose). Том ./mods:/lampac/mods ОБЯЗАТЕЛЕН — без него 10 модулей не загружаются (см. п.4)
config/init.conf Конфиг сервера (JSON) hot-reload для большинства ключей (кроме BaseModule.SkipModules — нужен рестарт); строго валидный JSON
config/passwd Пароль root, секрет не выводить в чат/логи/коммиты, в .gitignore
modules/* Старые override-копии (manifest.json ×4, extensions.json) не монтируются (убраны 01.10.2026): docs https://docs.lampac.dev/installation описывают только 6 томов (passwd, init.conf, lampainit.js, cache, database, mods/); одиночные json-тома — нештатный способ
mods/ Копии 10 модулей с enable: true (AdminPanel, DatabaseEditor, ExternalBind, LogUserRequest-Lite, Music, Telemetry, Tg-notify.bot, Tracks, Transcoding, WatchTogether) монтируется одним томом ./mods:/lampac/mods — единственный способ включить модули с enable: false в образе; при обновлении образа копии пересоздавать вручную (см. п.4)
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, ExternalBind и др.) включаются только штатно: копия всего каталога модуля с enable: true, смонтированная в /lampac/module/<Name>/, либо каталог в mods/<Name>/. Одиночные тома manifest.json/extensions.json не использовать — docs не описывают таких томов (https://docs.lampac.dev/installation, https://docs.lampac.dev/modules/overview). Список модулей: https://docs.lampac.dev/modules/overview
    • Текущее состояние (проверка: docker logs lampac | grep -c "loaded module" → 117): SkipModules пуст — включены ВСЕ модули, включая группы OnlineAnime/OnlineUKR/OnlinePaid/OnlineGEO и Transcoding. 10 модулей с enable: false в образе подняты через копии в mods/ (таблица «Файлы»). Если после обновления образа какой-то модуль из mods/ перестал компилироваться — пересоздать копию: docker cp lampac:/lampac/module/<Name> ./mods/<Name> и выставить enable: true в её manifest.json, затем docker compose up -d.
    • Плагины Lampa: /online.js, /sisi.js, /dlna.js, /ts.js и т.д. Большинство Lampac сам подключает клиенту через /lampainit.js (см. ниже про initPlugins); при необходимости плагин можно добавить вручную по URL.
    • Два уровня включения модуля: (1) SkipModules/manifest — модуль скомпилирован и работает на сервере; (2) LampaWeb.initPlugins.<name> в init.conf — плагин попадает в список {initiale}, который /lampainit.js добавляет клиенту Lampa (Lampa.Plugins.add). Без второго флага сервер отвечает, но пункт в Lampa не появится (так было с dlna — флаг initPlugins.dlna добавлен в init.conf). Сейчас подключены: dlna: true (в init.conf), из base.conf: online, sisi, torrserver, jacred, cubProxy, tmdbProxy, timecode, pirate_store. Особый случай jacred: модуль /jacred.js не регистрирует — флаг подставляет {jachost} = хост Lampac в шаблон, клиент пишет его в jackett_url (проверка: curl /api/v1.0/conf → 200).
    • Override plugins/override/lampainit.js (том ./plugins/lampainit.js) модули НЕ подключает: {initiale} сервер собирает из LampaWeb.initPlugins и подставляет в шаблон после чтения (ApiController.cs:695), т.е. и при override тоже. Override — только для правки шаблона настроек клиента (window.lampa_settings); в проекте не используется.
    • Магазин плагинов в Lampa (Настройки → Плагины) читает /extensions → образный LampaWeb/plugins/extensions.json (override-монтирование отключено). Дефект образа: 15 записей каталога ссылаются на 127.0.0.1:9118/plugins/*.js (pubtorr, checker, hotkeys, torrents...) — HTTP-роута /plugins/ в коде нет, все эти ссылки битые, устанавливать из магазина такие записи нельзя. Рабочий путь — прямой внешний URL (ручной установкой в Лампе или через LampaWeb.customPlugins; так подключён PubTorr: https://lampame.github.io/main/pubtorr.js). Если плагин уже установился с битым URL — удалить его в Лампе (Настройки → Плагины), иначе дедуп не даст добавить правильный (семейство pubtorr.js). Ответ кешируется Staticache на диске: cache/static/<bucket>/ — после правки удалить соответствующий файл (grep -rl secuses cache/static/) или весь каталог static, затем перезапросить.
    • Плагины модулей для ручной установки в Лампе (Настройки → Плагины → по URL): /tracks.js, /music.js, /tg-notify.js, /watchtogether.js (проверяются curl -o /dev/null -w '%{http_code}' http://localhost:9118/<name>.js → 200).
  5. Новые пользовательские модули и копии включаемых — класть в mods/<Name>/ (один том ./mods:/lampac/mods), переопределения шаблона настроек клиента — plugins/lampainit.js → /lampac/plugins/override/lampainit.js (модули через это НЕ подключаются — см. п.4).
  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 в образе — копия в mods/ с enable: true (см. п.4), монтирование одиночных manifest не используется.
  • 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 (новые ключи добавляются в стартовый конфиг).
View Git Blame Copy Permalink