name: erispulse-config-cli description: "适用于：配置声明式 schema、排查配置问题、使用 epsdk 命令行与部署。覆盖场景：- После изменения параметров подключения необходимо перезапустить фреймворк; при мгновенном сбое создания пула автоматически будет повторная попытка с экспоненциальной задержкой。Когда нужно читать эту страницу: забыли параметры команды epsdk, хотите добавить управление компонентами в скрипт, или хотите контролировать поведение run / stop / restart. Для повседневного использования init / install / run достаточно знать одну команду: epsdk <команда> --help — всегда можно посмотреть описание параметров, не читая всю статью.。Когда нужно читать эту статью: если вам нужно выбрать способ установки (pip / uv / Docker / клиентское приложение ErisPulse-App) или если установка не удалась и требуется устранение неполадок. Если вы хотите просто быстро запустить, 5-минутный старт уже охватывает самый простой процесс, и эту статью можно пропустить.。когда бот должен длительно работать на постоянной основе — здесь всё о развёртывании в..."

ErisPulse 配置系统与 CLI 工具链

This skill is auto-built from the ErisPulse documentation. Repository: https://github.com/ErisPulse/ErisPulse Source paths are annotated per section; see docs/ in the repository for the latest content.

内容大纲

AI 按需读取：只读需要的章节即可，不必全文加载。

• 配置系统: 69-80 行
• Путь к конфигурационному файлу: 82-99 行
• Обработка ошибок при загрузке конфигурации: 101-122 行
• Сохранение комментариев и минимизация записи на диск: 124-133 行
• Переменные окружения для переопределения: 135-187 行
• Горячая перезагрузка конфигурации: 189-257 行
• API чтения и удаления конфигурации: 259-283 行
• Полный пример конфигурации: 285-337 行
• Конфигурация сервера: 339-367 行
• Конфигурация системы владельца: 369-436 行
• Конфигурация журналирования: 438-486 行
• Конфигурация фреймворка: 488-559 行
• Конфигурация хранилища: 561-608 行
• Конфигурация событий: 610-637 行
• Конфигурация входящего ящика сессии (transcript): 639-656 行
• Конфигурация локализации: 658-667 行
• Конфигурация модуля: 669-696 行
• Конфигурация области (scope): 698-742 行
• Единая конфигурация перезаписи событий (event.overrides): 744-785 行
• Далее: 787-791 行
• CLI 参考: 793-806 行
• Команды управления пакетами: 808-815 行
• Команды диагностики: 817-964 行
• Команды для просмотра информации: 966-1029 行
• Команды конфигурации: 1031-1082 行
• Команды управления запуском: 1084-1174 行
• Команды управления проектом: 1176-1286 行
• Команды языка: 1288-1323 行
• Команды для генерации типовых аннотаций: 1325-1364 行
• Глобальные параметры: 1366-1379 行
• Диагностика окружения: 1381-1422 行
• Интерактивная установка: 1424-1435 行
• Общие способы использования: 1437-1564 行
• Далее: 1566-1570 行
• 安装: 1572-1579 行
• Системные требования: 1581-1585 行
• Способы установки: 1587-1660 行
• Инициализация проекта и установка модулей: 1662-1673 行
• Проверка установки: 1675-1698 行
• Часто задаваемые вопросы: 1700-1742 行
• Далее: 1744-1748 行
• 部署: 1750-1759 行
• Развёртывание в Docker (рекомендуется): 1761-1851 行
• Панель управления Dashboard: 1853-1879 行
• Супервизия процессов и жёсткий перезапуск: 1881-1890 行
• Проверка состояния: 1892-1912 行
• Обратный прокси: 1914-1944 行
• Ручное развёртывание (pip): 1946-2037 行
• Рекомендации по безопасности: 2039-2046 行
• Развёртывание нескольких экземпляров: 2048-2054 行
• Обновление и обслуживание: 2056-2109 行
• Следующие шаги: 2111-2116 行

配置系统

来源: docs/ru/user-guide/configuration.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/ru/user-guide/configuration.md）

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

В этой статье описывается конфигурационный файл самого фреймворка 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 и предоставляет действенные диагностические сообщения, а не просто тихо возвращается к конфигурации по умолчанию:

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

Например, если вы случайно напишете 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_:

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

