故障排查

排查时先记录实例版本、构建 commit、功能、聊天类型和时间，再按最小范围复现。不要为了“看起来更完整”而收集完整 Telegram update 或未脱敏日志。

服务无法启动

检查：

DATABASE_URL、BETTER_AUTH_SECRET 和 AUTH_OWNER_EMAIL 是否存在；
生产环境 BETTER_AUTH_URL 是否是实际 HTTPS origin；
DB_PASSWORD、volume 和数据库健康状态是否一致；
ENCRYPTION_KEY 是否被意外轮换；
GitHub App 五项变量是否只填写了一部分；
COMPOSE_PROFILES=coding 时是否同时设置了 CODING_WORKER_SECRET。

查看 app 日志和 /api/health/ready，将迁移错误与外部集成错误分开处理。

登录后又返回登录页

先确认 /api/auth/sign-in/email 是否成功，再检查同一浏览器会话的 /api/authz/me。前者成功、后者返回 401 时，检查会话 Cookie 与域名配置；返回 403 时，检查工作区成员资格。两个请求都成功却仍回到登录页，说明问题在面板的登录状态判断或跳转，不要反复重置密码。

能登录但看不到工作区

受邀邮箱必须与登录邮箱一致。Google Console 的测试用户、Better Auth 账户和工作区邀请是独立检查；三者任意一层不满足，账号都可能无法进入。请让 owner 重新发送邀请，不要直接修改数据库中的成员记录。

Bot 不回复

先在私聊发送 /help 和 /status（如果是管理员），再检查：

Bot Token 是否可用，Bot 是否处于启用状态。
AI 是否被 /stop 或面板开关暂停。
当前聊天的 Provider/模型是否存在并可调用。
群聊是否只配置了提及/回复触发，消息是否真的满足触发条件。
是否命中用量、并发、冷却或权限策略。

看到“接受任务”但没有最终消息时，继续查看生成、工具和投递阶段的日志，不要立即重复触发。

如果 AI 仍能回复，Bot 管理员可以问“为什么我上一条消息没有回复？请查询请求链路”，让 AI 使用只读运行诊断工具定位当前聊天的排队、模型、工具和投递状态。

在面板日志中先选择 Bot，再用群聊 ID 或关联 ID 缩小范围；历史记录和实时记录都会应用这些条件。操作说明见检索和清理日志。

Provider 或模型不可用

确认 Provider 凭据和外部服务状态，再清除当前聊天的模型/Provider 覆盖：

/provider reset
/model reset

如果列表为空，面板的默认配置可能没有发布到当前 Bot，或者 Provider 未提供可用模型。查看 AI 诊断日志中的错误类别，不要把 API Key 复制到报告里。

Mini App 打不开

Mini App 必须从 Telegram WebView 打开，并携带真实签名 initData。普通浏览器访问、旧 Cookie、轮换后的 session secret、Bot 被停用、用户没有群组授权或 Bot 无法查询成员关系，都会导致拒绝。

重新从 Telegram 菜单打开，检查 HTTPS、Bot 的 Mini App 开关、MINI_APP_SESSION_SECRET 和服务端日志。不要要求用户把会话 Cookie 或初始化数据发给管理员。

RSS、总结或提醒没有发送

分别确认：

RSS Feed 能被手动抓取，URL 没有过期凭据；
总结窗口内确实有消息，访问模式允许当前用户，Provider 可用；
定时器仍处于活跃状态且目标聊天允许发送；
时区、冷却和用量策略符合预期；
日志显示的是读取失败、模型失败、调度失败还是 Telegram 投递失败。

如何提交一份可用的诊断

提供以下脱敏信息即可：版本与 commit、功能页面或命令、聊天类型、UTC 或本地时间、可复现步骤、短错误类别、健康接口结果。删除用户名、Telegram ID、消息全文、URL 查询密钥、Authorization、Cookie、Bot Token、API Key 和原始媒体。

本页内容