AstrBot/docs/zh/others/diagnostics.md

异常诊断

当 AstrBot 出现“看起来没有报错，但明显变慢或卡住”的情况时，可以先从事件循环诊断日志入手。事件循环是 AstrBot 调度消息、插件、定时任务、模型请求和工具调用的核心；如果它被同步阻塞或长期无法恢复，很多功能都会表现为延迟。

常见现象

• 群聊或私聊消息已经进入 AstrBot，但过了几十秒甚至几分钟才继续处理。
• 日志停在 ready to request llm provider、acquired session lock for llm request、工具调用结果之后，很久才出现下一条 Agent 日志。
• 主动任务、定时任务已经触发，但中间某一步迟迟不继续。
• 多个平台或多个会话同时变慢，而不是只有单个用户的请求慢。
• 进程 CPU 异常升高，或 CPU 不高但请求长时间等待外部服务返回。

查看诊断日志

AstrBot 会记录事件循环延迟。如果延迟超过阈值，主日志中会出现类似日志：

Event loop lag detected: 18.432s (threshold 15.000s).

如果事件循环长时间没有恢复，AstrBot 会把 Python 线程栈写入：

data/logs/event_loop_watchdog.log

该文件超过 1MB 后会轮转为：

data/logs/event_loop_watchdog.log.1

你也可以同时查看主日志：

data/logs/astrbot.log

如果使用 Docker 部署，也可以用：

docker logs <container-name>

排查思路

1. 先确认是否有 Event loop lag detected 日志。如果有，说明 AstrBot 主事件循环确实经历了明显延迟。
2. 查看 data/logs/event_loop_watchdog.log，关注栈顶附近正在执行的代码。常见线索包括插件函数、平台适配器、MCP 工具、同步网络请求、time.sleep()、subprocess.run()、CPU 密集循环等。
3. 如果没有事件循环延迟日志，但某次对话仍然卡很久，优先检查模型服务商、代理、网络、工具调用超时、MCP 服务响应时间。
4. 如果只有某个会话卡住，可能是该会话内前一个请求还没有结束；如果所有会话都卡住，更可能是事件循环被阻塞。
5. 如果 CPU 长时间 100%，优先关注 watchdog 栈和 MCP/插件相关调用；如果 CPU 很低，更常见的是等待外部网络或模型服务返回。

提交 Issue 时请附带

提交问题时，请尽量提供以下信息，方便定位：

• 问题发生的大致时间点和时区。
• AstrBot 版本、部署方式（Docker、手动部署、桌面客户端等）、操作系统。
• 触发方式：普通聊天、群聊、定时任务、MCP 工具、插件功能等。
• data/logs/astrbot.log 中问题发生前后 1 到 3 分钟的日志。
• data/logs/event_loop_watchdog.log 和 data/logs/event_loop_watchdog.log.1（如果存在）。
• 如果使用 Docker，请附带对应时间段的 docker logs。
• 已安装插件列表，以及问题是否在禁用第三方插件后仍然出现。

提交日志前请先检查并遮盖 API Key、Token、Cookie、私聊内容等敏感信息。