Перейти к содержанию

Конфигурация

Конфигурационный файл описывает весь ваш бот: Telegram соединение, кто может его использовать, меню кнопок и журналирование. Вы передаете его с помощью --config командам, которые его читают — run, validate, fmt и list-functions (см. CLI).

Все ключи используют lower_snake_case. Неизвестные ключи отклонены, поэтому опечатка – это ошибка. Вы увидите эту ошибку сразу же, когда вы validate.

Обязательное означает, что проверка не удалась, если поле отсутствует или пусто после применения значений по умолчанию. Необязательные поля можно опустить; в столбце «По умолчанию» показано, какое значение будет использовано.

Впервые в проекте? Начните с Запуск в CLI, который описывает создание первой конфигурации. См. Концепции для словаря, используемого ниже.

Минимальная конфигурация

Только telegram (с токеном и одним разрешенным пользователем) и menu обязательны. Все остальное имеет значение по умолчанию:

Начните с одного разрешенного пользователя и трёх кнопок состояния

config.yaml (minimal)
telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_users:
    - "123456789"

menu:
  - name: System Status
    type: category
    icon: "🖥️"
    items:
      - name: Uptime
        type: button
        icon: "🕒"
        function: command
        command: "uptime"
      - name: Memory
        type: button
        icon: "🧮"
        function: command
        command: "free -h"
      - name: Disk Space
        type: button
        icon: "💾"
        function: command
        command: "df -h /"

Папка config-examples/ в релизе включает как минимальную, так и полный пример.

Корневые поля

Поле Тип Требуется По умолчанию Описание
telegram объект да — Настройки Telegram (см. ниже)
menu список да — Дерево меню; хотя бы один узел
function_directory строка нет не установлен Каталог YAML с пользовательскими функциями (см. правила ниже)
shell строка нет /bin/bash Оболочка используется как shell -c "<command>"
timeout продолжительность нет 60s Тайм-аут команды по умолчанию
max_output_bytes целое число нет 524288 Максимальный вывод, сохраняемый для каждой команды (см. Сколько вывода команды вы видите и Управление выводом)
output auto | text | file нет auto Как доставляется результат команды (см. Сколько выводимых команд вы видите и Управление выводом)
max_output_messages целое число нет 2 Только в корне. В режиме auto отправить файл .txt, если результат потребовал бы больше этого числа сообщений (1–10). Не указывайте, чтобы оставить 2. См. Управление выводом
workdir строка нет текущий каталог процесса Рабочий каталог по умолчанию для команд
env объект нет пустой Дополнительные переменные среды для команд
menu_columns целое число нет 2 Кнопки элементов в каждой строке под окном сообщения
page_size целое число нет 8 Элементов на странице до нумерации страниц
confirm_ttl продолжительность нет 5m Как долго приглашение confirmation остается действительным
delivery_retry_backoff продолжительность нет 1s Только для корня. Начальная пауза перед первой повторной попыткой после неудачной отправки. См. Повторные попытки доставки
delivery_retry_backoff_max продолжительность нет 30s Только для корня. Максимальная пауза между попытками. См. Повторные попытки доставки
delivery_retry_ttl продолжительность нет 2m Только для корня. Общее время, в течение которого бот продолжает попытки, прежде чем сдаться (отмечается только в журнале сервера). См. Повторные попытки доставки
enable_run_command логическое значение нет false Покажите кнопку $ >_ Run Command, которая запускает следующее сообщение как команду оболочки. По умолчанию выключено. Любой, кто может использовать бота, сможет затем выполнить любую команду на хосте, поэтому включайте это только в том случае, если вы доверяете каждому разрешенному пользователю. Помещение этого ключа в telegram недействительно.
logging объект нет встроенный журнал по умолчанию Именованные журналы (см. ниже)
Что, если я пропущу shell?

Его можно не указывать. Бот использует /bin/bash. То же самое для timeout, page_size, и другие необязательные корневые поля: опустите их, и будут применяться значения по умолчанию. Вам нужно только чтобы установить их, если вам нужно значение, отличное от значения по умолчанию (например, shell: /bin/sh).

Сколько выводимых команд вы видите

Применяются два ограничения, одно за другим. max_output_bytes — это ваш лимит поверх лимита Telegram, который нельзя изменить.

1. Ваш лимит: max_output_bytes (по умолчанию 524288, т. е. 512 КБ).

Пока команда выполняется, бот сохраняет не больше этого объёма вывода отдельно для обычного вывода и ошибок. Всё сверх этого отбрасывается, но сама команда продолжает работу до завершения или timeout. В этом случае результат начинается с (output truncated).

2. Как доставляется результат: output (по умолчанию auto)

Telegram допускает не больше 4096 байт в одном сообщении. Бот может разбить длинный результат на несколько ответных сообщений или отправить полный вывод файлом .txt. Выберите режим ключом output в корне или переопределите его на одной кнопке:

Значение Поведение
auto Текстовые сообщения, пока результат умещается в max_output_messages сообщений (по умолчанию 2). Если нужно больше — один файл .txt.
text Всегда дробить на текстовые сообщения. По-прежнему останавливается после 10 сообщений и отмечает обрезку.
file Всегда отправлять один файл .txt с короткой подписью (имя кнопки, код выхода, длительность).

