Telegram 无服务器平台

# Telegram 服务端无服务器化 来源：https://core.telegram.org/bots/serverless Telegram Serverless 让您可以为机器人和**Mini App** 的后端代码**直接在 Telegram 的基础设施上运行**——无需配置服务器、无需保持容器活动、无需考虑伸缩。您只需编写纯 JavaScript 模块，通过一条命令部署，Telegram 就会在一个快速、隔离的 V8 沙箱中运行它们，该沙箱紧邻 Bot API 和内置数据库。如果您曾经为了响应一个 `/start` 命令而将机器人连接到 VPS、云函数或托管面板，那么这部分工作您再也不需要做了。 **本页内容** - 为什么选择无服务器化 (https://core.telegram.org/bots/serverless#why-serverless) - 快速开始 (https://core.telegram.org/bots/serverless#getting-started) - 使用 AI 构建 (https://core.telegram.org/bots/serverless#building-with-ai) - 通过 BotFather 移动端操作 (https://core.telegram.org/bots/serverless#on-the-go-with-botfather) - 项目与模块 (https://core.telegram.org/bots/serverless#projects-and-modules) - 数据库 (https://core.telegram.org/bots/serverless#the-database) - SDK (https://core.telegram.org/bots/serverless#the-sdk) - CLI 参考 (https://core.telegram.org/bots/serverless#command-line-interface) ### https://core.telegram.org/bots/serverless#why-serverless ## 为什么选择无服务器化 一个 Telegram 机器人本质上是一个响应更新的程序。传统上，您必须将该程序托管在某个始终在线、可访问且安全的地方——并且要一直保持这种状态。Telegram Serverless 完全移除了这一层： - **无需基础设施。** 没有需要租用、修补或监控的机器。您的代码按需运行，并随着您的机器人自动伸缩。 - **开箱即用。** Telegram Bot API、基于 SQLite 的数据库以及出站 HTTP 请求，每个模块都自带可用——无需安装任何东西，也无需配置凭据。 - **快速且隔离的执行。** 每次调用都在一个轻量级的 V8 隔离环境中运行，紧邻 Telegram 自身的系统，因此对 Bot API 和数据库的调用快速且可靠。 - **真正的开发工作流。** 项目位于您机器上的一个文件夹中，受版本控制。您编辑文件，准确查看更改内容，原子化部署，并通过审阅的迁移来推进数据库 schema——就像您处理其他任何项目一样。 ### https://core.telegram.org/bots/serverless#the-mental-model ## 心智模型 您在**三个地方**工作，它们之间清晰对应： | 位置 | 内容 | |------|------| | 您的项目文件夹 | JavaScript 模块——schema、共享代码、更新处理函数 | | 云端 | 这些模块的已部署副本，加上您机器人的数据库 | | `tgcloud` CLI | 桥梁——显示差异并同步它们 | 您永远不需要 SSH 到任何东西。您在本地编辑文件，运行 `npx tgcloud push`，平台就会处理剩余部分。您机器人的流量由已部署的模块处理；您的数据库在调用之间持久保存。 一个项目只有三种代码： handlers/ # 入口点——每个 Telegram 更新类型一个文件 lib/ # 从任何地方导入的共享代码 schema.js # 您的数据库表 当更新到来时——一条消息、一个按钮点击、一个内联查询——Telegram 会将其路由到匹配的处理函数 (`handlers/message.js`、`handlers/callback_query.js` 等) 并调用其默认导出。该函数通过 SDK 与 Bot API 和数据库通信，然后返回。这就是整个循环。没有匹配处理函数的更新会被直接忽略，因此您只需添加需要的处理函数。 ### https://core.telegram.org/bots/serverless#quick-demo ## 快速演示 这是一个完整可运行的演示机器人。它会回复每条消息，并记住每个聊天中看到的消息数量。 `schema.js`: import { table, integer } from 'sdk/db'; export const counters = table('counters', { chatId: integer('chat_id').primaryKey(), seen: integer('seen').notNull().default(0), }); `handlers/message.js`: import { api, db } from 'sdk'; import { counters } from 'schema'; import { sql } from 'sdk/db'; export default async function (message) { const chatId = message.chat.id; // 插入计数器，如果该聊天已有记录则更新——并通过 .returning() 在同一语句中返回结果行。 const [row] = await db.insert(counters) .values({ chatId, seen: 1 }) .onConflictDoUpdate({ target: counters.chatId, set: { seen: sql`${counters.seen} + 1` } }) .returning() .run(); await api.sendMessage({ chat_id: chatId, text: `你好！我已经看到来自你的 ${row.seen} 条消息。`, }); } 部署它： npx tgcloud push # 上传模块 npx tgcloud migrate # 创建 `counters` 表 这就是一个带有持久状态的实时机器人，无需服务器。其中的所有内容——`api`、`db`、`table()` DSL——都在以下部分中描述。 Serverless 是 Telegram 机器人和 Mini Apps 的通用后端，而不是针对某类应用的模板。它非常适合： - **对话式 AI 机器人**：需要在数据库中存储每用户状态。 - **Mini App 后端**：存储用户数据并提供动态内容。 - **游戏和工具**：包括排行榜、测验等。 - **自动化和集成**：调用第三方 HTTP API 并将结果推入聊天。 ### https://core.telegram.org/bots/serverless#getting-started ## 快速开始 本教程将带您从一个空文件夹开始，最终得到一个能够响应消息并存储数据的实时机器人。它假设您已安装 Node.js 18 或更高版本，并且已通过 @BotFather 注册了一个机器人。最后，您将使用到日常所需的所有命令：`push`、`migrate`、`run` 和 `status`。 > **首先，开启 Serverless 功能。** 在 @BotFather 中，打开您的机器人 → **Serverless** 并启用它。这将为此机器人开启该功能，并解锁其 CLI 访问令牌、处理函数、库和数据库。 #### https://core.telegram.org/bots/serverless#1-create-a-project ### 1. 创建项目 最快的启动方式是使用项目创建器，它会生成项目结构并将 CLI 安装到其中： npm create @tgcloud/bot example_bot cd example_bot 参数是目标文件夹：传递 `.` 以在当前文件夹中生成，或传递任意路径。它也可以在已有文件夹中工作，且不会覆盖您已有的文件。 这将为您提供一个可直接编辑的项目： example_bot/ ├─ docs/ │ └─ tgcloud-sdk.md # SDK 参考（供您和 AI 工具使用） ├─ handlers/ │ └─ message.js # 入门消息处理函数（回显文本） ├─ lib/ # 您的共享模块放在这里（初始为空） ├─ AGENTS.md # AI 编程助手使用指南 ├─ package.json └─ schema.js # 您的数据库表 生成的文件是自文档化的——每个文件都包含注释示例，说明下一步可以做什么。CLI 作为本地开发依赖安装到项目中，因此您可以通过 `npx tgcloud <命令>` 运行它（`npx` 会在项目的 `node_modules` 中找到副本），或者通过生成器添加到 `package.json` 中的 `npm run` 快捷方式（`npm run deploy`、`npm run status`）。默认情况下，`PATH` 中没有全局的 `tgcloud`。您也可以全局安装它——`npm install -g @tgcloud/cli`——如果您更喜欢在任何地方直接键入 `tgcloud`。这在任何空文件夹中运行 `tgcloud init` 时很方便，也是 shell 制表符补全所需要的。无论哪种方式，您都会得到相同的项目。 #### https://core.telegram.org/bots/serverless#2-link-your-bot ### 2. 链接您的机器人 每个项目都绑定到一个机器人。使用 `login` 命令连接它们，该命令会要求您提供 CLI 访问令牌（@BotFather → 您的机器人 → Serverless → CLI Access → Access token——这是一个独立于机器人 API 令牌的令牌），并将其存储在本地： npx tgcloud login 令牌的形式为 `app:<...>`。CLI 将其保存在 `.tgcloud/` 中，该目录被 git 忽略，并且不会打印秘密部分。登录是唯一一次要求您提供令牌的时间——有关如何在 CI 中解析令牌，请参见认证部分。 #### https://core.telegram.org/bots/serverless#3-look-around ### 3. 查看情况 两个命令可以随时告诉您当前的状态，它们完全离线工作： npx tgcloud status # 本地与已部署副本之间发生了什么变化 npx tgcloud diff # 逐行变化 刚执行 `init` 后，所有内容都是新的，尚未部署。`status` 会显示等待上传的入门文件。 #### https://core.telegram.org/bots/serverless#4-deploy ### 4. 部署 将您的模块发送到云端： npx tgcloud push `push` 会以原子批量的方式上传每个已更改的模块，并更新您本地的云端内容记录。您的机器人现在已上线：在 Telegram 中打开它并向其发送一条消息——入门处理函数会将其回显回来。 > **部署绝不会触及您的数据库。** 推送代码和更改数据库 schema 是有意分开的步骤，因此代码部署永远不会让您意外地执行数据迁移。这就是下一步要做的。 #### https://core.telegram.org/bots/serverless#5-add-a-database-table ### 5. 添加数据库表 让机器人记住一些东西。打开 `schema.js` 并声明一个表： import { table, integer, text, sql } from 'sdk/db'; export const messages = table('messages', { id: integer('id').primaryKey({ autoIncrement: true }), chatId: integer('chat_id').notNull(), text: text('text'), created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`), }); 部署 schema，然后将其应用到数据库： npx tgcloud push # 上传新的 schema.js npx tgcloud migrate # 创建 `messages` 表 `push` 会报告 schema 不同步并显示待定更改，但不会应用任何内容。`migrate` 会引导您完成更改，并在您确认后创建表。这种两步模型——以及对于删除等风险较高的更改会发生什么——在迁移部分中有详细说明。 #### https://core.telegram.org/bots/serverless#6-store-and-read-data ### 6. 存储和读取数据 现在在处理函数中使用这个表。编辑 `handlers/message.js`： import { api, db } from 'sdk'; import { messages } from 'schema'; import { eq } from 'sdk/db'; export default async function (message) { // 保存这条消息。 await db.insert(messages) .values({ chatId: message.chat.id, text: message.text }) .run(); // 统计我们为该聊天存储了多少条消息。 const count = await db.$count(messages, eq(messages.chatId, message.chat.id)); await api.sendMessage({ chat_id: message.chat.id, text: `已保存。目前共收到来自此聊天的 ${count} 条消息。`, }); } 使用 `npx tgcloud push` 部署更新后的处理函数，然后向您的机器人发送几条消息，观察计数值增长。数据库在调用之间保持持久化——这就是您机器人的记忆。 #### https://core.telegram.org/bots/serverless#7-test-without-deploying ### 7. 无需部署的测试 您无需部署即可尝试更改。`npx tgcloud run` 会使用您的**本地**文件在平台上执行一个处理函数，而无需发布它们： npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }' 参数是您的处理函数接收的负载——对于 `handlers/message`，是一个消息对象——以 JSON5 格式编写（因此您可以省略键的引号）。该命令会打印处理函数通过 `console.*` 记录的任何内容、返回值以及耗时。这是迭代逻辑的最快循环——无需部署，无需等待真实消息。 #### https://core.telegram.org/bots/serverless#8-keep-in-sync ### 8. 保持同步 在您工作时，少数几个命令可以保持本地项目和云端同步：`npx tgcloud status` 显示更改内容、`npx tgcloud push` 部署、`npx tgcloud pull` 使本地项目与云端一致、`npx tgcloud fetch` 刷新参考副本而不触及您的文件、`npx tgcloud reset` 放弃本地更改。 > 如果两个人（或两台机器）部署到同一个机器人，平台会检测到冲突，`push` 会停止，让您先执行 `pull`——您永远不会静默覆盖他人的工作。请参见保持同步。 ### https://core.telegram.org/bots/serverless#building-with-ai ## 使用 AI 构建 更喜欢用 AI 助手来构建——或者您的团队中唯一的程序员就是 AI？您仍然可以发布机器人。我们已经迈出了第一步，让 AI 代理在项目中感觉宾至如归：每个新项目都附带一个 `AGENTS.md` 和一个 `docs/tgcloud-sdk.md` 参考文件，供代理编程工具自动读取。再加上一个小巧、独立的运行时——一个 SDK，无需管理 npm 包——这为助手提供了一个良好的起点，以了解通用代码生成往往容易遗漏的约定：使用裸名称导入、没有外键、每个 `db` 调用都是异步的、每个更新类型对应一个处理函数、以及两步的 `push`/`migrate` 流程。 试试看： npm create @tgcloud/bot my-bot cd my-bot opencode # 或 Claude Code、Cursor ... 任何读取 AGENTS.md 的代理 然后直接用自然语言提问： > 编写一个机器人，记录每个人的待办事项清单——当他们发送文本时添加一个项目，当他们发送 /list 时显示整个清单。 助手会为您编辑 `schema.js` 和处理函数；您进行审查，使用 `npx tgcloud run` 立即测试更改，然后通过 `npx tgcloud push` 和 `npx tgcloud migrate` 上线。`AGENTS.md` 是您项目的一部分——随着机器人发展而编辑它，以确保指导保持准确。 ### https://core.telegram.org/bots/serverless#on-the-go-with-botfather ## 通过 BotFather 移动端操作 手里只有手机？整个项目也在 @BotFather 中——打开您的机器人 → **Serverless**，您就能在触摸屏上获得 CLI 管理的所有内容： - **处理函数**——创建、编辑和测试运行更新处理函数；BotFather 会根据您拥有的处理函数保持 webhook 同步（与 CLI 报告的“同步/不同步”相同）。 - **库**——您的共享 `lib/` 模块。 - **数据库**——以类似的 Drizzle 语法编辑 `schema.js`，审查待定更改，并应用它们；**保存**即部署。 - **CLI 访问**——当您回到键盘时，可以在这里获取 CLI 访问令牌。 它与云端项目是同一个，因此您可以在手机上创建一个处理函数，稍后在笔记本电脑上通过 `npx tgcloud pull` 拉取——不与特定客户端绑定。运行处理函数甚至会在聊天中直接显示其**控制台**输出，就像 `npx tgcloud run` 一样。 ### https://core.telegram.org/bots/serverless#projects-and-modules ## 项目与模块 一个 Serverless 项目是一个受版本控制的普通文件夹。它只包含 JavaScript 模块和一些本地状态——没有构建步骤、运行时没有 `node_modules`、也没有服务器入口点。 #### https://core.telegram.org/bots/serverless#anatomy-of-a-project ### 项目结构 example_bot/ ├─ handlers/ # 更新处理函数——扁平结构，仅一层 │ ├─ message.js │ └─ callback_query.js ├─ lib/ # 共享模块；允许子目录 │ ├─ reply.js │ └─ internal/util.js ├─ schema.js # 数据库 schema——单个文件，位于根目录 └─ .tgcloud/ # CLI 状态——凭据、快照、缓存（git 忽略） 只有 `schema.js` 以及 `lib/` 和 `handlers/` 下的 `.js` 文件会被**部署**。其他所有内容——Markdown、配置文件、`.tgcloud/` 文件夹——都留在您的机器上。 - **`schema.js`**——您的数据库。它使用 schema DSL 以命名导出的方式声明表，并作为单个文件位于项目根目录。它像其他任何模块一样被部署，但部署它绝不会更改数据库——schema 更改通过 `npx tgcloud migrate` 单独应用。请参见数据库部分。 - **`lib/`**——共享代码，任何您希望跨处理函数重用的内容：纯辅助函数、数据库访问层、格式化、与外部服务的集成。`lib/` 是唯一可以包含**子目录**的目录（`lib/internal/util.js`、`lib/payments/stripe.js`），因此您可以根据需要