Jak hostować bota Telegraf 24/7 (Telegram, Node.js)

Aby hostować bota Telegraf 24/7, uruchamiasz go na maszynie, która stale działa: na VPS z Linuxem z usługą systemd, która uruchamia go ponownie po zatrzymaniu, albo w planie dla botów w PlayNHost (od 1,99 USD miesięcznie), gdzie panel instaluje twoje pakiety, przekazuje twojemu kodowi token i uruchamia bota ponownie, gdy ten się wywróci. W naszym teście bot na Telegraf 4.16.3 zużył ok. 60 MB pamięci na Node.js 22. bot.launch() w Telegraf domyślnie używa long pollingu, czego właśnie potrzebują nasze plany: nie mają jeszcze publicznego adresu HTTPS dla webhooka. Kroki w PlayNHost:

1. Na stronie hostingu botów Telegram kliknij Utwórz serwer przy wybranym planie. W oknie zamówienia na pytanie Na jaką platformę jest Twój bot? odpowiedz Telegram i wybierz Node.js.
2. Otwórz swój serwer w panelu. Karta Skonfiguruj swojego bota na stronie Przegląd otwiera się na Połącz z Telegramem; jej pierwszy krok, Co działa, powinien pokazywać Ten bot uruchamia Node.js Bot.
3. W kroku Połącz z Telegramem wklej token z @BotFather w polu Wklej token swojego bota, kliknij Połączenie, sprawdź wyświetloną nazwę bota i kliknij Tak, dalej.
4. W kroku Twój kod kliknij Prześlij pliki i prześlij package.json oraz index.js bez node_modules, albo kliknij Połącz Git.
5. Na stronie Bot, w panelu Kod, sprawdź, czy Plik startowy to plik, który uruchamia twojego bota (domyślnie index.js). Jeśli go zmienisz, kliknij Zapisz.
6. Kliknij Uruchom bota i otwórz Console. Przy pierwszym starcie npm instaluje Telegraf, potem bot wypisuje Logged in as @your_bot, a znacznik w sekcji Przegląd zmienia się na Online w Telegramie.
7. Na stronie Bot, w panelu Telegram, kliknij Otwórz w Telegramie i wyślij botowi /start.

Tworzenie bota w @BotFather i kroki w panelu opisuje Jak hostować bota Telegram. Ta strona dotyczy samego Telegrafa: czego używa na serwerze i co warto wiedzieć przed hostowaniem.

Co zmierzyliśmy

Jak: na naszym własnym węźle, w jednorazowym kontenerze skonfigurowanym jak plan bota 1 GB (obraz Node.js 22 i polecenie startowe naszego typu bota Node.js, z limitem pamięci Node na 80 procent), każdy bot wywołał Telegram z fałszywym tokenem, który Telegram odrzucił. Pamięć to pamięć rezydentna 15 sekund po tej odpowiedzi, czas startu liczymy od launch do odpowiedzi, a każda wartość to mediana uruchomień od 2 do 4.

To wartości minimalne: bot bez czatów i bez danych. Dochodzą do nich twój własny kod, to, co trzyma w pamięci, i liczba czatów, więc biblioteka to niewielka część 0,5 GB planu STARTER.

Minimalny bot Telegraf

Odpowiada na /start, czyta token, który daje mu panel, i wypisuje linię gotowości. Umieść oba pliki w głównym folderze bota.

package.json

{
  "name": "my-telegraf-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "telegraf": "^4.16.3"
  }
}

index.js

const { Telegraf } = require("telegraf");

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN);

bot.start((ctx) => ctx.reply("Hello! I am running on PlayNHost."));

// Without this, an error in one command stops the whole bot.
bot.catch((err, ctx) => {
  console.error(`Error while handling update ${ctx.update.update_id}:`, err);
});

// launch() only returns when the bot stops, so the ready line goes in its callback.
bot.launch(() => console.log(`Logged in as @${bot.botInfo.username}`)).catch((err) => {
  if (err.code === 401) {
    console.log("Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.");
  } else {
    console.error(err);
  }
  process.exit(1);
});

process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

Własne przykłady Telegrafa czytają process.env.BOT_TOKEN. Panel przekazuje twojemu kodowi token jako TELEGRAM_BOT_TOKEN, a także jako BOT_TOKEN, TOKEN, TELEGRAM_TOKEN i TELOXIDE_TOKEN, więc te przykłady działają bez zmian. To linia Logged in as @your_bot zmienia znacznik na Online w Telegramie.

