Telegram Bot API

Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案

· 9 分钟阅读

部署 Telegram 机器人,就是把代码放到一台始终在线、能访问 api.telegram.org 的机器上运行,再选择接收更新的方式:用 getUpdates 长轮询(任何服务器都行,不需要域名),或者用 Webhook(需要公网 HTTPS URL)。轮询机器人通常部署在装有 systemd 的小型 VPS 或 Docker 容器中;Cloudflare Workers 等 Serverless 平台则适合 Webhook 机器人。本文给出每种方案可直接复制的配置,并介绍日志、自动重启和上线检查清单。

服务器上用轮询还是 Webhook

Telegram 提供两种互斥的更新接收方式,无论哪种,未送达的更新最多保存 24 小时。选哪种决定了你的机器人托管环境需要满足什么条件:

长轮询(getUpdates)Webhook(setWebhook)
网络只需出站 HTTPS;NAT 后面也能运行公网 HTTPS URL,端口 443、80、88 或 8443,IPv4
进程长期运行的循环HTTP 处理程序;可以是 Serverless
实例数每个 Token 只能一个同一个 URL 后面可以有多个
适合的托管VPS、Docker、家用服务器带反向代理的 VPS、Cloudflare Workers、AWS Lambda、Vercel

如果轮询在你的机器上已经跑得很好,就继续用它:Telegram 官方的 Webhook 指南也说,使用 getUpdates 没有任何问题。只有当平台要求,或者需要多个实例分担负载时,再改用 Webhook。

一个可直接部署的轮询机器人

适合生产环境的代码要做到三点:从环境变量读取 Token,日志输出到 stdout,遇到网络错误不崩溃。下面这个回声机器人三点都做到了,并在启动时调用 deleteWebhook,因为设置了 Webhook 时 getUpdates 无法使用:

import logging
import os
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")

TOKEN = os.environ["BOT_TOKEN"]  # 不要把 Token 写死在代码里
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def main():
    call("deleteWebhook")  # 轮询和 Webhook 互斥
    log.info("started as @%s", call("getMe")["username"])
    offset = 0
    while True:
        try:
            updates = call("getUpdates", offset=offset, timeout=30)
        except Exception:
            log.exception("getUpdates failed, retrying in 5 s")
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            msg = update.get("message")
            if msg and "text" in msg:
                try:
                    call("sendMessage", chat_id=msg["chat"]["id"], text="回声:" + msg["text"])
                except Exception:
                    log.exception("update %s failed", update["update_id"])


if __name__ == "__main__":
    main()
const TOKEN = process.env.BOT_TOKEN; // 不要把 Token 写死在代码里
if (!TOKEN) throw new Error("BOT_TOKEN is not set");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

await call("deleteWebhook"); // 轮询和 Webhook 互斥
log("started as @" + (await call("getMe")).username);

let offset = 0;
while (true) {
  let updates;
  try {
    updates = await call("getUpdates", { offset, timeout: 30 });
  } catch (err) {
    log("getUpdates failed, retrying in 5 s:", err.message);
    await sleep(5000);
    continue;
  }
  for (const update of updates) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (!msg?.text) continue;
    try {
      await call("sendMessage", { chat_id: msg.chat.id, text: "回声:" + msg.text });
    } catch (err) {
      log(`update ${update.update_id} failed:`, err.message);
    }
  }
}

分别保存为 bot.py(在 requirements.txt 中写上 requests)或 bot.mjs(Node.js 18+,无依赖)。常用库列表中的框架会替你处理轮询循环,但下面的部署步骤完全一样。

用 systemd 在 VPS 上运行 Telegram 机器人

VPS 就是一台普通的 Linux 机器。让 systemd 在开机时启动机器人,并在崩溃时自动重启:

  1. 创建一个不能登录的系统用户,把代码复制到 /opt/mybot;Python 项目在该目录下创建虚拟环境并安装依赖。
  2. 把 Token 写入 /etc/mybot.env,内容为一行 BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours,并用 chmod 600 限制访问权限。
  3. 创建 unit 文件 /etc/systemd/system/mybot.service:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用服务并查看日志:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f        # 实时日志
sudo systemctl restart mybot  # 更新代码后重启

如果要在同一台 VPS 上使用 Webhook,就让机器人作为 HTTP 服务监听本地端口,前面放 nginx 或 Caddy 在 443 端口处理 TLS;带 secret token 校验的处理程序见 Webhook 设置教程。

用 Docker 部署 Telegram 机器人

容器把运行时和依赖打包在一起,机器人在你的电脑上和任何 Docker 主机上的表现都一致。Python 机器人的 Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]

构建并运行,Token 在运行时传入,绝不打包进镜像:

docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot

--restart unless-stopped 让机器人在崩溃和主机重启后自动恢复。.env 不要放进 Git,也不要放进镜像(把它加入 .dockerignore)。重新部署轮询机器人时,先停掉旧容器再启动新容器:两个容器用同一个 Token 轮询,getUpdates 会返回 409 Conflict。

Serverless:在 Cloudflare Workers 上运行 Telegram 机器人

Serverless 平台只在收到请求时才运行代码,因此必须使用 Webhook 模式。在 Cloudflare Workers 上,默认的 workers.dev 地址本身就在 443 端口提供 HTTPS。下面的 Worker 校验 secret token 请求头,立即返回响应,再用 ctx.waitUntil 在后台完成处理:

