Skip to content

Home

Jump to bottom
monkeycode-ai edited this page Jun 30, 2026 · 3 revisions

InboxBridge Wiki

欢迎来到 InboxBridge Wiki。

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

适合谁

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

使用边界

  • Telegram 私信隐私限制由 Telegram 平台决定，外部用户必须先主动联系 bot。
  • 当前版本适合单实例自托管和小团队共享收件箱；大规模多租户、复杂排班和 SLA 工单系统需要额外平台能力。
  • 当前版本实装 Telegram 渠道；Email、Discord、Web Chat 属于后续扩展方向。

核心概念

  • 外部联系人：私聊 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. Web 控制台：说明首页概览、配置仪表盘和运维仪表盘。
  4. 配置说明：逐项解释控制台配置和环境变量覆盖项。
  5. 管理命令手册：列出 Topic 内所有白名单管理员命令。
  6. 排障手册：整理常见错误和处理步骤。

补充阅读：

最短路径

首次启动可以直接执行：

npm ci
npm run migrate
npm run dev

打开 http://localhost:3000，使用日志中的 setup token 初始化控制台密码，再填写 Telegram 配置。常驻运行时使用 node dist/src/runtime/main.js。

Clone this wiki locally