Deployment

完整部署指南

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

1. 准备 Telegram Bot

1. 在 Telegram 打开 @BotFather。
2. 使用 /newbot 创建 bot。
3. 保存 BotFather 给出的 token，后续填入 Web 控制台的 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. 初始化 Web 控制台

常规部署无需预先填写 Telegram 变量。先准备数据库并启动服务：

npm run migrate
npm run dev

日志会输出 setupToken，打开 http://localhost:3000 后使用该 token 设置控制台密码。进入控制台后填写最小配置：

• TELEGRAM_BOT_TOKEN
• TELEGRAM_MANAGEMENT_CHAT_ID
• TELEGRAM_UPDATE_MODE=polling
• TELEGRAM_ADMIN_USER_IDS

Web 控制台保存后会自动尝试启动或重启 bot。

高级部署可以使用 .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/runtime/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 测试备注、/search 测试。
7. 执行 /expire 7、/expires、/audit，确认会话销毁策略和审计记录可用。
8. 打开 /operations，确认会话、投递、审计和搜索页面可访问。
9. 执行 npm run verify，确认构建、测试和审计通过。

11. Cloudflare Workers 部署

Workers 部署使用 Fetch、D1、Telegram webhook 和 Cron Trigger。部署前先创建 D1 数据库，并把 wrangler.toml 中的占位 database_id 替换为真实 D1 ID。

需要通过 Wrangler secrets 写入敏感配置。命令会交互式读取值，文档和日志中不要记录真实值：

wrangler secret put TELEGRAM_BOT_TOKEN
wrangler secret put TELEGRAM_WEBHOOK_SECRET
wrangler secret put WEB_CONSOLE_PASSWORD
wrangler secret put WEB_CONSOLE_SESSION_SECRET

WEB_CONSOLE_SESSION_SECRET 用于签名 Workers Web 控制台 cookie。建议使用足够长的随机字符串，并与控制台密码分开管理。

Workers smoke test：

1. GET /healthz 返回 JSON，并执行 D1 SELECT 1。
2. GET /login 渲染 Web 控制台登录页。
3. 登录成功后返回 HttpOnly session cookie。
4. GET /operations 在认证后渲染运维页面。
5. /telegram/webhook 对有效 secret header 返回已处理响应。
6. Cron Trigger 能运行维护任务且不抛出异常。

12. 常驻运行

PM2 示例：

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

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

node dist/src/runtime/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

确认无误后再启动服务。