ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

配置文件說明

Note

L1 核心必讀——首頁「閱讀路徑」中的五篇核心文件之一,模組開發必備。

這篇講框架自身的配置文件 config/config.toml:每個配置節管什麼、哪些支援熱更新、如何用環境變數覆蓋。第三方模組的配置項請參考模組自己的文件。

ErisPulse 使用 TOML 格式的配置文件 config/config.toml 來管理專案配置。

配置文件位置

配置文件位於專案根目錄的 config/ 資料夾中:

project/
├── config/
│   └── config.toml
├── main.py

多實例提示與鎖檔案

框架啟動時會在專案根的執行狀態目錄 .erispulse/ 下建立 config.lock 鎖檔案並持有到進程退出(用於偵測多實例共享配置目錄;2.10 及以前位於 config/ 目錄的 .erispulse_config.lock 會在升級後首次啟動時自動清除)。如果日誌出現「偵測到配置檔案可能正被另一個 ErisPulse 實例同時使用」的告警,說明有兩個以上的 ErisPulse 進程在寫同一份配置(典型場景:多個容器掛載了同一個宿主機 config/ 目錄)——併發寫入會互相覆蓋,請為每個實例使用獨立的配置目錄。

敏感配置不入庫

配置檔案含令牌(token / API key)等敏感資訊:框架初始化與 epsdk init 會自動在 config/ 目錄生成 .gitignore(內容僅一行 *——目錄內全部檔案不入版本庫,忽略檔案自身也在排除範圍內);已存在的 .gitignore 不會被覆蓋。.erispulse/ 運行狀態目錄(實例鎖、CLI 運行狀態檔案)同屬機器本地狀態,專案範本的 .gitignore 已預設忽略。

配置載入錯誤處理

框架在載入 config.toml 時會區分三種錯誤狀態,並給出可操作的診斷資訊,而不是靜默回退到預設配置:

錯誤狀態 觸發條件 框架行為
檔案遺失 config.toml 不存在 正常首次啟動,靜默使用空配置(不發警告)
TOML 語法錯誤 檔案存在但格式非法(如少了引號、括號未閉合) 輸出出錯行號/列號與原因,並保留上次有效配置繼續運行(本次檔案修改不生效)
權限/其他錯誤 無讀權限、IO 錯誤等 輸出明確原因,並保留上次有效配置繼續運行

注意"上次有效配置"≠ 預設配置:檔案損壞時框架沿用本次啟動前最後一份解析成功的配置(運行中熱更新改壞檔案則沿用舊值),而不是把所有配置項重置為出廠預設。故障處置時不要假設「配置已被重置」。

例如,當你不慎把配置寫成了 port = 8000(少了引號的字串)時,日誌會輸出類似:

[ERROR] [Config] 配置檔案 config/config.toml 語法錯誤(第 3 行 第 1 列): ...
[WARNING] [Config] 配置檔案讀取失敗。繼續使用上次有效配置運行,本次檔案修改未生效——請修復後重新載入或重啟

這樣你可以在預設 INFO 級別下立刻定位問題,而不會困惑「為什麼我改的配置沒生效」。

運行中改壞配置檔案? 如果你在機器人運行期間手動編輯 config.toml 引入了語法錯誤,框架在下次寫入(合併配置)時會輸出「配置檔案已損壞(語法錯誤,第 X 行),無法合併寫入——請先修復配置檔案後重啟」,而不是令人困惑的「寫入失敗」。待寫入的配置項會被保留,不會遺失。

注釋保留與最小化落盤

