基于 Cloudflare Workers 的高可用、零服务器成本、企业级安全 Telegram ID 与元数据查询机器人
TGID_bot 专为 Telegram 用户、频道主、社群管理员及 Bot 开发者设计。无需购买 VPS 服务器，依托 Cloudflare 全球边缘网络 (Serverless) 实现毫秒级响应、永久在线与零维护。
代码原生支持 Cloudflare 绑定 GitHub 自动化构建，每次提交代码自动热更新！
| 功能模块 | 图标 | 特性描述 |
|---|---|---|
| 发送者识别 | 👤 | 精准提取当前用户的 User ID、姓名、用户名、Telegram Premium 状态及语言代码 |
| 群聊与频道 | 💬 | 查询普通群、超级群（Supergroup）、频道（Channel）ID 及论坛话题（Topic ID） |
| 目标回复解析 | 🎯 | 群内 回复 (Reply) 某人消息并发送 /id，秒级提取被回复者的 ID 与媒体信息 |
| 转发深度溯源 | 🔄 | 深度解析 转发 (Forward) 消息来源（原作者、原频道/群组 ID、原始发送时间戳） |
| 全量媒体提取 | 📁 | 提取各类文件 file_id 与 file_unique_id（贴纸、图片、视频、音频、动图、名片等） |
| 点击即发送 | 👆 | 欢迎卡片里的 ID 是蓝色链接，轻触即让 Telegram 代你发送该 ID，机器人单独回一条便于复制/转发 |
| 安全加固体系 | 🛡️ | X-Telegram-Bot-Api-Secret-Token 官方验签 + 无默认密钥（缺失即 500） + 验签密钥与运维口令分离 + 常量时间比较 |
| 健壮容灾机制 | ⚡ | UTF-8 字节级截断 + HTML 解析失败自动纯文本降级（并解除 reply 绑定，避免二次失败） |
1. 私聊发送 /start（欢迎与使用指南卡片）
卡片里的 ID 是蓝色可点击链接：轻触后 Telegram 会自动替你发送
/start id_<该 ID>，机器人随即把该 ID 单独回一条消息，长按即可复制、直接转发也不带多余格式。
👋 欢迎使用 What's My ID 机器人！
这是一个极速、安全、无日志的 Telegram 身份与元数据查询工具 ⚡
🆔 您的基础信息：
├ 用户 ID: 123456789 <- 蓝色链接，点一下就把这个 ID 发给我
├ 姓名: 开发者
├ 用户名: @developer
└ 对话 ID: 123456789 <- 同上
📖 快捷使用指南：
• 极简查 ID： 发送 /id（仅返回纯数字 ID，防刷屏）
• 全量元数据： 发送 /info 或直接发媒体/转发消息
• 查他人： 在群内【回复他人消息】并输入 /id
• 查来源： 转发他人或频道消息给我，解析原作者与频道 ID
• 查群组： 在群内发送 /id 获取群组与话题 Topic ID
• 查媒体： 发送贴纸、图片、音视频或文件，提取开发专用 File ID
💡 提示：轻触上方数字，我会把该 ID 单独发给你（长按可复制、可直接转发）。
/start的完整卡片只在私聊发送；群内发送/start只回精简 ID，避免长文刷屏。
2. 发送 /id ——【极简极速模式】（轻量、干净、防群聊刷屏）
- 私聊查询自己：
🆔 用户 ID: 123456789 - 群聊直接发送：
🆔 用户 ID: 123456789 💬 群聊 ID: -1001234567890 🧵 话题 ID: 12 - 群内【回复他人消息】发送：
🎯 目标用户 ID: 987654321 🆔 用户 ID: 123456789 💬 群聊 ID: -1001234567890
3. 发送 /info 或【直接发送/转发媒体】 ——【全量元数据报告】
🆔 Telegram 详细元数据报告
🎯 被回复的目标消息 (Target Reply):
├ 消息 ID: 520
├ 目标用户 ID: 987654321
├ 目标姓名: 目标成员
├ 目标用户名: @target_user
└ 目标是机器人: 否
👤 发送者 (Sender):
├ 用户 ID: 123456789
├ 姓名: 管理员
├ 用户名: @admin
├ 会员状态: Telegram Premium 🌟
└ 语言代码: zh-hans
💬 当前所在对话 (Chat):
├ 对话 ID: -1001234567890
├ 对话类型: supergroup
├ 名称: 极客交流圈
├ 话题 Topic ID: 12
└ 当前消息 ID: 521
4. 转发频道/他人消息（深度溯源原作者与时间）
🔄 转发来源 (Forward Origin):
├ 来源类型: 频道
├ 频道 ID: -1001987654321
├ 频道名: 前沿技术资讯
├ 用户名: @tech_news
├ 原消息 ID: 888
└ 原始时间: 2026-08-30 08:00:00 UTC
5. 发送贴纸 / 图片 / 附件（提取 File ID）
📁 附加内容信息:
├ 类型: 贴纸 👍
├ 集合名: AnimatedDuck
├ File ID: CAACAgIAAxkBAAIC...AgADbQADNgQ
└ Unique ID: AQADbQADNgQ
只需简单的 4 步，即可实现 GitHub 代码改动时 Cloudflare 自动拉取构建与更新：
- 在 Telegram 中搜索并私聊 @BotFather，发送
/newbot。 - 按照提示设置机器人昵称与用户名（例如
MyAwesomeIdBot）。 - 复制生成的 Bot Token（格式如
123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ）。 -
(可选建议) 在
@BotFather中发送/setprivacy$\to$ 选择你的 Bot$\to$ 选择Disable（允许群内正常响应指令）。
将本项目代码克隆/推送到你的 GitHub 个人账户下。
- 登录 Cloudflare Dashboard。
- 进入左侧菜单 Compute (Workers & Pages)
$\to$ Create application。 - 选择 Workers 或 Pages 选项卡下的 Connect to Git（连接到 Git）。
- 授权你的 GitHub 账号，并选择刚才创建的
TGID_bot仓库。 -
构建设置 (Build settings)：
-
Project name:
tgid-bot（或自定义） -
Production branch:
main -
Framework preset:
None - Build command: 留空
- Deploy command: 保持默认
-
Project name:
- 点击 Save and Deploy 完成初次部署。
在 Cloudflare 该项目的 Settings
| 变量名 | 必填 | 说明 |
|---|---|---|
BOT_TOKEN |
✅ | 第一步拿到的 Bot Token |
SECRET_TOKEN |
✅ | Webhook 验签密钥。只允许 A-Z a-z 0-9 _ -，长度 1–256（Telegram 官方限制）。含空格或中文会导致注册失败 |
SETUP_KEY |
⭐ 推荐 | 部署/运维口令，至少 16 位。用于鉴权 /setWebhook 与 /deleteWebhook；不配置则这两个接口完全不暴露 |
BOT_USERNAME |
⭕ 可选 | 你的 Bot 用户名（不带 @）。留空时会自动调用 getMe 解析，功能不受影响 |
生成随机密钥：
node -e "console.log(crypto.randomUUID().replace(/-/g,''))"配置完成后点击 Save and Deploy，然后任选一种方式激活 Webhook：
# 方式一：浏览器直接访问（GET）
https://你的Cloudflare域名/setWebhook?key=你设置的SETUP_KEY
# 方式二：推荐，密钥走请求头，不会留在浏览器历史与访问日志里（GET / POST 均可）
curl -H "X-Setup-Key: 你设置的SETUP_KEY" https://你的Cloudflare域名/setWebhook看到返回 {"ok": true, "result": true, "description": "Webhook was set"} 即代表成功上线！🎉
⚠️ 若返回404 Setup endpoint disabled，说明还没配置SETUP_KEY； 返回403 Forbidden说明口令不对。两种情况下都不会有任何副作用。
需要换绑或下线时：
/deleteWebhook?key=...（可加&drop_pending=true丢弃积压更新）。
客户端请求 ──> [Cloudflare 全球边缘节点]
│
├──> readConfig 校验（缺失/非法即 500，绝不降级使用默认密钥）
│
├──> /setWebhook · /deleteWebhook ← 需 SETUP_KEY（不足 16 位则不启用）
│
├──> 常量时间校验 X-Telegram-Bot-Api-Secret-Token (防伪造)
│
├──> 正则校验指令与 @bot_username (防抢答；用户名缺失自动 getMe)
│
├──> 业务解析 (用户/群聊/转发/媒体/Topic)
│
└──> safeSendMessage 容灾发送
├─ UTF-8 字节级截断（中文/emoji 不超 4096 字节）
├─ 所有 Telegram 来源字段一律 HTML 转义
└─ 格式异常自动降级为纯文本重试（并解除 reply 绑定）
密钥职责分离：SECRET_TOKEN 只用于 Telegram 验签，SETUP_KEY 只用于运维接口，任一泄露都不会波及另一侧。
TGID_bot/
├── src/
│ ├── index.js # Worker 入口与路由（Webhook / 健康检查 / 运维接口）
│ ├── config.js # 环境变量读取、字符集校验、常量时间比较
│ ├── telegram.js # Bot API 客户端、getMe 缓存、健壮发送（截断 + 降级）
│ ├── handlers.js # /start 卡片、/id 精简、/info 全量报告、深链载荷解析
│ ├── extract.js # 转发溯源与媒体/名片/位置元数据提取
│ └── format.js # HTML 转义、体积格式化、UTF-8 字节截断
├── tests/ # node:test 单元测试（零依赖，npm test 直接跑）
├── wrangler.toml
├── package.json
└── .env.example
npm test # 运行全部单元测试（使用 Node 内置测试运行器，无需安装依赖）
npm run test:watch # 监听模式
npx wrangler dev # 本地起一个 Worker（复制 .env.example 为 .dev.vars 填好变量）
npm run deploy # 手动部署
npm run tail # 实时查看线上日志测试只需要 Node.js ≥ 20，不需要 npm install；
wrangler仅在本地调试/部署时才需要。
🔴 安全修复（破坏性变更）
- 移除硬编码默认密钥。 旧版
env.SECRET_TOKEN || "tg_id_bot_secret_token_123456"意味着只要漏配SECRET_TOKEN，公开仓库里的这个常量就成了验签密钥——任何人都能伪造 Update，让你的 Bot 向任意 chat_id 发消息，或用?drop_pending=true清空积压更新。现在缺失即返回 500。 - 密钥职责分离。 新增
SETUP_KEY专门鉴权/setWebhook；不再接受用SECRET_TOKEN调用运维接口，密钥不再出现在 URL 查询串里（改为 JSON body 传参）。 - 常量时间比较 +
SECRET_TOKEN字符集/长度校验（避免非法字符导致setWebhook静默失败）。 sticker.emoji补上 HTML 转义（唯一遗漏的用户可控字段）。
🟠 健壮性修复
- 恢复指令防抢答：
BOT_USERNAME未配置时旧逻辑会跳过校验、响应发给其他 Bot 的指令；现在会自动getMe解析自己的用户名。 - 纯文本降级重试解除
reply_to_message_id：旧逻辑在被回复消息已被删除时会以同样的 400 失败两次，用户完全收不到回复。 - 截断改为 UTF-8 字节级：旧逻辑按
String.length判断 4000，中文场景下实际字节数会超出 Telegram 上限。 humanDate在毫秒非 0 时不再残留.123Z。- 群/频道内的
/start不再发送长卡片（只回精简 ID）。
✨ 新特性
- 欢迎卡片中的 ID 改为点击即发送的蓝色深链（
https://t.me/<bot>?start=id_<值>），机器人会把该 ID 单独回一条消息。 - 新增
/help（等价于/start）。 - 新增
/deleteWebhook运维接口。 - 模块化拆分 + 56 个单元测试 + 启用 Workers Logs 可观测性 + wrangler v3 升级至 v4。
升级须知：请在 Cloudflare 配置好
SECRET_TOKEN，并新增SETUP_KEY（≥16 位），然后重新访问一次/setWebhook?key=...完成注册。
- 首个版本：用户/群聊/频道/Topic ID 查询、回复目标解析、转发溯源、全媒体 File ID 提取。
本项目在架构设计、功能构思与代码打磨过程中，得到了以下优秀 AI 技术的启发与支持，特此致谢：
- Google 反重力 (Antigravity) - 提供强大的智能代理架构与工程设计能力。
- ChatGPT (OpenAI) - 提供敏捷的代码优化思路与逻辑灵感。
本项目基于 MIT License 开源。欢迎 Star ⭐ 与 Fork 支持！