部署指南
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 映像時,需要修改 docker-compose.yml 中的 image:
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 |
映像 tag(如需鎖定版本可設為具體版本號) |
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)與映像自我修復:進入點會在每次容器啟動時做核心套件完整性自我檢查, 損壞時按「使用者已安裝版本優先」原則修復——持久化磁碟區內顯式安裝/升級的版本 (如 Dashboard 安裝的 pre 版本)會從 PyPI 重新安裝同版本,絕不靜默回退到 映像內建版本。因此 Dashboard 升級框架後,無論容器重新啟動多少次都應保持目標版本。
Dashboard 管理面板
ErisPulse Docker 映像內建 Dashboard 模組,提供 Web 視覺化管理介面。
功能概覽
| 功能 | 說明 |
|---|---|
| 儀表板 | 系統概覽、CPU/記憶體監控、執行時長、事件統計 |
| 機器人管理 | 檢視各平台機器人的線上狀態與資訊 |
| 事件檢視 | 即時事件流,支援依類型和平台篩選 |
| 日誌檢視 | 依模組和等級篩選的日誌檢視器 |
| 模組管理 | 檢視、載入、解除安裝已安裝的模組和配接器 |
| 模組商店 | 瀏覽遠端可用套件並一鍵安裝 |
| 設定編輯 | 線上編輯 config.toml |
| 儲存管理 | 瀏覽和編輯 Key-Value 儲存資料 |
| 備份 | 匯出/匯入設定和儲存資料 |
| 稽核日誌 | 記錄所有管理操作 |
透過 Dashboard 安裝模組
Dashboard 整合了模組商店功能,你可以:
- 從商店安裝:瀏覽遠端模組清單,選擇需要的模組一鍵安裝
- 上傳本機套件:直接上傳
.whl或.zip檔案進行安裝,方便測試個人開發的模組
模組開發者的快速測試流程:使用 Docker 部署後,在 Dashboard 中透過「上傳本機套件」功能直接上傳你建置的
.whl檔案進行測試,無需手動操作容器。
行程監督與硬重啟
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
反向代理
如果需要透過 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
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,元件(配接器/模組)應裝進專案.venvepsdk 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 重啟策略:官方 compose 的
restart: on-failure:5已確保異常退出(含硬重啟退出碼 42)後自動重啟 - 關閉 API 文件端點:
/docs、/redoc、/openapi.json預設開啟且無鑑權,公網部署時呼叫router.disable_docs()關閉 - Webhook 驗簽:鷹架產生的
verify_request預設放行,接入公網回呼前必須實現簽章/權杖校驗 - 安全模型邊界:主人/作用域體系約束的是平台側使用者;已載入模組視為可信程式碼(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 - 要調整框架與元件設定:查閱 設定檔說明,環境變數覆寫尤其適合容器部署