运维参考

部署完成后的日常运维：升级、内存优化、安全边界、备份恢复、自愈机制。 部署步骤见 部署。

升级

• 框架升级：下载新版 zip，覆盖 bin/ 下同名文件（config.toml、data/、plugins/ 都不动），重启
• 插件升级：新 .anzu 覆盖 plugins/ 同名包（热重载自动重装），或控制台上传
• 插件设置每次保存前自动轮转 4 份备份；误保存可在插件页一键恢复

内存怎么省（2G 小机器）

实测（28 插件）：独占进程 1.0GB → 共享池 ~430MB。下面按你能在控制台里做的顺序排：

1. 只启用真正要用的插件：「插件」页可直接禁用。canvas / fortune 这类带大资源的插件最占内存。 看效果：「插件」页有每插件内存列，概览页有总内存和 24h 趋势。

2. 给 Node 插件设堆上限（防跑一天涨到几十 MB）——改 config.toml 后重启：

   [plugin]
   node_options = "--max-old-space-size=96"

3. 每晚定时重启一次：把 Node 堆释放回基线（Windows 计划任务跑 start.bat 即可）。

4. 以上都不够再加内存。

共享池（进阶）：声明了 cohost = true 的纯 JS 插件可以共用一个 Node 进程， 28 插件实测 1.0GB → ~430MB——但这个声明在插件打包侧，官方插件包会逐步开启； 包声明了之后，你在「共享池」页把它分进池即可，不需要改任何文件。

安全边界（部署前必读）

• 安装插件 = 授予代码执行权限：插件是独立进程，但以机器人进程的系统权限运行，能读环境变量和 data 目录；只安装可信来源的 .anzu。
• 签名：配置了 [plugin] trusted_keys 后，没有可信公钥或公钥格式错误会拒绝安装，不会静默跳过校验。
• 聊天图片代理：只允许公网 http/https（80/443），拒绝本机/内网/元数据地址，只返回嗅探为图片的内容并带 nosniff。
• WebUI：默认密码务必修改；配置里可写明文（读取时就地哈希），控制台改密后落盘的是 PBKDF2 哈希； 未配置密码时每次启动生成临时密码，写进 data/webui-password.txt（0600），不进日志，登录后请尽快改掉。
• 会话：退出登录只接受 POST（页面上是表单按钮）；会话令牌使用系统随机数，随机数不可用时登录直接禁用。
• CSRF：所有写操作校验同源 Origin + 会话绑定的 CSRF Token（表单 _csrf / 请求头 X-CSRF-Token）；退出登录会立即落盘删除会话，改密码会撤销其他会话。
• 控制台 HTTP：ReadHeaderTimeout 5s、ReadTimeout 30s、IdleTimeout 120s、请求头上限 1MB。
• 配置保存：多个管理页面同时保存会串行化（独立临时文件 + 原子替换），不会互相截断。
• 非消息事件（notice/request）走有界队列（256）异步处理：极端情况下会丢弃并记录 dropped 计数；需要不丢事件的业务请用插件轮询做补偿。
• config.toml 保存为仅所有者可读写（0600），里面可能有账号凭据。

备份与恢复

备份自动做两件事：WAL 先 checkpoint 进主库（框架在跑也不会拷出撕裂的库）、 备份产物自身不会被打进包里。

# 打包整个运行目录（config + plugins/*.anzu + data/）
.\bin\qixinbot.exe -backup D:\backup\qixinbot-2026-10-24.zip

# 恢复到当前目录（必须 -force 才覆盖已有 data/）
.\bin\qixinbot.exe -restore D:\backup\qixinbot-2026-10-24.zip -force

打包内容：config.toml、plugins/*.anzu、data/ 全部（含插件运行区、overrides.json、plugins-state.json、audit/）。不含 bin/。

恢复后检查 config.toml 的 [web] password——可能还是备份时的旧密码。

自愈机制（框架会自己扛的，不用人管）

故障	框架行为
OneBot 连接静默断掉（对端假活）	30s 心跳检测，失败立即断开重连（指数退避）；对端 30 分钟无业务事件会在连接页标「对端可能已挂起」
插件进程崩溃	supervise 自动重启；连续 6 次才熔断禁用；稳定运行 ≥10 分钟计数清零
插件挂死（不崩也不回）	连续 5 次消息超时自动禁用，不拖慢其它插件
cohost worker 崩溃	multi-host 自动重启该 worker 并重初始化；同一插件 24h 内崩 3 次自动逐出共享池（回独占，不自动回池）
共享池进程死亡	自动重建；同一池 10 分钟内死 3 次熔断该池（成员回独占，重启框架后重试共享）
共享池写管道挂死	写超时 5s 判死，自动重建该池
事件风暴	有界队列（256）异步处理，极端时丢弃并计数，不堵消息分发

排错

挂了先看这 5 分钟

1. 进程在吗：Get-Process qixinbot。不在就重新启动；还起不来，看 data\stderr.log 最后 30 行
2. 连上协议端了吗：日志搜 已连接上游 / 登录账号； 看到 心跳失败，关闭连接准备重连 → 是协议端那头的问题（进程死了/端口不通）
3. 协议端活着吗：协议端进程在不在、端口 3001 是否监听—— "框架正常但全哑"最常见的原因就是协议端进程死了
4. 插件被自动禁用了：WebUI「插件」页看状态（红色 = failed）； 日志搜 连续 5 次消息超时 / 连续崩溃；修好插件后在界面点「启用」
5. 消息到了但没人回：开 [log] gate_debug = true 看门禁拦截原因（见下）

机器人不理我

按顺序查：

1. 日志里有没有 收到消息？没有 → 协议端没把消息推过来
2. 有 收到消息 但没 已处理 → 被门禁或权限拦了
3. 打开 [log] gate_debug = true 再看，会有：

level=DEBUG msg=门禁拦截 plugin=weather reason=需要命令前缀 text="probe order"
level=DEBUG msg=门禁拦截 plugin=weather reason=权限不足 text="/weather 北京"

排查完记得关掉，否则每条消息都会刷 5 条日志。

现象	看哪里
进程没起来	data\stderr.log 最后 20 行
起来了但没反应	日志里有没有 已连接上游 / 登录账号
连不上协议端	协议端是否在跑、端口 3001 是否监听
命令不响应	日志里 收到消息 之后有没有 已处理
插件加载失败	日志里 插件清单无效 / 插件启动失败

用 mock 调试

排查框架问题时可以临时用 mock 协议端替代（发行包 bin/mock-onebot.exe 自带）：

bin\mock-onebot.exe -addr 127.0.0.1:3001

注意端口 3001 和正式协议端冲突，先停正式的那一个。

删除插件要删两处：控制台删除只清服务器上的包和运行区； 本地留着的同名 .anzu 在热重载下会重新装回来，彻底移除要删掉源头那个包。