graph TB
    A[👤 用户] -->|发送消息| B[🤖 机器人]
    B -->|转发消息| C[👨‍💼 管理员]
    B -->|自动记录用户| D[(KV存储)]
    
    C -->|回复消息| B
    B -->|转发回复| A
    
    C -->|/post 群发命令| E[群发处理器]
    E -->|手动指定ID| F[解析用户列表]
    E -->|/post all| D
    D -->|返回用户列表| F
    
    F -->|批量发送| G[限速处理]
    G -->|发送消息| H[📢 所有目标用户]
    G -->|发送报告| C
    
    C -->|/users 命令| D
    D -->|返回用户信息| C
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style H fill:#e0f2f1

这是一个基于Cloudflare Workers的高性能Telegram双向消息转发机器人，采用无状态设计，支持用户消息转发给管理员，管理员直接回复，以及强大的群发消息功能。新增论坛话题模式支持，为每个用户创建独立话题，提供更好的消息管理体验。

• 🚀 一键部署 - 支持Deploy按钮快速部署到Cloudflare Workers
• 🔥 零成本部署 - 基于Cloudflare Workers免费额度
• ⚡ 极速响应 - 后台处理，毫秒级响应
• 🛡️ 高可靠性 - 完善错误处理，自动监控
• 🧹 代码简洁 - 函数式架构，易于维护
• 📦 开箱即用 - 单文件部署，配置简单
• 🗣️ 论坛模式 - 支持Telegram论坛群组，每个用户独立话题

graph TB
    A[👤 用户A] -->|发送消息| B[🤖 机器人]
    C[👤 用户B] -->|发送消息| B
    D[👤 用户C] -->|发送消息| B
    
    B -->|自动创建话题| E[📝 话题A: 💬 张三 123456]
    B -->|自动创建话题| F[📝 话题B: 💬 李四 789012]
    B -->|自动创建话题| G[📝 话题C: 💬 王五 345678]
    
    E -->|消息转发| H[👨‍💼 管理员]
    F -->|消息转发| H
    G -->|消息转发| H
    
    H -->|在话题中回复| E
    H -->|在话题中回复| F
    H -->|在话题中回复| G
    
    E -->|自动回复| A
    F -->|自动回复| C
    G -->|自动回复| D
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e1f5fe
    style D fill:#e1f5fe
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0
    style H fill:#e8f5e8

🎯 论坛模式优势

🛠️ 论坛模式配置

1. 创建论坛群组

   • 在Telegram中创建新群组
   • 进入群组设置 → 群组类型 → 选择"论坛"

2. 配置机器人

   • 将机器人添加到论坛群组
   • 设置环境变量 ENABLE_FORUM_MODE=true
   • 确保机器人有创建话题的权限

3. 自动功能

   • 🚀 用户首次发送消息时自动创建话题
   • 🎨 随机分配话题图标颜色
   • 📝 话题名称格式：💬 用户名 (用户ID)
   • 🔄 所有后续消息自动路由到对应话题

• 📞 客服系统 - 个人/小团队客服消息处理
• 🔗 消息中转 - 不同用户群体间的消息桥接
• 📱 通知转发 - 将系统通知转发到个人聊天
• 🤖 Bot集成 - 作为其他系统的消息接口
• 🗣️ 论坛管理 - 在论坛群组中为每个用户管理独立话题

🎯 超简单部署: 只需点击按钮，Fork仓库，配置环境变量即可完成部署！

BOT_TOKEN=1234567890:AAAA-BBBBBBBBBBBBBBBBBBBBBBBBBB
ADMIN_CHAT_ID=123456789
WEBHOOK_SECRET=your-random-secret-key
USER_ID_SECRET=your-user-id-secret-key
ENABLE_USER_TRACKING=true
ENABLE_FORUM_MODE=true  # 启用论坛话题模式（可选）

