ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Путь к конфигурационному файлу Предупреждение о нескольких экземплярах и файле блокировки Чувствительная конфигурация не попадает в репозиторий Обработка ошибок при загрузке конфигурации Сохранение комментариев и минимизация записи на диск Переменные окружения для переопределения Связывание переменных окружения с конфигурацией модуля (с версии 2.9.0+) Горячая перезагрузка конфигурации Внутреннее разбиение цепочки горячей перезагрузки API чтения и удаления конфигурации getAllConfig: полный снимок конфигурации delConfig: удаление ключа конфигурации Полный пример конфигурации Конфигурация сервера Конфигурация системы владельцев (master) Цепочка проверки и добавление/удаление во время выполнения Пользовательские источники идентификации (provider) Приоритет пользователя: область действия владельцев в конечном итоге определяет пользователь Конфигурация журнала Конфигурация фреймворка Конфигурация проактивного GC Строгий режим Конфигурация хранилища Конфигурация событий Конфигурация команд Конфигурация сообщений Конфигурация входящего ящика сессии (transcript) Конфигурация локализации Конфигурация модуля Конфигурация области (scope) Единая конфигурация перезаписи событий (event.overrides) Далее
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Описание конфигурационного файла

Note

Обязательно к прочтению для ядра L1 — одна из пяти ключевых статей в разделе "Путь к чтению" на главной странице, необходима для разработки модулей.

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

ErisPulse использует конфигурационный файл в формате TOML config/config.toml для управления настройками проекта.

Путь к конфигурационному файлу

Конфигурационный файл находится в папке config/ в корне проекта:

project/
├── config/
│   └── config.toml
├── main.py

Предупреждение о нескольких экземплярах и файле блокировки

При запуске фреймворк создает файл блокировки config.lock в каталоге состояния проекта .erispulse/ и удерживает его до завершения процесса (используется для обнаружения нескольких экземпляров, использующих один каталог конфигурации; до версии 2.10 он находился в каталоге config/ под именем .erispulse_config.lock и будет автоматически удален при первом запуске после обновления). Если в логах появится предупреждение о том, что "конфигурационный файл, возможно, используется другой экземпляром ErisPulse", это означает, что два или более процессов ErisPulse записывают в один и тот же файл конфигурации (типичная сцена: несколько контейнеров монтируют один и тот же каталог config/ хост-машины) — одновременные записи будут перезаписывать друг друга, поэтому каждому экземпляру следует использовать отдельный каталог конфигурации.

Чувствительная конфигурация не попадает в репозиторий

Конфигурационный файл содержит токены (token / API key) и другие конфиденциальные данные: при инициализации фреймворка и epsdk init автоматически создается файл .gitignore в каталоге config/ (содержит только одну строку * — все файлы в каталоге не попадают в репозиторий, исключая сам файл .gitignore); если .gitignore уже существует, он не будет перезаписан. Каталог состояния .erispulse/ (файл блокировки экземпляра, файл состояния CLI) также относится к локальному состоянию машины, и шаблон проекта .gitignore уже по умолчанию игнорирует его.

Обработка ошибок при загрузке конфигурации

Фреймворк различает три состояния ошибок при загрузке config.toml и предоставляет действенные диагностические сообщения, а не просто тихо возвращается к конфигурации по умолчанию:

Состояние ошибки Условие срабатывания Поведение фреймворка
Файл отсутствует config.toml не существует Нормальный запуск, тихо используется пустая конфигурация (не выдает предупреждение)
Ошибка синтаксиса TOML Файл существует, но формат некорректен (например, отсутствуют кавычки, не закрыты скобки) Выводит номер строки/столбца и причину ошибки, и сохраняет предыдущую действительную конфигурацию и продолжает работу (изменения в файле не вступают в силу)
Ошибка доступа/другие ошибки Нет прав на чтение, ошибки ввода-вывода и т.д. Выводит ясную причину, и сохраняет предыдущую действительную конфигурацию и продолжает работу

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

Например, если вы случайно напишете port = 8000 (без кавычек строки), в логах появится примерно такое:

[ERROR] [Config] Синтаксическая ошибка в конфигурационном файле config/config.toml (строка 3, столбец 1): ...
[WARNING] [Config] Не удалось прочитать конфигурационный файл. Продолжение работы с предыдущей действительной конфигурацией, изменения в файле не вступили в силу — пожалуйста, исправьте файл и перезагрузите или перезапустите

Таким образом, вы можете сразу найти проблему на уровне логирования INFO, а не задаваться вопросом "почему мои изменения в конфигурации не вступили в силу".

Что делать, если испортить конфигурационный файл во время работы? Если вы вручную отредактируете config.toml во время работы робота и внесете синтаксическую ошибку, фреймворк при следующей записи (объединении конфигурации) выведет сообщение "Конфигурационный файл поврежден (ошибка синтаксиса, строка X), невозможно записать — пожалуйста, сначала исправьте конфигурационный файл и перезапустите", а не запутанное "ошибка записи". Изменения, которые должны быть записаны, сохраняются, и они не теряются.

Сохранение комментариев и минимизация записи на диск

Комментарии и порядок ключей в config.toml сохраняются полностью при записи фреймворком: независимо от того, используется ли setConfig(), сохранение с помощью CLI-конфигуратора или генерация шаблона конфигурации адаптером/модулем, фреймворк изменяет только соответствующие ключи, и ваши комментарии, а также порядок, не будут стерты или пересортированы (используется без потерь TOML-движок tomlclass, не трогает неизмененные части, сохраняет байты без изменений, стиль завершения строк CRLF/LF также не изменяется).

