Руководство по развёртыванию
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— база данных хранения SQLiteconfig/.packages— персистентный том Python site-packages, где хранятся фреймворк, адаптеры и установленные модули (при первом запуске автоматически инициализируется точкой входа из встроенного в образ резервного экземпляра; все последующие установки модулей и горячие обновления фреймворка записываются в этот каталог)
Обновление фреймворка (включая pre/rc) и самовосстановление образа: точка входа при каждом запуске контейнера выполняет самопроверку целостности основных пакетов. При обнаружении повреждений восстановление выполняется по принципу «приоритет версии, установленной пользователем» — версия, явно установленная/обновлённая в персистентном томе (например, pre-версия, установленная через Dashboard), будет переустановлена той же версии из PyPI, без какого-либо тихого отката к версии, встроенной в образ. Поэтому после обновления фреймворка через Dashboard целевая версия сохраняется при любом количестве перезапусков контейнера.
Панель управления Dashboard
Docker-образ ErisPulse включает встроенный модуль Dashboard, предоставляющий веб-интерфейс для наглядного управления.
Обзор функций
| Функция | Описание |
|---|---|
| Обзорная панель | Обзор системы, мониторинг CPU/памяти, время работы, статистика событий |
| Управление ботами | Просмотр статуса онлайн и информации о ботах на различных платформах |
| Просмотр событий | Поток событий в реальном времени с фильтрацией по типу и платформе |
| Просмотр логов | Просмотрщик логов с фильтрацией по модулям и уровням |
| Управление модулями | Просмотр, загрузка и выгрузка установленных модулей и адаптеров |
| Магазин модулей | Просмотр доступных удалённых пакетов и установка в один клик |
| Редактор конфигурации | Онлайн-редактирование config.toml |
| Управление хранилищем | Просмотр и редактирование данных Key-Value хранилища |
| Резервное копирование | Экспорт/импорт конфигурации и данных хранилища |
| Журнал аудита | Запись всех операций управления |
Установка модулей через Dashboard
В Dashboard интегрирован магазин модулей, с помощью которого вы можете:
- Установить из магазина: просмотреть список удалённых модулей и установить нужный в один клик
- Загрузить локальный пакет: загрузить файл
.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) в каталог проекта
Рекомендации по безопасности
- Настройте токен Dashboard: используйте надёжный случайный токен, не используйте значения по умолчанию
- Не открывайте порты в публичную сеть: если не используется обратный прокси + SSL, ограничьте порт Dashboard внутренней сетью
- Защитите каталог данных: каталог
config/содержит конфигурацию и базу данных, установите соответствующие права доступа к файлам - Регулярно обновляйтесь: используйте
epsdk self-updateили загружайте новейший образ Docker - Не запускайте от имени root: при ручном развёртывании создайте отдельного пользователя
- Используйте политику перезапуска Docker:
restart: on-failure:5в официальном compose уже обеспечивает автоматический перезапуск после аварийного завершения (включая код выхода 42 при жёстком перезапуске) - Отключите конечные точки документации API:
/docs,/redoc,/openapi.jsonпо умолчанию включены и не требуют аутентификации; при развёртывании в публичной сети вызовитеrouter.disable_docs()для их отключения - Проверка подписи Webhook:
verify_request, сгенерированный скаффолдингом, по умолчанию пропускает все запросы; перед подключением публичных обратных вызовов необходимо реализовать проверку подписи/токена - Границы модели безопасности: система «владелец/область действия (scope)» ограничивает пользователей на стороне платформы; загруженные модули считаются доверенным кодом (при отсутствии конфигурации scope доступ разрешён по умолчанию, модули могут регистрировать provider), не загружайте модули неизвестного происхождения
Развёртывание нескольких экземпляров
При запуске нескольких экземпляров бота:
- Каждый экземпляр использует отдельный каталог проекта и свой
docker-compose.yml - Используйте разные номера портов:
ERISPULSE_PORT=8001 - Используйте разные имена контейнеров:
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 - Нужно настроить конфигурацию фреймворка и компонентов: обратитесь к Описанию файлов конфигурации; переопределение через переменные окружения особенно подходит для контейнерного развёртывания