# 1. 克隆仓库
git clone https://github.com/SCSHIRKER/cftgsx.git
cd cftgsx

# 2. 安装Wrangler CLI
npm install -g wrangler

# 3. 登录Cloudflare
wrangler auth login

# 4. 配置wrangler.toml
# 编辑wrangler.toml，取消KV存储注释（如需要）

# 5. 创建KV存储（可选）
wrangler kv:namespace create "USER_STORAGE"
wrangler kv:namespace create "USER_STORAGE" --preview

# 6. 设置环境变量
wrangler secret put BOT_TOKEN
wrangler secret put ADMIN_CHAT_ID
wrangler secret put WEBHOOK_SECRET
wrangler secret put USER_ID_SECRET

# 7. 部署
wrangler deploy

# 8. 设置Webhook
curl https://your-worker.your-subdomain.workers.dev/setWebhook

# 或者使用npm脚本（更方便）
npm run deploy          # 部署到默认环境
npm run deploy:prod     # 部署到生产环境
npm run dev             # 本地开发模式
npm run webhook:set     # 设置Webhook（需要先修改URL）
npm run status          # 检查服务状态

• Cloudflare账号 (免费)
• Telegram Bot Token
• 管理员的Telegram Chat ID

1. 获取Bot Token

   # 1. 在Telegram中找到 @BotFather
   # 2. 发送 /newbot 创建机器人
   # 3. 记录返回的Bot Token

2. 获取Chat ID

   # 方法1: 使用 @userinfobot 获取你的Chat ID
   # 方法2: 发消息给bot后访问 https://api.telegram.org/bot<TOKEN>/getUpdates

3. 部署到Cloudflare

   • 复制 worker.js 内容到Cloudflare Workers编辑器
   • 设置环境变量 (见下方配置)
   • 访问 /setWebhook 端点完成配置

就是这么简单！🎉

示例输出:
Use this token to access the HTTP API:
1234567890:AAAA-BBBBBBBBBBBBBBBBBBBBBBBBBB

1. 在Telegram中搜索 @userinfobot
2. 发送 /start
3. 记录显示的Chat ID

1. 向你的机器人发送任意消息
2. 访问: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
3. 在返回的JSON中找到 "chat":{"id": 123456789}

{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}

现在你的机器人已经可以正常工作了：

• 用户发送消息会自动转发给管理员
• 管理员回复转发的消息即可回复给用户
• 管理员可使用/post命令进行消息群发

/start                    # 开始对话，显示欢迎信息
发送任意消息               # 自动转发给管理员
等待管理员回复             # 收到管理员的回复消息

/start                    # 显示管理员控制面板
/status                   # 查看机器人运行状态  
/help                     # 获取帮助信息
/users                    # 查看用户列表（需启用用户跟踪）
回复转发的消息             # 直接回复给对应用户

# 📢 群发功能
/post all 消息内容        # 向所有用户群发（需启用用户跟踪）
/post 123,456,789 消息内容 # 向指定用户群发
回复媒体+/post命令        # 群发媒体消息

# 🚫 封禁管理
/ban                      # 封禁用户（回复消息或在话题中使用）
/ban 123456789            # 封禁指定ID的用户
/unban                    # 解封用户（回复消息或在话题中使用）
/unban 123456789          # 解封指定ID的用户

# 🗣️ 论坛模式操作（启用论坛模式时）
在用户话题中直接发送消息    # 直接回复给对应用户
回复话题中的消息           # 回复给对应用户
在用户话题中使用/ban       # 封禁该话题对应的用户
查看话题列表              # 每个话题对应一个用户

cftgsx/
├── 📄 worker.js                 # 主程序文件 (单文件部署)
├── 📄 package.json              # 项目配置和脚本命令
├── 📄 wrangler.toml             # Cloudflare Workers配置文件
├── 📄 deploy-config.example.json # 部署配置示例文件
├── 📄 README.md                 # 项目说明文档
├── 📄 LICENSE                   # MIT开源协议
└── 📄 .gitignore               # Git忽略文件

