部署指南

将 ErisPulse 机器人部署到生产环境的最佳实践。

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 镜像时，需要修改 docker-compose.yml 中的 image：

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

docker-compose.yml

services:
  erispulse:
    image: erispulse/erispulse:latest
    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}
      - ERISPULSE_DASHBOARD_TOKEN=${ERISPULSE_DASHBOARD_TOKEN:-}
    init: true
    stop_grace_period: 30s
    restart: unless-stopped

推荐直接使用仓库根目录的 docker-compose.yml，它已包含上述配置及健康检查、时区与语言环境变量。

环境变量

数据持久化

./config 目录挂载了配置文件和数据库，包含：

• config/config.toml — 配置文件
• config/config.db — SQLite 存储数据库
• config/.packages — Python site-packages 持久化卷，保存框架、适配器和已安装模块（首次启动时由入口点从镜像内置备份自动初始化，之后的模块安装与框架热更新均写入此目录）

框架升级（含 pre/rc）与镜像自愈：入口点会在每次容器启动时做核心包完整性自检， 损坏时按"用户已安装版本优先"原则修复——持久卷内显式安装/升级的版本 （如 Dashboard 安装的 pre 版本）会从 PyPI 重装同版本，绝不静默回退到 镜像内置版本。因此 Dashboard 升级框架后，任意次容器重启都应保持目标版本。

Dashboard 管理面板

ErisPulse Docker 镜像内置 Dashboard 模块，提供 Web 可视化管理界面。

功能概览

通过 Dashboard 安装模块

Dashboard 集成了模块商店功能，你可以：

1. 从商店安装：浏览远程模块列表，选择需要的模块一键安装
2. 上传本地包：直接上传 .whl 或 .zip 文件进行安装，方便测试个人开发的模块

模块开发者的快速测试流程：使用 Docker 部署后，在 Dashboard 中通过「上传本地包」功能直接上传你构建的 .whl 文件进行测试，无需手动操作容器。

进程监督与硬重启

ErisPulse 的硬重启（sdk.hard_restart()）依赖外部监督者在进程退出码为 42 时重新拉起进程——SDK 自己不拉起新进程。生产环境务必配置监督者，否则硬重启后进程不会自动恢复：

• Docker：restart: unless-stopped（任何退出码都会重启，含 42）
• systemd：Restart=on-failure + RestartForceExitStatus=42
• PM2 / supervisord：将 42 加入可重启退出码
• 纯 Python 自定义监督者：循环 Popen + 检测 returncode == 42

各监督者的完整配置示例与退出码 42 契约说明见 启动流程 → 监督者指南。

健康检查

SDK 内置健康检查端点：

# 健康检查
curl http://localhost:8000/health

Docker 健康检查可在 docker-compose.yml 中添加：

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

反向代理

如果需要通过 Nginx 等反向代理暴露 Dashboard：

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

安全建议

1. 设置 Dashboard 令牌：使用强随机令牌，不要使用默认值
2. 不要暴露端口到公网：除非使用反向代理 + SSL，否则将 Dashboard 端口限制在内网
3. 保护数据目录：config/ 目录包含配置和数据库，设置适当的文件权限
4. 定期更新：使用 epsdk self-update 或拉取最新 Docker 镜像
5. 不要以 root 运行：手动部署时创建专用用户
6. 使用 Docker 重启策略：restart: unless-stopped 确保异常退出后自动重启

多实例部署

运行多个机器人实例时：

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

备份

定期备份 config/ 目录：

# Docker 部署
tar czf erispulse-backup-$(date +%Y%m%d).tar.gz config/

# 或在 Dashboard 中使用「备份」功能导出