Фреймворк сдерживает записываемые данные:

  • Конфигурация по умолчанию фреймворка не записывается автоматически: gc, scope, transcript и другие встроенные значения хранятся только в памяти, в config.toml записываются только явно установленные ключи, сохраняя минимальный объем. Полный список настраиваемых параметров см. в config/config.full.example проекта, скопируйте его в config.toml и измените по мере необходимости (не настроенные параметры по-прежнему используют встроенные значения по умолчанию, поведение не меняется)
  • config.full.example автоматически поддерживается: независимо от того, выполнялся ли epsdk init, при запуске фреймворка (epsdk run / main.py) в случае отсутствия config/config.full.example автоматически генерируется полный пример конфигурации; первая строка файла является маркером, поддерживаемым фреймворком, при обновлении генератора (например, при добавлении новых параметров конфигурации, установке нового компонента) при запуске файл обновляется один раз, удаление или изменение первой строки означает ручное управление, фреймворк больше не будет перезаписывать
  • Шаблоны конфигурации адаптеров/модулей: при первом инициализации шаблон с комментариями сохраняется на диск (описание полей — это комментарии); поля, помеченные как example, не записываются на диск, только упоминаются в config.full.example для справки
  • Читаемые комментарии: комментарии в конфигурационном файле сами по себе являются документацией — ep doctor и сообщения об ошибках при проверке конфигурации будут ссылаться на оригинальные комментарии в файле (даже если вы вручную изменили комментарии, сообщения будут соответствовать текущему состоянию файла), при возникновении ошибки не нужно снова искать описание поля в документации

Переменные окружения для переопределения

Фреймворк поддерживает переопределение конфигурационных параметров ErisPulse.* с помощью переменных окружения (подходит для Docker / контейнеризации / CI-развертывания, без необходимости изменять config.toml).

Правило именования: замените точечный путь ErisPulse.<section>.<key> на все заглавные буквы, замените . на _ и добавьте префикс ERISPULSE_:

Параметр конфигурации Переменная окружения Пример значения
ErisPulse.server.port ERISPULSE_SERVER_PORT 9000
ErisPulse.server.host ERISPULSE_SERVER_HOST 0.0.0.0
ErisPulse.logger.level ERISPULSE_LOGGER_LEVEL DEBUG
ErisPulse.framework.strict_mode ERISPULSE_FRAMEWORK_STRICT_MODE 2

Описание поведения:

  • Наивысший приоритет: переменные окружения переопределяют "конфигурационный файл" и "значения по умолчанию", автоматически преобразуются по типу (bool / int / float / с) и список, разделенный запятыми
  • Не сохраняются: переопределение действует только в процессе выполнения, не записывается обратно в config.toml
  • Поддержка горячей перезагрузки: после изменения переменных окружения во время выполнения, при перезагрузке с помощью мониторинга конфигурации изменения вступают в силу
# Пример развертывания с Docker: без изменения config.toml, напрямую переопределяем порт
ERISPULSE_SERVER_PORT=9000 docker compose up -d

Примечание: ErisPulse.server.port и другие конфигурационные параметры фреймворка, получаемые через get_server_config() и другие API, подвержены влиянию переменных окружения.

Связывание переменных окружения с конфигурацией модуля (с версии 2.9.0+)

Сама конфигурация модуля (на основе ConfigClass) поддерживает привязку переменных окружения на уровне полей — в field(metadata=...) объявите env:

@dataclass
class MyConfig(BaseConfig):
    api_key: str = field(default="", metadata={
        "description": "API-ключ",
        "env": "MYMODULE_API_KEY",   # привязка переменной окружения
    })
    retries: int = field(default=3, metadata={"env": "MYMODULE_RETRIES"})

Описание поведения:

  • Приоритет: переменные окружения > config.toml > значение по умолчанию (конфигурация при горячей перезагрузке сохраняет этот приоритет)
  • Тип преобразования: значение переменной окружения автоматически преобразуется по типу поля — str остается без изменений, int / float / bool (true / 1 / yes / on) автоматически преобразуются, list / dict проходят JSON-парсинг; при неудачном преобразовании переопределение игнорируется (возвращается значение из конфигурационного файла / значения по умолчанию) и выводится предупреждение
  • Одно объявление, везде применяется: при чтении конфигурации, горячей перезагрузке, проверке используется один и тот же канал; схема конфигурационной панели будет помечена env-именем, комментарии в шаблоне config.toml также упомянут доступные переменные окружения (шаблон не записывает фактические значения переменных окружения, предотвращая утечку)
  • Полная совместимость: поведение полей, не объявленных с env, остается неизменным; прямое создание экземпляра ConfigClass (без использования канала конфигурации фреймворка) не подвержено влиянию переменных окружения
# Пример развертывания с Docker: без изменения config.toml, напрямую вставляем API-ключ модуля
MYMODULE_API_KEY=sk-xxx docker compose up -d

Как выбрать между конфигурационным классом и полем модели? Конфигурационный класс управляет "как работает модуль" (параметры поведения, горячая перезагрузка), ORM Field() управляет "какие данные были созданы пользователем" (таблицы базы данных, запросы). Оба используют одну и ту же систему ограничений и движок проверки; таблица сопоставления см. в Слое модели данных · Когда использовать какой тип объявления.

Горячая перезагрузка конфигурации

Начиная с версии 2.7.0, фреймворк системно поддерживает горячую перезагрузку конфигурации. После внешнего изменения config.toml (фоновый монитор каждые 5 секунд обнаруживает изменения) или вызова setConfig() из кода, компоненты автоматически реагируют:

Компонент Поддерживаемые параметры конфигурации Поведение
Logger logger.level / log_files / log_dir (включая параметры сегментации) / memory_limit / format / exclude_levels Автоматически переприменяются (с обнаружением изменений)
CommandHandler event.command.prefix / case_sensitive / allow_space_prefix / must_at_bot Действуют с первой следующей командой
Адаптеры framework.handler_max_concurrency Сигнал обнуления кэша, перестроение по новому значению
Активный GC framework.proactive_gc_* Конфигурация изменяется, задача GC перезапускается, поддержка изменения/отключения/переактивации во время выполнения
Master master.users Каждый вызов is_master() проверяет в реальном времени, перезапуск не требуется
Модули/Адаптеры Собственные параметры конфигурации Вызывается on_config_update(old, new)

