Skip to content

Deployment

Jump to bottom
Kana edited this page May 17, 2026 · 1 revision

完整部署指南

本文从零开始部署 InboxBridge。默认推荐 polling 模式，因为它不需要公网 HTTPS 地址，适合 Serv00、VPS、本地小主机和开发环境。

1. 准备 Telegram Bot

  1. 在 Telegram 打开 @BotFather。
  2. 使用 /newbot 创建 bot。
  3. 保存 BotFather 给出的 token，填入 .env 的 TELEGRAM_BOT_TOKEN。
  4. 如果管理群里需要接收普通消息，建议在 BotFather 中确认 bot 的隐私设置符合预期。InboxBridge 的核心处理依赖 bot 能收到管理群 Topic 内消息。

2. 准备私密管理群

管理群必须满足：

  • 类型是 supergroup。
  • 已启用 Forum Topics。
  • bot 已加入群。
  • bot 有发送消息和管理 topics 的权限。

推荐做法：

  1. 创建一个私密 Telegram 群。
  2. 在群设置中开启 Topics。
  3. 把 bot 拉入群。
  4. 将 bot 提升为管理员。
  5. 至少授予管理 topics 和发送消息权限。

3. 获取管理群 ID

TELEGRAM_MANAGEMENT_CHAT_ID 通常是 -100 开头的数字。可用下面任一方式获取：

  • 把 bot 加入群后运行项目内检查脚本，根据输出确认 chat id。
  • 临时向 bot 或诊断脚本发送测试消息后查看 Telegram API 返回。
  • 使用可信的 Telegram ID 获取工具，但不要把 bot token 发给不可信服务。

填入 .env 时必须保留负号，例如：

TELEGRAM_MANAGEMENT_CHAT_ID=-1001234567890

4. 获取管理员 user_id

TELEGRAM_ADMIN_USER_IDS 只接受 Telegram 数字 user_id，不是用户名。

获取方式：

  • 先填一个已知 ID 后启动，在管理 Topic 内使用 /whoami 查看。
  • 使用 Telegram 官方 API 或可信 ID 查询 bot 获取。
  • 如果暂时没有 ID，可先用自己的账号私聊一些 ID 查询 bot，再填入 .env。

多个管理员用英文逗号分隔：

TELEGRAM_ADMIN_USER_IDS=123456789,987654321

5. 安装依赖

项目要求 Node.js 24 或更高版本。

npm ci

如果部署平台对 npm 可执行权限有限，请优先参考 Serv00 部署指南。

6. 配置 .env

复制示例文件：

cp .env.example .env
nano .env

最小可运行配置：

TELEGRAM_BOT_TOKEN=你的_bot_token
TELEGRAM_MANAGEMENT_CHAT_ID=-1001234567890
TELEGRAM_UPDATE_MODE=polling
TELEGRAM_ADMIN_USER_IDS=123456789
DATABASE_URL=file:./data/inboxbridge.sqlite
AI_DRAFTS_ENABLED=false

启用 AI 草稿时再填写：

OPENAI_COMPATIBLE_BASE_URL=https://你的服务地址/v1
OPENAI_COMPATIBLE_API_KEY=你的_api_key
OPENAI_COMPATIBLE_MODEL=你的模型名
AI_DRAFTS_ENABLED=true

AI 草稿只会发送到管理 Topic，不会自动回复外部用户。

7. 检查 Telegram 权限

先检查 token、群、Forum 和 bot 权限：

npm run telegram:check

进一步测试发送权限：

TELEGRAM_CHECK_SEND_TEST=true npm run telegram:check

进一步测试创建和删除 Topic 权限：

TELEGRAM_CHECK_TOPIC_TEST=true npm run telegram:check

Topic 测试会临时创建测试 Topic、发送测试消息，然后尝试删除。

8. 初始化数据库

npm run migrate

迁移脚本是幂等的，重复执行不会重复建表。数据库默认位于：

data/inboxbridge.sqlite

请不要把 data/ 或 .env 提交到 Git。

9. 启动

开发或前台验证：

npm run dev

生产运行建议先构建，再启动编译产物：

npm run build
node dist/src/app/main.js

如果使用 webhook，需要额外配置公网 HTTPS：

TELEGRAM_UPDATE_MODE=webhook
TELEGRAM_WEBHOOK_URL=https://example.com/telegram/webhook
TELEGRAM_WEBHOOK_PORT=3000

第一版更推荐 polling，部署更简单，也更适合 Serv00。

10. 本地验收

按下面顺序测试：

  1. 用外部测试账号私聊 bot，发送 /start 或普通文本。
  2. 管理群中自动出现该用户的 Topic。
  3. Topic 内能看到用户消息。
  4. 白名单管理员在 Topic 内发送普通消息。
  5. 外部用户收到 bot 代发的回复。
  6. Topic 内执行 /whoami、/info、/note 测试备注。
  7. 执行 /expire 7 和 /expires，确认会话销毁策略可单独设置。
  8. 执行 npm run verify，确认构建、测试和审计通过。

11. 常驻运行

PM2 示例：

npm run build
pm2 start dist/src/app/main.js --name inboxbridge
pm2 save
pm2 logs inboxbridge

没有 PM2 时，也可以使用系统提供的进程管理器。关键点是最终运行：

node dist/src/app/main.js

12. 升级流程

推荐升级顺序：

git pull
npm ci
npm run migrate
npm run verify
npm run build

然后重启常驻进程。

13. 备份与恢复

需要备份：

.env
data/inboxbridge.sqlite

恢复后执行：

npm run migrate
npm run telegram:check

确认无误后再启动服务。

Clone this wiki locally