name: erispulse-config-cli description: "适用于：配置声明式 schema、排查配置问题、使用 epsdk 命令行与部署。覆盖场景：- 连接参数变更后需重启框架生效；连接池创建瞬时失败会自动指数退避重试。忘记某个 epsdk 命令的参数、想把组件管理写进脚本，或要控制 run / stop / restart 行为时查阅。日常只用 init / install / run 的话，记住一条就够：epsdk <命令> --help 随时可查参数说明，不需要通读本文。需要挑一种安装方式（pip / uv / Docker / ErisPulse-App 客户端），或安装失败要排查时读。只想最快跑起来，5 分钟快速开始 已覆盖最简流程，。机器人要长期挂着跑时——Docker 部署、systemd / Supervisor 进程守护、反向代理与 SSL、备份与升级都在这里。本地开发调试阶段。"

ErisPulse 配置系统与 CLI 工具链

本技能由 ErisPulse 文档自动构建（generate-skills.py）。 仓库：https://github.com/ErisPulse/ErisPulse 各节末尾标注了来源文档路径，需要最新内容请以仓库 docs/zh-CN/ 为准。

内容大纲

AI 按需读取：只读需要的章节即可，不必全文加载。

• 配置系统: 65-76 行
• 配置文件位置: 78-95 行
• 配置加载错误处理: 97-118 行
• 注释保留与最小化落盘: 120-140 行
• 环境变量覆盖: 142-196 行
• 配置热更新: 198-267 行
• 配置读取与删除 API: 269-295 行
• 完整配置示例: 297-349 行
• 服务器配置: 351-379 行
• 主人系统配置: 381-453 行
• 日志配置: 455-503 行
• 框架配置: 505-576 行
• 存储配置: 578-625 行
• 事件配置: 627-654 行
• 会话收件箱配置（transcript）: 656-673 行
• 国际化配置: 675-684 行
• 模块配置: 686-713 行
• 作用域配置（scope）: 715-763 行
• 统一事件覆写配置（event.overrides）: 765-810 行
• CLI 参考: 812-825 行
• 包管理命令: 827-834 行
• 诊断命令: 836-989 行
• 信息查询命令: 991-1054 行
• 配置命令: 1056-1107 行
• 运行控制命令: 1109-1209 行
• 项目管理命令: 1211-1321 行
• 语言命令: 1323-1358 行
• 类型存根命令: 1360-1399 行
• 全局参数: 1401-1414 行
• 环境诊断: 1416-1457 行
• 交互式安装: 1459-1470 行
• 常见用法: 1472-1599 行
• 安装: 1601-1608 行
• 系统要求: 1610-1614 行
• 安装方式: 1616-1691 行
• 项目初始化与模块安装: 1693-1707 行
• 验证安装: 1709-1732 行
• 常见问题: 1734-1776 行
• 部署: 1778-1787 行
• Docker 部署（推荐）: 1789-1879 行
• Dashboard 管理面板: 1881-1907 行
• 进程监督与硬重启: 1909-1918 行
• 健康检查: 1920-1940 行
• 反向代理: 1942-1972 行
• 手动部署（pip）: 1974-2065 行
• 安全建议: 2067-2074 行
• 多实例部署: 2076-2082 行
• 更新与维护: 2084-2138 行

配置系统

来源: docs/zh-CN/user-guide/configuration.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/zh-CN/user-guide/configuration.md）

配置文件说明

这篇讲框架自身的配置文件 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 时会区分三种错误状态，并给出可操作的诊断信息，而不是静默回退到默认配置：

注意"上次有效配置"≠ 默认配置：文件损坏时框架沿用本次启动前最后一份解析成功的配置（运行中热更新改坏文件则沿用旧值），而不是把所有配置项重置为出厂默认。故障处置时不要假设"配置已被重置"。

例如，当你不慎把配置写成了 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_ 前缀：

行为说明：

• 优先级最高：环境变量覆盖「配置文件」与「默认值」，按原值类型自动转换（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 检测到外部修改后只更新内存缓存，不会把外部改动回写文件。

自动响应方清单（两类事件通常会都订阅，响应内容一致）：

