Home

InboxBridge Wiki

欢迎来到 InboxBridge Wiki。

InboxBridge 是一个本地自托管的双向沟通 bot。它把 Telegram 私聊入口转换成私密 Telegram Forum 管理群中的 Topic 会话，让你在不开放个人私信的情况下，仍然可以接收外部用户来信，并由白名单管理员集中回复。

适合谁

• 创作者、站长、项目维护者：公开 bot 作为联系入口，减少个人账号暴露。
• 小团队客服：多人在同一个私密群里处理外部用户消息。
• 需要留痕的运营场景：会话有 Topic、备注、标签、优先级、导出和销毁策略。
• 重视隐私的自托管用户：数据库在本地，消息内容可定期清理。

不适合谁

• 需要绕过 Telegram 隐私限制的场景。InboxBridge 不做这件事，用户必须先主动联系 bot。
• 需要大规模多租户后台、Web 工单系统或复杂客服排班的场景。当前版本没有 Web 管理台。
• 需要 Email、Discord、Web Chat 立即可用的场景。当前版本只实装 Telegram，其他 connector 是扩展骨架。

核心概念

• 外部联系人：私聊 bot 的 Telegram 用户。
• 会话：InboxBridge 为联系人创建的沟通记录。
• 管理群：启用 Forum Topics 的私密 Telegram supergroup。
• Topic：一个联系人对应一个 Topic，管理员在 Topic 内处理该联系人消息。
• 白名单管理员：出现在 TELEGRAM_ADMIN_USER_IDS 中的 Telegram user_id，只有这些人可以代发回复和执行管理命令。
• 销毁策略：每个会话可以设置独立保留天数，到期后同步删除 Topic 和数据库会话数据。

文档导航

建议按下面顺序阅读：

1. 完整部署指南：适合第一次部署，覆盖 Telegram 准备、.env、迁移、启动和验收。
2. Serv00 部署指南：适合 Serv00 用户，包含 FreeBSD 环境下的 npm、权限和常驻运行建议。
3. 环境变量说明：逐项解释 .env 中每个变量的作用。
4. 管理命令手册：列出 Topic 内所有白名单管理员命令。
5. 排障手册：整理常见错误和处理步骤。

补充阅读：

• 主仓库 README
• 架构说明
• 运维手册
• 安全与隐私

最短路径

已经准备好 bot 和管理群时，可以直接执行：

npm ci
cp .env.example .env
nano .env
npm run telegram:check
npm run migrate
npm run dev

第一次跑通后，再根据部署环境把 node dist/src/app/main.js 交给 PM2、supervisor、systemd 或托管平台的进程管理器。