Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг
Чтобы задеплоить Telegram-бота, запустите его код на машине, которая работает круглосуточно и видит api.telegram.org, и выберите способ получения апдейтов: long polling через getUpdates — работает на любом сервере без домена — или вебхук, которому нужен публичный HTTPS-URL. Для бота на polling обычно берут небольшой VPS с systemd или Docker-контейнер; для бота на вебхуке подходят serverless-платформы вроде Cloudflare Workers. В этом гайде — каждый вариант с готовыми конфигами, а также логи, перезапуски и чек-лист перед запуском.
Polling или вебхук на сервере
У Telegram два взаимоисключающих способа получать апдейты, и в обоих случаях недоставленные апдейты хранятся не дольше 24 часов. От выбора зависит, какой хостинг нужен телеграм-боту:
Long polling (getUpdates) | Вебхук (setWebhook) | |
|---|---|---|
| Сеть | Только исходящий HTTPS; работает за NAT | Публичный HTTPS-URL, порты 443, 80, 88 или 8443, IPv4 |
| Процесс | Постоянно работающий цикл | HTTP-обработчик; может быть serverless |
| Экземпляры | Ровно один на токен | Можно несколько за одним URL |
| Где запускать | VPS, Docker, домашний сервер | VPS с reverse proxy, Cloudflare Workers, AWS Lambda, Vercel |
Если polling у вас уже работает, оставьте его: в официальном гайде по вебхукам Telegram прямо пишет, что в getUpdates нет ничего плохого. Переходите на вебхук, когда этого требует платформа или нужно распределить нагрузку между несколькими экземплярами.
Бот на polling, готовый к деплою
Код для продакшена должен делать три вещи: читать токен из переменной окружения, писать логи в stdout и переживать сетевые ошибки, а не падать. Этот эхо-бот делает всё это и при старте вызывает deleteWebhook, потому что 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"] # никогда не пишите токен в коде
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") # polling и вебхук взаимоисключающие
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="Echo: " + msg["text"])
except Exception:
log.exception("update %s failed", update["update_id"])
if __name__ == "__main__":
main()const TOKEN = process.env.BOT_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"); // polling и вебхук взаимоисключающие
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: "Echo: " + msg.text });
} catch (err) {
log(`update ${update.update_id} failed:`, err.message);
}
}
}Сохраните код как bot.py (с requests в requirements.txt) или bot.mjs (Node.js 18+, без зависимостей). Фреймворки из списка библиотек берут цикл на себя, но шаги деплоя ниже остаются теми же.
Телеграм-бот на VPS с systemd
VPS — это обычная Linux-машина. Пусть systemd запускает бота при загрузке и перезапускает после падения:
- Создайте пользователя без права входа и скопируйте код в
/opt/mybot; для Python создайте там виртуальное окружение и установите зависимости. - Запишите токен в
/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 запустите бота как HTTP-сервер на локальном порту и поставьте перед ним nginx или Caddy, который терминирует TLS на порту 443; обработчик с проверкой секретного токена есть в гайде по вебхукам.
Деплой Telegram-бота в Docker
Контейнер упаковывает рантайм и зависимости, поэтому бот одинаково работает на ноутбуке и на любом Docker-хосте. Dockerfile для бота на Python:
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"]
Соберите и запустите образ, передав токен при запуске, а не зашив его в образ:
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). При передеплое бота на polling сначала остановите старый контейнер и только потом запускайте новый: два контейнера с одним токеном приводят к ошибке 409 Conflict в getUpdates.
Serverless: телеграм-бот на Cloudflare Workers
Serverless-платформы запускают код только при входящем запросе, поэтому им нужен вебхук. На Cloudflare Workers стандартный адрес workers.dev уже отдаёт HTTPS на порту 443. Этот Worker проверяет заголовок с секретным токеном, сразу отвечает и доделывает работу в фоне через 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: "Echo: " + msg.text }),
});
if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}
Сохраните оба значения как секреты 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"}'
Или заполните форму setWebhook в Bot API Tester. Та же схема работает на AWS Lambda (за HTTPS function URL или API Gateway) и в функциях Vercel: разобрать JSON-тело, проверить заголовок, быстро вернуть 2XX. Платформы ограничивают время работы функции и фоновых задач, поэтому долгую работу выносите в очередь. Telegram повторяет запрос при любом ответе, отличном от 2XX, так что функция, которая упала или не уложилась во время, получит тот же апдейт ещё раз.
Бесплатный и недорогой хостинг для телеграм-бота
- Бесплатные тарифы serverless подходят ботам на вебхуке с умеренным трафиком и короткими обработчиками.
- Небольшой VPS — самый гибкий вариант: polling или вебхук, любой язык, база данных рядом с ботом.
- Домашний сервер или одноплатный компьютер подойдёт для polling, потому что входящие соединения не нужны; аптайм зависит от вашего электричества и интернета.
- Контейнерные платформы, которые держат процесс запущенным, справятся с ботом на polling; проверьте, что они не усыпляют простаивающие приложения.
Требования к вебхуку на любом хостинге
- Только HTTPS, TLS 1.2 или новее, сертификат на ваш домен с полной цепочкой — или самоподписанный сертификат, загруженный через
certificate. - Порты 443, 80, 88 или 8443; IPv4 (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.
После каждого деплоя открывайте getWebhookInfo в Bot API Tester: растущий pending_update_count или свежий last_error_message означают, что Telegram не может доставить апдейты.
Переменные окружения, логи и перезапуски
- Токен: только в переменной окружения или хранилище секретов — никогда в Git, образах или клиентском коде. Если он утёк, отзовите его, как описано в гайде по токену бота, и обновите сервер.
- Логи: пишите в stdout/stderr, а собирают их journald, Docker или платформа. Не логируйте полные URL запросов: в них есть токен.
- Перезапуски: падения обрабатывает супервизор (
Restart=always,--restart unless-stopped). Telegram хранит апдейты на своей стороне, пока они не подтверждены: апдейт подтверждается, как толькоgetUpdatesвызван с большимoffset, поэтому после перезапуска бот получает только неподтверждённые. Последняя пачка перед падением может прийти повторно — где это важно, отсеивайте дубли поupdate_id. - Лимиты: на
429 Too Many Requestsждитеretry_afterсекунд; подробнее — в гайде лимиты Telegram Bot API.
Чек-лист деплоя
- Токен берётся из переменной окружения или секрета;
getMeна сервере проходит успешно. - На один токен — ровно один экземпляр с polling или вебхук с
secret_token, но не то и другое сразу. - Процесс автоматически перезапускается после падений и перезагрузок.
- Логи собираются и не содержат токенов.
- Ошибка в одном апдейте логируется, а не роняет бота; обработчики вебхука быстро возвращают 2XX.
- Для вебхука
getWebhookInfoпоказывает правильный URL и нет свежих ошибок. - Для экспериментов используется отдельный тестовый бот или тестовый сервер Telegram, а не боевой токен.
Проблемы после деплоя
| Симптом | Причина и решение |
|---|---|
409 Conflict: terminated by other getUpdates request | С одним токеном опрашивают два экземпляра (старый контейнер, ваш ноутбук). Оставьте один. |
409 Conflict с упоминанием активного вебхука | Вебхук всё ещё установлен. Вызовите deleteWebhook перед polling. |
401 Unauthorized | Переменная с токеном пустая, с опечаткой или токен отозван. Проверьте его через getMe. |
| Локально работает, на сервере молчит | Исходящий HTTPS к api.telegram.org заблокирован или файл окружения не подгружается. Смотрите логи. |
| Бот на вебхуке ничего не получает | Смотрите last_error_message в getWebhookInfo: TLS, неверный порт, 403 из-за несовпадения секрета или падающий обработчик. |
Только начинаете? Сначала прочитайте, как создать бота в Telegram, а потом возвращайтесь к деплою.
Частые вопросы
Где разместить Telegram-бота?
На любой машине, которая может делать исходящие HTTPS-запросы: VPS, Docker-хост, домашний сервер или serverless-платформа. Боту на getUpdates публичный адрес не нужен; боту на вебхуке нужен публичный HTTPS-URL на порту 443, 80, 88 или 8443.
Что выбрать для бота на сервере: polling или вебхук?
В продакшене работают оба варианта. Long polling через getUpdates проще всего на VPS или в Docker: не нужны ни домен, ни сертификат. На serverless-платформах нужен вебхук, потому что код там запускается только при входящем запросе.
Почему после деплоя бот получает 409 Conflict?
Либо всё ещё установлен вебхук, а бот опрашивает getUpdates (вызовите deleteWebhook), либо одновременно работают две копии бота: например, старый и новый контейнер во время деплоя или ваш ноутбук и сервер. На один токен — ровно один экземпляр с polling.
Как сделать, чтобы бот работал 24/7?
Запускайте его под супервизором, который перезапустит процесс после падения и перезагрузки: сервис systemd с Restart=always на VPS или Docker-контейнер с --restart unless-stopped. Пишите логи в stdout и смотрите их через journalctl или docker logs.
Можно ли запустить Telegram-бота на Cloudflare Workers?
Да, в режиме вебхука. Worker получает каждый апдейт POST-запросом, проверяет заголовок X-Telegram-Bot-Api-Secret-Token и вызывает Bot API через fetch. Его HTTPS-адрес на workers.dev регистрируется через setWebhook. Цикл long polling в эту модель не вписывается.
Где хранить токен бота на сервере?
В переменной окружения, которая загружается из файла с доступом только для пользователя бота, или в хранилище секретов платформы (например, секрет Worker). Никогда не коммитьте токен в Git и не зашивайте в Docker-образ. Если токен утёк, отзовите его в @BotFather.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Ошибки 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 в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Команды Telegram-бота: setMyCommands, области видимости и deep link для /start
Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.
Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.
Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений
Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы
Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.
Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки
Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.