配置读取与删除 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-----"""

端口占用不是致命错误：启动时若检测到 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             # 单模块内存日志条数上限（0 = 关闭内存日志副本）
total_memory_limit = 5000       # 全部模块内存日志总条数上限（0 = 不限）
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"]

当某个组件被严格模式拒绝时，日志会明确提示如何恢复加载（加入豁免清单或调低级别）。

与 CLI 的联动

epsdk run 的启动前自检（配置文件可解析性、组件必填配置完整性）默认跟随本配置：非 0 时检查失败即拒绝启动，0 时仅警告继续。也可以不改配置临时切换：epsdk run --strict 本次将自检与严格级别同时开启（级别只升不降，经 ERISPULSE_FRAMEWORK_STRICT_MODE 环境变量传导到运行进程），--no-strict 本次临时压到宽松并仅警告。

存储配置

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

会话收件箱配置（transcript）

[ErisPulse.transcript]
enabled = true
max_per_session = 50
ttl_hours = 168.0
self_echo = "bot"

保留策略的风险与审计见 会话收件箱；归因字段（sender / meta）与出站归属（meta.module）同见该文档。

国际化配置

[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 访问） 见 事件处理入门 · 事件覆写。

CLI 参考

来源: docs/zh-CN/user-guide/cli-reference.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/zh-CN/user-guide/cli-reference.md）

CLI 命令参考

epsdk 是 ErisPulse 的命令行工具：初始化项目、安装 / 升级模块与适配器、交互式配置组件、运行与停止机器人、诊断环境，都在这一条命令下。

提示：epsdk（不带命令）的主帮助按类别分组展示：项目（init / create / run）、组件管理（install / uninstall / upgrade / list / list-remote / types）、配置与诊断（config / doctor / i18n）、其他（self-update / version）。

包管理命令

诊断命令

install

安装 ErisPulse 模块或适配器包。若不指定包名则进入交互式安装界面。

别名： i, add

uv 项目联动（2.11.1+）：在 uv 管理的项目内（存在 uv.lock 或 [tool.uv]）， install / upgrade / uninstall 自动改走 uv add / uv remove——依赖同步写入 pyproject.toml 与 uv.lock，uv sync 不再清掉 epsdk 装的组件；失败自动回退 uv pip / pip 通道。--user 等 uv 不支持的参数直接走 pip。目标环境解析顺序： ERISPULSE_PYTHON → UV_PROJECT_ENVIRONMENT → 项目 .venv → UV_PYTHON → VIRTUAL_ENV → 当前解释器（epsdk doctor 可查看完整决策链）。

参数：

示例：

# 安装单个模块
epsdk install Weather

# 安装多个模块
epsdk install Yunhu Weather

# 从镜像源安装并升级
epsdk install Weather -U --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 可编辑模式安装（开发模式）
epsdk install -e ./my-adapter

uninstall

卸载已安装的 ErisPulse 模块或适配器包。若不指定包名则进入交互式卸载界面。

别名： rm, remove

参数：

示例：

# 卸载单个模块
epsdk uninstall Weather

# 卸载多个模块
epsdk uninstall Yunhu Weather

upgrade

升级已安装的 ErisPulse 组件。不指定包名则交互式升级全部。

别名： up

参数：

示例：

# 升级所有包
epsdk upgrade

# 升级指定包
epsdk upgrade Weather

# 强制升级（跳过确认）
epsdk upgrade -f

self-update

更新 ErisPulse SDK 本身到最新版本。

别名： su, update

参数：

示例：

# 更新到最新稳定版
epsdk self-update

# 更新到指定版本
epsdk self-update 1.2.3

# 允许预发布版本
epsdk self-update --pre

# 强制更新
epsdk self-update -f

信息查询命令

list

列出已安装的 ErisPulse 模块和适配器。

别名： l, ls

参数：

示例：

# 列出所有已安装的组件
epsdk list

# 只列出模块
epsdk list -t modules

# 只列出适配器
epsdk list -t adapters

# 只显示可升级的包
epsdk list -o

list-remote

列出远程仓库中可用的 ErisPulse 模块和适配器。

别名： lsr

参数：

示例：

# 列出所有远程可用组件
epsdk list-remote

# 只列出远程模块
epsdk list-remote -t modules

# 强制刷新缓存后列出
epsdk list-remote -r

配置命令

config

交互式填写适配器/模块的声明式配置项。向导由适配器/模块声明的配置类（ConfigClass / AccountConfigClass）驱动，自动生成表单并校验，无需手写 config.toml。

适配器额外支持多账户（bot 账户）管理：添加/编辑/删除账户，以及启用/禁用开关。

别名： cfg, conf

参数：

示例：

# 查看所有适配器/模块的配置状态
epsdk config --list

# 以 JSON 输出配置状态（CI / 脚本消费）
epsdk config --json

# 交互选择目标进行配置
epsdk config

# 直接配置指定适配器
epsdk config yunhu

# 直接配置指定模块
epsdk config MyModule

说明：

• 配置状态分为四档：已就绪（校验通过）、待完善（必填项缺失或校验失败）、未配置（从未生成）、无配置（目标未声明配置类）
• 字段值带来源标注：已有配置显示 （当前:值），未配置时显示 schema 默认值 （默认:值）；直接回车即保留该值
• 密钥类字段（声明 secret）输入时不回显，回车保留已设置的值
• 交互选择模式下，单个向导结束后会回到选择菜单（状态已刷新），可连续配置多个目标，留空退出
• 全局表单校验失败且放弃重新填写时，本次向导中止且不写入任何配置（避免产生"已启用但配置不完整"的半成品状态）
• 保存后立即写入 config/config.toml，Dashboard 与运行中的 SDK 均可见；运行中的适配器如需应用新账户配置，重启进程即可
• epsdk install（交互式安装）与 epsdk init 安装适配器成功后，若检测到配置声明会自动引导进入本向导；命令行直接指定包名安装时仅打印配置提示

运行控制命令

run

运行 ErisPulse 项目脚本或直接启动 SDK。支持热重载模式。

别名： r

参数：

示例：

# 直接运行 SDK
epsdk run

# 运行指定脚本文件
epsdk run main.py

# 热重载模式运行（文件变更自动触发代码级热重载）
epsdk run main.py --reload

# SDK 热重载模式
epsdk run --reload

# 临时严格模式：启动前自检失败即退出，框架严格级别本次提升为至少 1
epsdk run main.py --strict

# 临时宽松模式（配置里开了 strict_mode 但本次想先跑起来）
epsdk run main.py --no-strict

启动前自检： run 启动前会快速检查 config/config.toml 可解析性与已安装组件的必填配置完整性，严格性默认跟随 ErisPulse.framework.strict_mode（非 0 时检查失败即退出，0 时仅警告继续）。配置文件缺失视为正常首次启动，仅提示不判失败。--strict 临时开启：预检失败即退出，同时框架严格级别本次提升为至少 1（跳过不合规组件，经 ERISPULSE_FRAMEWORK_STRICT_MODE 环境变量传导到运行进程，不写入配置文件）；--no-strict 反之临时压到宽松。自检自身异常时自动跳过，不含网络探测，不会阻塞启动。

--reload 的监督结构（2.11.1 起）：epsdk run --reload 以「监督进程 + 重载 worker 子进程」运行。保存 .py 文件触发的热重载全部在 worker 内完成（互斥串行、风暴合并）；模块侧语法错误会被整体预检拒绝，旧实例继续服务。sdk.hard_restart() 时 worker 以退出码 42 退出，监督进程展示原因后自动重拉全新 worker——升级框架本体后新代码即刻生效。

stop

停止正在运行的 ErisPulse 实例（由 epsdk run 启动、并在同一项目目录下执行）。 run 启动时会把监督进程 PID、当前框架子进程 PID 与原始启动命令写入 .erispulse/runtime.json，stop 据此定位实例。

停止顺序： POSIX 下先向监督进程发 SIGINT（与 Ctrl+C 同款优雅收尾路径—— finally 链自动终止框架子进程），超时逐级升级 SIGTERM / SIGKILL；Windows 无 进程信号语义，先终止框架子进程再终止监督进程（避免监督者把强杀误判为崩溃 重新拉起）。

参数：

示例：

# 停止当前项目的运行实例
epsdk stop

# 强制终止
epsdk stop --force

restart

重启正在运行的 ErisPulse 实例：按 stop 的语义停止后，以状态文件中记录的 原始启动命令重新启动（前台接管当前终端，新实例会写入新的运行状态文件）。

参数： 同 stop（--force / --pid PID）。

示例：

# 优雅重启（pip 升级适配器/模块后让代码生效；运行中模块也可用
# sdk.reload_module / sdk.adapter.reload 代码级热重载，无需重启）
epsdk restart

项目管理命令

init

初始化一个新的 ErisPulse 项目。支持交互式与快速模式，2.8.4 起生成 pyproject.toml（依赖清单）、可选创建项目 .venv 虚拟环境并安装框架与适配器，并支持指定任意目录。

参数：

示例：

# 交互式初始化
epsdk init

# 快速初始化（当前目录下创建 my_bot/，含 pyproject.toml + .venv）
epsdk init -q -n my_bot

# 快速初始化并预装适配器（免交互，脚本 / CI 场景）
epsdk init -q -n my_bot --adapter yunhu,telegram

# 指定任意目录初始化（../apps/mybot）
epsdk init ../apps/mybot

# 组合父目录与项目名
epsdk init -n my_bot --path ../apps

# 强制覆盖已有配置
epsdk init -f

# 在当前目录初始化
epsdk init --here -n my_bot

# 只生成项目结构，不创建虚拟环境
epsdk init --no-venv -n my_bot

init 产物：main.py、pyproject.toml（依赖清单）、config/config.toml + config.full.example、config/ssl/、logs/、.gitignore、README.md；选择创建虚拟环境时额外生成 .venv 并将 erispulse 与所选适配器安装其中。

create

创建 ErisPulse 模块或适配器的脚手架项目；pack 子命令将本地插件（plugins/ 目录）转换为可发布的标准项目。

参数：

示例：

# 交互式创建（引导选择类型和填写信息）
epsdk create

# 直接创建 Module 项目
epsdk create module -n MyModule

# 创建本地插件（放入项目 plugins/ 目录，启动时自动发现）
epsdk create module -n MyModule --local

# 创建本地适配器插件（同上，免打包开发）
epsdk create adapter -n MyAdapter --local

# 直接创建 Adapter 项目
epsdk create adapter -n MyAdapter

# 将本地插件转换为可发布项目（交互选择插件 → 补全元信息 → 生成标准项目）
epsdk create pack

# 完整参数
epsdk create module -n MyModule -d "模块描述" -a "作者" -e "[email protected]"

# 指定输出目录
epsdk create module -n MyModule -o ./projects

# 强制覆盖已有目录
epsdk create module -n MyModule -f

语言命令

i18n

查看当前 CLI 语言、列出支持的语言、切换显示语言。若不指定参数则进入交互式选择界面。

别名： language, lang

参数：

示例：

# 交互式选择语言
epsdk i18n

# 切换到英文
epsdk i18n en

# 切换到日文
epsdk i18n ja

# 列出所有支持的语言
epsdk i18n --list

类型存根命令

types

扫描已安装的 ErisPulse 模块和适配器，为它们生成 .pyi 类型存根文件，从而在 IDE 中获得准确的代码补全与类型检查支持。

别名： t, stub

参数：

注意： --adapters-only 与 --modules-only 互斥，同时指定时后者生效。

示例：

# 为所有已安装的模块和适配器生成类型存根
epsdk types

# 仅生成适配器存根
epsdk types --adapters-only

# 输出到指定目录
epsdk types -o ./typings

# 强制覆盖已有文件
epsdk types --force

全局参数

以下参数适用于所有命令：

环境诊断

doctor

诊断当前 CLI 运行环境，输出健康报告。用于排查"为什么装不上 / 连不上"类问题。

检查项：

• Python：解释器版本与路径
• 安装后端：使用 uv 还是 pip
• 目标解释器：包实际安装到的目标 Python 环境
• 配置文件：config/config.toml 是否存在
• 组件配置：已安装组件的声明式配置完整性（"装好了跑不起来"多因必填项缺失）
• 配置污染（2.11.1+）：扫描历史升级遗留的残留键（旧版运行时绑定的影子状态键、游离配置节），检出即提示
• PyPI 连通性：能否访问 PyPI（并显示发现的组件数）
• 系统代理：是否检测到代理

自动修复（--fix）：

• config.toml 缺失 → 按当前语言生成初始配置文件（与 init 建项同源）
• 组件配置"待完善" → 逐个拉起交互式配置向导补全必填项（非交互环境提示改用 epsdk config <名称>）
• 配置污染残留键 → 列明来源并经确认后删除（tomlclass 无损路径，注释与顺序保真）
• Python 版本过低、PyPI 无法访问等需人工介入的问题 → 仅输出行动建议

# 运行环境诊断
epsdk doctor

# 使用别名
epsdk diag

# 诊断并尝试自动修复
epsdk doctor --fix

交互式安装

运行 epsdk install 不指定包名时进入交互式安装：

epsdk install

交互界面提供：

1. 适配器选择
2. 模块选择
3. 自定义安装

常见用法

安装模块

# 安装单个模块
epsdk install Weather

# 安装多个模块
epsdk install Yunhu Weather

# 升级模块
epsdk install Weather -U

列出组件

# 列出所有组件
epsdk list

# 只列出适配器
epsdk list -t adapters

# 只列出可升级的组件
epsdk list -o

# 查看远程可用组件
epsdk list-remote

卸载组件

# 卸载单个组件
epsdk uninstall Weather

# 卸载多个组件
epsdk uninstall Yunhu Weather

配置组件

# 查看配置状态
epsdk config --list

# 交互选择目标配置
epsdk config

# 配置指定适配器
epsdk config yunhu

升级组件

# 升级所有组件
epsdk upgrade

# 升级指定组件
epsdk upgrade Weather

# 强制升级
epsdk upgrade -f

运行项目

# 普通运行
epsdk run main.py

# 热重载模式
epsdk run main.py --reload

切换语言

# 交互式选择语言
epsdk i18n

# 直接切换到英文
epsdk i18n en

# 列出支持的语言
epsdk i18n --list

生成类型存根

# 生成所有类型存根
epsdk types

# 仅生成模块类型存根
epsdk types --modules-only

初始化项目

# 交互式初始化
epsdk init

# 快速初始化
epsdk init -q -n my_bot

创建脚手架

# 交互式创建（引导选择类型和填写信息）
epsdk create

# 直接创建 Module 项目
epsdk create module -n MyModule

# 直接创建 Adapter 项目
epsdk create adapter -n MyAdapter

# 完整参数
epsdk create module -n MyModule -d "模块描述" -a "作者" -e "[email protected]"

# 强制覆盖已有目录
epsdk create module -n MyModule -f

安装

来源: docs/zh-CN/user-guide/installation.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/zh-CN/user-guide/installation.md）

安装参考

系统要求

• Python 3.10 – 3.14（3.14t 自由线程 / 无 GIL 构建为实验性支持，框架以实验性 CI 冒烟持续监测，不作正式承诺）
• pip 或 uv（推荐）
• 足够的磁盘空间（至少 100MB）

安装方式

方式一：使用 pip 安装

# 安装 ErisPulse
pip install ErisPulse

# 升级到最新版本
pip install ErisPulse --upgrade

方式二：使用 uv 安装（推荐）

uv 是一个更快的 Python 工具链，推荐用于开发环境。

安装 uv

# 使用 pip 安装 uv
pip install uv

# 验证安装
uv --version

创建虚拟环境

# 创建项目目录
mkdir my_bot && cd my_bot

# 安装 Python 3.12
uv python install 3.12

# 创建虚拟环境
uv venv

激活虚拟环境

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

安装 ErisPulse

# 安装 ErisPulse
uv pip install ErisPulse --upgrade

方式三：使用 uv tool 安装（全局 CLI，推荐）

只想把 epsdk 当全局命令行工具使用时，uv tool install 是最干净的方式—— epsdk 运行在独立的工具环境中，不污染任何项目环境：

# 安装（epsdk 立即可用，无需激活任何虚拟环境）
uv tool install ErisPulse

# 升级（或直接使用 epsdk self-update，会自动走此通道）
uv tool upgrade ErisPulse

项目初始化与模块安装

安装完成后，项目初始化、模块安装、运行的完整流程见 5 分钟快速开始。

方式四：使用 ErisPulse-App 客户端（免终端）

不想装 Python 环境？ErisPulse-App 是官方全平台客户端 （Android / Windows / Linux / macOS），手机直接运行，桌面版支持最小化到 系统托盘后台常驻；内置 Python 运行时与 ErisPulse SDK，无需终端与手动配置：

• 从 GitHub Releases 按平台选择下载 （Android online/offline APK、Windows setup.exe/zip、Linux tar.gz、macOS zip）
• 在 App 内创建并启动实例，通过原生界面管理适配器与模块、浏览模块商店

完整说明见 ErisPulse-App 安装与使用。

验证安装

检查安装

# 检查 ErisPulse 版本
epsdk --version

运行测试

# 运行项目
epsdk run main.py

如果看到类似的输出说明安装成功：

[INFO] 正在初始化 ErisPulse...
[INFO] 适配器已加载: Yunhu
[INFO] 模块已加载: MyModule
[INFO] ErisPulse 初始化完成

常见问题

安装失败

1. 检查 Python 版本是否在支持范围内（支持 3.10 – 3.14；3.14t 自由线程 / 无 GIL 构建为实验性支持，不作正式承诺）
2. 尝试使用 uv pip install ErisPulse 替代 pip install
3. 如果提示权限错误，尝试 pip install --user ErisPulse 或使用虚拟环境
4. 如果在企业代理环境下遇到 SSL 证书错误，尝试 pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ErisPulse
5. 确保网络连接正常，pip 源可访问

配置错误

1. 检查 config.toml 语法是否正确（TOML 格式对缩进和引号敏感）
2. 确认所有必需的配置项都已填写
3. 查看终端日志获取详细错误信息
4. 使用 epsdk init 重新生成配置文件

模块安装失败

1. 确认模块名称拼写正确（大小写敏感）
2. 检查网络连接
3. 使用 epsdk list-remote 查看可用模块列表
4. 确认模块与你当前 SDK 版本兼容

Windows PowerShell 执行策略

如果 PowerShell 提示"无法加载文件...因为在此系统上禁止运行脚本"：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Debian/Ubuntu 虚拟环境创建失败

如果安装脚本提示「虚拟环境创建失败」，且错误信息包含 ensurepip is not available，是因为 Debian/Ubuntu 默认未安装 python3-venv（系统 Python 的 ensurepip 被禁用）：

sudo apt install python3.13-venv   # 按实际 Python 版本安装对应包
# 或安装通用元包：
sudo apt install python3-venv

安装后重新运行安装脚本即可。新版安装脚本在检测到该问题时会主动询问并尝试自动安装对应系统包；也可以改用 uv（uv venv 不依赖 ensurepip）。

部署

来源: docs/zh-CN/user-guide/deployment.md（https://github.com/ErisPulse/ErisPulse/blob/main/docs/zh-CN/user-guide/deployment.md）

部署指南

机器人开发完只是开始。这篇覆盖把它稳定挂在服务器上所需的三种部署方式（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 保持一致（仓库版本头部另有镜像加速与环境变量说明注释），推荐直接下载使用。

环境变量

数据持久化

./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：官方 compose 使用 restart: on-failure:5——非零退出码即重启（覆盖硬重启的退出码 42），连续 5 次上限防死循环；需要不限次数可自行改为 unless-stopped
• systemd：Restart=on-failure + RestartForceExitStatus=42
• PM2 / supervisord：将 42 加入可重启退出码
• 纯 Python 自定义监督者：循环 Popen + 检测 returncode == 42

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

健康检查

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，组件（适配器/模块）应装进项目 .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 进项目目录

安全建议

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

多实例部署

运行多个机器人实例时：

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

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 中使用「备份」功能导出