Описание конфигурационного файла
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 в Руководстве по развертыванию