В режимах auto и file файл включает заголовок, stdout и stderr, поэтому повышение max_output_bytes действительно доставляет больше вывода. Если отправка файла не удалась, бот сначала автоматически повторяет попытку и возвращается к текстовым сообщениям только после того, как сдался. См. Повторные попытки доставки.

Писать output и max_output_messages не обязательно. Если их нет, бот использует auto и 2. Уже работающий файл не меняется. max_output_messages есть только в корне. На кнопке не указывайте output, чтобы взять корневое значение; задайте его только если эта кнопка всегда должна слать файл или всегда оставаться текстом.

Для длинных журналов предпочитайте output: auto (по умолчанию) или output: file на этой кнопке. Команду по-прежнему можно укоротить, если нужен только хвост лога.

Подробнее: Управление выводом

Этим трём полям посвящена отдельная страница. Она разбирает каждое сочетание корня и кнопки по очереди и показывает картинку чата Telegram для каждого случая.

Открыть «Управление выводом»

function_directory правила

Ситуация Результат
Ключ отсутствует Информационный журнал; только встроенные функции
Ключ присутствует, но пуст ("") Информационный журнал; только встроенные функции
Ключ установлен на путь, который не существует или недоступен Критическая ошибка; процесс останавливается
Путь существует, но каталог пуст ОК

Неверный путь останавливает бота

Если function_directory указывает на папку, которая не существует или не может быть прочитать, программа останавливается с ошибкой вместо того, чтобы запуститься без вашего пользовательские функции.

telegram

Поле Тип Требуется По умолчанию Описание
bot_token строка да — Токен бота от BotFather
allowed_users список строк да — Разрешенные пользователи
api строка нет https://api.telegram.org Базовый URL-адрес API бота
proxy.enabled логическое значение нет false Использовать прокси для Telegram API
proxy.url строка условный — Требуется, если proxy.enabled — true
insecure логическое значение нет false Пропустить проверку TLS (не рекомендуется)

Неавторизованные пользователи получают сообщение со своими user_id и username, чтобы они могли запросить доступ у администратора. Точно так же вы сможете найти свой собственный идентификатор в первый раз — см. Запуск в CLI → Шаг 5.

Подключиться через прокси

telegram section with a proxy
telegram:
  bot_token: "123456789:AAExampleTokenValue"
  allowed_users:
    - "123456789"        # числовой id пользователя
    - "@alice"           # или имя пользователя
  proxy:
    enabled: true
    url: "socks5://127.0.0.1:10808"

Чтобы разрешенные пользователи могли вводить команды оболочки из Telegram, установите это в корне файла (не в telegram):

Добавьте одну корневую настройку

Enable the Run Command button
enable_run_command: true

Этот раздел является справочником по полю. Подробное объяснение с примерами см. Меню. Каждая кнопка или узел категории:

Поле Тип Требуется Описание
name строка да Отображаемое имя (уникальное среди соседних элементов без учёта регистра)
type category | button да Тип узла
items список да, если category Дочерние элементы; категория должна иметь хотя бы один
function строка да, если button Имя функции
command строка да, если function: command Команда оболочки для встроенного command
path строка да, если function: script Путь к скрипту для встроенного script
icon строка нет Дополнительный префикс эмодзи
id строка нет Необязательный идентификатор для этого узла. Его можно не указывать
confirm логическое значение нет Запросите подтверждение перед запуском (по умолчанию false)
timeout продолжительность нет Переопределить глобальный тайм-аут
workdir строка нет Переопределить рабочий каталог
env объект нет Дополнительные переменные окружения для этой кнопки
columns целое число нет Переопределить столбцы для этой категории
output auto | text | file нет Необязательно. Не указывайте, чтобы взять корневой output. Задайте только чтобы заставить эту кнопку в file или text (см. Сколько выводимых команд вы видите и Управление выводом)
args строка нет Необязательные аргументы для script
Любое объявленное имя параметра скаляр как объявлено функцией Значение, передаваемое выбранной функции, например url, host, unit или lines

Для кнопки любой другой скалярный ключ рассматривается как параметр функции. Его имя должно соответствовать параметру, объявленному выбранной функцией. Неизвестные имена параметров не проходят validate. Значения, объявленные как int или bool также проверяются. Строки, числа и логические значения можно записывать напрямую как значения YAML; числа не нуждаются в кавычках.

В категории любой ключ за пределами полей категории выше является ошибкой. Категории не запускают функции, поэтому у них не может быть ключей параметров.

command, path и args — поля ярлыков, которые заполняют параметры те же имена. Другие имена parameter записываются напрямую на кнопке. Не размещайте значения кнопок внутри вложенной карты params:. См. Функции → Передача значений из кнопки.

logging

Необязательно. Если этот параметр опущен, используется консольный журнал по умолчанию на stderr по адресу info.

Именованные журналы:

Запись обычных журналов и файла аудита

logging section with an audit file
logging:
  logs:
    default:
      level: info
      format: console   # или JSON
      output:
        - output: stderr
    audit:
      level: info
      format: json
      output:
        - output: file
          file: /var/log/telegram-commander/audit.log

Поддерживаемые места вывода: stdout, stderr, file, discard.

Показанный выше журнал audit записывает каждую запущенную команду (кто, какая кнопка, код выхода, продолжительность). См. Журнал аудита .

Похожие страницы