从Polling到WebhookTLG_JoinCaptchaBot高并发架构实战附SSL证书生成与配置【免费下载链接】TLG_JoinCaptchaBotTelegram Bot to verify if users joining a group are human. The Bot sends a captcha challenge to each new user and removes those who fail to solve it within a specified time.项目地址: https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBotTLG_JoinCaptchaBot 是一款 Telegram 入群验证机器人新成员加入群聊时会自动收到一个 CAPTCHA 验证码挑战超时未通过则被自动移出群组同时清理未验证用户的广告消息。对于管理单个小群的爱好者默认的 Polling 轮询模式完全够用但当你的机器人同时守护几十个活跃群组、入群事件密集爆发时轮询的延迟和 API 配额就会成为瓶颈。本文带你完整走一遍从 Polling 切换到 Webhook 的高并发架构改造并附赠 Webhook 必备的SSL 证书生成与配置全流程。什么时候需要从 Polling 切换到 Webhook先理解两种连接模式的本质差异对比项Polling默认Webhook推荐高并发工作方式机器人周期性向 Telegram 服务器拉取更新Telegram 服务器主动推送更新到你的 HTTPS 接口延迟表现存在轮询间隔突发入群时有延迟事件实时推送响应最快API 配额消耗每次轮询都占用 Bot API 配额无轮询开销部署门槛无开箱即用需要公网可达的 443/8443 端口与 SSL 证书适用场景个人小群、低频验证多群组托管、高并发入群场景判断标准很简单当make status显示的群组数量超过 20 个或日志中频繁出现 Timeout 慢连接告警时就该考虑切换到 Webhook 了。TLG_JoinCaptchaBot 双模式架构源码里的关键点这个项目把 Polling / Webhook 的切换封装得非常干净核心逻辑集中在启动函数 src/join_captcha_bot.py 中未启用 Webhook 时调用app.run_polling()机器人进入轮询循环启用 Webhook 后调用app.run_webhook()传入监听地址、端口、URL 路径、证书文件与密钥、以及用于校验请求来源的 Secret Token。两种模式共用同一套业务处理器入群事件、验证码消息、投票选项等切换模式不会改变任何验证逻辑只改变事件进入机器人的通道。所有连接参数都集中在 src/settings.py 中定义而 src/constants.py 表明环境变量会覆盖 settings.py 中的同名配置——这一点在 Docker 部署时非常有用参考 docker/README.md。SSL 证书生成openssl 完整步骤Telegram 的 Webhook 要求你的接口通过 HTTPS 提供服务。自托管场景下最快的方式是生成一张自签名证书Telegram 会通过证书指纹来校验不要求公网 CA 签发。在src/目录下执行openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem参数速记-nodes私钥不加密机器人启动时无需交互式输密码-days 3650有效期 10 年避免证书过期导致 Webhook 静默失效生成期间会依次询问国家、组织等信息直接回车使用默认值即可。最终会得到两个文件路径与 settings.py 中的默认值一致证书文件src/cert.pem私钥文件src/private.key⚠️ 注意private.key的权限应收紧如chmod 600且切勿提交到代码仓库。Webhook 配置清单5 步启用高并发模式编辑 src/settings.py按清单逐项确认打开总开关CAPTCHABOT_USE_WEBHOOK: True监听地址与端口CAPTCHABOT_WEBHOOK_IP: 0.0.0.0、CAPTCHABOT_WEBHOOK_PORT: 84438443 是 Telegram 官方允许的 Webhook 端口之一也是本项目默认值回调路径CAPTCHABOT_WEBHOOK_PATH: /TLG_JoinCaptchaBot即 Telegram 访问https://你的域名:8443/TLG_JoinCaptchaBot证书路径CAPTCHABOT_WEBHOOK_CERT指向cert.pemCAPTCHABOT_WEBHOOK_CERT_PRIV_KEY指向private.key来源校验CAPTCHABOT_WEBHOOK_SECRET_TOKEN设置一个随机长字符串不要复用 Bot Token。Telegram 推送时会携带该 Token服务端可借此拒绝伪造请求确认服务器防火墙已放行 8443 端口后用项目自带的 Makefile 重启即可make stop make start make status如果想实时观察入群与验证码流程tools/monitor会持续过滤出关键日志tools/entrypoint.sh 则是 Docker 场景下的启动入口。反向代理 WebhookNginx 进阶配置如果你的服务器用域名 443 端口对外提供服务比如已有一个 Nginx 反代可以启用TLS 由代理终结的模式在 Nginx 中把https://your.domain.com/TLG_JoinCaptchaBot反向代理到本机127.0.0.1:8443settings.py 中填入CAPTCHABOT_WEBHOOK_URL: https://your.domain.com:8443/TLG_JoinCaptchaBot证书由 Nginx 托管Bot 本地证书不再参与握手此模式下必须配置CAPTCHABOT_WEBHOOK_SECRET_TOKEN因为代理层无法替你鉴别请求是否真的来自 Telegram。这种方式的好处统一域名管理证书续期、对外只暴露一个 443 端口安全性与可维护性最佳。验证与回滚部署最佳实践验证 Webhook 是否就绪用浏览器或 curl 访问你的回调地址应能收到 Telegram 的响应而不是连接拒绝同时查看output.log中是否出现Setup Bot for Webhook.的启动日志。回滚到 Polling 只有一行把CAPTCHABOT_USE_WEBHOOK改回False再重启机器人会恢复轮询并丢弃积压的旧事件代码中drop_pending_updatesTrue保证了这一点无需任何其他迁移。项目提供make setup一键初始化环境克隆仓库后可直接体验git clone https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBot cd TLG_JoinCaptchaBot make setupWebhook 高并发 FAQQ为什么默认端口是 8443 而不是 443Telegram 的 Webhook 服务仅接受 443、80、88、8443 四个端口。8443 无需 root 权限即可绑定是个人服务器的安全折中生产环境建议配合 Nginx 使用 443。Q切换模式需要迁移数据吗不需要。会话数据、群组配置src/data/chats/与验证码目录都与连接模式解耦restore_session()会在重启后恢复超时计时状态。QPolling 模式会被 API 限流吗会。轮询次数越高越容易触发 Telegram 的 429 RetryAfter 限流日志中有专门告警这正是高并发场景选择 Webhook 的根本原因。小结TLG_JoinCaptchaBot 用一行配置开关就打通了 Polling 与 Webhook 两条链路自签名证书十分钟搞定、8443 端口免特权绑定、Secret Token 防伪造请求——三件套配齐后你的入群验证机器人就能平滑承接几十甚至上百个群组的高并发入群事件。先从小群用 Polling 跑起来规模上去再按本文清单切 Webhook是最稳妥的演进路径。【免费下载链接】TLG_JoinCaptchaBotTelegram Bot to verify if users joining a group are human. The Bot sends a captcha challenge to each new user and removes those who fail to solve it within a specified time.项目地址: https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从Polling到Webhook：TLG_JoinCaptchaBot高并发架构实战（附SSL证书生成与配置）
从Polling到WebhookTLG_JoinCaptchaBot高并发架构实战附SSL证书生成与配置【免费下载链接】TLG_JoinCaptchaBotTelegram Bot to verify if users joining a group are human. The Bot sends a captcha challenge to each new user and removes those who fail to solve it within a specified time.项目地址: https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBotTLG_JoinCaptchaBot 是一款 Telegram 入群验证机器人新成员加入群聊时会自动收到一个 CAPTCHA 验证码挑战超时未通过则被自动移出群组同时清理未验证用户的广告消息。对于管理单个小群的爱好者默认的 Polling 轮询模式完全够用但当你的机器人同时守护几十个活跃群组、入群事件密集爆发时轮询的延迟和 API 配额就会成为瓶颈。本文带你完整走一遍从 Polling 切换到 Webhook 的高并发架构改造并附赠 Webhook 必备的SSL 证书生成与配置全流程。什么时候需要从 Polling 切换到 Webhook先理解两种连接模式的本质差异对比项Polling默认Webhook推荐高并发工作方式机器人周期性向 Telegram 服务器拉取更新Telegram 服务器主动推送更新到你的 HTTPS 接口延迟表现存在轮询间隔突发入群时有延迟事件实时推送响应最快API 配额消耗每次轮询都占用 Bot API 配额无轮询开销部署门槛无开箱即用需要公网可达的 443/8443 端口与 SSL 证书适用场景个人小群、低频验证多群组托管、高并发入群场景判断标准很简单当make status显示的群组数量超过 20 个或日志中频繁出现 Timeout 慢连接告警时就该考虑切换到 Webhook 了。TLG_JoinCaptchaBot 双模式架构源码里的关键点这个项目把 Polling / Webhook 的切换封装得非常干净核心逻辑集中在启动函数 src/join_captcha_bot.py 中未启用 Webhook 时调用app.run_polling()机器人进入轮询循环启用 Webhook 后调用app.run_webhook()传入监听地址、端口、URL 路径、证书文件与密钥、以及用于校验请求来源的 Secret Token。两种模式共用同一套业务处理器入群事件、验证码消息、投票选项等切换模式不会改变任何验证逻辑只改变事件进入机器人的通道。所有连接参数都集中在 src/settings.py 中定义而 src/constants.py 表明环境变量会覆盖 settings.py 中的同名配置——这一点在 Docker 部署时非常有用参考 docker/README.md。SSL 证书生成openssl 完整步骤Telegram 的 Webhook 要求你的接口通过 HTTPS 提供服务。自托管场景下最快的方式是生成一张自签名证书Telegram 会通过证书指纹来校验不要求公网 CA 签发。在src/目录下执行openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem参数速记-nodes私钥不加密机器人启动时无需交互式输密码-days 3650有效期 10 年避免证书过期导致 Webhook 静默失效生成期间会依次询问国家、组织等信息直接回车使用默认值即可。最终会得到两个文件路径与 settings.py 中的默认值一致证书文件src/cert.pem私钥文件src/private.key⚠️ 注意private.key的权限应收紧如chmod 600且切勿提交到代码仓库。Webhook 配置清单5 步启用高并发模式编辑 src/settings.py按清单逐项确认打开总开关CAPTCHABOT_USE_WEBHOOK: True监听地址与端口CAPTCHABOT_WEBHOOK_IP: 0.0.0.0、CAPTCHABOT_WEBHOOK_PORT: 84438443 是 Telegram 官方允许的 Webhook 端口之一也是本项目默认值回调路径CAPTCHABOT_WEBHOOK_PATH: /TLG_JoinCaptchaBot即 Telegram 访问https://你的域名:8443/TLG_JoinCaptchaBot证书路径CAPTCHABOT_WEBHOOK_CERT指向cert.pemCAPTCHABOT_WEBHOOK_CERT_PRIV_KEY指向private.key来源校验CAPTCHABOT_WEBHOOK_SECRET_TOKEN设置一个随机长字符串不要复用 Bot Token。Telegram 推送时会携带该 Token服务端可借此拒绝伪造请求确认服务器防火墙已放行 8443 端口后用项目自带的 Makefile 重启即可make stop make start make status如果想实时观察入群与验证码流程tools/monitor会持续过滤出关键日志tools/entrypoint.sh 则是 Docker 场景下的启动入口。反向代理 WebhookNginx 进阶配置如果你的服务器用域名 443 端口对外提供服务比如已有一个 Nginx 反代可以启用TLS 由代理终结的模式在 Nginx 中把https://your.domain.com/TLG_JoinCaptchaBot反向代理到本机127.0.0.1:8443settings.py 中填入CAPTCHABOT_WEBHOOK_URL: https://your.domain.com:8443/TLG_JoinCaptchaBot证书由 Nginx 托管Bot 本地证书不再参与握手此模式下必须配置CAPTCHABOT_WEBHOOK_SECRET_TOKEN因为代理层无法替你鉴别请求是否真的来自 Telegram。这种方式的好处统一域名管理证书续期、对外只暴露一个 443 端口安全性与可维护性最佳。验证与回滚部署最佳实践验证 Webhook 是否就绪用浏览器或 curl 访问你的回调地址应能收到 Telegram 的响应而不是连接拒绝同时查看output.log中是否出现Setup Bot for Webhook.的启动日志。回滚到 Polling 只有一行把CAPTCHABOT_USE_WEBHOOK改回False再重启机器人会恢复轮询并丢弃积压的旧事件代码中drop_pending_updatesTrue保证了这一点无需任何其他迁移。项目提供make setup一键初始化环境克隆仓库后可直接体验git clone https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBot cd TLG_JoinCaptchaBot make setupWebhook 高并发 FAQQ为什么默认端口是 8443 而不是 443Telegram 的 Webhook 服务仅接受 443、80、88、8443 四个端口。8443 无需 root 权限即可绑定是个人服务器的安全折中生产环境建议配合 Nginx 使用 443。Q切换模式需要迁移数据吗不需要。会话数据、群组配置src/data/chats/与验证码目录都与连接模式解耦restore_session()会在重启后恢复超时计时状态。QPolling 模式会被 API 限流吗会。轮询次数越高越容易触发 Telegram 的 429 RetryAfter 限流日志中有专门告警这正是高并发场景选择 Webhook 的根本原因。小结TLG_JoinCaptchaBot 用一行配置开关就打通了 Polling 与 Webhook 两条链路自签名证书十分钟搞定、8443 端口免特权绑定、Secret Token 防伪造请求——三件套配齐后你的入群验证机器人就能平滑承接几十甚至上百个群组的高并发入群事件。先从小群用 Polling 跑起来规模上去再按本文清单切 Webhook是最稳妥的演进路径。【免费下载链接】TLG_JoinCaptchaBotTelegram Bot to verify if users joining a group are human. The Bot sends a captcha challenge to each new user and removes those who fail to solve it within a specified time.项目地址: https://gitcode.com/gh_mirrors/tl/TLG_JoinCaptchaBot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考