Telegram会员销售与自动充值机器人部署

演示机器人：@HFTGPRObot

TGPro Admin 是一套面向 Telegram Premium 会员和 Telegram Stars 销售场景的自动化机器人系统。它把用户下单、USDT 充值、账户余额、Fragment 订单创建、TON 链上付款、结果通知、订单记录和后台运维整合到同一套系统中，适合希望搭建 7×24 小时自助销售机器人的个人或团队。

本项目不是只有一个机器人脚本，而是由可视化管理后台、Telegram 机器人、TON 支付程序、MySQL 数据库和 Cloudflare Tunnel共同组成。管理员不需要频繁修改代码，即可在网页后台维护价格、收款配置、回复内容、按钮布局、用户余额、订单和授权信息。

一、系统可以完成什么

1. Telegram Premium 自动开通

用户在机器人中输入接收会员的 Telegram 用户名，选择 3 个月、6 个月或 12 个月套餐，并使用机器人账户余额支付。系统会先校验接收账号，再通过 Fragment 创建礼物订单，使用配置的 TON 钱包在本地签名并广播交易，确认上链后自动更新订单状态并通知用户和管理员。

2. Telegram Stars 自动购买

系统支持按数量购买 Telegram Stars。用户填写接收用户名和星星数量后，机器人会根据后台设置的单价计算 USDT 金额，生成订单并检查余额；支付成功后自动调用 Fragment/TON 交付链路，保存交易哈希和订单结果。

3. USDT TRC20 自动充值与余额支付

用户可在机器人内选择或输入充值金额，系统生成带唯一金额尾数的充值订单，并通过 TRON API 扫描收款地址交易。匹配到账后，余额自动写入用户账户。购买会员或星星时可以直接从余额扣款，避免每一笔商品订单都要求用户重新链上转账。

4. 单个与批量开通

除单个用户名下单外，机器人还提供批量开会员入口，可连续处理多个接收账号，并分别汇总成功与失败结果，适合代理或需要一次处理多笔订单的运营场景。

二、可视化管理后台功能

仪表板：查看用户数、订单数据、机器人容器状态、CPU/内存占用、运行时间和最近活动。
机器人管理：配置 Bot Token、管理员 ID、客服链接、TRC20 收款地址、机器人跳转链接、会员价格、星星单价、Fragment 登录参数、TON 钱包和 TRON API Key；保存后可在后台重启机器人容器。
机器人命令：维护命令名称、描述、回复文案、启用状态和功能链绑定。
功能链：把机器人命令、底部键盘按钮、关键词回复和内联按钮按序号连接起来，让不同入口复用同一套业务动作。
关键词回复：分别管理命令回复、按钮回复和触发型回复，支持纯文本、文本加按钮、图片加文本和按钮等组合。
键盘与内联按钮：可视化调整机器人底部键盘布局，每行支持 1～4 个按钮；内联按钮可配置 callback_data 或 URL。
用户管理：按 Telegram ID、用户名和状态搜索用户，查看余额与活跃信息，支持导入用户、调整余额和状态。
订单管理：查看会员、充值和星星订单的金额、状态、支付方式、失败原因及交易哈希；支持筛选、导出、删除和对失败订单执行重试。
授权管理：使用购买订单号/激活码验证授权，绑定当前域名或服务器标识，并查看授权状态、版本、有效期和历史记录。
系统设置：管理后台账号和角色，查看 App/Bot 本地镜像与远程 latest 镜像的构建时间，并检测是否存在新版本。

说明：当前版本采用“一个管理后台对应一个已配置机器人实例”的部署方式。机器人主要环境配置保存后需要重启机器人才能完全生效；关键词、按钮等内容配置支持运行时重新加载。

三、完整业务流程

用户向机器人发送 /start，系统记录 Telegram 用户资料并展示功能键盘。
用户先通过 TRC20 地址充值 USDT，系统扫描链上交易并自动增加机器人账户余额。
用户选择购买 Premium 或 Stars，填写接收用户名、套餐时长或星星数量。
机器人校验用户、价格和余额，创建订单并把状态设为处理中。
系统请求 Fragment 创建订单，使用 TON 钱包助记词在本地完成签名，再通过指定的 TON API 网关广播。
链上确认后，订单写入交易哈希和完成时间；失败时记录失败原因，避免在状态不明时重复付款。
用户与管理员同时收到处理结果，后台可继续查询、统计或重试失败订单。

四、技术架构

组件	技术	作用
管理后台	Nuxt 3、Vue 3、TypeScript、Nuxt UI、Tailwind CSS	SSR 管理界面、登录鉴权、REST API、配置和业务管理
机器人服务	Python 3.9、python-telegram-bot	处理命令、消息、按钮、充值、会员和星星订单
TON 支付	Go、TON SDK	选择付款钱包、本地签名、广播交易并轮询确认
数据存储	MySQL 8.0、utf8mb4	保存后台账号、Telegram 用户、余额、订单、交易和授权历史
公网访问	Cloudflare Tunnel	无需直接暴露后台端口，把 HTTPS 域名安全转发到 App 容器
部署方式	Docker Compose、GHCR 镜像	统一编排数据库、后台、机器人和 Tunnel，支持 amd64/arm64

