Dujiao-Bot 是为 Dujiao-Next 设计的独立 Telegram 业务插件。它不是一个只会回复固定文字的简单机器人，而是把商城商品、用户绑定、订单查询、自动发货、状态通知和人工客服串到 Telegram 会话中，让用户可以在聊天窗口完成浏览、查询和售后操作，管理员则可以在 Dujiao-Next 后台统一管理机器人行为。
本文基于 IDE/Dujiao-Next/plugins/dujiao-bot 当前项目代码整理，重点说明它能解决什么问题、内部如何协作，以及如何以插件方式完成部署。
一、Dujiao-Bot 适合什么场景
传统发卡商城通常要求用户反复打开网页：登录、查订单、复制订单号、查看卡密，再跳到客服工具咨询。Dujiao-Bot 把高频动作搬进 Telegram，适合数字商品、卡密、兑换码、软件授权、会员服务和其他需要自动交付的业务。
- 购买前：展示商城入口、商品按钮、活动入口和自定义菜单。
- 购买后：查询个人订单、跟踪指定订单、接收付款与发货通知。
- 售后：创建客服会话、转发用户消息、由管理员结束或继续处理。
- 运营：广播消息、低库存预警、关键词回复、命令和键盘布局配置。
二、项目架构：插件、商城与 Telegram 如何协作
Dujiao-Bot 的插件 ID 为 dujiao-bot，版本为 1.0.0，属于自管理插件。运行时使用独立的 Express 服务，默认监听 3020 端口，并加入 Dujiao-Next 的 dujiao-network 网络。
Telegram 用户
│
▼
Dujiao-Bot（Express + node-telegram-bot-api）
├── Dujiao-Next Core API：商品、用户、订单
├── PostgreSQL：绑定关系、发货队列、客服会话、配置数据
├── Redis：缓存与运行状态
└── Next.js 管理面板：机器人可视化配置插件依赖 Dujiao-Next 的 PostgreSQL、Redis 和 Core API，但数据目录、日志目录、生命周期脚本以及管理界面都归插件自己管理。这样做的好处是：启用或停用机器人时，不需要破坏商城核心服务；升级机器人镜像时，也不必重新构建整套商城。
三、核心功能详解
1. Telegram 用户入口与多语言菜单
机器人内置 /start、/menu、/help、/orders、/track 和 /support 等主要命令。菜单不仅能放普通回复，还可以配置商城、邀请、赠品、订单中心和 Mini App 等链接。
当前代码准备了简体中文、繁体中文和英文文案。用户可以通过按钮进入商品、订单和个人中心，减少记忆命令的成本。机器人既支持 Telegram Webhook，也支持长轮询：配置 Webhook 地址后自动使用 Webhook；没有配置时可回退到 polling，适合本地调试。
2. 用户绑定与订单查询
用户完成 Telegram 与商城账户绑定后，机器人可以通过 Dujiao-Next Core API 获取该用户的订单数据。/orders 会返回最近订单和状态，/track 订单号 用于查询指定订单，并显示金额、商品、创建时间和发货时间。
绑定状态和通知开关会保存到数据库。用户可以关闭非必要通知，同时保留订单查询能力，避免机器人消息过多。
3. 自动发货队列
商城支付成功后，可通过受保护的回调接口把订单加入发货队列。发货服务会按队列顺序处理任务，避免同一订单被重复加入；成功后向用户推送卡密或交付内容，并回写主系统状态。
默认配置支持失败重试，最大尝试次数为 3 次，重试间隔默认为 5 秒。单笔回调、批量回调和取消发货都有独立接口，适合高峰期批量处理，也方便管理员干预异常订单。
4. 订单、付款、退款与库存通知
通知服务可以按开关处理新订单、付款成功、发货完成、退款和低库存事件。管理员可以收到订单号、金额、商品和用户等摘要；绑定了 Telegram 的用户可以同步收到与自己相关的状态通知。
低库存阈值默认是 10，可通过环境变量调整。对于依赖卡密库存的商城，这类预警能在商品售罄前提醒运营人员补货。
5. 内置客服会话
用户发送 /support 后可以创建客服会话。客服模块记录会话状态、用户消息、管理员回复和最后活动时间，默认会话超时为 30 分钟，默认最大并发会话数为 100。
管理员既可以在机器人里处理，也可以配置独立人工客服链接。会话结束后，用户仍可重新发送 /support 发起新咨询，因此不会因为一次会话关闭而失去售后入口。
6. 可视化 Bot 管理面板
插件自带 Next.js 静态管理面板，通过 Dujiao-Next 后台 iframe 打开。当前页面包括：
- 机器人设置；
- 功能链配置；
- 命令设置；
- 键盘按钮；
- 内联按钮；
- 关键词回复；
- 群组与用户。
这些配置统一使用插件命名空间 /plugins/dujiao-bot/，避免与商城核心 API 冲突。后台保存的运行配置写入持久卷中的 /plugin/data/.env，容器重建后仍能继续加载。
四、插件目录说明
plugins/dujiao-bot/
├── plugin.json 插件声明、权限和生命周期
├── docker-compose.yml 独立容器编排
├── .env.example 配置模板
├── backend/ Express、Telegram 与业务服务
├── admin/ Next.js 管理后台
├── public/ 后台注入脚本与备用面板
├── migrations/ PostgreSQL 迁移
├── hooks/ 安装、启用、停用、卸载脚本
├── nginx.conf 插件路由代理
└── Dockerfile 生产镜像构建五、推荐部署方式
方式一：从 Dujiao-Next 应用商店启用
推荐在 Dujiao-Next 的应用商店或插件管理页安装并启用 Dujiao-Bot。插件宿主会读取 plugin.json，注册 Compose 服务、后台入口、静态资源、权限和生命周期脚本。
方式二：手动启用
cp plugins/dujiao-bot/.env.example plugins/dujiao-bot/.env
vim plugins/dujiao-bot/.env
plugins/dujiao-bot/hooks/install.sh
plugins/dujiao-bot/hooks/enable.sh至少需要填写 Telegram Bot Token、机器人用户名、管理员 Telegram ID，以及与 Dujiao-Next 一致的数据库连接信息。生产环境还应修改 JWT Secret、Session Secret 和数据库密码，不能继续使用示例值。
六、主要环境变量
TELEGRAM_BOT_TOKEN：从 BotFather 获取的机器人 Token。TELEGRAM_BOT_USERNAME：机器人用户名。TELEGRAM_ADMIN_IDS：管理员 Telegram ID，多个值用逗号分隔。TELEGRAM_WEBHOOK_URL：公网 HTTPS Webhook 地址，可留空使用 polling。API_INTERNAL_URL：容器网络中的 Dujiao-Next Core API 地址。ENABLE_AUTO_DELIVERY：自动发货总开关。ENABLE_CUSTOMER_SERVICE：客服模块开关。ENABLE_NOTIFICATION：通知模块开关。ENABLE_ORDER_TRACKING：订单跟踪开关。
七、启动后的检查方法
docker compose ps
docker compose logs -f dujiao-bot
curl http://127.0.0.1:3020/health健康接口正常时会返回插件 ID、版本、运行时间和当前时间。之后应继续验证 Telegram Webhook、数据库连接和 Core API，而不是只看到容器处于运行状态就认为全部可用。
建议依次测试：/start 菜单、账号绑定、/orders、/track、测试订单付款、自动发货、通知和 /support 客服会话。
八、停用与卸载的区别
disable 只停止服务并撤销前端与路由注册；uninstall 默认仍保留 data 和 logs。只有管理员明确选择删除数据时，才应设置删除数据标记。这样的设计能避免误操作导致绑定关系、配置和日志一起丢失。
九、安全与运维建议
- Webhook 与主系统回调必须使用 HTTPS 和随机密钥校验。
- 不要把真实 Token、数据库密码或 Session Secret 提交到 Git。
- 限制 Telegram 管理员 ID，避免把管理命令开放给普通用户。
- 定期检查发货失败队列和低库存告警。
- 插件升级前备份持久卷中的配置和数据库。
- 外部访问只暴露必要路由，PostgreSQL 与 Redis 保持在内部 Docker 网络。
十、总结
Dujiao-Bot 的价值并不是简单地“给商城加一个 Telegram 机器人”，而是把 Dujiao-Next 的商品、用户、订单、交付和客服能力组合成一条完整的聊天式业务链路。插件化目录、独立 Compose、持久化配置、自动迁移和清晰的生命周期，让它既适合直接部署，也方便继续扩展自定义命令、关键词回复、活动入口和业务通知。
暂无评论内容