config.toml 中的注釋與鍵順序在框架寫入後完整保留:無論是程式碼 setConfig()、 CLI 配置向導保存還是適配器/模組首次生成配置範本,框架都只改動涉及的鍵, 你寫的注釋、整理的順序不會被抹掉或重排(基於 tomlclass 無損 TOML 引擎, 未觸碰的內容逐字節保真,檔案原有的 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_ 前綴:

配置項 環境變數 示例值
ErisPulse.server.port ERISPULSE_SERVER_PORT 9000
ErisPulse.server.host ERISPULSE_SERVER_HOST 0.0.0.0
ErisPulse.logger.level ERISPULSE_LOGGER_LEVEL DEBUG
ErisPulse.framework.strict_mode ERISPULSE_FRAMEWORK_STRICT_MODE 2

行為說明:

  • 優先級最高:環境變數覆蓋「配置檔案」與「預設值」,按原值類型自動轉換(bool / int / float / 逗號分隔的 list / 字串)
  • 不持久化:覆蓋只在運行期生效,不會寫回 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 解析;轉換失敗時忽略該覆蓋(回退配置檔案 / 預設值)並輸出告警
  • 宣告一處、處處生效:配置讀取、熱更新、校驗使用同一管道;配置面板 Schema 會標註 env 名,config.toml 範本注釋也會提示可用的環境變數(範本不寫入環境變數的實際值,避免洩露)
  • 完全相容:未聲明 env 的字段行為不變;直接實例化 ConfigClass(不經框架配置管道)不受環境變數影響
# Docker 部署示例:不修改 config.toml,直接注入模組密鑰
MYMODULE_API_KEY=sk-xxx docker compose up -d

配置類 vs 模型字段怎麼選? 配置類管「模組怎麼運轉」(行為參數、熱更新), ORM 的 Field() 管「用戶產生了什麼資料」(資料庫表、查詢)。兩者共享同一套 約束詞表與校驗器引擎;對照表見 資料模型層 · 兩種宣告何時用哪個。

配置熱更新

從 2.7.0 起,框架對配置熱更新做了系統化支援。外部修改 config.toml 後(後台 watcher 每 5 秒檢測一次),或程式碼呼叫 setConfig() 後,各組件自動回應:

組件 支援熱更新的配置 行為
日誌 Logger logger.level / log_files / log_dir(含分段參數)/ memory_limit / format / exclude_levels 自動重新應用(帶變更檢測)
命令系統 CommandHandler event.command.prefix / case_sensitive / allow_space_prefix / must_at_bot 下一條訊息即生效
適配器併發 framework.handler_max_concurrency 失效快取信號量,按新值重建
主動 GC framework.proactive_gc_* 配置變更即時重啟 GC 任務,支援運行時調整/禁用/重新啟用
主人系統 Master master.users 每次 is_master() 檢查實時讀取,無需重啟
模組/適配器配置 各自的配置項 觸發 on_config_update(old, new) 回調

需重啟的配置(無法安全熱切換,變更時會輸出告警「需重啟進程後生效」):

配置 原因
router.cors.* / router.security.* 中間件在服務啟動時寫入 FastAPI,運行時無法安全熱切換
storage.use_global_db SQLite 檔案句柄已在運行時打開,切換路徑不安全

中途編輯保存出錯? 若編輯 config.toml 時出現瞬時語法錯誤,框架會保留上次有效配置並輸出診斷日誌,不會把空配置廣播給各組件(避免 on_config_update 收到空值誤回退預設)。

熱更新鏈路內部拆解

「改了配置,各組件怎麼知道的?」——背後是一條檢測 → 重載 → 廣播的鏈路:

flowchart TD
    A["外部編輯 config.toml"] --> B{"誰先發現?"}
    B -->|"後台 watcher 線程<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 / 命令 / GC ...)"]

兩條檢測路徑(取其一即可,均能兜底):

路徑 機制 觸發時機
後台 watcher daemon 線程 config-watcher 每 5 秒 wait 輪詢檔案 mtime 外部改檔案後最多 5 秒內
慢性檢測 任何 getConfig() 讀取時,若快取超過 60 秒則先查檔案 下次讀配置時

框架不會誤傷自己:setConfig() 寫盤時會記錄「自身寫入的 mtime」,watcher 對比時把它排除,只把外部編輯視為變更。

