unraid-xml-generator: Скилл создания Docker шаблонов

--- name: unraid-xml-generator description: | Генератор XML-файлов для пользовательских шаблонов DockerMan в Unraid. Используйте, когда пользователь запрашивает "生成 Unraid XML 模板" (сгенерировать шаблон Unraid XML), "创建 Docker 模板" (создать шаблон Docker), "为 XXX 写 Unraid 模板" (написать шаблон Unraid для XXX) или "生成 DockerMan XML" (сгенерировать XML для DockerMan) для любого контейнера. Ключевой навык, полученный (2026-04-02): Шаблоны DockerMan в Unraid поддерживают `<ExtraParams>--entrypoint /bin/sh</ExtraParams> + `<PostArgs>` для обхода `ENTRYPOINT` образа контейнера. Это позволяет переопределить любую команду запуска образа из шаблона. Переменные конфигурации используют: `<Config Name="..." Target="ENV_VAR" Default="..." Type="..." Display="..." Required="..." Mask="...">` Эти переменные становятся переменными окружения, передаваемыми в контейнер. Скрипт генерирует полный, допустимый XML-файл и, опционально, развертывает его в `/boot/config/plugins/dockerMan/templates-user/my-<name>.xml` (требуется подтверждение пользователя перед записью). --- # Генератор XML для Unraid ## Основной шаблон Ключевая идея для шаблонов Docker в Unraid: ```xml <Container version="2"> <Name>mycontainer</Name> <Repository>image:tag</Repository> <Network>bridge</Network> <!-- КЛЮЧ: переопределите ENTRYPOINT на /bin/sh --> <ExtraParams>--entrypoint /bin/sh</ExtraParams> <!-- КЛЮЧ: передайте реальную команду запуска через оболочку -ec --> <PostArgs>-ec 'реальная команда запуска здесь'</PostArgs> <!-- Пользовательские переменные конфигурации --> <Config Name="Display Name" Target="ENV_VAR" Default="..." Type="Variable" Display="always" Required="false" Mask="true">default_value</Config> <Config Name="Port" Target="PORT" Default="8080" Mode="tcp" Type="Port" Display="always" Required="true">8080</Config> <Config Name="Data Path" Target="/data" Default="/mnt/user/appdata/mycontainer" Mode="rw" Type="Path" Display="always" Required="true">/mnt/user/appdata/mycontainer</Config> </Container> ``` ## Справочник по полям шаблона | Поле | Назначение | |-------|---------| | `<Name>` | Уникальный идентификатор контейнера | | `<Repository>` | Docker-образ с тегом | | `<Registry>` | URL-адрес реестра (необязательно, информативно) | | `<Network>` | Режим сети: `bridge`, `host`, `none` | | `<Shell>` | Оболочка по умолчанию (`bash` / `sh`) | | `<ExtraParams>` | Дополнительные флаги для запуска Docker (например, `--entrypoint /bin/sh`) | | `<PostArgs>` | Команда запуска, передаваемая оболочке с параметром `-ec` | | `<WebUI>` | Формат: `http://[IP]:[PORT:nnnn]/` — отображает кнопку в интерфейсе Unraid | | `<Icon>` | URL-адрес изображения значка | | `<Category>` | Строка категории Unraid | | `<Config>` | Параметр, настраиваемый пользователем | ## Типы конфигурации | Тип | Пример | |------|---------| | `Variable` | Переменная окружения (`Target` = имя переменной окружения) | | `Port` | Отображение порта (`Mode="tcp"/"udp"`) | | `Path` | Путь к тому (`Mode="rw"/"ro"`) | | `Slider` | Числовой слайдер (требует `Min`, `Max`, `Step`) | | `Description` | Текст описания только для чтения | ## Варианты отображения конфигурации | Значение отображения | Когда отображается | |----------------|-----------| | `always` | Всегда виден в интерфейсе | | `advanced` | Скрыт за переключателем "Дополнительно" | | `hidden` | Никогда не отображается (ручная конфигурация) | ## Маскированные переменные (секреты) Установите `Mask="true"` для записей `Type="Variable"` в разделе `<Config>`, чтобы: - Скрыть значение в интерфейсе (отображается как `••••••`) - Рассматривать как конфиденциальные данные (ключи API, токены, пароли) ## Шаблон PostArgs для оболочки ```bash # Правильный способ записи PostArgs в XML: <PostArgs>-ec 'export VAR1="value1" && export VAR2="value2" && exec real_command --flag arg'</PostArgs> # Разбор: # -e : выход при ошибке # -c : чтение команды из строки (не из stdin) # '...' : строка команды в одинарных кавычках ``` ## Стандартные переменные конфигурации для включения Для любого контейнера: ```xml <Config Name="HTTP Proxy" Target="HTTP_PROXY" Default="" Type="Variable" Display="advanced" Required="false" Mask="false">http://192.168.8.30:7893</Config> <Config Name="HTTPS Proxy" Target="HTTPS_PROXY" Default="" Type="Variable" Display="advanced" Required="false" Mask="false">http://192.168.8.30:7893</Config> <Config Name="NO Proxy" Target="NO_PROXY" Default="" Type="Variable" Display="advanced" Required="false" Mask="false">localhost,127.0.0.1,192.168.0.0/16</Config> <Config Name="TZ" Target="TZ" Default="Asia/Shanghai" Type="Variable" Display="advanced" Required="false" Mask="false">Asia/Shanghai</Config> ``` ## Использование скрипта ```bash python3 scripts/generate_template.py --name opencode --image ghcr.io/anomalyco/opencode:latest --port 4096 --web-port 4097 --output /tmp/opencode.xml # Генерация со всеми стандартными переменными окружения: python3 scripts/generate_template.py --name opencode --image ghcr.io/anomalyco/opencode:latest --port 4096 --web-port 4097 --proxy 192.168.8.30:7893 --tz Asia/Shanghai --output /tmp/opencode.xml ``` ## Типичные ошибки 1. **Двойные кавычки в PostArgs** → экранируйте как `&quot;` в XML 2. **Обход ENTRYPOINT** → всегда используйте `<ExtraParams>--entrypoint /bin/sh</ExtraParams>` 3. **Подстановка переменных оболочки** → используйте одинарные кавычки для PostArgs, чтобы предотвратить расширение `$VAR` парсером XML 4. **Имя файла шаблона** → должно начинаться с `my-` и заканчиваться на `.xml` 5. **Права доступа к файлам** → Unraid запускает контейнеры с PUID/PGID = 99/100 по умолчанию ## Вывод Сгенерированный XML-файл находится по адресу: ``` /boot/config/plugins/dockerMan/templates-user/my-<name>.xml ``` Пользователь должен подтвердить, прежде чем развернуть (записать) в этот путь.