// worker.js:用 "npx wrangler deploy" 部署
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
      return new Response("Not found", { status: 404 });
    }
    const enc = new TextEncoder();
    const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
    const expected = enc.encode(env.WEBHOOK_SECRET);
    if (received.byteLength !== expected.byteLength ||
        !crypto.subtle.timingSafeEqual(received, expected)) {
      return new Response("Forbidden", { status: 403 });
    }
    const update = await request.json();
    ctx.waitUntil(handleUpdate(update, env)); // 先返回 200,再继续处理
    return new Response("OK");
  },
};

async function handleUpdate(update, env) {
  const msg = update.message;
  if (!msg?.text) return;
  const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: msg.chat.id, text: "回声:" + msg.text }),
  });
  if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}

把两个值都保存为 Worker secret,部署后用同一个 secret 注册 Worker 的 URL:

npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'

也可以在 Bot API Tester 的 setWebhook 中填写参数。同样的思路也适用于 AWS Lambda(通过 HTTPS 函数 URL 或 API Gateway 暴露)和 Vercel Functions:解析 JSON 请求体,校验请求头,尽快返回 2XX。各平台都会限制函数及其后台任务的运行时长,耗时任务请交给队列处理。Telegram 会重试所有非 2XX 响应,所以超时或崩溃的函数会再次收到同一个更新。

免费和低成本的 Telegram 机器人托管方式

任何托管环境下的 Webhook 要求

每次部署后,打开 Bot API Tester 中的 getWebhookInfo 看一看:pending_update_count 不断增长,或出现新的 last_error_message,说明 Telegram 无法推送更新。

环境变量、日志与自动重启

部署检查清单

  1. Token 来自环境变量或密钥存储;在服务器上调用 getMe 成功。
  2. 每个 Token 只有一个轮询实例,或者使用带 secret_token 的 Webhook,二者不能并存。
  3. 进程在崩溃和重启后能自动恢复。
  4. 日志被收集,且不包含 Token。
  5. 单个更新出错只记录日志,不会导致进程退出;Webhook 处理程序尽快返回 2XX。
  6. 使用 Webhook 时,getWebhookInfo 显示的 URL 正确,且近期没有错误。
  7. 做实验时使用单独的测试机器人或 Telegram 测试服务器,不要动用生产环境的 Token。

部署常见问题排查

现象原因及解决方法
409 Conflict: terminated by other getUpdates request有两个实例用同一个 Token 轮询(旧容器、你的电脑)。只保留一个。
提到 Webhook 处于启用状态的 409 ConflictWebhook 仍然处于设置状态。轮询前先调用 deleteWebhook。
401 UnauthorizedToken 环境变量为空、填错或已被撤销。用 getMe 检查。
本地正常,服务器上没有任何反应到 api.telegram.org 的出站 HTTPS 被拦截,或者环境变量文件没有加载。查看日志。
Webhook 机器人收不到任何更新查看 getWebhookInfo 中的 last_error_message:TLS 问题、端口不对、secret 不一致导致的 403,或者处理程序崩溃。

刚开始接触机器人?请先阅读创建 Telegram 机器人教程,再回来部署。

常见问题

Telegram 机器人可以部署在哪里?

任何能发起出站 HTTPS 请求的地方都可以:VPS、Docker 主机、家用服务器或 Serverless 平台。使用 getUpdates 的机器人不需要公网地址;使用 Webhook 的机器人需要一个端口为 443、80、88 或 8443 的公网 HTTPS URL。

部署后的机器人该用轮询还是 Webhook?

两种方式都能用于生产环境。在 VPS 或 Docker 上,用 getUpdates 长轮询最简单,不需要域名和证书。Serverless 平台只在收到请求时才运行代码,所以必须使用 Webhook。

部署机器人后为什么出现 409 Conflict?

要么机器人用 getUpdates 轮询时 Webhook 仍然处于设置状态(调用 deleteWebhook),要么有两个机器人实例在同时轮询,例如部署过程中新旧两个容器,或者你的电脑和服务器。每个 Token 只能运行一个轮询实例。

怎样让 Telegram 机器人 7×24 小时运行?

用进程守护工具运行,让它在崩溃和重启后自动拉起:VPS 上用带 Restart=always 的 systemd 服务,或者用带 --restart unless-stopped 的 Docker 容器。日志输出到 stdout,用 journalctl 或 docker logs 查看。

Telegram 机器人能跑在 Cloudflare Workers 上吗?

可以,使用 Webhook 模式。Worker 以 POST 请求的形式接收每个更新,校验 X-Telegram-Bot-Api-Secret-Token 请求头,再用 fetch 调用 Bot API。用 setWebhook 注册它的 workers.dev HTTPS 地址即可。长轮询循环不适合这种运行模式。

服务器上的机器人 Token 应该存在哪里?

放在环境变量中,从只有机器人用户能读取的文件加载,或者放进平台的密钥存储(例如 Worker secret)。绝不要把 Token 提交到 Git 或打包进 Docker 镜像。一旦泄露,立即在 @BotFather 中撤销。

Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息

Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。

Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等

Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。

Telegram Bot API 错误码大全:每种报错的含义与解决方法

Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。

Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度

Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。

Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接

Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。

Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘

Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。

n8n Telegram 集成教程:连接机器人、触发工作流并发送消息

n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。

Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理

Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。

Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token

Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。

Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token

Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。

Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID

Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。

Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询

Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。

Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅

Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。

Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人

Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。

Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮

在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。

TelegramWidget JavaScript API:属性、事件、错误码与限制参考

TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。

Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码

可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。

Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML

Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。

Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端

Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。