Telegram机器人平台

电报机器人平台+MCP服务器

此存储库包含：

• Telegram机器人平台 --客户端机器人+WebApp（注册、登录、电报ID恢复）。部署到 /www/wwwroot/telegrambot/ybrjch.qgsm.store.
• MCP服务器 --可选附加组件（订单、服务、提供商、管理员聊天）。单独出售；核心产品并不依赖于它。

Telegram机器人平台（客户端）

具有WebApp注册/认证和安全恢复功能的生产就绪Telegram Bot。为商业分发而构建（Docker Compose、备份/恢复、安装程序占位符、许可证挂钩）。

回购布局

• app/ -节点（Telegraf+Fastify）客户端机器人程序+WebApp+API
• migrations/ --SQL迁移
• docker/ --Dockerfiles和compose
• scripts/ --安装、备份.sh、还原器。
• README.md --这个文件

目标目录（VPS）

同一存储库在两个目录中展开。每个人都有自己的 .env （自己的） BOT_TOKEN, WEBAPP_BASE_URL）和必要时自己的港口（客户3000，管理员3001）。

路径

• Webhook： /telegram-webhook
• WebApp： /webapp/register, /webapp/login, /webapp/recover
• API /api/*

设置

1. 环境

   复制

   cp app/.env.example .env
   # Edit: BOT_TOKEN, WEBAPP_BASE_URL, ADMIN_IDS, DATABASE_URL (or POSTGRES_PASSWORD for Docker)
   

2. 使用Docker Compose运行

   复制

   docker compose -f docker-compose.telegram.yml up -d --build
   

   迁移在容器启动时运行。

3. 或者安装脚本（提示输入env、创建.env、启动容器、打印webhook命令）

   复制

   ./scripts/install.sh
   

4. 设置Telegram webhook

   复制

   https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=https://ybrjch.qgsm.store/telegram-webhook
   

Nginx（aaPanel）

代理到 http://127.0.0.1:3000:

• / → http://127.0.0.1:3000
• /webapp/* → http://127.0.0.1:3000
• /telegram-webhook → http://127.0.0.1:3000

普通HTTP（不需要websocket/SSE）。HTTPS正在生产中。

备份和恢复

• 备份 （将Postgres转储到 ./backups/<date>.sql.gz):

  复制

  ./scripts/backup.sh
  # Or: ./scripts/backup.sh /path/to/dir
  

• 恢复 （来自a .sql.gz 档案；删除公共架构，然后恢复）：

  复制

  ./scripts/restore.sh ./backups/telegram_bot_YYYYMMDD_HHMMSS.sql.gz
  

  如果需要，请重新运行迁移：
  docker compose -f docker-compose.telegram.yml run --rm telegram-bot node dist/db/migrate.js

下载到VPS（进入战斗目录）

在VPS上，我们展开两个文件夹进行实时测试：

1. 在VPS上创建目录 （如果没有）：

   复制

   sudo mkdir -p /www/wwwroot/telegrambot/ybrjch.qgsm.store
   sudo mkdir -p /www/wwwroot/telegrambot/jqidyrb.qgsm.store
   sudo chown "$USER:$USER" /www/wwwroot/telegrambot/ybrjch.qgsm.store
   sudo chown "$USER:$USER" /www/wwwroot/telegrambot/jqidyrb.qgsm.store
   

2. 下载项目 （一个选项）：

   • Git （如果服务器上有回购）：
     复制

     cd /www/wwwroot/telegrambot/ybrjch.qgsm.store && git clone <URL_репо> .   # клиент
     cd /www/wwwroot/telegrambot/jqidyrb.qgsm.store && git clone <URL_репо> .   # админ
     

   • 手动装货：复制回购内容（文件夹） app/, docker/, migrations/, scripts/, docker-compose.telegram.yml 等等。D.其他事项）在两个目录中（通过SCP、RSYNC或AAPanel→File窗格）。

3. 在每个目录 创建 .env 运行：

   • 客户 (ybrjch.qgsm.store): WEBAPP_BASE_URL=https://ybrjch.qgsm.store港口 3000自己的 BOT_TOKEN.
   • 管理员 (jqidyrb.qgsm.store): WEBAPP_BASE_URL=https://jqidyrb.qgsm.store在Compose中指定端口 3001 （不与客户发生冲突） BOT_TOKEN. 然后在每个文件夹中： docker compose -f docker-compose.telegram.yml up -d --build.

4. 在 aaPanel 配置两个站点： ybrjch.qgsm.store → 代理на 127.0.0.1:3000, jqidyrb.qgsm.store → 代理на 127.0.0.1:3001SSL（Let’s Encrypt）

5. 网络钩子 对于每个机器人：

   • 客户： https://api.telegram.org/bot<CLIENT_TOKEN>/setWebhook?url=https://ybrjch.qgsm.store/telegram-webhook
   • 管理员： https://api.telegram.org/bot<ADMIN_TOKEN>/setWebhook?url=https://jqidyrb.qgsm.store/telegram-webhook

迁移到新的VPS

1. 在新的VPS上：安装Docker、克隆仓库、复制 .env.
2. 还原：运行 ./scripts/restore.sh <backup.sql.gz> （DB正在运行或使用 DATABASE_URL).
3. 开始： docker compose -f docker-compose.telegram.yml up -d.
4. 将域和webhook指向新主机。

Env（电报平台）

测试计划

1. /以新用户身份启动 → 按钮«Регистрация»→ 注册流程（姓名、电话、PIN）→ 用户行已创建。
2. /以现有用户身份启动 →Button“登入”→Profile Shown（“您已注册”+name，masked phone，recovered flag）。
3. 恢复 --管理员运行 /issue_recovery <new_tg_id> → open /recover?token=... → 请求OTP（中立消息）→ 验证OTP→ 验证PIN→ tg_id 更新， tg_id_prev 保存， recovered_flag 确实如此。
4. 使用错误的手机进行恢复 --流量相同；必须显示相同的中性信息；审核日志显示 recovery_phone_not_found.
5. 洪水 --与 FLOOD_PROTECTION_ENABLED=false：垃圾邮件仅触发审核(flood_suspected).启用后：用户收到一条阻止消息，然后进一步的更新仅为ACK（无回复）；机器人还活着。

WebApp安全模型

• 仅限电报 --WebApp只能在Telegram内部运行。开场 /webapp/* 或致电 /api/* 从正常浏览器返回 403 （或API调用失败），因为有效的Telegram WebApp initData 是API所必需的，并且 /webapp/* 只有当请求来自Telegram的WebView（用户代理检查）或具有有效的initData时，才会提供HTML。
• 直接浏览器访问被阻止 --开幕式 https://domain/webapp/register 在正常浏览器中返回403。从Telegram应用程序（WebApp按钮）打开相同的URL是有效的。
• 会话绑定到Telegram用户 --验证Telegram后 initData，服务器将会话绑定到 tg_id对于注册和登录， session.tg_id 必须等于已验证的Telegram用户id；否则，请求是 401未经授权。被盗的会话链接不能被其他Telegram用户使用。
• 恢复令牌绑定到新的tg_id --恢复令牌是为特定对象发放的 bound_tg_id。每个恢复端点都会检查验证的Telegram用户id是否等于 recovery_tokens.bound_tg_id否则 401。不能使用其他帐户中被盗的令牌滥用恢复。
• 速率限制 --轻量级内存速率限制适用于所有 /api/* 路由：对于一般端点，每个用户每分钟60个请求，对于恢复端点，每分钟20个请求。超额回报 429请求太多 并接受审计(rate_limit_exceeded).

MCP服务器（可选附加组件）

Telegram Bot项目的生产就绪MCP服务器。为订单、服务、供应商、管理员提供MCP工具；内部管理员聊天；通过OpenAI API的LLM（可选Ollama回退）；承载认证；利率限制；审计日志。

技术栈

• Node.js 20 +TypeScript
• 禁食 （选择性能、原生TypeScript、内置模式验证）
• PostgreSQL + 瑞迪斯
• MCP-SDK （可流式传输HTTP+stdio）
• 开放人工智能 API（默认）；可选的 奥拉玛 作为OpenAI回退的首选
• Docker Compose + 引擎X + 系统守护进程

VPS文件系统和外壳工具（MCP）

如果MCP服务器在VPS上运行，则Cursor可用于有限目录中的文件和命令：

tool描述 |------|----------| | vps_fs_list –显示文件/文件夹（相对于数据库或下面的路径）。 | | vps_fs_copy 复制文件或目录。 | | vps_fs_move 移动（重命名）文件或目录。 | | vps_shell_exec 执行shell命令（例如 ls -la, cp -r MCP ybrjch.qgsm.store, docker compose up -d).默认超时60秒。 |

所有路径都受限于基本目录 VPS_FS_BASE_PATH （默认） /www/wwwroot/telegrambot).要使MCP容器在主机上看到此文件夹，请在 docker-compose.yml 服务 mcp 连接Volume：

volumes:
  - ${VPS_FS_MOUNT_PATH:-/www/wwwroot/telegrambot}:/www/wwwroot/telegrambot

环境变量（可选）： VPS_FS_BASE_PATH, VPS_FS_MOUNT_PATH （安装主机的路径） VPS_SHELL_TIMEOUT_SEC （超时） vps_shell_exec默认为60）。

项目结构

MCP/
├── src/
│   ├── config.ts           # Env config, secret masking
│   ├── logger.ts           # Pino, token masking
│   ├── index.ts            # HTTP Fastify app + MCP /mcp
│   ├── stdio-entry.ts      # Stdio entry for Cursor
│   ├── mcp/
│   │   └── server.ts       # McpServer + tools
│   ├── tools/
│   │   ├── index.ts        # Tool handlers
│   │   └── vpsFs.ts        # VPS fs list/copy/move, shell exec
│   ├── llm/
│   │   └── router.ts       # OpenAI / Ollama+fallback
│   ├── db/
│   │   ├── client.ts       # pg pool
│   │   └── migrate.ts      # Migrations
│   ├── redis/
│   │   └── client.ts       # ioredis
│   └── middleware/
│       ├── auth.ts         # Bearer auth
│       ├── rateLimit.ts    # Redis rate limit
│       └── audit.ts        # Audit logging
├── app/                    # Telegram Bot Platform
│   ├── src/
│   │   ├── bot/            # Telegraf, start, issue_recovery, flood
│   │   ├── routes/         # API + webapp
│   │   ├── api/            # register, login, recover
│   │   ├── services/       # flood
│   │   ├── db/             # client, users, authSessions, etc.
│   │   └── ...
│   └── public/             # WebApp HTML/JS
├── migrations/             # Telegram platform SQL
├── docker/
├── docker-compose.yml      # MCP
├── docker-compose.telegram.yml
├── scripts/
│   ├── install.sh         # Telegram platform installer
│   ├── backup.sh
│   └── restore.sh
├── .env.example
└── README.md

（以下是原始README中的其他MCP部分，用于快速入门、部署、端点、环境等）