Параметры, требующие перезапуска (небезопасно переключать во время выполнения, при изменении выводится предупреждение "Требуется перезапуск процесса для вступления в силу"):

Параметр Причина
router.cors.* / router.security.* Промежуточные слои записываются в FastAPI при запуске сервиса, безопасное переключение во время выполнения невозможно
storage.use_global_db SQLite-дескриптор файла открыт во время выполнения, безопасное переключение пути невозможно

Что делать, если редактирование и сохранение файла завершилось ошибкой? Если при редактировании config.toml возникнет временный синтаксический сбой, фреймворк сохранит предыдущую действительную конфигурацию и выведет диагностическое сообщение, не будет рассылать пустую конфигурацию компонентам (чтобы избежать ошибочного возврата on_config_update к значениям по умолчанию).

Внутреннее разбиение цепочки горячей перезагрузки

"Как компоненты узнают, что конфигурация изменилась?" — за этим стоит цепочка обнаружения → перезагрузки → рассылки:

flowchart TD
    A["Внешнее редактирование config.toml"] --> B{"Кто первым обнаружит?"}
    B -->|"Фоновый поток-монитор<br/>каждые 5 секунд опрашивает mtime"| C["_check_file_change определяет изменение"]
    B -->|"При чтении конфигурации<br/>кэш старше 60 секунд"| C
    C --> D["_load_config перезагружает TOML"]
    D --> E{"Успешно?"}
    E -->|"Нет (синтаксическая ошибка)"| F["Сохраняет предыдущую действительную конфигурацию<br/>не рассылает, выводит диагностическое сообщение"]
    E -->|"Да"| G["lifecycle.emit config.updated<br/>передает old_config / new_config"]
    G --> H["Реагируют подписчики компонентов<br/>(logger / scope / command / GC ...)"]

Две линии обнаружения (достаточно одной, обе обеспечивают резервирование):

Путь Механизм Время срабатывания
Фоновый монитор демон-поток config-watcher каждые 5 секунд wait опрашивает mtime файла максимум через 5 секунд после внешнего изменения файла
Ленивое обнаружение при любом getConfig() чтении, если кэш старше 60 секунд, сначала проверяет файл при следующем чтении конфигурации

Фреймворк не повредит сам себя: setConfig() при записи файла сохраняет "время последнего изменения, вызванного самим фреймворком", монитор при сравнении исключает его, и только внешние изменения считаются изменением.

Два типа событий изменения конфигурации:

Событие Инициатор Данные Типичный сценарий
config.set код / Dashboard вызывает setConfig() {key, old_value, new_value} одиночное изменение (генерация шаблона, запись состояния, изменение конфигурации во время выполнения)
config.updated внешнее изменение после обнаружения монитором/ленивым обнаружением {old_config, new_config, config_file} ручное редактирование config.toml

setConfig() по умолчанию задерживает запись на диск на 5 секунд (объединяет несколько записей), immediate=True записывает немедленно. Монитор обнаруживает внешнее изменение и обновляет только кэш в памяти, не записывает изменения обратно в файл.

Список автоматических реакций (обычно оба события подписаны, реакция одинаковая):

Компонент Подписка Реакция
Logger config.set + config.updated уровень/файлы/директория сегментации/память/формат/уровни исключения переприменяются (с обнаружением изменений, без изменений не изменяются)
Scope config.updated перестраивается кэш привязки области
Командная система config.updated параметры префикса/регистра/пробел/must_at_bot перезагружаются, действие срабатывает с первой следующей командой
Адаптеры config.set + config.updated handler_max_concurrency сбрасывает и перестраивает семафор
Активный GC config.set + config.updated proactive_gc_* немедленно перезапускает фоновую задачу GC
Адаптеры маршрутизация в on_config_update обратный вызов on_config_update(old, new) для каждого адаптера
Модули маршрутизация в on_config_update обратный вызов on_config_update(old, new) для каждого модуля
Хранилище config.updated изменение use_global_db только предупреждение (требуется перезапуск)
Роутер config.updated изменение cors.* / security.* только предупреждение (требуется перезапуск)

API чтения и удаления конфигурации

getAllConfig: полный снимок конфигурации

Вместо прямого чтения приватного _cache (внешнее чтение приватных свойств не защищено обратной совместимостью):

config = sdk.config.getAllConfig()     # глубокая копия снимка, изменение in-place не влияет на состояние фреймворка
config["ErisPulse"]["server"]["port"]

Вид отчета соответствует getConfig: изменения setConfig() / delete отражены, строго соответствует содержимому файла после задержки записи.

delConfig: удаление ключа конфигурации

setConfig(key, None) просто устанавливает значение в пустое, ключ остается в файле; delConfig удаляет ключ из файла:

sdk.config.delConfig("ErisPulse.modules.status.OldModule")            # задержанная запись
sdk.config.delConfig("OneBot.deprecated_key", immediate=True)         # немедленная запись
  • Поддерживает точечные пути; возвращает False, если ключ не существует
  • Запись идет по пути сохранения комментариев, остальное содержимое и порядок файла не изменяются
  • Переиспользует событие config.set (с new_value=None): существующие слушатели адаптеров / модулей on_config_update без изменений могут обнаружить удаление

Полный пример конфигурации

[ErisPulse.server]
host = "0.0.0.0"
port = 8000
auto_start = true
ssl_certfile = ""
ssl_keyfile = ""

[ErisPulse.master]
# users поддерживает два формата (выберите один):
#   глобальный владелец (действует на всех платформах): users = ["123456", "789012"]
#   владелец по платформе: users = { yunhu = ["123456"], telegram = ["789012"] }
users = {}

