ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

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

Tip

Когда читать этот документ: когда бот должен долго и непрерывно работать — здесь собраны развёртывание через Docker, защита процессов с помощью systemd / Supervisor, обратный прокси и SSL, резервное копирование и обновление. Если вы на этапе локальной разработки и отладки, документ можно пропустить.

Завершение разработки бота — это только начало. Этот документ охватывает три способа развёртывания (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 из корня репозитория (в версии из репозитория в начале файла есть дополнительные комментарии об ускорении загрузки через зеркала и переменных окружения); рекомендуется скачать и использовать его напрямую.

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

Переменная Значение по умолчанию Описание
ERISPULSE_PORT 8000 Проброс порта Dashboard
ERISPULSE_TAG latest Тег образа (для фиксации версии укажите конкретный номер версии)
CONTAINER_NAME erispulse Имя контейнера (для различения экземпляров при развёртывании нескольких экземпляров)
ERISPULSE_DASHBOARD_TOKEN Генерируется автоматически Токен входа в Dashboard (настоятельно рекомендуется задать)
TZ Asia/Shanghai Часовой пояс
LANG en_US.UTF-8 Язык системы; язык стартового интерфейса определяется автоматически
ERISPULSE_LANG пусто Принудительный язык стартового интерфейса: zh / zh_TW / en / ja / ru (переопределяет LANG)

Персистентность данных

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

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

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

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

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

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

Функция Описание
Обзорная панель Обзор системы, мониторинг CPU/памяти, время работы, статистика событий
Управление ботами Просмотр статуса онлайн и информации о ботах на различных платформах
Просмотр событий Поток событий в реальном времени с фильтрацией по типу и платформе
Просмотр логов Просмотрщик логов с фильтрацией по модулям и уровням
Управление модулями Просмотр, загрузка и выгрузка установленных модулей и адаптеров
Магазин модулей Просмотр доступных удалённых пакетов и установка в один клик
Редактор конфигурации Онлайн-редактирование config.toml
Управление хранилищем Просмотр и редактирование данных Key-Value хранилища
Резервное копирование Экспорт/импорт конфигурации и данных хранилища
Журнал аудита Запись всех операций управления

Установка модулей через 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 см. в разделе Процесс запуска → Руководство по супервизорам.

Перезапуск внутри контейнера (экземпляр PID 1)

Эта функциональность требует ErisPulse 2.12+.

Когда фреймворк работает как главный процесс контейнера (PID 1), команда epsdk restart не завершает процесс для повторного запуска — завершение PID 1 означает выход контейнера. Вместо этого фреймворку-процессу отправляется сигнал SIGUSR1, и фреймворк выполняет мягкий перезапуск на уровне компонентов внутри процесса (sdk.restart()): только что установленный через ep i <пакет> адаптер и обновлённый код модулей сразу вступают в силу благодаря горячей перезагрузке.

  • Если требуется перезапуск всего процесса (обновление самого фреймворка, структурные изменения конфигурации), перезапустите контейнер: docker restart <контейнер>
  • epsdk stop для экземпляра PID 1 по-прежнему означает завершение процесса — контейнер останавливается вместе с ним (политика restart определяет, будет ли он запущен автоматически)

Проверка работоспособности

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 при жёстком перезапуске)
  7. Отключите конечные точки документации API: /docs, /redoc, /openapi.json по умолчанию включены и не требуют аутентификации; при развёртывании в публичной сети вызовите router.disable_docs() для их отключения
  8. Проверка подписи Webhook: verify_request, сгенерированный скаффолдингом, по умолчанию пропускает все запросы; перед подключением публичных обратных вызовов необходимо реализовать проверку подписи/токена
  9. Границы модели безопасности: система «владелец/область действия (scope)» ограничивает пользователей на стороне платформы; загруженные модули считаются доверенным кодом (при отсутствии конфигурации scope доступ разрешён по умолчанию, модули могут регистрировать provider), не загружайте модули неизвестного происхождения

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

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

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

Примечание о бэкендах хранения: экземпляры не разделяют состояние между собой (входящие сообщения сессий / контрольные точки диалогов / кулдауны команд — всё это состояние в памяти каждого экземпляра). SQLite по умолчанию является однофайловым бэкендом и не может быть открыт несколькими экземплярами одновременно; каталоги config/ каждого экземпляра должны быть независимыми, переключение на mysql / postgres также означает лишь отдельные независимые базы — текущая версия не поддерживает взаимодействие нескольких экземпляров (общие сессии / распределение нагрузки), несколько экземпляров в одной группе будут отвечать независимо друг от друга, дедупликацию необходимо выполнять самостоятельно на стороне платформы или бизнес-логики.

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

Способ с 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
  • Нужно настроить конфигурацию фреймворка и компонентов: обратитесь к Описанию файлов конфигурации; переопределение через переменные окружения особенно подходит для контейнерного развёртывания