Skip to content

Troubleshooting

Jump to bottom
Laffey-82 edited this page Aug 31, 2026 · 1 revision

排查与运维指南

按症状快速定位问题。

收不到消息 / 连接不上

按顺序检查：

  1. 「连接中心」适配器状态是否为「已连接」；未连接时检查协议配置与端口占用。
  2. 群消息是否被群白名单拦截：系统插件 /whitelist list 查看，需要时 /whitelist add <群号>。
  3. 消息是否以命令前缀开头（默认 / 或 !），config.yaml 的 basic.command_start 可调整。
  4. 机器人账号是否在目标群内，且未被禁言。
  5. 反向 WS 模式由协议端主动连入，请确认协议端已启动且反向 WS 地址与 access_token 一致。

AI 命令提示"请先配置 Provider"

前往「AI 能力」页选择 Provider（OpenAI 兼容 / Anthropic / Gemini / Ollama 等），填写 API Key 与模型名后保存。Ollama 本地模型无需 Key。多 Provider 支持按优先级切换与失败降级。

登录失败多次被锁定

默认 5 次失败锁定 5 分钟。等待自动解锁，或调整 security.max_login_attempts / security.login_lock_seconds。

保存 Cron 表达式报错

必须是标准 5 段 cron（分 时 日 月 周），例如 0 8 * * *。可在「定时任务」页使用 Cron 预设快速生成。

数据库文件被占用 / 无法删除

Windows 下常见于服务仍在运行。先停止服务（关闭 main.py 进程）再操作数据库文件；测试环境偶发文件锁可通过重启进程解决。

导出任务失败

在「导出中心」查看任务消息并点击「重试」。常见原因：格式依赖缺失（如 Excel 需要 openpyxl）、磁盘空间不足、数据量超出单次上限（审计后台导出上限 50000 条）。

任务或流程被自动停用

这是自愈保护：连续失败达到阈值（scheduler.auto_disable_after_failures / web.auto_disable_workflows_after_failures）会自动停用并告警。在任务页 / 流程页点击「重新启用」即可恢复，建议先排查失败原因。「执行历史」页支持失败一键重试。

告警通知太频繁

设置全局去抖 web.alert_min_interval_seconds，或为单条规则设置「通知去抖间隔」覆盖全局。

公网部署检查清单

框架默认面向本地/私域使用。公网部署务必：

  • 启用 HTTPS（反向代理）；
  • 修改默认 admin/admin 密码；
  • REST API 配置 web.api_keys（未配置时 /api/v1/* 要求后台管理员登录会话）；
  • Webhook 接收配置 web.webhook_secret（未配置时 /webhook/{name} 不校验）；
  • 每个连接配置 access_token（反向 WS/HTTP 事件入口会校验 Authorization: Bearer）；
  • 按需关闭 8080 公网暴露。

详见 Security。

环境自检

ofbot2 doctor        # Python 版本、依赖、数据库与配置完整性
ofbot2 status        # 运行状态
ofbot2 logs --tail 50

Web 后台「系统 → 设置向导」也提供环境自检。

相关

OFbot 2

GitHub 仓库

Clone this wiki locally