[ErisPulse.logger]
level = "INFO"
format = "rich"
log_files = []
log_dir = ""
log_rotation = "size"
log_max_size_mb = 10
log_backup_count = 5
log_rotation_when = "midnight"
memory_limit = 1000
exclude_levels = []

[ErisPulse.framework]
enable_lazy_loading = true
uninit_timeout = 30
strict_mode = 0

[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []

[ErisPulse.storage]
backend = "sqlite"
use_global_db = false

[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false
must_at_bot = false

[ErisPulse.event.message]
ignore_self = true

[ErisPulse.i18n]
language = "auto"

Конфигурация сервера

[ErisPulse.server]
host = "0.0.0.0"
port = 8000
auto_start = true
ssl_certfile = "/path/to/cert.pem"
ssl_keyfile = "/path/to/key.pem"
# В сценариях контейнеризации / отсутствия монтирования файлов можно встроить PEM-контент (имеет приоритет над путями certfile/keyfile)
# ssl_cert = """-----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----"""
# ssl_key = """-----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----"""
Параметр Тип Значение по умолчанию Описание
host string 0.0.0.0 Адрес прослушивания, 0.0.0.0 означает все интерфейсы
port integer 8000 Номер порта прослушивания
auto_start boolean true Автоматически запускать сервер маршрутизации при sdk.init()? Установите false, чтобы пропустить запуск сервера маршрутизации (сценарии без WebUI)
ssl_certfile string пустая строка Путь к файлу SSL-сертификата
ssl_keyfile string пустая строка Путь к файлу SSL-приватного ключа
ssl_cert string пустая строка Встроенный PEM-контент сертификата (не путь). Вместе с ssl_key имеет приоритет над ssl_certfile/ssl_keyfile путями; фреймворк временно сохраняет SSL-контекст, затем удаляет временный файл
ssl_key string пустая строка Встроенный PEM-контент приватного ключа (не путь), семантика аналогична выше

Занятость порта не является фатальной ошибкой: при запуске, если обнаруживается, что port уже занят, фреймворк пропускает запуск сервера маршрутизации и выводит предупреждение, адаптеры и модули продолжают работать (только HTTP/WS/SSE маршруты и WebUI недоступны). При диагностике "робот работает, но WebUI не открывается" сначала проверьте порт.

Конфигурация системы владельцев (master)

Система владельцев используется для определения аккаунтов «владельца фреймворка» (например, администраторов бота). master.users поддерживает три способа записи:

[ErisPulse.master]
# Способ 1: глобальные владельцы (действуют на всех платформах, включая добавленные позже)
users = ["123456", "789012"]

# Способ 2: владельцы только по платформам (dict)
# users = { yunhu = ["123456"], telegram = ["789012"] }

# Способ 3: глобальные + платформенные одновременно — ключ global в dict служит хранилищем глобальных владельцев
# users = { global = ["123456"], yunhu = ["789012"] }
Параметр Тип Значение по умолчанию Описание
users array / object пусто Список аккаунтов владельцев. Форма list означает глобальных владельцев (действуют на всех платформах); форма dict задаёт владельцев по платформам (ключ — имя платформы, ключ global — хранилище глобальных владельцев), значение — список аккаунтов владельцев этой платформы

О новых платформах: форма list и ключ global в dict оба работают по принципу «определил один раз — действует на всех платформах», поэтому при подключении новых платформ менять конфигурацию не требуется; платформенные записи действуют только на платформы с тем же именем (включая гибкое сопоставление по префиксам/подстановочным знакам). master.add(None, uid) при сохранении записывает в хранилище global, существующие платформенные записи при этом не затрагиваются.

В коде проверка выполняется через master.is_master(event) или master.is_master(platform, user_id), при каждом вызове конфигурация читается в реальном времени (поддерживается горячая перезагрузка, перезапуск не требуется):

from ErisPulse.Core import master

if master.is_master(event):
    await event.reply("Привет, хозяин")

Цепочка проверки и добавление/удаление во время выполнения

Цепочка определения владельца: владельцы из конфигурации → записи времени выполнения → цепочка provider:

from ErisPulse.Core import master

master.is_master(event)                      # определение по событию
master.is_master("yunhu", "123")             # явная проверка
master.add("yunhu", "123")                   # добавление во время выполнения (по умолчанию с сохранением; persist=False — только в памяти)
master.remove("yunhu", "123")                # удаление (по умолчанию с сохранением)
master.list()                                # сводка: {"global": [...], "<platform>": [...]}

Пользовательские источники идентификации (provider)

Помимо конфигурации, можно регистрировать пользовательские источники идентификации: fn(platform, user_id) -> bool, если встроенные источники идентификации (конфигурация + записи времени выполнения) не дали результата, они пробуются по очереди; если любой provider дал положительный ответ, аккаунт считается владельцем. Подходит для интеграции с интерфейсами администраторов адаптеров, ролями в базах данных и другими внешними системами идентификации.

Точка регистрации master.provider поддерживает два способа: через декоратор / функциональный, отмена регистрации всегда выполняется через fn.unregister() на зарегистрированной функции:

from ErisPulse.Core import master

# Способ 1: декоратор (постоянный источник идентификации, рекомендуется)
@master.provider
def admin_provider(platform, user_id):
    return user_id in {"999"}     # пользовательская логика проверки

master.is_master("yunhu", "999")   # True
admin_provider.unregister()        # отмена регистрации, когда больше не нужен

# Способ 2: функциональный (регистрация при загрузке модуля / отмена при выгрузке)
fn = master.provider(admin_provider)
fn.unregister()

Исключения provider перехватываются и пропускаются, не прерывая цепочку проверки идентификации. Привязанные методы экземпляра не могут получить unregister; для сценариев, где требуется парная регистрация/отмена регистрации, используйте функции уровня модуля.

Приоритет пользователя: область действия владельцев в конечном итоге определяет пользователь

master=True у команды — это лишь значение по умолчанию, заданное разработчиком: пользователь может в ErisPulse.event.overrides.command.<module>.<cmd>.master = true/false переопределить его, ужесточив или ослабив (см. Единую конфигурацию переопределения событий; явная настройка пользователя применяется сразу).

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

[ErisPulse.logger]
level = "INFO"
log_files = []                # Явный список файлов журнала (взаимоисключает с log_dir, имеет более высокий приоритет)
log_dir = ""                  # Каталог журнала (после установки — автоматическая сегментированная ротация)
log_rotation = "size"         # Способ сегментации: "size" / "date" / "none"
log_max_size_mb = 10          # Лимит размера одного файла в режиме size (МБ)
log_backup_count = 5          # Количество хранимых исторических файлов журнала
log_rotation_when = "midnight"  # Период ротации в режиме date: S/M/H/D/midnight
memory_limit = 1000             # Лимит записей журнала в памяти для одного модуля (0 = отключить копию журнала в памяти)
total_memory_limit = 5000       # Общий лимит записей журнала в памяти для всех модулей (0 = без ограничений)
exclude_levels = ["EVENT"]
Параметр Тип По умолчанию Описание
level string INFO Уровень журнала: TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL (TRACE — самый низкий уровень, выводит подробную отладочную информацию о внутренних процессах фреймворка)
format string rich Формат вывода журнала: rich (цветной, по умолчанию), plain (обычный текст без цвета, подходит для сбора логов/перенаправления в пайплайны), json (структурированный JSON, подходит для ELK и т. п.)
log_files array пусто Список файлов вывода журнала (явные пути, без сегментации)
log_dir string пусто Каталог вывода журнала (создаётся автоматически). После установки в каталоге создаётся erispulse.log с автоматической сегментацией по log_rotation; взаимоисключает с log_files, приоритет у log_files
log_rotation string size Способ сегментации: size (по размеру) / date (по времени) / none (без сегментации)
log_max_size_mb float 10 Лимит размера одного файла в режиме size (МБ); при превышении выполняется ротация в резервные копии .1/.2
log_backup_count integer 5 Количество хранимых исторических файлов журнала; самые старые резервные копии сверх лимита удаляются автоматически
log_rotation_when string midnight Период ротации в режиме date: S/M/H/D/midnight (по умолчанию ежедневно в полночь)
memory_limit integer 1000 Количество записей журнала, хранящихся в памяти для одного модуля; 0 — отключить копию журнала в памяти (запись в память прекращается, существующие записи сохраняются)
total_memory_limit integer 5000 Общий лимит записей журнала в памяти для всех модулей; 0 — без ограничений. При превышении по стратегии ротации удаляются самые старые записи (в первую очередь сокращается очередь модуля с наибольшим количеством записей); действует независимо от параметра memory_limit отдельного модуля
exclude_levels array пусто Блокировка указанных уровней журнала. Записи заблокированных уровней полностью отбрасываются (не записываются в память, не отправляются подписчикам, таким как Dashboard, не выводятся на печать, не записываются в файлы). Поддерживает горячее обновление

Также можно динамически переключать в коде:

from ErisPulse.Core import logger

# Сегментация по размеру: один файл 10 МБ, хранить 5 копий
logger.set_output_dir("logs", rotation="size", max_size_mb=10, backup_count=5)

# Сегментация по времени: ротация ежедневно в полночь, хранить 7 копий
logger.set_output_dir("logs", rotation="date", backup_count=7)

Note

Параметр log_dir и связанные с сегментацией настройки требуют ErisPulse 2.8.0+.

Защита конфиденциальности: содержимое отправляемых и получаемых сообщений записывается с уровнем EVENT (числовое значение 21). Установка exclude_levels = ["EVENT"] не позволит бэкенду (например, панели логов Dashboard) видеть содержимое сообщений в группах/личных чатах, не влияя при этом на логи других уровней.

Помимо файла конфигурации (с поддержкой горячего обновления), те же возможности можно переключать во время выполнения с помощью кода — при реализации административных команд вида /privacy on|off не нужно изменять конфигурацию:

from ErisPulse import logger

logger.exclude_level("EVENT")        # Блокировка уровня во время выполнения (семантика аналогична конфигурации exclude_levels)
logger.allow_level("EVENT")          # Восстановление этого уровня
logger.list_excluded_levels()        # Просмотр текущих заблокированных уровней
logger.set_format("json")            # Переключение вывода на построчный протокол JSON (аналогично конфигурационному ключу format)

Note

Для функции exclude_levels требуется ErisPulse 2.8.0+.

Конфигурация фреймворка

[ErisPulse.framework]
enable_lazy_loading = true
uninit_timeout = 30
strict_mode = 0

[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []
Параметр Тип По умолчанию Описание
enable_lazy_loading boolean true Включать ли ленивую загрузку модулей
uninit_timeout integer 30 Общий таймаут корректного завершения (в секундах), по истечении которого выполняется принудительное завершение. 0 означает отсутствие таймаута
strict_mode integer 0 Уровень строгого режима, см. описание «Строгий режим» ниже
handler_max_concurrency integer 64 Максимальное количество параллельных Task обработчиков событий; большее значение повышает пропускную способность, но увеличивает потребление памяти
handler_queue_max_pending integer 4096 Backpressure очереди при наплыве событий: лимит ожидающих handler Task для одной платформы; при превышении Task обработчика нового события отбрасывается напрямую с записью WARNING (счётчик отброшенных можно посмотреть в разделе диагностики troubleshoot); 0 означает без ограничений
offline_bot_expiry integer 3600 Время автоматического истечения записей офлайн-ботов (в секундах), 0 означает без истечения
plugins_dir string / list "plugins" Папка локальных плагинов (относительно корня проекта); добавление/удаление/изменение файлов плагинов автоматически обнаруживается watcher'ом горячей перезагрузки
watch_ignore_dirs list встроенный список Имена каталогов, игнорируемых при наблюдении файлов для горячей перезагрузки (.venv/.git/__pycache__ и т.д.); непустой список полностью заменяет встроенный список, [] означает не игнорировать никакие каталоги
watch_include_plugin_dirs boolean true Передаёт ли epsdk run --reload каталоги плагинов watcher'у горячей перезагрузки плагинов для точечной обработки (перезагрузка отдельного модуля) и исключает их из общего наблюдения
event_dedupe boolean true Идемпотентная дедупликация событий: повторные доставки событий с одинаковым id (повторная отправка на уровне соединения / повторная отправка шлюзом) распределяются только один раз
cross_account_policy string "off" Политика обработки дублирующихся приёмов между аккаунтами: обработка случая, когда одно и то же физическое сообщение поступает последовательно через несколько аккаунтов — off не связывает (события распределяются по одному как обычно); mark — в копию добавляется поле верхнего уровня multi_receipt (указывающее на первое принятое событие), после чего копия распределяется как обычно, модуль читает это поле и принимает решение самостоятельно; drop — копия отбрасывается прямо на входе распределения (дедупликация на уровне фреймворка, модуль ничего не замечает)

Конфигурация проактивного GC

После инициализации SDK запускается фоновая задача проактивного GC, которая периодически выполняет Python GC и освобождение внутренних ресурсов (очистка офлайн-ботов и т.д.). Все параметры поддерживают горячее обновление; при изменении задача немедленно перезапускается.

Параметр Тип По умолчанию Описание
proactive_gc_interval number 300 Интервал освобождения (в секундах), поддерживаются дробные значения. 0 отключает проактивный GC
proactive_gc_generation integer 0 Поколение для освобождения в обычных циклах (0/1/2, ограничивается до 0..2). Обратите внимание, что gc.collect(2) эквивалентен полному освобождению; значение по умолчанию 0 сохраняет лёгкость; глубокое освобождение периодически запускается через proactive_gc_full_every
proactive_gc_full_every integer 20 Выполнять полное освобождение каждые N циклов, 0 отключает периодическое полное освобождение. Полное освобождение ограничено порогом proactive_gc_memory_growth_mb
proactive_gc_memory_growth_mb integer 32 Порог роста памяти для полного освобождения (МБ): сравнивается с базовой линией памяти после последнего полного освобождения (приоритет у tracemalloc, затем RSS); полное освобождение выполняется только если рост достигает этого значения. 0 означает без порога
proactive_gc_idle_only boolean false Если включено, при наплыве событий (есть незавершённые pending handler) Python GC пропускается в текущем цикле, чтобы избежать пауз и конкуренции с обработкой сообщений; освобождение внутренних ресурсов не затрагивается
proactive_gc_gen0_min integer 500 Нижний порог количества мусора gen0 для запуска освобождения в обычных циклах: если gc.get_count()[0] ниже этого значения, цикл сразу пропускается (простаивающие циклы почти без накладных расходов). 0 означает освобождать всегда

Изменение 2.7.1: значение по умолчанию proactive_gc_generation изменено с 2 на 0, значение по умолчанию proactive_gc_full_every изменено с 0 на 20. Ранее generation=2 означало самое тяжёлое полное освобождение в каждом цикле; новые значения по умолчанию значительно снижают накладные расходы простоя, сохраняя при этом охват освобождения. Явно заданные старые значения продолжают действовать в соответствии со своей буквальной семантикой.

Строгий режим

Строгий режим управляет стратегией обработки несоответствующих требованиям или сбойных модулей/адаптеров на этапе загрузки. Современные модули/адаптеры должны наследоваться от соответствующих базовых классов (BaseModule/BaseAdapter); компоненты, не наследующие базовый класс, нарушают работу системы контекста фреймворка и резервной очистки, что может привести к утечке ресурсов.

Изменение 2.5.2: уровень по умолчанию изменён с 1 (пропуск) на 0 (мягкий), чтобы уменьшить количество проблем загрузки, с которыми сталкиваются новые пользователи при первом использовании. Компоненты, не наследующие базовый класс, будут загружаться с предупреждением WARNING, а не отклоняться напрямую. Чтобы восстановить старое поведение, явно установите strict_mode = 1.

Уровень Название Поведение
0 Мягкий (по умолчанию) Нарушения только предупреждаются, компоненты, не наследующие базовый класс, всё равно пытаются загрузиться (совместимость со старыми компонентами)
1 Строгий-пропуск Отклонять компоненты, не наследующие базовый класс, и пропускать их, остальное запускается нормально
2 Строгий-фатальный Собрать все нарушения, сообщить о них единым отчётом и прервать весь запуск

На каждом уровне собственные сбои компонентов, такие как «ошибки на этапах загрузки/регистрации/инициализации», всегда пропускаются; различия заключаются в следующем:

  • 0 → 1: единственное изменение поведения — «не наследует базовый класс» меняется с «всё равно загружается» на «пропускается».
  • 1 → 2: все нарушения (не наследует базовый класс, ошибка загрузки, ошибка регистрации, ошибка инициализации и т.д.) повышаются до фатальных; после сбора на контрольной точке запуска список нарушений выводится единым отчётом и запуск прерывается.

Список исключений

Если некоторые компоненты действительно временно невозможно перенести (например, старые модули, от которых есть зависимости), их можно добавить в список исключений; перечисленные компоненты даже при несоответствии требованиям будут обрабатываться в мягком режиме и продолжат загрузку:

[ErisPulse.framework.strict_mode_exceptions]
modules = ["SeTu", "SomeLegacyModule"]
adapters = ["OldAdapter"]

Когда компонент отклоняется строгим режимом, журнал явно подсказывает, как восстановить загрузку (добавить в список исключений или понизить уровень).

Взаимодействие с CLI

Предзапусковая самопроверка epsdk run (разбираемость файла конфигурации, полнота обязательной конфигурации компонентов) по умолчанию следует этой конфигурации: при значении не 0 сбой проверки отклоняет запуск, при 0 выдаётся только предупреждение с продолжением. Можно также временно переключиться без изменения конфигурации: epsdk run --strict в этом запуске включит одновременно самопроверку и строгий уровень (уровень только повышается, не понижается, передаётся в запускаемый процесс через переменную окружения ERISPULSE_FRAMEWORK_STRICT_MODE), --no-strict временно понижает до мягкого режима и только предупреждает.

Конфигурация хранилища

Начиная с версии 2.8.0, движок хранилища поддерживает три асинхронных бэкенда, API полностью одинаковы, конфигурация переключается одним кликом:

Бэкенд Драйвер Установка Особенности
SQLite (по умолчанию) aiosqlite В комплекте Нулевая конфигурация, одиночный файл, WAL-параллелизм
MySQL / MariaDB aiomysql pip install ErisPulse[mysql] Существующая инфраструктура MySQL, многократное использование
PostgreSQL asyncpg pip install ErisPulse[postgres] Сильная транзакционность, высокая параллельность
[ErisPulse.storage]
backend = "sqlite"        # "sqlite" (по умолчанию) / "mysql" / "postgres"
use_global_db = false     # Только SQLite: использовать глобальную базу данных в пакете data/config.db

[ErisPulse.storage.mysql]      # backend = "mysql" при активации
host = "127.0.0.1"
port = 3306
user = "erispulse"
password = ""
database = "erispulse"
# charset = "utf8mb4"
# pool_min = 1
# pool_max = 10

[ErisPulse.storage.postgres]   # backend = "postgres" при активации
host = "127.0.0.1"
port = 5432
user = "erispulse"
password = ""
database = "erispulse"
# pool_min = 1
# pool_max = 10
Параметр Тип Значение по умолчанию Описание
backend string sqlite Бэкенд хранилища: sqlite / mysql / postgres, переключение без изменений кода
use_global_db boolean false Только SQLite: использовать глобальную базу данных, а не проектную базу данных
storage.mysql.* table см. выше Параметры подключения MySQL (host / port / user / password / database / charset / pool)
storage.postgres.* table см. выше Параметры подключения PostgreSQL (host / port / user / password / database / pool)

Также поддерживаются переменные окружения (Docker / 12-factor): ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST.

Tip

  • После изменения параметров подключения необходимо перезапустить фреймворк; при мгновенном сбое создания пула автоматически будет повторная попытка с экспоненциальной задержкой
  • Перед переключением бэкенда можно использовать скрипт проверки: python tests/devs/test_storage_backend_verify.py --backend mysql
  • Детальные объяснения транзакций, диалектов, пользовательских бэкендов см. в Хранилищные бэкенды

Конфигурация событий

Конфигурация команд

[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false
Параметр Тип Значение по умолчанию Описание
prefix string / Префикс команд
case_sensitive boolean true Учитывать ли регистр (являются ли /Help и /help разными командами)
allow_space_prefix boolean false Разрешать ли пробел в качестве префикса
must_at_bot boolean false Требуется ли упоминание бота (@) для срабатывания команды (в личных сообщениях ограничений нет)

Конфигурация сообщений

[ErisPulse.event.message]
ignore_self = true
Параметр Тип Значение по умолчанию Описание
ignore_self boolean true Игнорировать ли собственные сообщения бота

Дедупликация событий состоит из трёх уровней, каждый из которых обрабатывает свой тип дублирования: event_dedupe (framework, повторная доставка событий с одинаковым id) → ignore_self (этот раздел, собственные сообщения бота) → cross_account_policy (framework, дубли содержимого в одной группе от разных аккаунтов). Подробнее о распределении обязанностей между уровнями см. в разделе Основные концепции адаптеров.

Конфигурация входящего ящика сессии (transcript)

[ErisPulse.transcript]
enabled = true
max_per_session = 50
ttl_hours = 168.0
self_echo = "bot"
Параметр Тип Значение по умолчанию Описание
enabled boolean true Записывать ли автоматически входящие/исходящие сообщения (после отключения запись прекращается, история остаётся доступной для запросов)
max_per_session int 50 Количество хранимых записей на одну сессию (0 = отключить обрезку для этой сессии)
ttl_hours float 168.0 Глобальный срок хранения (в часах, 0 = никогда не очищать)
self_echo string bot Обработка входящего эхо-сообщения бота (self.user_id == user_id, например OneBot report-self-message): bot = записывать как bot и помечать meta.self_echo; skip = не записывать; user = записывать как user (прежнее поведение)

О рисках и аудите политики хранения см. Входящий ящик сессии; поля атрибуции (sender / meta) и принадлежность исходящих сообщений (meta.module) также описаны в этом документе.

Конфигурация локализации

[ErisPulse.i18n]
language = "auto"
Параметр Тип Значение по умолчанию Описание
language string auto Язык отображения встроенных текстов фреймворка. Установите auto для автоматического определения системного языка, или укажите конкретный код: zh-CN, zh-TW, en, ja, ru

Конфигурация модуля

Каждый модуль может определить свою конфигурацию в конфигурационном файле:

[MyModule]
api_url = "https://api.example.com"
timeout = 30
enabled = true

В модуле читать и записывать конфигурацию:

from ErisPulse import sdk

# Чтение конфигурации
config = sdk.config.getConfig("MyModule", {})
api_url = config.get("api_url", "https://default.api.com")

# Запись конфигурации во время выполнения (отложенная запись)
sdk.config.setConfig("MyModule.timeout", 60)

# Немедленная запись в файл
sdk.config.setConfig("MyModule.timeout", 60, immediate=True)

setConfig по умолчанию использует отложенную запись (примерно каждые 5 секунд массовая запись в файл), установка immediate=True немедленно сохраняет. Изменения конфигурации запускают событие жизненного цикла config.set.

Конфигурация области (scope)

Note

Эта функция требует ErisPulse 2.8.0+.

Область определяет "в каком диапазоне действует" — какие модули доступны в какой платформе / боте / сессии (① уровень модуля), какие события принимаются для какой пользовательской / групповой / бот / адаптерной идентичности (② уровень идентичности), какие исходящие вызовы может выполнять модуль (③ уровень исходящих вызовов):

[ErisPulse.scope]
default_allow = true        # Глобальный фолбэк (false = явный отказ в строгом режиме; не влияет на исходящий уровень)
cache_size = 1024           # Размер LRU-кэша

# ① Уровень модуля (приоритет: сессия > бот > платформа; записи поддерживают точные / glob / re: регулярные выражения)
[ErisPulse.scope.platforms.onebot11]
modules = ["Chat", "Tool*"]
blocked = ["re:^Danger"]

# Подуровень привязки с merge = true объединяет с низшим уровнем по каждому элементу (по умолчанию общее перезаписывание)
[ErisPulse.scope.bots.onebot11."123456"]
modules = ["Music"]
merge = true

# ② Уровень идентичности (приоритет: пользователь > сессия > бот > адаптер; на каждом уровне записываются только allow или deny)
[ErisPulse.scope.identity.adapters.onebot11]
deny = true                 # Все события этой платформы отбрасываются на входе
[ErisPulse.scope.identity.users.onebot11]
allow = ["u_admin"]         # Поддержка glob / re: регулярных выражений
deny = ["u_bad", "spam_*"]

# ③ Уровень исходящих действий (по умолчанию разрешено все; правила встроенная таблица, записи поддерживают точные / glob / re: регулярные выражения)
[ErisPulse.scope.actions.MyModule]
send = { deny = true }                    # Полный запрет отправки
api = { allow = ["get_*"] }               # Только разрешенные стандартные API запросов
request = { deny = true }                 # Запрет обработки запросов
Параметр Тип Описание
scope.default_allow boolean Глобальный фолбэк: разрешение/отказ для модулей/идентичностей, не попавших в правила (true)
scope.cache_size integer Размер LRU-кэша (по умолчанию 1024)
scope.platforms / bots / sessions table ① Трехуровневая привязка модуля: {modules=[...], blocked=[...], merge=bool?}
scope.identity.adapters / bots / sessions / users table ② Четырехуровневая привязка идентичности: {allow=true} / {deny=true}
scope.actions.<module>.<action> table ③ Правила исходящих действий: `{allow=[...], deny=true

Подробности и API времени выполнения (модульные sdk.scope.set_module() / set_identity() / set_action(), проверка is_allowed() / is_identity_allowed() / is_action_allowed(), а также словарный фолбэк get() / set() / delete()) см. в Область (scope).

Единая конфигурация перезаписи событий (event.overrides)

Система перезаписи событий: по типу события перезаписывает поведение любого модуля, не изменяя код модуля. Стандартные типы OneBot12 (meta / message / notice / request) и расширенные типы (command) имеют свои собственные настраиваемые параметры:

[ErisPulse.event.overrides]

# message: текстовые условия (AND с условиями в коде)
[ErisPulse.event.overrides.message.ChatModule]
pattern = "闲聊*"

# notice / request / meta: detail_type белый список (записи поддерживают точные / glob / re: регулярные выражения)
[ErisPulse.event.overrides.notice.MyModule]
detail_types = ["group_increase"]

# command (расширение): параметры перезаписи (приоритет пользователя; отключение через acl deny)
[ErisPulse.event.overrides.command.MyModule.restart]
master = true               # Перезапись только для владельца фреймворка (false — разрешить ограничения владельца)
hidden = true               # Скрыть в списке помощи
aliases = ["rs"]            # Активные псевдонимы

# acl (только для command): черный/белый список пользователей (имя команды поддерживает glob / re: регулярные выражения, точные ключи имеют приоритет)
[ErisPulse.event.overrides.acl."roll*"]
allow = ["onebot11:u_vip"]  # Идентификатор пользователя "platform:user_id"
deny = ["onebot11:u_bad"]

# ACL фолбэк: разрешение (true) / строгий отказ (false) для команд без ACL
acl_default_allow = true
Параметр Тип Описание
event.overrides.message.<module> table Текстовое условие: {pattern="...", regex="..."}
event.overrides.notice / request.<module> table {detail_types=[...], pattern, regex}
event.overrides.meta.<module> table {detail_types=[...]}
event.overrides.command.<module> table Параметры перезаписи модуля (скаляры)
event.overrides.command.<module>.<command> table Параметры перезаписи команды (командный приоритет)
event.overrides.acl.<command> table Черный/белый список пользователей: {allow=[...], deny=[...]}
event.overrides.acl_default_allow boolean ACL фолбэк: разрешение (true) / строгий отказ (false) для команд без ACL

API времени выполнения (после from ErisPulse.Core.Event import overrides по подпространствам типа вызывать overrides.message.set() / overrides.command.set() / overrides.acl.set() и т.д., или через sdk.Event.overrides доступ к overrides.message.set() / overrides.command.set() / overrides.acl.set() и т.д.) См. Введение в обработку событий · Перезапись событий.

Далее

  • Продолжить по пути L1: следующая статья Обработка ошибок, научитесь писать обработку ошибок, не тормозящих фреймворк
  • Не хотите вручную писать TOML : используйте интерактивный мастер epsdk config для заполнения декларативных конфигурационных элементов, см. Справочник команд CLI · config
  • Не хотите изменять файл конфигурации при развертывании : используйте переменные среды для перекрытия конфигурационных элементов, в сочетании с методами Docker в Руководстве по развертыванию