Skip to content

Troubleshooting

Jump to bottom
monkeycode-ai edited this page Jul 1, 2026 · 3 revisions

排障手册

本文整理 InboxBridge 部署和运行时最常见的问题。

配置没有被读取

症状：

Invalid input: expected string, received undefined
TELEGRAM_BOT_TOKEN
TELEGRAM_MANAGEMENT_CHAT_ID

处理：

  1. 确认当前命令在仓库根目录执行。
  2. 打开 Web 控制台，确认配置已保存。
  3. 使用 .env 覆盖时，确认文件名是 .env，变量名没有拼错。
  4. 确认等号两侧没有多余空格。
  5. 如果用 PM2 或面板启动，确认工作目录是项目根目录。

Web 控制台无法进入

检查：

  • WEB_CONSOLE_PORT 是否被其他进程占用。
  • 首次登录是否使用日志中的 setupToken。
  • 已设置密码后，登录凭据是否为控制台密码。
  • 反向代理是否正确转发到控制台端口。

启动日志中应能看到：

InboxBridge web console started.

Cloudflare Workers 部署还需要确认 WEB_CONSOLE_SESSION_SECRET 已通过 Wrangler secret 写入。缺少该 secret 时，Workers Web 控制台会返回安全的 503 响应。

wrangler secret put WEB_CONSOLE_SESSION_SECRET

chat not found

常见原因：

  • TELEGRAM_MANAGEMENT_CHAT_ID 填错。
  • bot 没有加入管理群。
  • 管理群不是 supergroup。
  • 使用了用户 ID 或普通群 ID，而不是管理群 ID。

处理：

npm run telegram:check

确认输出中的 chat id、type 和 is_forum。

not enough rights to create a topic

bot 在群里，但没有创建 Topic 的权限。

处理：

  1. 打开管理群设置。
  2. 将 bot 提升为管理员。
  3. 授予管理 topics 权限。
  4. 重新运行：
npm run telegram:check
TELEGRAM_CHECK_TOPIC_TEST=true npm run telegram:check

message thread not found

通常说明数据库记录的 Topic 已被删除或失效。

当前版本会在下一次用户来信时清理旧会话并重建 Topic。如果需要手动处理，可在确认无误后删除对应会话数据，或等待用户再次发消息触发重建。

管理员回复没有外发

检查：

  • 当前发送者的 Telegram user_id 是否在 TELEGRAM_ADMIN_USER_IDS 中。
  • 消息是否发在正确的用户 Topic 内。
  • 消息是否以 / 开头。命令不会外发。
  • bot 是否能收到群内消息。
  • BotFather privacy mode 是否影响当前群消息接收。

可先在 Topic 内发送：

/whoami
/info

如果命令无响应，说明 bot 没收到消息或管理员白名单不匹配。

菜单没有刷新

Telegram 客户端会缓存 bot 命令菜单。

处理：

  • 重启 Telegram 客户端。
  • 切换聊天再回来。
  • 确认服务启动时没有报错。
  • 重新运行 bot，让 setMyCommands 再注册一次。

npm 平台不支持或依赖安装失败

旧版本曾使用不适合 FreeBSD 的原生依赖。当前版本已移除这类依赖。

建议：

建议重新安装依赖前，先备份或移动现有 node_modules 目录，再执行：

npm ci

Serv00 用户请参考 Serv00 部署指南。

tsc: Permission denied

当前脚本不直接执行 tsc，而是使用：

node ./node_modules/typescript/bin/tsc -p tsconfig.json

如果仍出现该问题：

  1. 确认 package.json 已更新。
  2. 删除 node_modules 后重新 npm ci。
  3. 确认没有使用旧的全局脚本。

AI 草稿不可用

AI 草稿失败不会影响消息转发。

检查：

  • AI_DRAFTS_ENABLED=true
  • OPENAI_COMPATIBLE_BASE_URL 是合法 URL。
  • OPENAI_COMPATIBLE_API_KEY 已填写。
  • OPENAI_COMPATIBLE_MODEL 已填写。
  • 服务商没有拦截或限流。
  • 单个会话没有被 /ai_off 关闭。

不需要 AI 时可关闭：

AI_DRAFTS_ENABLED=false

草稿发送失败

/draft send 会创建投递记录。发送失败时：

  1. 草稿会保留，可以再次执行 /draft send。
  2. 打开 /operations/deliveries 查看失败原因。
  3. 修复 Telegram 权限或用户状态问题后，可在运维仪表盘对失败投递触发重试。

永久失败记录表示系统已确认无法继续自动投递，适合保留用于排查。

审计、搜索或会话列表为空

检查：

  • 是否已经有白名单管理员在 Topic 内执行过命令。
  • 搜索关键词是否存在于仍保留的消息正文中。
  • MESSAGE_RETENTION_DAYS 是否已经清理了旧消息正文。
  • 会话列表筛选条件是否过窄，例如状态或负责人筛选。

会话没有按预期销毁

检查：

  • DEFAULT_CONVERSATION_RETENTION_DAYS 是否为正整数或 never。
  • 当前会话是否被 /expire never 覆盖。
  • CONVERSATION_EXPIRY_SWEEP_INTERVAL_MINUTES 是否设置过大。
  • bot 是否一直在运行。扫描只在进程运行时发生。

查看当前会话策略：

/expires

Cloudflare Workers smoke test 失败

检查：

  • wrangler.toml 中的 D1 database_id 是否已替换为真实 ID。
  • D1 binding 名称是否保持为 DB。
  • TELEGRAM_UPDATE_MODE 是否为 webhook。
  • TELEGRAM_BOT_TOKEN、TELEGRAM_WEBHOOK_SECRET、WEB_CONSOLE_PASSWORD、WEB_CONSOLE_SESSION_SECRET 是否已通过 Wrangler secrets 写入。
  • /healthz 是否能返回 JSON，且数据库状态为 reachable。
  • /telegram/webhook 请求是否带有正确的 x-telegram-bot-api-secret-token header。

提交前安全检查

提交前建议执行：

git diff
npm run verify

确认没有提交：

  • .env
  • data/*.sqlite
  • Telegram bot token
  • AI API key
  • 用户导出数据
  • 备份文件

Clone this wiki locally