• Наивысший приоритет: переменные окружения переопределяют "конфигурационный файл" и "значения по умолчанию", автоматически преобразуются по типу (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() из кода, компоненты автоматически реагируют:

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

Что делать, если редактирование и сохранение файла завершилось ошибкой? Если при редактировании 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 ...）"]

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

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

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

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

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

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-----"""

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

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

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

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

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

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

from ErisPulse.Core import master

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

Цепочка проверки и изменение во время выполнения

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

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>": [...]}

Пользовательские источники идентификации (провайдеры)

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

Регистрация через 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: функциональный (регистрация в модуле / отмена в unload)
fn = master.provider(admin_provider)
fn.unregister()

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

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

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

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

[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"]

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

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)

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

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

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

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

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

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

Изменение 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: единственное изменение поведения — компоненты, «не наследующие базовый класс», меняются с «всё равно загружать» на «пропускать».
• 1 → 2: все нарушения (не наследует базовый класс, сбой загрузки, сбой регистрации, сбой инициализации и т.д.) становятся фатальными; после сбора на контрольной точке запуска весь список нарушений выводится однократно, и запуск прерывается.

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

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

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

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

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

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

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

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

[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

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

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

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

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

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

[ErisPulse.event.message]
ignore_self = true

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

[ErisPulse.transcript]
enabled = true
max_per_session = 50
ttl_hours = 168.0
self_echo = "bot"

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

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

[ErisPulse.i18n]
language = "auto"

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

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

[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)

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

[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 }                 # Запрет обработки запросов

Подробности и 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

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

CLI 参考

来源: docs/ru/user-guide/cli-reference.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/ru/user-guide/cli-reference.md）

Справочник командной строки

epsdk — это инструмент командной строки ErisPulse: инициализация проекта, установка / обновление модулей и адаптеров, интерактивная настройка компонентов, запуск и остановка робота, диагностика среды — всё это доступно одной командой.

Совет: epsdk (без команды) показывает основную справку по категориям: Проект (init / create / run), Управление компонентами (install / uninstall / upgrade / list / list-remote / types), Конфигурация и диагностика (config / doctor / i18n), Прочее (self-update / version).

Команды управления пакетами

Команды диагностики

install

Установка пакетов модуля или адаптера ErisPulse. Если имя пакета не указано, запускается интерактивный установщик.

Алиас: i, add

Связь с uv (2.11.1+): в проектах, управляемых uv (существует uv.lock или [tool.uv]), install / upgrade / uninstall автоматически используют uv add / uv remove — зависимости записываются в pyproject.toml и uv.lock, uv sync больше не удаляет компоненты, установленные через epsdk; в случае сбоя автоматически возвращается к uv pip / pip. Параметры, не поддерживаемые uv, например --user, используют pip. Порядок определения целевой среды: ERISPULSE_PYTHON → UV_PROJECT_ENVIRONMENT → .venv проекта → UV_PYTHON → VIRTUAL_ENV → текущий интерпретатор (команда epsdk doctor показывает полную цепочку).

Параметры:

Примеры:

# Установка одного модуля
epsdk install Weather

# Установка нескольких модулей
epsdk install Yunhu Weather

# Установка из зеркала и обновление
epsdk install Weather -U --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Установка в режиме редактирования (для разработки)
epsdk install -e ./my-adapter

uninstall

Удаление установленного модуля или адаптера ErisPulse. Если имя пакета не указано, запускается интерактивный удалитель.

Алиас: rm, remove

Параметры:

Примеры:

# Удаление одного модуля
epsdk uninstall Weather

# Удаление нескольких модулей
epsdk uninstall Yunhu Weather

upgrade

Обновление установленных компонентов ErisPulse. Если имя пакета не указано, запускается интерактивное обновление всех.

Алиас: up

Параметры:

Примеры:

# Обновление всех пакетов
epsdk upgrade

# Обновление указанного пакета
epsdk upgrade Weather

# Принудительное обновление (без подтверждения)
epsdk upgrade -f

self-update

Обновление самого ErisPulse SDK до последней версии.

Алиас: su, update

Параметры:

Примеры:

# Обновление до последней стабильной версии
epsdk self-update

# Обновление до указанной версии
epsdk self-update 1.2.3

# Разрешить предварительные версии
epsdk self-update --pre

# Принудительное обновление
epsdk self-update -f

Команды для просмотра информации

list

Вывод списка установленных модулей и адаптеров ErisPulse.

Алиас: l, ls

Параметры:

Примеры:

# Вывод всех установленных компонентов
epsdk list

# Только модули
epsdk list -t modules

# Только адаптеры
epsdk list -t adapters

# Только обновляемые пакеты
epsdk list -o

list-remote

Вывод списка доступных удалённых модулей и адаптеров ErisPulse.

Алиас: lsr

Параметры:

Примеры:

# Вывод всех доступных удалённых компонентов
epsdk list-remote

# Только удалённые модули
epsdk list-remote -t modules

# Обновление кэша и вывод
epsdk list-remote -r

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

config

Интерактивное заполнение конфигурационных параметров адаптера/модуля. Визуальный помощник генерируется на основе класса конфигурации (ConfigClass / AccountConfigClass), автоматически создаёт форму и проводит валидацию, без необходимости ручного редактирования config.toml.

Адаптеры дополнительно поддерживают управление несколькими аккаунтами (бот-аккаунтами): добавление/редактирование/удаление аккаунтов, а также включение/отключение.

Алиас: cfg, conf

Параметры:

Примеры:

# Просмотр состояния всех адаптеров/модулей
epsdk config --list

# Вывод состояния в JSON (для CI / скриптов)
epsdk config --json

# Интерактивный выбор цели для конфигурации
epsdk config

# Конфигурация указанного адаптера
epsdk config yunhu

# Конфигурация указанного модуля
epsdk config MyModule

Описание:

• Состояние конфигурации делится на четыре категории: Готово (валидация пройдена), Незавершено (отсутствуют обязательные поля или валидация не пройдена), Не настроено (никогда не генерировалось), Нет конфигурации (цель не объявляет класс конфигурации)
• Значения полей снабжены пометками источника: уже настроенные отображаются как （当前:значение）, не настроенные — как （默认:значение）; просто нажмите Enter, чтобы сохранить значение
• Секретные поля (объявленные как secret) не отображаются при вводе, нажатие Enter сохраняет установленное значение
• В режиме интерактивного выбора, после завершения одного помощника, возвращается в меню выбора (состояние обновлено), можно настроить несколько целей подряд, нажатие Enter завершает
• При неудачной валидации формы и отказе от повторного ввода, текущий помощник завершается без сохранения конфигурации (избегает состояния "включено, но конфигурация не полна")
• После сохранения конфигурация немедленно записывается в config/config.toml, видна в Dashboard и запущенном SDK; для применения новой конфигурации аккаунта в работающем адаптере перезапустите процесс
• epsdk install (интерактивная установка) и epsdk init после успешной установки адаптера автоматически запускают помощник конфигурации, если обнаружено объявление конфигурации; при установке по имени пакета в командной строке выводится только подсказка о конфигурации

Команды управления запуском

run

Запуск проекта ErisPulse или прямой запуск SDK. Поддерживает режим горячей перезагрузки.

Алиас: r

Параметры:

Примеры:

# Прямой запуск SDK
epsdk run

# Запуск указанного файла скрипта
epsdk run main.py

# Горячая перезагрузка (изменения файлов автоматически перезапускают код)
epsdk run main.py --reload

# Горячая перезагрузка SDK
epsdk run --reload

# Временный строгий режим: предварительная проверка завершается с ошибкой, если не пройдена, уровень строгости повышается как минимум до 1 (пропускает некорректные компоненты, передаётся через `ERISPULSE_FRAMEWORK_STRICT_MODE` в процесс, не записывается в файл конфигурации)
epsdk run main.py --strict

# Временный лёгкий режим (строгий режим включен в конфигурации, но на этот раз нужно запустить)
epsdk run main.py --no-strict

Предварительная проверка: run перед запуском быстро проверяет разбор config/config.toml и обязательную конфигурацию установленных компонентов, строгость по умолчанию следует ErisPulse.framework.strict_mode (если не 0, проверка завершается с ошибкой, если 0 — только предупреждение и продолжение). Отсутствие конфигурационного файла считается нормальным для первого запуска, только предупреждение, не ошибка. --strict временно включает строгость: предварительная проверка завершается с ошибкой, при этом уровень строгости повышается как минимум до 1 (пропускает некорректные компоненты, передаётся через ERISPULSE_FRAMEWORK_STRICT_MODE в процесс, не записывается в файл конфигурации); --no-strict временно снижает до лёгкого. Сама предварительная проверка при ошибках автоматически пропускается, не включает проверку сети, не блокирует запуск.

Структура наблюдения --reload (начиная с 2.11.1): epsdk run --reload запускается как "надзирательный процесс + перезагрузочный дочерний процесс". Сохранение .py файлов запускает перезагрузку в дочернем процессе (исключительная последовательная обработка, объединение шторма); ошибки синтаксиса модуля отклоняются на уровне предварительной проверки, старый экземпляр продолжает обслуживать; при sdk.hard_restart() дочерний процесс завершается с кодом 42, надзирательный процесс отображает причину и автоматически перезапускает новый дочерний процесс — после обновления фреймворка новая кодовая база сразу активируется.

stop

Остановка запущенного экземпляра ErisPulse (запущен с помощью epsdk run и в том же каталоге проекта). run при запуске записывает PID надзирательного процесса, PID дочернего процесса фреймворка и исходную команду запуска в .erispulse/runtime.json, stop использует эти данные для определения экземпляра.

Порядок остановки: в POSIX сначала отправляется сигнал SIGINT надзирательному процессу (аналогичный Ctrl+C, с корректным завершением), при таймауте постепенно повышаются до SIGTERM / SIGKILL; в Windows нет семантики сигналов процесса, сначала останавливается дочерний процесс фреймворка, затем надзирательный процесс (чтобы избежать ошибочного восстановления надзирателя).

Параметры:

Примеры:

# Остановка запущенного экземпляра в текущем проекте
epsdk stop

# Принудительная остановка
epsdk stop --force

restart

Перезапуск запущенного экземпляра ErisPulse: остановка по семантике stop, затем перезапуск с использованием команды запуска из файла состояния (перехватывает терминал, новый экземпляр записывает новый файл состояния).

Параметры: такие же, как у stop (--force / --pid PID).

Примеры:

# Корректный перезапуск (после обновления адаптера/модуля через pip, чтобы код вступил в силу; кодовые горячие перезагрузки модулей в процессе также возможны с помощью `sdk.reload_module` / `sdk.adapter.reload`, без необходимости перезапуска)
epsdk restart

Команды управления проектом

init

Инициализация нового проекта ErisPulse. Поддерживает интерактивный и быстрый режим, начиная с 2.8.4 создаёт pyproject.toml (список зависимостей), по умолчанию создаёт виртуальное окружение .venv и устанавливает фреймворк и адаптер, поддерживает указание произвольного каталога.

Параметры:

Примеры:

# Интерактивная инициализация
epsdk init

# Быстрая инициализация (создаёт my_bot/ в текущем каталоге, с `pyproject.toml` + `.venv`)
epsdk init -q -n my_bot

# Быстрая инициализация с предустановленными адаптерами (без интеракции, для скриптов / CI)
epsdk init -q -n my_bot --adapter yunhu,telegram

# Инициализация в произвольном каталоге (../apps/mybot)
epsdk init ../apps/mybot

# Комбинация родительского каталога и имени проекта
epsdk init -n my_bot --path ../apps

# Принудительная перезапись конфигурации
epsdk init -f

# Инициализация в текущем каталоге
epsdk init --here -n my_bot

# Создание только структуры проекта, без виртуального окружения
epsdk init --no-venv -n my_bot

Результат инициализации: main.py, pyproject.toml (список зависимостей), config/config.toml + config.full.example, config/ssl/, logs/, .gitignore, README.md; при выборе создания виртуального окружения дополнительно создаётся .venv и устанавливаются erispulse и выбранные адаптеры.

create

Создание шаблона модуля или адаптера ErisPulse; подкоманда pack преобразует локальный плагин (plugins/ каталог) в публикуемый стандартный проект.

Параметры:

Примеры:

# Интерактивное создание (выводит выбор типа и заполняет информацию)
epsdk create

# Прямое создание проекта модуля
epsdk create module -n MyModule

# Создание локального плагина (в каталог `plugins/` проекта, автоматически обнаруживается при запуске)
epsdk create module -n MyModule --local

# Создание локального адаптера плагина (аналогично, без установки через пакет)
epsdk create adapter -n MyAdapter --local

# Прямое создание проекта адаптера
epsdk create adapter -n MyAdapter

# Преобразование локального плагина в публикуемый проект (интерактивный выбор плагина → заполнение метаинформации → генерация стандартного проекта)
epsdk create pack

# Полные параметры
epsdk create module -n MyModule -d "Описание модуля" -a "Автор" -e "[email protected]"

# Указание каталога вывода
epsdk create module -n MyModule -o ./projects

# Принудительная перезапись существующего каталога
epsdk create module -n MyModule -f

Команды языка

i18n

Просмотр текущего языка CLI, список поддерживаемых языков, смена языка отображения. Если параметр не указан, запускается интерактивное меню выбора.

Алиас: language, lang

Параметры:

Примеры:

# Интерактивный выбор языка
epsdk i18n

# Смена на английский
epsdk i18n en

# Смена на японский
epsdk i18n ja

# Вывод списка всех поддерживаемых языков
epsdk i18n --list

Команды для генерации типовых аннотаций

types

Сканирование установленных модулей и адаптеров ErisPulse, генерация файлов .pyi с аннотациями типов, для получения точного автодополнения и проверки типов в IDE.

Алиас: t, stub

Параметры:

Важно: --adapters-only и --modules-only взаимоисключительны, при одновременном указании последний параметр имеет приоритет.

Примеры:

# Генерация аннотаций для всех установленных модулей и адаптеров
epsdk types

# Только аннотации для адаптеров
epsdk types --adapters-only

# Вывод в указанный каталог
epsdk types -o ./typings

# Принудительная перезапись файлов
epsdk types --force

Глобальные параметры

Следующие параметры применимы ко всем командам:

Диагностика окружения

doctor

Диагностика текущей среды CLI, вывод отчета о состоянии. Используется для выявления проблем "почему не устанавливается / не подключается".

Проверяемые пункты:

• Python: версия и путь интерпретатора
• Установщик: используется uv или pip
• Целевой интерпретатор: фактическая среда, куда установлены пакеты
• Конфигурационный файл: существует ли config/config.toml
• Конфигурация компонентов: полнота обязательных полей конфигурации установленных компонентов ("установлен, но не запущен" часто из-за отсутствующих обязательных полей)
• Загрязнение конфигурации (2.11.1+): поиск остаточных ключей от прошлых обновлений (тени состояния, привязанные к старой версии, отдельные конфигурационные секции), при обнаружении — предупреждение
• Доступность PyPI: можно ли подключиться к PyPI (и показать количество обнаруженных компонентов)
• Системный прокси: обнаружен ли прокси

Автоматическое исправление (--fix):

• Отсутствует config.toml → генерируется начальный конфигурационный файл на основе текущего языка (так же, как при init)
• Конфигурация компонента "незавершена" → поочередно запускает интерактивный помощник конфигурации для заполнения обязательных полей (в неинтерактивной среде — подсказка использовать epsdk config <имя>)
• Остаточные ключи загрязнения конфигурации → перечисление источников и удаление после подтверждения (без потери порядка и комментариев)
• Проблемы с низкой версией Python, недоступностью PyPI и т.д. — только рекомендации по действию

# Диагностика среды
epsdk doctor

# Алиас
epsdk diag

# Диагностика и автоматическое исправление
epsdk doctor --fix

Интерактивная установка

Запуск epsdk install без указания пакета ведёт к интерактивной установке:

epsdk install

Интерфейс предоставляет:

1. Выбор адаптера
2. Выбор модуля
3. Пользовательская установка

Общие способы использования

Установка модуля

# Установка одного модуля
epsdk install Weather

# Установка нескольких модулей
epsdk install Yunhu Weather

# Обновление модуля
epsdk install Weather -U

Вывод списка компонентов

# Вывод всех компонентов
epsdk list

# Только адаптеры
epsdk list -t adapters

# Только обновляемые компоненты
epsdk list -o

# Вывод доступных удалённых компонентов
epsdk list-remote

Удаление компонентов

# Удаление одного компонента
epsdk uninstall Weather

# Удаление нескольких компонентов
epsdk uninstall Yunhu Weather

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

# Просмотр состояния конфигурации
epsdk config --list

# Интерактивный выбор цели для конфигурации
epsdk config

# Конфигурация указанного адаптера
epsdk config yunhu

Обновление компонентов

# Обновление всех компонентов
epsdk upgrade

# Обновление указанного компонента
epsdk upgrade Weather

# Принудительное обновление
epsdk upgrade -f

Запуск проекта

# Обычный запуск
epsdk run main.py

# Горячая перезагрузка
epsdk run main.py --reload

Смена языка

# Интерактивный выбор языка
epsdk i18n

# Прямая смена на английский
epsdk i18n en

# Вывод списка поддерживаемых языков
epsdk i18n --list

Генерация типовых аннотаций

# Генерация всех типовых аннотаций
epsdk types

# Только типовые аннотации для модулей
epsdk types --modules-only

Инициализация проекта

# Интерактивная инициализация
epsdk init

# Быстрая инициализация
epsdk init -q -n my_bot

Создание шаблона

# Интерактивное создание (выводит выбор типа и заполняет информацию)
epsdk create

# Прямое создание проекта модуля
epsdk create module -n MyModule

# Прямое создание проекта адаптера
epsdk create adapter -n MyAdapter

# Полные параметры
epsdk create module -n MyModule -d "Описание модуля" -a "Автор" -e "[email protected]"

# Принудительная перезапись существующего каталога
epsdk create module -n MyModule -f

Далее

• После установки компонентов нужно заполнить конфигурацию: используйте интерактивный помощник epsdk config, или посмотрите описание конфигурационного файла для ручного редактирования
• После написания кода нужна подсказка IDE: запустите epsdk types, подробнее см. генерацию типовых аннотаций
• Робот не запускается: сначала проведите диагностику среды с помощью epsdk doctor (см. диагностика среды), для долгосрочной развертки смотрите руководство по развертыванию

安装

来源: docs/ru/user-guide/installation.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/ru/user-guide/installation.md）

Справочник по установке

Системные требования

• Python 3.10 – 3.14 (свободный поток 3.14t / сборка без GIL поддерживается экспериментально, фреймворк находится под экспериментальным мониторингом CI-смокинга, без официальных гарантий)
• pip или uv (рекомендуется)
• Достаточное количество места на диске (не менее 100 МБ)

Способы установки

Способ 1: Установка с помощью pip

# Установка ErisPulse
pip install ErisPulse

# Обновление до последней версии
pip install ErisPulse --upgrade

Способ 2: Установка с помощью uv (рекомендуется)

uv — это более быстрая инструментальная цепочка для Python, рекомендуемая для среды разработки.

Установка uv

# Установка uv с помощью pip
pip install uv

# Проверка установки
uv --version

Создание виртуального окружения

# Создание директории проекта
mkdir my_bot && cd my_bot

# Установка Python 3.12
uv python install 3.12

# Создание виртуального окружения
uv venv

Активация виртуального окружения

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

Установка ErisPulse

# Установка ErisPulse
uv pip install ErisPulse --upgrade

Способ 3: Установка с помощью uv tool (глобальный CLI, рекомендуется)

Если вы хотите использовать epsdk как глобальный командную строку, uv tool install — самый чистый способ: epsdk работает в независимой среде инструментов, не загрязняя никакую проектную среду:

# Установка (epsdk сразу доступен, без необходимости активации виртуального окружения)
uv tool install ErisPulse

# Обновление (или просто используйте epsdk self-update, который автоматически использует этот канал)
uv tool upgrade ErisPulse

Инициализация проекта и установка модулей

После установки полный процесс инициализации проекта, установки модулей и запуска описан в 5 минут к быстрому старту.

Способ 4: Использование клиентского приложения ErisPulse-App (без терминала)

Не хотите устанавливать среду Python? ErisPulse-App — это официальное клиентское приложение для всех платформ (Android / Windows / Linux / macOS), которое можно запускать прямо с телефона, а настольная версия поддерживает сворачивание в системную панель для постоянной фоновой работы; включает в себя встроенный интерпретатор Python и SDK ErisPulse, не требуя терминала и ручной настройки:

• Скачайте нужную версию с GitHub Releases в зависимости от вашей платформы (для Android — online/offline APK, для Windows — setup.exe/zip, для Linux — tar.gz, для macOS — zip)
• Создайте и запустите экземпляр в приложении, управляйте адаптерами и модулями через родной интерфейс, просматривайте каталог модулей

Подробное руководство см. в разделе Установка и использование ErisPulse-App.

Проверка установки

Проверка установки

# Проверка версии ErisPulse
epsdk --version

Запуск теста

# Запуск проекта
epsdk run main.py

Если вы видите подобный вывод, значит установка прошла успешно:

[INFO] Инициализация ErisPulse...
[INFO] Загружен адаптер: Yunhu
[INFO] Загружен модуль: MyModule
[INFO] Инициализация ErisPulse завершена

Часто задаваемые вопросы

Ошибка установки

1. Проверьте, входит ли версия Python в поддерживаемый диапазон (поддерживается 3.10 – 3.14; экспериментальная поддержка 3.14t с свободным потоком / без GIL не гарантируется).
2. Попробуйте использовать uv pip install ErisPulse вместо pip install.
3. Если возникает ошибка прав, попробуйте pip install --user ErisPulse или используйте виртуальное окружение.
4. Если SSL-ошибка сертификата возникает в корпоративной среде с прокси, попробуйте pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ErisPulse.
5. Убедитесь, что сетевое подключение работает и доступен репозиторий pip.

Ошибка конфигурации

1. Проверьте синтаксис config.toml (TOML-формат чувствителен к отступам и кавычкам).
2. Убедитесь, что все необходимые параметры конфигурации заполнены.
3. Просмотрите логи терминала для получения подробной информации об ошибке.
4. Используйте epsdk init, чтобы пересоздать конфигурационный файл.

Ошибка установки модуля

1. Убедитесь, что имя модуля написано правильно (регистр важен).
2. Проверьте сетевое подключение.
3. Используйте epsdk list-remote, чтобы просмотреть список доступных модулей.
4. Убедитесь, что модуль совместим с текущей версией SDK.

Стратегия выполнения Windows PowerShell

Если PowerShell выводит сообщение «Невозможно загрузить файл... так как выполнение скриптов запрещено на этой системе»:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Ошибка создания виртуального окружения в Debian/Ubuntu

Если скрипт установки сообщает о «неудаче создания виртуального окружения» и ошибка содержит ensurepip is not available, это связано с тем, что python3-venv не установлен по умолчанию в Debian/Ubuntu (системный ensurepip для Python отключен):

sudo apt install python3.13-venv   # Установите пакет, соответствующий вашей версии Python
# Или установите универсальный метапакет:
sudo apt install python3-venv

После установки перезапустите скрипт установки. Новые версии скриптов установки при обнаружении этой проблемы спрашивают пользователя и могут автоматически установить соответствующий системный пакет; также можно использовать uv (так как uv venv не зависит от ensurepip).

Далее

• Инициализация проекта и установка адаптеров после установки: следуйте инструкциям в 5-минутном руководстве, чтобы завершить оставшиеся шаги
• Управление компонентами через командную строку в повседневной работе: см. Справочник по командам CLI
• Для заполнения токенов и настройки портов: ознакомьтесь с описанием конфигурационного файла

部署

来源: docs/ru/user-guide/deployment.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/ru/user-guide/deployment.md）

Руководство по развёртыванию

Завершение разработки бота — это только начало. Этот документ охватывает три способа развёртывания, необходимых для стабильной работы бота на сервере (Docker / systemd / Supervisor), а также обратный прокси, усиление безопасности и резервное копирование.

Развёртывание в Docker (рекомендуется)

ErisPulse предоставляет официальный Docker-образ со встроенными фреймворком ErisPulse и панелью управления Dashboard, поддерживающий архитектуры linux/amd64 и linux/arm64.

Быстрый старт

# Загрузка образа
docker pull erispulse/erispulse:latest

# Скачивание docker-compose.yml
curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml

# Задайте токен входа в Dashboard и запустите
ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d

После запуска откройте http://localhost:8000/Dashboard и войдите, используя установленный токен в качестве пароля.

Ускорение загрузки образа через зеркало (для Китая)

Если Docker Hub недоступен, образ можно загрузить через GitHub Container Registry:

docker pull ghcr.io/erispulse/erispulse:latest

При использовании образа из ghcr.io необходимо изменить поле image в docker-compose.yml:

services:
  erispulse:
    image: ghcr.io/erispulse/erispulse:latest

docker-compose.yml

services:
  erispulse:
    image: erispulse/erispulse:${ERISPULSE_TAG:-latest}
    container_name: ${CONTAINER_NAME:-erispulse}
    ports:
      - "${ERISPULSE_PORT:-8000}:8000"
    volumes:
      - ./config:/app/config
      # Персистентный каталог Python-пакетов
      - ./config/.packages:/usr/local/lib/python3.13/site-packages
    environment:
      - TZ=${TZ:-Asia/Shanghai}
      - LANG=${LANG:-en_US.UTF-8}
      - ERISPULSE_LANG=${ERISPULSE_LANG:-}
      - ERISPULSE_DASHBOARD_TOKEN=${ERISPULSE_DASHBOARD_TOKEN:-}
    init: true
    # Корректная остановка выполняется обработкой сигналов внутри фреймворка (SIGTERM); здесь задаётся только длительность льготного периода
    stop_grace_period: 30s
    restart: on-failure:5
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/ping')"]
      interval: 30s
      timeout: 5s
      start_period: 20s
      retries: 3

Вышеуказанное соответствует docker-compose.yml в корне репозитория (в версии из репозитория в начале файла содержатся дополнительные комментарии об ускорении через зеркало и переменных окружения); рекомендуется скачивать и использовать напрямую.

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

Сохранение данных

В каталог ./config смонтированы файлы конфигурации и база данных, он содержит:

• config/config.toml — файл конфигурации
• config/config.db — база данных хранилища SQLite
• config/.packages — персистентный том Python site-packages, в котором хранятся фреймворк, адаптеры и установленные модули (при первом запуске автоматически инициализируется точкой входа из встроенного в образ резервного хранилища; все последующие установки модулей и «горячие» обновления фреймворка записываются в этот каталог)

Обновление фреймворка (включая pre/rc) и самолечение образа: точка входа при каждом запуске контейнера выполняет самопроверку целостности основных пакетов. При повреждении восстановление выполняется по принципу «приоритет версии, установленной пользователем» — версии, явно установленные/обновлённые в персистентном томе (например, pre-версия, установленная через Dashboard), будут переустановлены в той же версии из PyPI, без тихого отката к версии, встроенной в образ. Поэтому после обновления фреймворка через Dashboard целевая версия сохраняется при любом количестве перезапусков контейнера.

Панель управления Dashboard

Docker-образ ErisPulse содержит встроенный модуль Dashboard, предоставляющий веб-интерфейс визуального управления.

Обзор функций

Установка модулей через Dashboard

В Dashboard интегрирована функция магазина модулей, с помощью которой можно:

1. Установить из магазина: просмотреть список удалённых модулей и установить нужный в один клик
2. Загрузить локальный пакет: загрузить файл .whl или .zip напрямую для установки — удобно для тестирования самостоятельно разработанных модулей

Быстрый процесс тестирования для разработчиков модулей: после развёртывания в Docker загружайте собранные вами файлы .whl напрямую через функцию «Загрузить локальный пакет» в Dashboard для тестирования — без ручных операций с контейнером.

Супервизия процессов и жёсткий перезапуск

Жёсткий перезапуск ErisPulse (sdk.hard_restart()) рассчитан на внешнего супервизора, который заново запускает процесс при коде выхода 42, — сам SDK новый процесс не запускает. В производственной среде обязательно настройте супервизора, иначе после жёсткого перезапуска процесс не восстановится автоматически:

• Docker: официальный compose использует restart: on-failure:5 — перезапуск при любом ненулевом коде выхода (включая код выхода 42 жёсткого перезапуска); лимит в 5 последовательных перезапусков защищает от бесконечного цикла; при необходимости неограниченного числа перезапусков самостоятельно измените на unless-stopped
• systemd: Restart=on-failure + RestartForceExitStatus=42
• PM2 / supervisord: добавьте 42 в число кодов выхода, при которых выполняется перезапуск
• Собственный супервизор на чистом Python: цикл Popen + проверка returncode == 42

Полные примеры настройки каждого супервизора и описание контракта кода выхода 42 см. в разделе Процесс запуска → Руководство по супервизорам.

Проверка состояния

В SDK встроена конечная точка проверки состояния:

# Проверка состояния
curl http://localhost:8000/health

В официальном docker-compose.yml уже встроена приведённая ниже проверка состояния; при написании собственного compose-файла можно ориентироваться на неё:

services:
  erispulse:
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/ping')"]
      interval: 30s
      timeout: 5s
      start_period: 20s
      retries: 3

Обратный прокси

Если необходимо предоставить доступ к Dashboard через обратный прокси (например, Nginx):

server {
    listen 80;
    server_name bot.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Поддержка WebSocket (необходима для потока событий Dashboard в реальном времени)
    location /Dashboard/ws {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Для SSL можно использовать Let's Encrypt:

sudo certbot --nginx -d bot.example.com

Ручное развёртывание (pip)

Если Docker не используется, можно развернуть вручную.

Конфигурация для производственного окружения

# config/config.toml

[ErisPulse.server]
host = "0.0.0.0"
port = 8000

[ErisPulse.logger]
level = "INFO"
log_files = ["app.log"]
memory_limit = 5000

[ErisPulse.framework]
enable_lazy_loading = true

systemd (Linux)

Создайте файл /etc/systemd/system/erispulse-bot.service:

[Unit]
Description=ErisPulse Bot
After=network.target

[Service]
Type=simple
User=bot
WorkingDirectory=/opt/erispulse-bot
ExecStart=/opt/erispulse-bot/venv/bin/epsdk run main.py
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Управление:

sudo systemctl daemon-reload
sudo systemctl start erispulse-bot
sudo systemctl enable erispulse-bot
sudo journalctl -u erispulse-bot -f

Supervisor

Создайте файл /etc/supervisor/conf.d/erispulse-bot.conf:

[program:erispulse-bot]
command=/opt/erispulse-bot/venv/bin/python -m ErisPulse run main.py
directory=/opt/erispulse-bot
user=bot
autostart=true
autorestart=true
stderr_logfile=/var/log/erispulse-bot/err.log
stdout_logfile=/var/log/erispulse-bot/out.log

Изолированное развёртывание через uv tool (разделение CLI и окружения проекта)

uv tool install устанавливает epsdk как отдельное инструментальное окружение, полностью изолируя сам CLI от зависимостей проекта: обновление CLI не затрагивает .venv проекта, а изменения зависимостей проекта не влияют на CLI.

# 1. Глобальная установка CLI (команды epsdk / ep становятся доступны автоматически)
uv tool install ErisPulse

# 2. В проекте размещаются только зависимости бота (.venv управляется uv)
cd /opt/erispulse-bot
uv add erispulse ErisPulse-Adapter-Yunhu   # добавляйте адаптеры по мере необходимости

# 3. Запуск через CLI (интерпретатор из .venv проекта определяется и используется автоматически)
epsdk run main.py

Ключевые аспекты поведения:

• Порядок разрешения целевого интерпретатора для epsdk run: переменная окружения ERISPULSE_PYTHON → .venv проекта → текущий интерпретатор; само инструментальное окружение содержит только CLI, компоненты (адаптеры/модули) следует устанавливать в .venv проекта
• epsdk install / uninstall / upgrade / list также действуют на .venv проекта и не засоряют инструментальное окружение
• Обновление CLI: uv tool upgrade ErisPulse (или напрямую epsdk self-update — в окружении uv tool автоматически перенаправляется на uv tool upgrade); обновление зависимостей проекта: выполните uv sync / uv add в каталоге проекта; эти операции не влияют друг на друга
• В серверных сценариях инструментальные окружения управляются централизованно через uv (просмотр — uv tool list, массовое обновление — uv tool upgrade --all), ручное обслуживание глобальных pip-пакетов не требуется
• Если выполнить uv run epsdk ... в каталоге без проекта, вы попадёте во временное одноразовое изолированное окружение (установленные компоненты не сохраняются); на сервере всегда вызывайте epsdk напрямую или сначала перейдите через cd в каталог проекта

Рекомендации по безопасности

1. Задайте токен Dashboard: используйте сильный случайный токен, не используйте значения по умолчанию
2. Не открывайте порт в публичную сеть: если не используется обратный прокси + SSL, ограничьте доступ к порту Dashboard внутренней сетью
3. Защитите каталог данных: каталог config/ содержит конфигурацию и базу данных, установите соответствующие права доступа к файлам
4. Регулярно обновляйтесь: используйте epsdk self-update или загружайте новейший Docker-образ
5. Не запускайте от root: при ручном развёртывании создайте отдельного пользователя
6. Используйте политику перезапуска Docker: restart: on-failure:5 в официальном compose гарантирует автоматический перезапуск после аварийного завершения (включая код выхода 42 жёсткого перезапуска)

Развёртывание нескольких экземпляров

При запуске нескольких экземпляров бота:

1. Каждый экземпляр использует отдельный каталог проекта и docker-compose.yml
2. Используйте разные номера портов: ERISPULSE_PORT=8001
3. Используйте разные имена контейнеров: container_name: erispulse-bot2

Обновление и обслуживание

Через Docker

# Загрузка новейшего образа
docker compose pull

# Перезапуск с использованием нового образа
docker compose up -d

Через pip

epsdk self-update
epsdk upgrade

Через uv tool

# Обновление инструментального окружения CLI
uv tool upgrade ErisPulse

# Обновление зависимостей проекта (выполнять в каталоге проекта)
uv sync

Горячая перезагрузка конфигурации сервера во время выполнения

После изменения адреса прослушивания / порта / SSL-сертификата перезапускать процесс не нужно — вызовите router.reload() из любой сопрограммы:

await sdk.router.reload(port=9000)                                # смена порта
await sdk.router.reload(ssl_cert=new_pem, ssl_key=new_key)        # горячая замена сертификата (сценарий продления сертификата)
await sdk.router.reload(host="0.0.0.0", port=9000)                # опущенные параметры наследуют текущую конфигурацию

• Переиспользуется то же приложение FastAPI; все маршруты HTTP / WebSocket / SSE, зарегистрированные модулями, полностью сохраняются
• Сначала проверяется новая конфигурация (сертификат может быть загружен, порт доступен), и только затем выполняется переключение; при сбое сервис восстанавливается на старой конфигурации и возвращается False, гарантируется: возврат False = старый сервис остаётся доступным
• Если сервер не запущен, возвращается False (для первого запуска используйте sdk.router.start())

Резервное копирование

Регулярно создавайте резервные копии каталога config/:

# Развёртывание Docker
tar czf erispulse-backup-$(date +%Y%m%d).tar.gz config/

# Или выполните экспорт через функцию «Резервное копирование» в Dashboard

Следующие шаги

• Хотите визуальное управление после развёртывания: установите ErisPulse-Dashboard — управляйте модулями, просматривайте логи и изменяйте конфигурацию прямо в браузере
• Подозреваете проблемы с окружением: сначала запустите epsdk doctor для вывода отчёта о состоянии, см. Справочник команд CLI · doctor
• Нужно настроить конфигурацию фреймворка и компонентов: обратитесь к Описанию файла конфигурации; переопределение через переменные окружения особенно подходит для контейнерного развёртывания