五、部署前需要准备

一台 Linux 服务器，建议至少 2 核 CPU、2GB 内存、10GB 可用磁盘；业务量较大时建议 4GB 内存。
Docker Engine 20.10+ 与 Docker Compose v2。
一个 Telegram Bot Token，可通过 @BotFather 创建。
管理员 Telegram 数字 ID、客服账号或客服链接。
一个用于接收用户充值的 USDT TRC20 地址，以及可用的 TRON API Key。
已经登录并可正常使用的 Fragment 账号，以及对应的 ResHash 和 ResCookie。
用于支付 Fragment 订单、且有足够 TON 余额的付款钱包助记词。
可用的 TON API 网关地址和令牌；网关必须使用 HTTPS 域名，不能直接填写 TON 公共上游或 IP 地址。
托管在 Cloudflare 的域名，以及 Cloudflare Tunnel Token。
TGPro Admin 的购买订单号/激活码。

重要：Bot Token、Fragment Cookie、TON 钱包助记词、API Token 和数据库密码都属于敏感凭据。请只保存在服务器的 .env 中，不要发送到群聊、截图公开或提交到 Git 仓库。

六、服务器部署步骤

第 1 步：安装 Docker

可以使用纯 Linux、宝塔或 1Panel 管理服务器，但宝塔并不是运行本项目的必需组件。安装完成后先确认 Docker 和 Compose 可用：

docker --version
docker compose version

第 2 步：上传交付文件

将购买后获得的部署包上传到服务器并解压，例如放到 /opt/tgpro-admin。目录至少需要包含 docker-compose.yml、.env 配置文件，以及机器人日志和关键词配置所需的挂载目录。

cd /opt/tgpro-admin
mkdir -p hf-tgpro/logs
chmod 600 .env

项目目录应遵循最小权限原则，只需保证 Docker 能读取配置文件、并能写入明确的日志或数据目录。

第 3 步：填写 .env

以下为配置分组示例，所有值都必须替换为自己的真实信息。不要直接复制示例占位符上线。

# 数据库
DB_HOST=db
DB_PORT=3306
DB_NAME=hftgpro
DB_USER=REPLACE_WITH_DB_USER
DB_PASSWORD=REPLACE_WITH_STRONG_PASSWORD
DB_ROOT_PASSWORD=REPLACE_WITH_STRONG_ROOT_PASSWORD

# Telegram 机器人
BOT_TOKEN=REPLACE_WITH_BOT_TOKEN
BOT_ADMIN_ID=REPLACE_WITH_TELEGRAM_NUMERIC_ID
BOT_CUSTOMER_SERVICE_ID=REPLACE_WITH_CUSTOMER_SERVICE
BOT_TIAOZHUAN=REPLACE_WITH_BOT_LINK

# 套餐与星星价格，单位为 USDT
BOT_THREE_PRICE=15
BOT_SIX_PRICE=20
BOT_YEAR_PRICE=35
BOT_STAR_PRICE=0.01

# TRC20 充值
BOT_CONTROL_ADDRESS=REPLACE_WITH_TRC20_ADDRESS
TRON_API_KEY=REPLACE_WITH_TRON_API_KEY

# Fragment 与 TON 支付
ResHash=REPLACE_WITH_FRAGMENT_HASH
ResCookie=REPLACE_WITH_FRAGMENT_COOKIE
WalletMnemonic="REPLACE WITH TON WALLET MNEMONIC"
TON_API_GATEWAY=https://REPLACE_WITH_GATEWAY_DOMAIN
TON_API_GATEWAY_TOKEN=REPLACE_WITH_GATEWAY_TOKEN

# 后台域名和访问控制
CURRENT_DOMAIN=https://admin.example.com
BOT_CURRENT_DOMAIN=https://admin.example.com
ADMIN_PATH=REPLACE_WITH_RANDOM_ADMIN_PATH
ALLOW_DOMAIN_ACCESS=true
ALLOW_IP_ACCESS=false
ALLOWED_DOMAINS=admin.example.com
NUXT_SECRET_KEY=REPLACE_WITH_LONG_RANDOM_SECRET

# Cloudflare Tunnel
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_TOKEN=REPLACE_WITH_CLOUDFLARE_TUNNEL_TOKEN

# Telegram 更新接收方式：false 为 polling，true 为 webhook
WEBHOOK_MODE=false
BOT_WEBHOOK_PATH=/api/bot-webhook

# 可选：Cloudflare Turnstile 登录验证
TURNSTILE_ENABLED=true
TURNSTILE_SITE_KEY=REPLACE_WITH_TURNSTILE_SITE_KEY
TURNSTILE_SECRET_KEY=REPLACE_WITH_TURNSTILE_SECRET_KEY

