配置文件說明

本文件將介紹框架的配置文件，若有第三方模組需要配置，請參考模組的文件。

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

配置文件位置

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

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

多實例提示與鎖檔案

框架啟動時會在 config/ 目錄下建立 .erispulse_config.lock 鎖檔案並持有至進程退出（用於偵測多實例共享配置目錄）。如果日誌出現「偵測到配置檔案可能正被另一個 ErisPulse 實例同時使用」的告警，說明有兩個以上的 ErisPulse 進程在寫同一份配置（典型場景：多個容器掛載了同一個主機 config/ 目錄）—— 並發寫入會互相覆蓋，請為每個實例使用獨立的配置目錄。

配置載入錯誤處理

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

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

例如，當你不慎把配置寫成了 port = 8000（缺少引號的字串）時，日誌會輸出類似：

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

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

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

註釋保留與最小化落盤

config.toml 中的註釋與鍵順序在框架寫入後完整保留：無論是程式碼 setConfig()、 CLI 配置向導儲存還是適配器/模組首次生成配置範本，框架都只修改涉及的鍵， 你寫的註釋、整理的順序不會被抹掉或重排（基於 tomlkit 註釋保留往返實現）。

框架對落盤內容保持克制：

• 框架預設配置不自動落盤：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 供參考

環境變數覆蓋

框架支援使用環境變數覆蓋 ErisPulse.* 配置項目（適合 Docker / 容器化 / CI 部署，無需修改 config.toml）。

命名規則：將點分路徑 ErisPulse.<section>.<key> 改為全大寫、. 替換為 _，並加上 ERISPULSE_ 前綴：

行為說明：

• 優先級最高：環境變數覆蓋「配置檔案」與「預設值」，按原值類型自動轉換（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() 後，各組件自動響應：

需重新啟動的配置（無法安全熱切換，變更時會輸出警告「需重新啟動進程後生效」）：

中途編輯保存出錯？ 若編輯 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 ...）"]

兩條檢測路徑（取其一即可，均能兜底）：

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

兩類配置變更事件：

setConfig() 預設延遲 5 秒落盤（合併多次寫入），immediate=True 立即寫。watcher 檢測到外部修改後只更新記憶體緩存，不會把外部變更回寫文件。

自動響應方清單（兩類事件通常會都訂閱，響應內容一致）：

完整配置示例

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

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

主人系統配置

主人系統用於識別「框架主人」帳號（如 Bot 管理員）。master.users 支援兩種寫法：

[ErisPulse.master]
# 寫法一：全局主人（所有平台生效）
users = ["123456", "789012"]

# 寫法二：按平台指定主人（dict）
# users = { yunhu = ["123456"], telegram = ["789012"] }

程式碼中透過 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
exclude_levels = ["EVENT"]

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

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)

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

框架配置

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

[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []

主動 GC 配置

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

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：唯一行為變化是「未繼承基類」從「仍加載」變為「跳過」。
• 1 → 2：所有違規（未繼承基類、加載失敗、註冊失敗、初始化失敗等）升級為致命，會在啟動檢查點收集後一次性輸出違規清單並中止。

豁免清單

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

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

當某個組件被嚴格模式拒絕時，日誌會明確提示如何恢復加載（加入豁免清單或調低等級）。

存儲配置

2.8.0 起儲存引擎支援三種非同步後端，API 完全一致、配置一鍵切換：

[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

也支援環境變數覆蓋（Docker / 12-factor）：ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST。

事件配置

命令配置

[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false

訊息配置

[ErisPulse.event.message]
ignore_self = true

國際化配置

[ErisPulse.i18n]
language = "auto"

模組配置

每個模組可以在配置文件中定義自己的配置：

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

作用域宣告"什麼範圍內生效"——某平台 / 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 }                 # 禁止處理請求

詳解與運行時 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

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

命令解析配置（event.command）

下一步

• CLI 命令參考 - 了解所有命令列命令
• 開發者指南 - 學習開發自訂模組