Telegram Serverless: 直接在 Telegram 基础设施上运行 Bot 后端代码

Telegram Serverless 是一个允许开发者直接在 Telegram 的基础设施上运行 Telegram Bot 和 Mini App 后端代码的平台。通过利用快速、隔离的 V8 沙箱，该平台消除了开发者配置服务器、管理容器或手动处理扩展的需求。

核心架构与思维模型

Telegram Serverless 运行在一种代码在本地开发并同步到云端的模型上。开发者的工作流分为三个主要环境：

• 本地项目文件夹： 包含 JavaScript 模块，包括数据库模式（schema）和更新处理器（update handlers）。
• 云端： 托管已部署的模块和 Bot 的持久化 SQLite 数据库。
• tgcloud CLI： 作为将本地更改同步到云端的桥梁。

项目结构

Serverless 项目是一个受版本控制的标准文件夹，在运行时没有构建步骤或 node_modules。它由三个主要组件组成：

1. handlers/：Bot 的入口点。每个文件对应一种 Telegram 更新类型（例如，message.js 用于新消息，callback_query.js 用于按钮点击）。平台将更新路由到匹配处理器的默认导出函数。
2. lib/：在处理器之间共享的 JavaScript 模块。此目录支持子目录以实现更好的组织。
3. schema.js：位于项目根目录的单个文件，使用类型化的 DSL 定义数据库表。

数据库与模式管理

每个 Bot 都会获得一个专用的 SQLite 后端存储。该平台使用类似于 Drizzle 的 ORM 进行模式定义和查询，为熟悉 Drizzle 的开发者提供了熟悉的 API。

模式定义与迁移

表在 schema.js 中作为命名导出进行定义。平台将代码部署与数据迁移分开，以防止意外的数据丢失。工作流如下：

1. npx tgcloud push：上传更新后的 schema.js 但不修改数据库。
2. npx tgcloud migrate：计算模式与实时数据库之间的差异，并引导开发者应用更改。

迁移按风险等级分类：Safe（增量更改）、Warning（潜在的破坏性更改，如删除列）和 Manual（复杂的更改，如需要原始 SQL 的类型变更）。

数据库约束

值得注意的是，该平台在 PRAGMA foreign_keys 关闭的状态下运行。DSL 不支持外键，如果声明外键将会抛出错误。开发者必须在应用程序逻辑中强制执行引用完整性。

平台 SDK

在运行时，模块可以访问单个库：sdk。该 SDK 提供三个核心能力：

• db：用于与 SQLite 数据库交互的查询构建器和模式 DSL。
• api：直接访问 Telegram Bot API 的接口。它解包了标准的响应封装，直接返回 result，并在返回 ok: false 时抛出 BotApiError。
• fetch：用于向第三方 API 发送出站 HTTP 请求的类 fetch 客户端。它支持 AI API 响应的流式传输，但将总响应大小限制在 32 MB，且不支持二进制负载。

开发者工作流与 CLI

tgcloud CLI 管理 Bot 的生命周期。关键命令包括：

• login：使用来自 @BotFather 的 CLI 访问令牌将项目链接到 Bot。
• push：原子化地部署更改后的模块。如果另一个开发者部署了更新的版本，push 将被拒绝以防止覆盖工作。
• run：在平台运行本地文件而不进行部署，从而在测试逻辑时提供快速的内部循环。
• webhook sync：确保 Telegram webhook 配置正确，以便仅交付处理器已部署的更新类型。

社区洞察与考量

虽然技术能力非常广泛，但 Hacker News 上的社区讨论强调了几个尚未解决的问题和担忧：

• 资源限制： 用户询问了关于执行时间、存储和带宽的具体配额。
• 定价： 由于文档没有明确说明成本，人们对定价模型表现出了极大的好奇。
• 密钥管理： 开发者指出缺乏用于 API 密钥和凭据的显式密钥存储机制，这在传统的 VPS 设置中通常通过环境变量处理。
• 可访问性： 一些用户报告在 @BotFather 中还看不到 "Serverless" 选项，这表明该功能正在逐步推出。