Orion
c3437ae163
更新项目根目录 README.md 以更清晰地展示脚本集合架构，并为 Homebrew、Sub-Store 和 Telegram 模块新增详细的使用说明文档。 同时移除了 brew-upgrade-manager.sh 中的硬编码 sudo 密码，改为空字符串占位符以提升代码安全性。 - 增强根目录文档的可读性与结构 - 为每个子模块添加独立的 README.md - 修复脚本中的敏感信息泄露问题 (SUDO_PWD)
Telegram Bot Worker
tg-bot.js 是一个部署在 Cloudflare Workers 上的 Telegram Bot。它把用户私聊消息转发到管理员论坛群的独立话题中，并提供验证、过滤、封禁、备注、自动回复、备份和配置面板。
核心功能
- 私聊用户消息转发到管理员群论坛话题。
- 每个用户自动创建独立 topic，并推送用户身份卡片。
- 管理员在对应 topic 内回复，即可把消息复制回用户私聊。
- 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证。
- 支持二次问答验证。
- 支持文本、媒体、链接、转发、频道转发、音频、贴纸/GIF 等类型过滤。
- 支持关键词自动回复和屏蔽词计数封禁。
- 支持黑名单 topic、用户解封、备注、资料卡置顶。
- 支持消息编辑记录同步。
- 支持消息备份到指定群或频道。
- 内置 Telegram 管理面板，管理员通过
/start打开。
运行环境
- Cloudflare Workers
- Cloudflare D1 数据库绑定
- Telegram Bot Token
- 启用话题的 Telegram 管理群
- 可选：Cloudflare Turnstile 或 Google reCAPTCHA 密钥
必需环境变量
| 名称 | 说明 |
|---|---|
BOT_TOKEN |
Telegram Bot Token |
ADMIN_IDS |
管理员 Telegram user id，多个用英文或中文逗号分隔 |
ADMIN_GROUP_ID |
管理员论坛群 ID，通常是 -100... |
WORKER_URL |
Worker 公开访问地址，不要带结尾斜杠 |
D1 绑定
Worker 需要绑定一个 D1 数据库，绑定名必须是：
TG_BOT_DB
脚本会自动创建和维护以下表：
config：配置项。users：用户状态、封禁状态、topic 映射、用户资料。messages：用户消息与管理员群 topic 消息的映射。
可选环境变量
| 名称 | 说明 |
|---|---|
TURNSTILE_SITE_KEY |
Cloudflare Turnstile site key |
TURNSTILE_SECRET_KEY |
Cloudflare Turnstile secret key |
RECAPTCHA_SITE_KEY |
Google reCAPTCHA site key |
RECAPTCHA_SECRET_KEY |
Google reCAPTCHA secret key |
WELCOME_MESSAGE |
默认欢迎语，对应配置项 welcome_msg |
VERIF_QUESTION |
默认问答验证问题，对应 verif_q |
VERIF_ANSWER |
默认问答验证答案，对应 verif_a |
大多数运行时配置也可以在管理员面板中调整，并优先保存到 D1。
默认配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
welcome_msg |
欢迎 {name}！使用前请先完成验证。 |
欢迎语，支持 {name} 或 {user} |
enable_verify |
true |
是否启用网页人机验证 |
enable_qa_verify |
true |
是否启用问答验证 |
captcha_mode |
turnstile |
验证模式：turnstile 或 recaptcha |
verif_q |
1+1=? |
问题验证题目 |
verif_a |
3 |
问题验证答案 |
block_threshold |
5 |
命中屏蔽词多少次后封禁 |
busy_mode |
false |
是否启用非营业自动回复 |
enable_admin_receipt |
false |
管理员回执开关 |
部署流程
- 在 Telegram 中创建 Bot，拿到
BOT_TOKEN。 - 创建一个启用 Topics 的 Telegram 群，把 Bot 拉入群。
- 给 Bot 管理员权限，至少需要发消息、管理话题、置顶消息等能力。
- 在 Cloudflare 创建 D1 数据库并绑定为
TG_BOT_DB。 - 创建 Worker，把 tg-bot.js 作为 Worker 代码。
- 配置环境变量
BOT_TOKEN、ADMIN_IDS、ADMIN_GROUP_ID、WORKER_URL。 - 设置 Telegram Webhook：
curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"
- 访问 Worker 根路径，若返回
Bot v3.67 Active，说明 Worker 基本可用。 - 管理员私聊 Bot 发送
/start，打开控制面板。
Webhook 路由
| 路径 | 方法 | 用途 |
|---|---|---|
/ |
GET |
健康检查 |
/verify |
GET |
Telegram Web App 验证页面 |
/submit_token |
POST |
验证 token 提交 |
/ |
POST |
Telegram Webhook 更新入口 |
管理员面板
管理员私聊 Bot 发送 /start 后会打开配置面板，包含：
- 基础：欢迎语、验证问题、验证答案、验证码模式、问题验证开关。
- 自动回复：添加或删除关键词自动回复。
- 屏蔽词：添加或删除正则关键词，命中后累计封禁。
- 过滤：控制转发、媒体、语音、贴纸、链接、频道、文本等类型。
- 协管：维护额外授权管理员。
- 备份/通知：设置备份群、重置黑名单 topic。
- 营业状态：切换忙碌模式并修改自动回复语。
自动回复新增格式：
关键词===回复内容
授权管理员可输入多个 ID：
123456,789012
用户流程
- 用户私聊 Bot 发送
/start。 - Bot 发送欢迎语。
- 如果启用网页验证，用户点击按钮完成 Turnstile 或 reCAPTCHA。
- 如果启用问答验证，用户继续回答问题。
- 验证通过后，用户消息会转发到管理员群中的个人 topic。
- 管理员在 topic 中回复，Bot 会把回复发送给该用户。
注意事项
ADMIN_IDS使用字符串包含判断，建议使用完整 ID 并用逗号分隔，避免 ID 片段误匹配。- 管理员群必须开启 Topics，否则自动创建用户话题会失败。
WORKER_URL要使用 HTTPS 公开地址，否则 Telegram Web App 验证页面无法正常工作。- Turnstile 和 reCAPTCHA 至少配置一种；如果关闭网页验证，可只使用问答验证。
- Worker 使用内存缓存减少 D1 读取，配置修改后脚本会主动清缓存。
- 请妥善保护
BOT_TOKEN、验证码 secret、D1 数据库和 Cloudflare 账号权限。