Gdy token jest błędny

W naszym teście, z fałszywym tokenem, bot.launch() w Telegraf zakończyło się błędem TelegramError, którego err.code wynosi 401. Wypisany jako nazwa i komunikat wygląda tak:

Error: 401: Unauthorized

Nazwa pokazuje się jako Error, bo klasa błędu Telegrafa nie ustawia własnej nazwy. Telegraf nie ponawia odrzuconego tokena: bot.launch() kończy się błędem od razu, tak samo jak przy bocie, który w ogóle nie dostał tokena (401: Bot Token is required). Bot powyżej przechwytuje oba przypadki i zamiast tego wypisuje Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., a panel pokazuje nad Console baner Telegram nie przyjął tokena twojego bota. Aby to naprawić, wyślij w @BotFather /mybots, wybierz swojego bota, potem API Token i skopiuj token jeszcze raz. Na stronie Bot, w panelu Telegram, kliknij Zastąp token, wklej go, kliknij Zapisz token, a potem Zrestartuj teraz.

Co warto wiedzieć o Telegrafie na serwerze

• Wydania: najnowszy Telegraf to 4.16.3, wydany 29 lut 2024. Wersja 4.16.0 (25 lut 2024) dodała Bot API 7.0 i 7.1 od Telegrama; własny changelog Telegrama sięga Bot API 10.3 (24 sie 2026). Do repozytorium GitHub ostatni push trafił 24 wrz 2026. W naszym teście 4.16.3 zainstalował się i wystartował normalnie na Node.js 22.
• Linia gotowości idzie do callbacka launch(). bot.launch() wraca dopiero, gdy bot się zatrzyma, więc console.log po await bot.launch() nigdy się nie wypisze, dopóki bot działa. Od 4.16.0 launch() przyjmuje callback, który Telegraf wywołuje, gdy Telegram przyjmie token, z wypełnionym bot.botInfo.
• Błąd w komendzie zatrzymuje bota, jeśli nie ustawisz bot.catch. Domyślny handler Telegrafa wypisuje Unhandled error while processing wraz z aktualizacją i rzuca błąd ponownie, co kończy polling, więc proces się zatrzymuje. Nasz panel uruchamia wywrócony bot ponownie w ciągu około minuty, ale do tego czasu jest offline. Z bot.catch, jak wyżej, błąd jest wypisywany, a bot działa dalej.
• Każda aktualizacja ma 90 sekund. Aktualizacja, której handlery trwają dłużej, jest zgłaszana jako błąd (opcja handlerTimeout, domyślnie 90.000 ms), który trafia do bot.catch. Przy dłuższych zadaniach przekaż new Telegraf(token, { handlerTimeout: ... }).
• Webhook pozostawiony na bocie jest usuwany za ciebie. bot.launch() bez opcji webhook wywołuje deleteWebhook przed pollingiem i zachowuje czekające wiadomości, chyba że przekażesz dropPendingUpdates: true. bot.launch({ webhook: ... }) wymaga publicznego adresu HTTPS, którego te plany jeszcze nie zawierają: używaj zwykłego bot.launch(). Przenosiny z hosta z webhookiem: Jak przenieść bota Telegram do PlayNHost.
• Inna kopia bota zatrzymuje tę. Przy 409 Conflict (ten sam token w pollingu gdzie indziej) polling Telegrafa rzuca błąd zamiast ponawiać. Panel pokazuje Twój bot działa też gdzie indziej: zatrzymaj kopię na swoim komputerze lub u starego hosta. Zobacz Jak naprawić błąd 409 Conflict bota Telegram. Podczas pollingu błędy sieci, 429 i własne błędy 5xx Telegrama są ponawiane po czasie oczekiwania, którego żąda Telegram, albo po 5 sekundach.
• Wersja Node.js: Telegraf 4.16.3 wymaga Node.js 12.20 lub 14.13.1 i nowszego. Runtime w panelu Kod oferuje Node.js 20, 22 (recommended), 24, 25 i 26.
• Limit pamięci: skrypt startowy ustawia NODE_OPTIONS=--max-old-space-size na 80 procent pamięci twojego planu, aby reszta procesu miała miejsce. Szczegóły skryptu startowego Node.js: Jak hostować bota Discord w Node.js.

Hostowanie samemu na VPS z Linuxem

W Debianie 12 lub 13 albo Ubuntu 24.04 wystarczy pakiet z dystrybucji (Debian 12 ma Node.js 18.20, Debian 13 ma 20.19, Ubuntu 24.04 ma 18.19):