兩類配置變更事件:

事件 觸發者 數據 典型場景
config.set 程式碼 / Dashboard 調 setConfig() {key, old_value, new_value} 單鍵寫入(範本生成、狀態記錄、運行時改配置)
config.updated 外部編輯後 watcher/慢性檢測捕獲 {old_config, new_config, config_file} 手改 config.toml

setConfig() 預設延遲 5 秒落盤(合併多次寫入),immediate=True 立即寫。watcher 檢測到外部修改後只更新記憶體快取,不會把外部變更回寫檔案。

自動回應方清單(兩類事件通常會都訂閱,回應內容一致):

組件 監聽 回應
Logger config.set + config.updated 級別/檔案/目錄分段/記憶體上限/格式/屏蔽等級重新應用(帶變更檢測,無變化不動)
Scope config.updated 作用域綁定快取重建
命令系統 config.updated 前綴/大小寫/空格前綴/must_at_bot 解析參數刷新,下一條訊息生效
適配器併發 config.set + config.updated handler_max_concurrency 失效重建信號量
主動 GC config.set + config.updated proactive_gc_* 即時重啟 GC 後台任務
適配器 路由到 on_config_update 各適配器 on_config_update(old, new) 回調
模組 路由到 on_config_update 各模組 on_config_update(old, new) 回調
存儲 config.updated use_global_db 變更僅告警(需重啟)
路由 config.updated cors.* / security.* 變更僅告警(需重啟)

配置讀取與刪除 API

getAllConfig:全量配置快照

替代直接讀取私有 _cache(外部讀私有屬性不受版本相容保護):

