FlareGram

FlareGram 是一个基于 Cloudflare Workers + grammY + D1 的 Telegram 双向私信中转机器人。

当前版本支持：

• 用户私聊机器人
• 机器人将消息转发给单个管理员
• 管理员在 Telegram 中直接回复该转发消息
• 机器人将管理员回复回传给原用户

技术栈

• Cloudflare Workers
• Cloudflare D1
• Wrangler
• grammY
• TypeScript
• Vitest

本地要求

• Node.js 20+
• pnpm
• Cloudflare 账号
• 一个已通过 @BotFather 创建的 Telegram Bot

一次性初始化

1. 安装依赖

pnpm install

2. 登录 Cloudflare

pnpm wrangler login

3. 创建 D1 数据库

pnpm wrangler d1 create flaregram

执行后会返回一段类似下面的信息：

[[d1_databases]]
binding = "DB"
database_name = "flaregram"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

把返回的 database_id 填到项目根目录的 wrangler.jsonc：

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "flaregram",
      "database_id": "你的真实 database_id"
    }
  ]
}

4. 获取管理员 Chat ID

你需要知道“接收所有私信转发的管理员账号”的 chat_id。

最简单的方式：

1. 先在 Telegram 里给机器人发一条消息
2. 临时调用 Telegram API 查看 update

curl "https://api.telegram.org/bot<你的BOT_TOKEN>/getUpdates"

在返回 JSON 里找到管理员账号对应的：

• message.from.id
• 或 message.chat.id

然后把它填到 wrangler.jsonc：

{
  "vars": {
    "ADMIN_CHAT_ID": "你的管理员 chat id"
  }
}

5. 设置 Secrets

pnpm wrangler secret put BOT_TOKEN
pnpm wrangler secret put WEBHOOK_SECRET

建议：

• BOT_TOKEN：直接填 BotFather 给你的 token
• WEBHOOK_SECRET：填一个高强度随机字符串，例如 flaregram-prod-2026-xxxxxx

说明：

• BOT_INFO 不再需要手工配置
• Worker 会在首次请求时基于 BOT_TOKEN 自动调用 Telegram getMe 获取 bot 信息
• 如果你之前已经配置过 BOT_INFO，当前版本仍会兼容读取，但新部署可以不再设置

数据库初始化

先把表结构应用到远端 D1：

pnpm run db:migrate:remote

如果你只想先本地验证 D1 SQL，也可以用：

pnpm run db:migrate:local

部署

pnpm run deploy

默认情况下，部署完成后你会拿到 Worker 地址，通常类似：

https://flaregram.<your-subdomain>.workers.dev

如果你要直接绑定 Cloudflare 托管的自定义域名，推荐把它写进 wrangler.jsonc，并把本地配置作为唯一真源。例如：

{
  "routes": [
    {
      "pattern": "flaregram.knowsky404.com",
      "custom_domain": true
    }
  ]
}

说明：

• custom_domain: true 适用于“这个子域名的所有流量都直接交给 Worker 处理”
• 当域名所在 Zone 已托管在 Cloudflare 时，Cloudflare 会自动为 Custom Domain 管理 DNS 记录和证书
• 如果你之后仍使用 wrangler deploy，不要只在 Cloudflare Dashboard 里修改路由；下次部署时本地 wrangler.jsonc 会覆盖 Dashboard 中的路由配置

注册 Telegram Webhook

本项目 webhook 路径固定为：

/telegram/webhook/<WEBHOOK_SECRET>

例如你的 Worker 域名是：

https://flaregram.<your-subdomain>.workers.dev

如果你使用自定义域名，例如：

https://flaregram.knowsky404.com

并且 WEBHOOK_SECRET 是：

my-secret-path

那么完整 webhook 地址就是：

https://flaregram.<your-subdomain>.workers.dev/telegram/webhook/my-secret-path

使用自定义域名时，则是：

https://flaregram.knowsky404.com/telegram/webhook/my-secret-path

注册命令：

curl "https://api.telegram.org/bot<你的BOT_TOKEN>/setWebhook?url=https://flaregram.<your-subdomain>.workers.dev/telegram/webhook/<你的WEBHOOK_SECRET>"

如果你已经切到自定义域名，请改成：

curl "https://api.telegram.org/bot<你的BOT_TOKEN>/setWebhook?url=https://flaregram.knowsky404.com/telegram/webhook/<你的WEBHOOK_SECRET>"

检查 webhook 状态：

curl "https://api.telegram.org/bot<你的BOT_TOKEN>/getWebhookInfo"

部署后联调

按下面顺序测试：

1. 普通用户私聊机器人，发送一条文本消息
2. 管理员账号应收到机器人转发的该消息
3. 管理员直接“回复这条转发消息”
4. 原用户应收到管理员回复

再补测一次非文本消息，例如图片、文件、表情包或动图，确认 copyMessage 路径正常。

本地测试

运行单元测试：

pnpm test

运行类型检查：

pnpm exec tsc --noEmit

常见问题

1. Telegram 设置 webhook 后没有消息进来

优先检查：

• Worker 是否已成功部署
• WEBHOOK_SECRET 是否和注册 URL 完全一致
• getWebhookInfo 是否返回最近错误

2. 管理员能收到转发，但回复后用户收不到

先检查你是不是“回复了那条机器人转发消息本身”。

这个项目当前靠 reply_to_message.message_id 去 D1 查映射，如果你不是直接回复那条消息，而是新发一条独立消息，机器人不会知道应该回给谁。

3. 管理员回复后提示找不到映射

通常原因：

• 不是回复那条转发消息
• D1 还没初始化成功
• 部署的是旧版本代码

4. 用户收不到管理员回复，但管理员侧没有报错

常见原因：

• 用户屏蔽了机器人
• 用户从未真正和机器人建立私聊
• Telegram 侧临时错误

5. wrangler 命令报权限或本地监听错误

这类问题一般出现在受限沙箱或 CI 环境里。真实本地机器上执行通常不会有问题。优先在你自己的终端环境里运行：

pnpm wrangler d1 create flaregram
pnpm run db:migrate:remote
pnpm run deploy

当前限制

当前版本故意保持最简，只支持：

• 单管理员
• 通过“回复转发消息”回私信
• 无 Web 管理后台
• 无多客服分配
• 无自动回复规则

如果你准备在验证部署后继续迭代，下一步最值得加的是：

1. 管理员身份校验与更清晰的错误提示
2. webhook 注册/检查脚本
3. 多管理员支持