Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
部署 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 在开机时启动机器人,并在崩溃时自动重启:
- 创建一个不能登录的系统用户,把代码复制到
/opt/mybot;Python 项目在该目录下创建虚拟环境并安装依赖。 - 把 Token 写入
/etc/mybot.env,内容为一行BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours,并用chmod 600限制访问权限。 - 创建 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 机器人托管方式
- Serverless 免费额度适合流量不大、处理时间短的 Webhook 机器人。
- 小型 VPS 最灵活:轮询、Webhook 都行,任何语言都能跑,还能在旁边部署数据库。
- 家用服务器或单板电脑可以运行轮询机器人,因为不需要入站连接;可用性取决于你家的供电和网络。
- 能保持进程常驻的容器平台可以托管轮询机器人;注意确认平台不会让空闲应用进入休眠。
任何托管环境下的 Webhook 要求
- 只支持 HTTPS,TLS 1.2 及以上;证书必须与域名匹配并提供完整证书链,或者通过
certificate上传自签名证书。 - 端口 443、80、88 或 8443;使用 IPv4(Webhook 不支持 IPv6);不支持重定向。
- 请求来自
149.154.160.0/20和91.108.4.0/22;Telegram 提示这些网段将来可能变化。 - 设置
secret_token(1–256 个字符,A-Z a-z 0-9 _ -),并校验X-Telegram-Bot-Api-Secret-Token请求头。
每次部署后,打开 Bot API Tester 中的 getWebhookInfo 看一看:pending_update_count 不断增长,或出现新的 last_error_message,说明 Telegram 无法推送更新。
环境变量、日志与自动重启
- Token:只放在环境变量或密钥存储中,绝不放进 Git、镜像或客户端代码。如果泄露,按 Telegram Bot Token 获取与管理教程中的方法撤销,并更新服务器上的配置。
- 日志:写到 stdout/stderr,交给 journald、Docker 或平台收集。不要记录完整的请求 URL,因为里面包含 Token。
- 重启:由进程守护(
Restart=always、--restart unless-stopped)处理崩溃。更新保存在 Telegram 服务端,直到被确认为止:用更大的offset调用getUpdates时,之前的更新就算确认了,所以重启后机器人只会收到未确认的更新。崩溃前的最后一批更新可能会收到两次,关键业务请按update_id去重。 - 频率限制:遇到
429 Too Many Requests时等待retry_after秒;详见 Telegram Bot API 限制。
部署检查清单
- Token 来自环境变量或密钥存储;在服务器上调用
getMe成功。 - 每个 Token 只有一个轮询实例,或者使用带
secret_token的 Webhook,二者不能并存。 - 进程在崩溃和重启后能自动恢复。
- 日志被收集,且不包含 Token。
- 单个更新出错只记录日志,不会导致进程退出;Webhook 处理程序尽快返回 2XX。
- 使用 Webhook 时,
getWebhookInfo显示的 URL 正确,且近期没有错误。 - 做实验时使用单独的测试机器人或 Telegram 测试服务器,不要动用生产环境的 Token。
部署常见问题排查
| 现象 | 原因及解决方法 |
|---|---|
409 Conflict: terminated by other getUpdates request | 有两个实例用同一个 Token 轮询(旧容器、你的电脑)。只保留一个。 |
提到 Webhook 处于启用状态的 409 Conflict | Webhook 仍然处于设置状态。轮询前先调用 deleteWebhook。 |
401 Unauthorized | Token 环境变量为空、填错或已被撤销。用 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 校验代码。