本项目已实现用户身份伪造防护机制，确保消息转发的安全性：

• 身份伪造攻击: 恶意用户曾可通过在消息中插入 [USER:其他用户ID] 来伪造身份
• 影响: 管理员回复可能被错误发送给其他用户

1. 加密签名验证

   • 用户标识采用 [USER:id:signature] 格式
   • 使用HMAC-SHA256生成不可伪造的签名
   • 自动验证签名有效性

2. 环境变量保护

   USER_ID_SECRET=your-random-secret-key  # 签名密钥
   WEBHOOK_SECRET=your-webhook-secret     # Webhook验证

3. 向后兼容

   • 支持旧格式标识符（仅在无新格式时使用）
   • 自动迁移到安全格式
   • 记录安全警告日志

1. 设置强密钥

   # 生成随机密钥示例
   openssl rand -hex 32  # 用于 USER_ID_SECRET
   openssl rand -hex 16  # 用于 WEBHOOK_SECRET

2. 监控安全日志

   • 查看Cloudflare Workers日志
   • 关注"检测到无效的用户ID签名"警告
   • 监控"使用了不安全的旧格式"提示

3. 最佳实践

   • 定期更换密钥
   • 启用Webhook验证
   • 限制管理员访问权限

⚠️ 重要提醒: 如果不设置 USER_ID_SECRET，系统将使用后备哈希机制，安全性相对较低。强烈建议配置此环境变量。

在Cloudflare Workers控制台查看实时日志：

Workers → 你的Worker → Logs 标签

• 并发处理: Cloudflare Workers免费版有并发限制 (1000 requests/min)
• 消息大小: 受Telegram API限制（文件最大50MB）
• 存储: 无持久化存储，适合消息转发场景
• 功能: 专注消息转发，不支持群聊管理等复杂功能

• 高并发: 升级Cloudflare Workers套餐
• 大文件: 使用文件压缩或分片上传
• 数据存储: 集成KV存储实现持久化（如需要）

欢迎提交Issue和Pull Request！

1. 克隆项目

   git clone https://github.com/SCSHIRKER/cftgsx.git
   cd cftgsx

2. 本地测试

   # 使用 Wrangler CLI 进行本地开发
   npm install -g wrangler
   wrangler dev

3. 代码风格

   • 使用ES6+语法
   • 函数式编程优先
   • 添加适当的错误处理
   • 保持代码简洁明了

• 🐛 fix: 修复Bug
• ✨ feat: 新功能
• 📚 docs: 文档更新
• 🎨 style: 代码格式
• ♻️ refactor: 代码重构
• ⚡ perf: 性能优化
• 🧪 test: 测试相关

项目采用最新的Cloudflare Workers最佳实践进行优化。

• ✨ 新增封禁管理: 支持封禁/解封用户，被封禁用户无法发送消息
• 🎯 多种封禁方式: 支持指定用户ID、回复消息、论坛话题内封禁
• 🔧 智能识别: 依次尝试从参数、回复消息、话题ID获取目标用户
• 🗣️ 论坛模式优化: 在用户话题中直接使用 /ban 即可封禁该用户
• 🛠️ 条件判断优化: 修复封禁命令的条件判断逻辑，确保所有方式都能正常工作
• 💾 持久化存储: 封禁状态保存在KV存储中，重启不丢失
• 🔐 安全管理: 仅管理员可以执行封禁/解封操作

• 🔗 修复链接渲染: 移除等宽字体包装，确保用户链接可正常点击跳转
• 🎨 优化显示格式: 使用"📍 来源:"标签替代原反引号包装，提升消息可读性
• 💫 改进用户体验: 管理员现在可以直接点击用户链接查看用户信息或跳转对话
• 🔧 技术细节: 基于Telegram Markdown规范优化格式化，确保链接正确渲染

