Troubleshooting

排障手册

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

配置没有被读取

症状：

Invalid input: expected string, received undefined
TELEGRAM_BOT_TOKEN
TELEGRAM_MANAGEMENT_CHAT_ID

处理：

1. 确认当前命令在仓库根目录执行。
2. 确认文件名是 .env，不是 .env.example。
3. 确认变量名没有拼错。
4. 确认等号两侧没有多余空格。
5. 如果用 PM2 或面板启动，确认工作目录是项目根目录。

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 的原生依赖。当前版本已移除这类依赖。

建议：

rm -rf 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 时可关闭：

AI_DRAFTS_ENABLED=false

会话没有按预期销毁

检查：

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

查看当前会话策略：

/expires

提交前安全检查

提交前建议执行：

git diff
npm run verify

确认没有提交：

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