Telegram 双向机器人

企业级私聊托管与风控解决方案 - 支持 Docker 部署和 Cloudflare Worker 部署，具备三模态验证、可视化协管系统和智能 CRM 管理

项目简介

这是一个高性能 Telegram 双向机器人，支持两种部署方式：

• Docker 部署（推荐）：使用 Node.js + SQLite，适合自建服务器
• Cloudflare Worker 部署：使用 D1 数据库，适合无服务器架构

版本特性

特性	说明
混合验证架构	支持 Cloudflare Turnstile、Google Recaptcha 及关闭模式一键切换
模块化风控	"人机验证（Captcha）"与"问题验证（Q&A）"逻辑解耦
可视化协管	列表直接显示管理员 ID，支持精准删除与添加
CRM 增强	支持通过回复 /clear 快速撤销用户备注
智能维护	数据库自动初始化、单人单卡聚合、双向状态同步

核心功能

1. 多维安全验证系统

• 三模态一键切换：Cloudflare/Google Recaptcha/关闭
• 独立问答验证：数学题或自定义问答
• 组合防御：验证码 + 问答双重验证

2. 协管权限系统

• 主管理员可添加多名协管员
• 可视化管理协管 ID

3. 双向消息中继

• 每个用户自动创建独立话题
• 管理员无感回复

4. CRM 客户管理

• 智能备注与标签
• 全局同步更新

5. 聚合收件箱

• 防刷屏机制
• 一键直达用户话题

6. 黑名单隔离

• 双向同步
• 一键解封

7. 营业状态管理

• 一键切换营业/休息
• 自动回复忙碌提示

---

Docker 部署指南（推荐）

1. 环境准备

1. 安装 Docker 和 Docker Compose
2. 准备一个可以从公网访问的域名（建议配置 HTTPS）
3. 获取 Telegram Bot Token（通过 @BotFather）
4. 获取管理员群组 ID（必须是开启话题的超级群，以 -100 开头，可在 Group Settings → Topics 开启）
5. 获取主管理员 Telegram ID（通过 @raw_data_bot 或类似工具）

2. 克隆项目

git clone https://github.com/huliyoudiangou/TG_Chat_Bot.git
cd TG_Chat_Bot
cp .env.example .env

3. 配置环境变量（.env）

编辑 .env 文件，至少配置以下内容：

# 必填配置
BOT_TOKEN=123456789:AAH_your_bot_token_here        # 机器人 Token
ADMIN_IDS=123456789                                # 主管理员 ID，多个用逗号分隔
ADMIN_GROUP_ID=-100123456789                       # 管理员群组 ID（开启话题）
WORKER_URL=https://your-domain.com                 # 对外访问的根地址（域名或反向代理地址）

# 推荐：Webhook Secret（用于校验 Telegram 回调来源）
WEBHOOK_SECRET=请填一串随机的长字符串

# 可选：Cloudflare Turnstile 验证
TURNSTILE_SITE_KEY=
TURNSTILE_SECRET_KEY=

# 可选：Google reCAPTCHA v2 验证
RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=

说明：

• WORKER_URL：
  • 需要能被 Telegram 访问到，例如 https://bot.example.com
  • 程序会自动将 webhook 设置为 ${WORKER_URL}/webhook
• WEBHOOK_SECRET：
  • 用于绑定 Telegram 的 secret_token，服务端会校验请求头 X-Telegram-Bot-Api-Secret-Token
  • 请使用一串随机且足够长的字符串，防止被第三方伪造请求

4. 启动容器

docker-compose up -d

默认会在宿主机暴露 http://127.0.0.1:3000（见 docker-compose.yml 中端口映射），生产环境建议通过 Nginx 等代理到 HTTPS 域名。

5. 设置 Telegram Webhook

容器启动后，在本机或任意能访问 Telegram API 的环境中执行：

export BOT_TOKEN=123456789:AAH_your_bot_token_here
export WORKER_URL=https://your-domain.com          # 与 .env 中保持一致
export WEBHOOK_SECRET=请填一串随机的长字符串      # 与 .env 中保持一致

curl "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -d "url=${WORKER_URL}/webhook" \
  -d "secret_token=${WEBHOOK_SECRET}"

返回 JSON 中 ok: true 即表示设置成功。此时用户给机器人发消息时，Telegram 会把更新推送到你的 Docker 服务。

6. 常用运维命令

# 查看实时日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 重新构建并启动（更新代码/依赖后）
docker-compose up -d --build

# 查看服务状态和健康检查
docker-compose ps

7. 使用 Nginx 反向代理（推荐）

如果需要 HTTPS 支持，示例 Nginx 配置如下（假设 Docker 暴露在本机 3000 端口）：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

Cloudflare Worker 部署

如果你更倾向于使用 Cloudflare Worker，请参考以下步骤：

步骤一：创建 D1 数据库

1. 登录 Cloudflare Dashboard
2. 导航至 存储和数据库 → D1 数据库
3. 创建数据库，命名为 tg-bot-db

步骤二：创建 Worker

1. 进入 Workers 和 Pages → 创建 Worker
2. 将 Telegram Bot Worker v3.39（混合验证版） 文件的代码粘贴进去
3. 部署

步骤三：绑定 D1 数据库

• 变量名称：TG_BOT_DB
• 选择创建的数据库

步骤四：配置环境变量

变量名称	说明
BOT_TOKEN	Bot Token
ADMIN_IDS	管理员 ID
ADMIN_GROUP_ID	群组 ID
WORKER_URL	Worker URL
TURNSTILE_SITE_KEY	Turnstile 站点密钥
TURNSTILE_SECRET_KEY	Turnstile 密钥
RECAPTCHA_SITE_KEY	reCAPTCHA 站点密钥
RECAPTCHA_SECRET_KEY	reCAPTCHA 密钥

步骤五：设置 Webhook

https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>

---

常见问题

问题	解决方案
系统忙，请稍后再试	检查群组是否为超级群组并开启话题
/start 无反应	检查 BOT_TOKEN 配置
回复消息无反应	检查 ADMIN_IDS 配置
Docker 启动失败	检查端口是否被占用，查看日志

---

项目结构

TG_Chat_Bot/
├── src/
│   └── index.js          # Docker 版本主程序
├── Dockerfile            # Docker 构建文件
├── docker-compose.yml    # Docker Compose 配置
├── package.json          # Node.js 依赖
├── .env.example          # 环境变量示例
├── .dockerignore         # Docker 忽略文件
└── Telegram Bot Worker v3.39（混合验证版）  # CF Worker 版本

---

许可证

MIT License

---

部署完成后，向机器人发送 /start 即可体验！