• ✨ 智能用户链接: 根据用户类型生成不同格式的可点击链接
  • 有username用户: [@username (ID:signature)](https://t.me/username)
  • 无username用户: [👤 USER:ID:signature](tg://user?id=ID)
• 🎯 优先显示username: 有username的用户优先显示@username格式，更符合Telegram使用习惯
• 🛡️ 安全性保持: 所有链接格式仍包含签名验证，确保安全性
• 🔄 完全向后兼容: 支持多种历史格式的用户标识解析
• 📱 跨平台支持: username链接使用web格式，在所有设备上都能正常工作
• 💾 数据增强: 用户信息存储中新增username字段，提升数据完整性

• 🐛 修复Markdown解析错误: 解决包含特殊字符的消息发送失败问题
• 🔧 新增escapeMarkdown函数: 自动转义Telegram Markdown特殊字符 (*, _, [, ], (, ), ~, `, >, #, +, =, |, {, }, ., !, -)
• 🛡️ 全面安全加固: 对管理员回复、广播消息、用户caption、错误消息等6个关键位置进行转义处理
• ⚡ 改进sendMessage函数: 支持自定义parse_mode选项，保持向后兼容性
• 📈 提升稳定性: 彻底解决"Bad Request: can't parse entities"错误
• 🎯 用户体验优化: 消息内容保持可读性的同时确保发送成功

• ✨ 新增论坛话题模式: 支持Telegram论坛群组，每个用户独立话题
• 🏗️ 架构重构: 基于Cloudflare Workers最佳实践全面优化代码质量
• 🛡️ 安全增强: 强化输入验证、错误处理和HMAC签名机制
• ⚡ 性能优化: 添加API超时处理、重试机制和批量优化
• 🔧 新增常量管理: 统一配置管理，提高代码可维护性
• 📊 日志系统: 实现结构化日志记录，便于监控和调试
• 🗣️ 论坛功能: 自动创建用户话题、随机图标色彩、话题内直接回复
• 🔍 系统消息过滤: 智能过滤创建话题等系统消息，避免误报
• 📚 文档完善: 详细的论坛模式配置指南和功能对比说明
• 🧪 代码质量: 添加输入验证、错误边界处理和API响应验证

• 🛡️ 重要安全修复: 修复用户身份伪造漏洞
• ✨ 新增加密签名验证机制 (HMAC-SHA256)
• 🔧 新增 USER_ID_SECRET 环境变量
• 🔒 用户标识格式升级为 [USER:id:signature]
• 📝 向后兼容旧格式标识符，自动迁移
• 📚 新增详细安全说明和配置指南
• ⚡ 优化安全日志和警告提示

• ✨ 新增群发消息功能
• ✨ 新增用户跟踪管理
• ✨ 新增KV存储支持
• 🔧 新增 /post 命令支持文本和媒体群发
• 🔧 新增 /users 命令查看用户列表
• ⚡ 优化批量处理和自动限速
• 📚 完善文档和使用说明

• 🎉 首次发布
• ✨ 双向消息转发功能
• ⚡ 无状态高性能设计
• 🛡️ 完善错误处理机制
• 📦 单文件部署方案
• 🔧 管理员命令支持

• 群聊消息转发支持
• 消息过滤和规则配置
• 数据统计和分析面板
• 多管理员支持
• 消息模板和自动回复

本项目采用 MIT License 开源协议。

MIT License - 可自由使用、修改、分发

• 感谢 Cloudflare Workers 提供的优秀Serverless平台
• 感谢 Telegram Bot API 的强大功能
• 感谢所有贡献者和使用者的支持

如果这个项目对你有帮助，请考虑：

• ⭐ 给项目加个Star
• 🐛 报告Bug或提出建议
• 📢 推荐给其他人
• 🤝 参与项目贡献

• Cloudflare Workers 文档
• Telegram Bot API 文档
• GitHub仓库