sudo apt update
sudo apt install nodejs npm
node --version

Utwórz użytkownika dla bota, skopiuj pliki i zainstaluj pakiety:

sudo useradd --system --create-home --home-dir /opt/mybot mybot
sudo cp package.json index.js /opt/mybot/
sudo chown -R mybot: /opt/mybot
cd /opt/mybot && sudo -u mybot npm install --omit=dev

Trzymaj token poza kodem, w pliku, który może czytać tylko root:

sudo sh -c 'echo "TELEGRAM_BOT_TOKEN=123456789:your-token" > /etc/mybot.env'
sudo chmod 600 /etc/mybot.env

Utwórz /etc/systemd/system/mybot.service:

[Unit]
Description=Telegraf Telegram bot
Wants=network-online.target
After=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/usr/bin/node index.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Uruchom go teraz i przy każdym starcie systemu, a potem śledź jego wyjście:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
sudo journalctl -u mybot -f

Restart=always uruchamia bota ponownie po awarii lub po process.exit(1). systemctl stop mybot wysyła SIGTERM, który linie process.once zamieniają na bot.stop(). Najpierw zatrzymaj każdą inną kopię, inaczej Telegram odpowie obu błędem 409 Conflict.

Samodzielnie czy w planie dla botów

Na VPS, którym zarządzasz sam, zajmujesz się:

• Aktualizacjami i bezpieczeństwem systemu oraz aktualizacjami Node.js.
• Uruchamianiem npm install po każdej zmianie, plikiem usługi, plikiem tokena i jego uprawnieniami.
• Czytaniem journalctl, by ustalić, dlaczego bot się zatrzymał.
• Kopiami zapasowymi danych bota.

W zamian VPS uruchomi wszystko, a możesz mu nadać domenę z HTTPS dla webhooka.

W planie dla botów PlayNHost robi to za ciebie panel:

• Wybór wersji Node.js oraz npm install, gdy zmieni się package.json, plik blokady lub wersja Node.js.
• Token sprawdzany w Telegramie przed zapisem, przechowywany w postaci zaszyfrowanej i przekazywany twojemu kodowi.
• Ponowne uruchomienie bota po awarii. Jeśli wywróci się znowu w ciągu minuty, pozostaje zatrzymany, a Console podaje powód.
• Banery nad Console, które wskazują przyczynę, gdy Telegram odrzuca token, działa inna kopia albo ustawiony jest webhook, z przyciskiem Usuń webhook w panelu Telegram.
• Przesyłanie plików, wdrożenia z Gita i kopie zapasowe z poziomu panelu.

Pytania, które zadają ludzie

Dlaczego nic się nie wypisuje po await bot.launch()?

Bo bot.launch() czeka, aż polling się skończy, a polling trwa tak długo, jak bot. Kod po nim wykona się dopiero, gdy bot się zatrzyma. Umieść komunikaty startowe w callbacku, bot.launch(() => ...), i zarejestruj komendy, zanim wywołasz launch().

Czy mogę dalej używać Telegrafa, czy przejść na grammY?

Działający bot na Telegraf 4 działa w naszych planach bez zmian: do hostowania nie trzeba nic zmieniać. Ostatnie wydanie jest z lutego 2024, więc metody dodane przez Telegram po Bot API 7.1 nie mają skrótu w Telegrafie. grammY 1.46.0 (26 sie 2026) obsługuje Bot API 10.3, a nasz bot startowy dla Node.js go używa. Przejdź, gdy potrzebujesz czegoś nowszego, niż oferuje Telegraf.

Mój bot Telegraf zatrzymał się z 409: Conflict. Co teraz?

Inna kopia robi polling z tym samym tokenem, często na twoim komputerze lub u starego hosta. Telegraf zatrzymuje się zamiast ponawiać. Panel uruchamia go ponownie w ciągu około minuty; jeśli zatrzyma się znowu w ciągu minuty od tego, pozostaje zatrzymany. Znajdź i zatrzymaj drugą kopię albo utwórz nowy token w @BotFather i wklej go przez Zastąp token.

Czy mogę uruchomić Telegraf na Bun?

Tak. Przy zamawianiu wybierz Bun zamiast Node.js: nasza strona hostingu botów Telegram wymienia dla niego Telegraf. Kroki na tej stronie dotyczą Node.js.

Gotowy, by twój bot Telegraf działał całą dobę? Zobacz plany na stronie hostingu botów Telegram.