config = sdk.config.getAllConfig()     # 深拷貝快照,原地修改不受框架狀態影響
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-----"""
配置項 類型 預設值 說明
host string 0.0.0.0 監聽位址,0.0.0.0 表示所有介面
port integer 8000 監聽埠號
auto_start boolean true 是否在 sdk.init() 時自動啟動路由伺服器。設為 false 可跳過路由伺服器啟動(純事件/無 WebUI 場景)
ssl_certfile string 空 SSL 證書檔案路徑
ssl_keyfile string 空 SSL 私鑰檔案路徑
ssl_cert string 空 內聯 PEM 證書內容(非路徑)。與 ssl_key 成對使用時優先於 ssl_certfile/ssl_keyfile;框架臨時落盤建構 SSL 上下文後立即刪除臨時檔案
ssl_key string 空 內聯 PEM 私鑰內容(非路徑),語義同上

埠口占用不是致命錯誤:啟動時若檢測到 port 已被占用,框架會跳過路由伺服器啟動並告警,適配器與模組照常運行(僅 HTTP/WS/SSE 路由與 WebUI 不可用)。排查「機器人能跑但 WebUI 打不開」時先確認埠口。

主人系統設定

主人系統用於識別「框架主人」帳號(如 Bot 管理員)。master.users 支援三種寫法:

[ErisPulse.master]
# 寫法一:全域主人(所有平台生效,含之後新增的平台)
users = ["123456", "789012"]

# 寫法二:僅按平台指定主人(dict)
# users = { yunhu = ["123456"], telegram = ["789012"] }

# 寫法三:全域 + 平台專屬共存——dict 中的 global 鍵為全域主人桶
# users = { global = ["123456"], yunhu = ["789012"] }
設定項 類型 預設值 說明
users array / object 空 主人帳號列表。list 形式為全域主人(所有平台生效);dict 形式按平台指定(鍵為平台名,global 鍵為全域主人桶),值為該平台的主人帳號列表

關於新平台:list 形式與 dict 中的 global 桶都是「定義一次、全平台生效」, 之後接入新平台無需再改設定;平台專屬條目則只對同名(含前綴/萬用字元寬容匹配)平台生效。 master.add(None, uid) 持久化時寫入 global 桶,已有平台條目不受影響。

程式碼中透過 master.is_master(event) 或 master.is_master(platform, user_id) 檢查,每次呼叫即時讀取設定(支援熱更新,無需重啟):

from ErisPulse.Core import master

if master.is_master(event):
    await event.reply("主人你好")

判定鏈與執行時增刪

主人判定鏈為 設定主人 → 執行時記錄 → provider 鏈:

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

自訂身分來源(provider)

除設定外,還可註冊自訂身分來源:fn(platform, user_id) -> bool, 內建身分來源(設定 + 執行時記錄)未命中時依序嘗試,任一 provider 放行即認定為主人。 適合對接轉接器管理員介面、資料庫角色等外部身分體系。

註冊入口 master.provider 支援裝飾器 / 函式風格兩種寫法, 註銷統一透過被註冊函式上的 fn.unregister():

from ErisPulse.Core import master

# 寫法一:裝飾器(常駐身分來源,推薦)
@master.provider
def admin_provider(platform, user_id):
    return user_id in {"999"}     # 自訂判定邏輯

master.is_master("yunhu", "999")   # True
admin_provider.unregister()        # 不再需要時註銷

# 寫法二:函式風格(模組載入期註冊 / 卸載期註銷)
fn = master.provider(admin_provider)
fn.unregister()

provider 例外會被捕獲並跳過,不阻斷身分判定鏈。 綁定實例方法無法掛載 unregister,需要註冊/註銷配對的情境請用模組級函式。

使用者優先:主人生效範圍由使用者最終決定

指令的 master=True 只是開發者預設:使用者可在 ErisPulse.event.overrides.command.<module>.<cmd>.master = true/false 覆寫收緊或放寬(見統一事件覆寫設定,使用者明確設定即生效)。

日誌設定

[ErisPulse.logger]
level = "INFO"
log_files = []                # 明確日誌檔案清單(與 log_dir 互斥,優先級更高)
log_dir = ""                  # 日誌目錄(設定後自動分段輪轉)
log_rotation = "size"         # 分段方式: "size" / "date" / "none"
log_max_size_mb = 10          # size 模式單檔案上限(MB)
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"]
設定項 類型 預設值 說明
level string INFO 日誌級別:TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL(TRACE 為最低級別,輸出框架內部詳細除錯資訊)
format string rich 日誌輸出格式:rich(彩色,預設)、plain(純文字無顏色,適合日誌擷取/管道重新導向)、json(JSON 結構化,適合 ELK 等)
log_files array 空 日誌輸出檔案清單(明確路徑,不分段)
log_dir string 空 日誌輸出目錄(自動建立)。設定後寫入目錄內 erispulse.log 並按 log_rotation 自動分段;與 log_files 互斥,log_files 優先
log_rotation string size 分段方式:size(按大小)/ date(按時間)/ none(不分段)
log_max_size_mb float 10 size 模式單檔案大小上限(MB),超過後輪轉為 .1/.2 備份
log_backup_count integer 5 保留的歷史日誌檔案數,超出的最舊備份自動刪除
log_rotation_when string midnight date 模式輪轉週期:S/M/H/D/midnight(預設每天零點)
memory_limit integer 1000 單模組記憶體中保存的日誌條數;0 表示關閉記憶體日誌副本(不再寫入記憶體,已有記錄保留)
total_memory_limit integer 5000 全部模組記憶體日誌總條數上限;0 表示不限。超限時按輪轉策略淘汰最舊記錄(優先削減條數最多的模組佇列),與單模組 memory_limit 獨立生效
exclude_levels array 空 屏蔽指定日誌等級。被屏蔽等級的日誌完全丟棄(不寫記憶體、不推送給 Dashboard 等訂閱器、不列印、不寫檔案)。支援熱更新

也可在程式碼中動態切換:

from ErisPulse.Core import logger

# 按大小分段:單檔案 10MB,保留 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)

Note

log_dir 及分段相關設定需要 ErisPulse **2.8.0+**。

隱私保護:訊息收發內容以 EVENT 等級(數值 21)記錄。設定 exclude_levels = ["EVENT"] 即可讓後台(如 Dashboard 日誌面板)無法看到各群/私聊的訊息內容,同時不影響其它等級日誌。

除設定檔(支援熱更新)外,也可在執行時以程式碼切換同等能力——做 /privacy on|off 類管理命令時不必寫設定:

from ErisPulse import logger

logger.exclude_level("EVENT")        # 執行時屏蔽某等級(同 exclude_levels 設定語義)
logger.allow_level("EVENT")          # 恢復該等級
logger.list_excluded_levels()        # 檢視目前被屏蔽的等級
logger.set_format("json")            # 輸出切 JSON 行協定(與 format 設定鍵同效)

Note

exclude_levels 本特性需要 ErisPulse **2.8.0+**。

框架設定

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

[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []
設定項 類型 預設值 說明
enable_lazy_loading boolean true 是否啟用模組懶載入
uninit_timeout integer 30 優雅關閉的總逾時時間(秒),超過後強制終止。0 表示不設逾時
strict_mode integer 0 嚴格模式級別,見下方「嚴格模式」說明
handler_max_concurrency integer 64 事件處理器最大並行 Task 數,設大提高吞吐但增加記憶體佔用
handler_queue_max_pending integer 4096 事件洪峰入列背壓:單平台待處理 handler Task 數上限,超限時新事件的處理器 Task 直接丟棄並記 WARNING(丟棄計數可在 troubleshoot 疑難排解中查看);0 表示不限
offline_bot_expiry integer 3600 離線 Bot 記錄自動過期時間(秒),0 表示不過期
plugins_dir string / list "plugins" 本機外掛資料夾(相對專案根目錄);新增/刪除/修改外掛檔案會被熱重載 watcher 自動發現
watch_ignore_dirs list 內建清單 熱重載檔案監控忽略的目錄名(.venv/.git/__pycache__ 等);非空列表整體替換內建清單,[] 表示不忽略任何目錄
watch_include_plugin_dirs boolean true epsdk run --reload 是否把外掛目錄交給外掛熱重載 watcher 精確處理(單模組重載),並從全量監控中排除
event_dedupe boolean true 事件冪等去重:相同事件 id 的重複投遞(連線層重推 / 閘道重發)只分發一次
cross_account_policy string "off" 跨帳戶重複受理策略:同一實體訊息經多個帳戶先後到達時的處理——off 不關聯(事件照常逐一分發);mark 副本注入頂層 multi_receipt 欄位(指向首個受理事件)後照常分發,模組讀取該欄位自行裁決;drop 副本在分發入口直接丟棄(框架層去重,模組無感)

主動 GC 設定

SDK 初始化完成後啟動主動 GC 背景任務,週期性執行 Python GC 與內部資源回收(離線 Bot 清理等)。全部參數均支援熱更新,變更時即時重啟任務。

設定項 類型 預設值 說明
proactive_gc_interval number 300 回收間隔(秒),支援小數。0 表示停用主動 GC
proactive_gc_generation integer 0 常規輪次回收分代(0/1/2,鉗制到 0..2)。注意 gc.collect(2) 等同於全量回收,預設 0 保持輕量;深度回收由 proactive_gc_full_every 週期性觸發
proactive_gc_full_every integer 20 每 N 輪做一次全量回收,0 表示停用週期性全量。全量回收受 proactive_gc_memory_growth_mb 門檻約束
proactive_gc_memory_growth_mb integer 32 全量回收的記憶體成長門檻(MB):對比上次全量後的記憶體基線(優先 tracemalloc,其次 RSS),僅當成長達到此值才執行全量回收。0 表示不設門檻
proactive_gc_idle_only boolean false 開啟後,事件洪峰(存在未完成的 pending handler)時本輪跳過 Python GC,避免停頓與訊息處理競爭;內部資源回收不受影響
proactive_gc_gen0_min integer 500 常規輪次觸發回收的 gen0 垃圾量下限:gc.get_count()[0] 低於此值直接跳過(空轉輪次近乎零開銷)。0 表示始終回收

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 嚴格-跳過 拒絕未繼承基底類別的元件並跳過,其餘正常啟動
2 嚴格-致命 收集所有違規後統一報告並中止整個啟動

各級別下,「載入/註冊/初始化階段報錯」這類元件自身崩潰始終會被跳過;區別在於:

  • 0 → 1:唯一行為變化是「未繼承基底類別」從「仍載入」變為「跳過」。
  • 1 → 2:所有違規(未繼承基底類別、載入失敗、註冊失敗、初始化失敗等)升級為致命,會在啟動檢查點收集後一次性輸出違規清單並中止。

豁免清單

如果某些元件確實暫時無法遷移(例如依賴的舊模組),可以將其加入豁免清單,被列名的元件即使不合規也會按寬鬆模式對待,繼續載入:

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

當某個元件被嚴格模式拒絕時,日誌會明確提示如何恢復載入(加入豁免清單或調低級別)。

與 CLI 的聯動

epsdk run 的啟動前自檢(設定檔可解析性、元件必填設定完整性)預設跟隨本設定:非 0 時檢查失敗即拒絕啟動,0 時僅警告繼續。也可以不改設定臨時切換:epsdk run --strict 本次將自檢與嚴格級別同時開啟(級別只升不降,經 ERISPULSE_FRAMEWORK_STRICT_MODE 環境變數傳導至執行中的處理程序),--no-strict 本次臨時壓到寬鬆並僅警告。

存儲配置

2.8.0 起存儲引擎支援三種異步後端,API 完全一致、配置一鍵切換:

後端 驅動 安裝 特點
SQLite(預設) aiosqlite 開箱即用 零配置、單檔案、WAL 併發
MySQL / MariaDB aiomysql pip install ErisPulse[mysql] 已有 MySQL 基礎設施、多實例共享
PostgreSQL asyncpg pip install ErisPulse[postgres] 事務能力強、高併發
[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
配置項 類型 預設值 說明
backend string sqlite 存儲後端:sqlite / mysql / postgres,切換零程式碼改動
use_global_db boolean false 僅 SQLite:是否使用包內全局資料庫而非專案獨立資料庫
storage.mysql.* table 見上 MySQL 連線參數(host / port / user / password / database / charset / pool)
storage.postgres.* table 見上 PostgreSQL 連線參數(host / port / user / password / database / pool)

也支援環境變數覆蓋(Docker / 12-factor):ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST。

Tip

  • 連線參數變更後需重啟框架生效;連線池建立瞬時失敗會自動指數退避重試
  • 切換後端前可用驗證腳本自檢:python tests/devs/test_storage_backend_verify.py --backend mysql
  • 事務 / 方言差異 / 自訂後端等完整說明見存儲後端

事件配置

命令配置

[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false
配置項 類型 預設值 說明
prefix string / 命令前綴
case_sensitive boolean true 是否區分大小寫(/Help 與 /help 是否為不同命令)
allow_space_prefix boolean false 是否允許空格作為前綴
must_at_bot boolean false 是否必須@機器人才能觸發命令(私聊不受限制)

訊息配置

[ErisPulse.event.message]
ignore_self = true
配置項 類型 預設值 說明
ignore_self boolean true 是否忽略機器人自己的訊息

事件去重共三層,各管一類重複:event_dedupe(framework,相同事件 id 的重複投遞)→ ignore_self(本節,機器人自身訊息)→ cross_account_policy(framework,多帳戶同群的內容級副本)。分層職責詳見適配器核心概念。

會話收件匣配置(transcript)

[ErisPulse.transcript]
enabled = true
max_per_session = 50
ttl_hours = 168.0
self_echo = "bot"
配置項 類型 預設值 說明
enabled boolean true 是否自動記錄入站/出站訊息(關閉後停止寫入,歷史仍可查詢)
max_per_session int 50 單會話保留條數(0 = 關閉該會話裁剪)
ttl_hours float 168.0 全域保留時長(小時,0 = 永不清理)
self_echo string bot 入站 bot 回聲(self.user_id == user_id,如 OneBot report-self-message)處理:bot = 記為 bot 並標記 meta.self_echo;skip = 不記錄;user = 記為 user(舊行為)

保留策略的風險與稽核見 會話收件匣;歸因欄位(sender / meta)與出站歸屬(meta.module)同見該文檔。

國際化配置

[ErisPulse.i18n]
language = "auto"
配置項 類型 預設值 說明
language string auto 框架內建文字的顯示語言。設為 auto 自動檢測系統語言,也可設為具體代碼:zh-CN、zh-TW、en、ja、ru

模組配置

每個模組可以在配置檔案中定義自己的配置:

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

Note

本特性需要 ErisPulse **2.8.0+**。

作用域宣告「什麼範圍內生效」——某平台 / Bot / 會話裡哪些模組可用(① 模組維度)、 某用戶 / 群 / Bot / 適配器的事件收不收(② 身份維度)、 模組能發起哪些出站呼叫(③ 出站維度):

[ErisPulse.scope]
default_allow = true        # 全局兜底(false = 隱式拒絕嚴格模式;不受影響出站維度)
cache_size = 1024           # LRU 快取大小

# ① 模組維度(優先級:會話 > Bot > 平台;條目支援精確 / glob / re: 正則)
[ErisPulse.scope.platforms.onebot11]
modules = ["Chat", "Tool*"]
blocked = ["re:^Danger"]

# 子級綁定寫 merge = true 時與低優先級逐條目並集(預設整體覆蓋)
[ErisPulse.scope.bots.onebot11."123456"]
modules = ["Music"]
merge = true

# ② 身份維度(優先級:用戶 > 會話 > Bot > 適配器;每級只寫 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 }                 # 禁止處理請求
配置項 類型 說明
scope.default_allow boolean 全局兜底:模組/身份未命中規則的放行/拒絕(true)
scope.cache_size integer LRU 快取大小(預設 1024)
scope.platforms / bots / sessions table ① 模組三級綁定:{modules=[...], blocked=[...], merge=bool?}
scope.identity.adapters / bots / sessions / users table ② 身份四級綁定:{allow=true} / {deny=true}
scope.actions.<module>.<動作> table ③ 出站規則:`{allow=[...], 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 兜底:未配置 ACL 的命令放行(`true`)/ 嚴格拒絕(`false`)
acl_default_allow = true
配置項 類型 說明
event.overrides.message.<module> table 文本條件:{pattern="...", regex="..."}
event.overrides.notice / request.<module> table {detail_types=[...], pattern, regex}
event.overrides.meta.<module> table {detail_types=[...]}
event.overrides.command.<module> table 模組級參數覆寫(hidden = true 等標量)
event.overrides.command.<module>.<command> table 命令級覆寫(命令級優先)
event.overrides.acl.<命令名> table 用戶黑白名單:{allow=[...], deny=[...]}
event.overrides.acl_default_allow boolean ACL 兜底:未配置 ACL 的命令放行(true)/ 嚴格拒絕(false)

運行時 API(from ErisPulse.Core.Event import overrides 後按類型子命名空間調用 overrides.message.set() / overrides.command.set() / overrides.acl.set() 等, 或經 sdk.Event.overrides 訪問) 見 事件處理入門 · 事件覆寫。

下一步

  • 按 L1 路徑繼續:下一篇 異常捕獲,學會寫不拖垮框架的錯誤處理
  • 不想手寫 TOML:用 epsdk config 互動式向導填寫宣告式配置項,見 CLI 命令參考 · config
  • 部署時不想改配置檔案:用環境變數覆蓋配置項,配合 部署指南 的 Docker 用法