首次部署建议先使用 WEBHOOK_MODE=false 的 polling 模式完成整体测试。需要改成 webhook 时，再设置为 true；系统会根据 ADMIN_PATH 自动为 /api/bot-webhook 添加后台路径前缀，并由 App 容器转发给 Bot 容器。

第 4 步：配置 Cloudflare Tunnel

进入 Cloudflare Zero Trust，新建一个 Tunnel。
添加 Public Hostname，例如 admin.example.com。
Service 类型选择 HTTP，目标填写 http://app:3000。这里的 app 是 Docker Compose 服务名。
复制 Tunnel Token，填入 CLOUDFLARED_TOKEN。
确保 CURRENT_DOMAIN、BOT_CURRENT_DOMAIN 和 ALLOWED_DOMAINS 与实际域名一致。

正式 Compose 配置只在 Docker 内部暴露管理后台的 3000 端口，不直接映射到服务器公网；外部访问统一经过 Cloudflare Tunnel。

第 5 步：拉取镜像并启动

cd /opt/tgpro-admin
docker compose pull
docker compose up -d
docker compose ps

当前正式部署直接使用已发布的 GHCR 镜像，通过拉取镜像并启动容器即可完成更新。Compose 会启动以下服务：

tgpro-mysql：MySQL 8.0 数据库，首次启动自动初始化并应用迁移。
tgpro-app：Nuxt 管理后台与服务端 API。
tgpro-bot：Telegram 机器人、TRC20 扫块和 TON 付款程序。
tgpro-tunnel：Cloudflare Tunnel 客户端。

第 6 步：检查日志和健康状态

docker compose ps
docker compose logs --tail=100 app
docker compose logs --tail=100 bot
docker compose logs --tail=100 db
docker compose logs --tail=100 cloudflared

四个服务都应处于运行状态，数据库应通过健康检查。机器人日志中需要看到数据库连接完成和机器人启动成功；如果 Bot Token 无效，会出现 Telegram 401；如果 Fragment 或 TON 配置不正确，通常会在实际下单时显示对应错误。

第 7 步：登录并激活授权

后台访问地址由域名和随机后台路径组成：

https://admin.example.com/你的ADMIN_PATH/

使用交付时设置的管理员账号登录。
进入“更新授权”。
输入购买订单号/激活码；授权标识可留空，系统默认使用当前域名。
先执行授权验证，确认通过后点击立即激活。
激活完成后检查授权状态、版本、到期时间和已授权域名/IP。

第 8 步：完成机器人初始配置

进入“机器人管理”，逐项复核 Token、管理员 ID、客服链接、收款地址和价格。
展开资源配置，确认 Fragment Hash、Cookie、TON 助记词、TRON API Key 和 TON 网关。
保存配置并点击“重启机器人”。
按需要修改命令、功能链、关键词回复、底部键盘和内联按钮。
在 Telegram 中依次测试 /start、/help、/buy 和 /info。

七、上线前必须完成的测试

小额充值测试：使用最小可接受金额测试 TRC20 到账识别，确认余额只增加一次。
会员测试：使用测试接收账号购买最短套餐，核对 Fragment 订单、TON 交易和 Telegram 通知。
星星测试：使用少量 Stars 测试数量、价格、余额扣减和交付结果。
失败保护：分别测试余额不足、TON 余额不足、错误用户名和过期 Fragment Cookie，确认失败原因会被记录且不会重复扣款。
后台安全：确认服务器 IP 无法直接打开后台、随机 ADMIN_PATH 生效、Turnstile 正常、非白名单域名返回拒绝访问。
重启恢复：执行 docker compose restart 后确认数据库数据、用户余额、订单和配置仍然存在。

八、日常更新、备份与维护

更新 App 与 Bot 镜像

后台“系统设置”可以检查 App/Bot 镜像是否存在新版本。当前可靠的生产升级方式仍然是由服务器执行：

cd /opt/tgpro-admin
docker compose pull
docker compose up -d
docker compose ps

数据库备份

cd /opt/tgpro-admin
docker compose exec db sh -c 'mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > tgpro-backup.sql

建议在每次升级前备份数据库和 .env，并定期把备份复制到服务器之外。MySQL 数据默认存放在 Docker 命名卷 mysql_data 中，执行普通的 docker compose down 不会删除；不要使用 docker compose down -v，否则会删除数据库卷。

常用维护命令

# 查看服务
docker compose ps

# 持续查看机器人日志
docker compose logs -f bot

# 修改 .env 后重建容器以加载新环境变量
docker compose up -d --force-recreate app bot cloudflared

# 只重启机器人
docker compose restart bot

九、常见问题

1. 后台打不开或显示 403

优先检查 Cloudflare Tunnel 是否在线、Public Hostname 是否指向 http://app:3000，以及 CURRENT_DOMAIN、ALLOWED_DOMAINS、ALLOW_DOMAIN_ACCESS 是否一致。后台 URL 还必须包含正确的 ADMIN_PATH。