كيفية استضافة بوت Telegraf على مدار الساعة 24/7 (Telegram، Node.js)

لاستضافة بوت Telegraf على مدار الساعة 24/7 تشغّله على جهاز يبقى مفتوحًا دائمًا: إما VPS لينكس مع خدمة systemd تعيد تشغيله عند توقفه، أو باقة للبوتات لدى PlayNHost (ابتداءً من US$1.99 شهريًا)، حيث تثبّت اللوحة حزمك وتمنح شيفرتك الرمز (token) وتعيد تشغيل البوت إن تعطّل. في اختبارنا استهلك بوت Telegraf 4.16.3 نحو 60 MB من الذاكرة على Node.js 22. يستخدم bot.launch() في Telegraf الاستطلاع الطويل (long polling) افتراضيًا، وهذا ما تحتاجه باقاتنا: فليس لديها بعد عنوان HTTPS عام لـ webhook. الخطوات على PlayNHost:

1. في صفحة استضافة بوتات Telegram، انقر أنشئ سيرفرًا على إحدى الباقات. في نافذة الطلب أجب عن لأي منصة بوتك؟ بالخيار Telegram واختر Node.js.
2. افتح سيرفرك في اللوحة. تُفتح بطاقة إعداد بوتك في نظرة عامة عند الاتصال بـ Telegram؛ ويجب أن تعرض خطوتها الأولى، ما الذي يعمل، العبارة يشغّل هذا البوت Node.js Bot.
3. عند الاتصال بـ Telegram، الصق الرمز الذي حصلت عليه من @BotFather تحت الصق رمز بوتك، وانقر الاتصال، وتحقق من اسم البوت المعروض وانقر نعم، متابعة.
4. عند كودك، انقر رفع الملفات وارفع package.json وindex.js دون node_modules، أو انقر ربط Git.
5. في صفحة بوت، قسم الكود، تأكد أن ملف البدء هو الملف الذي يشغّل بوتك (index.js افتراضيًا). انقر حفظ إن غيّرته.
6. انقر تشغيل البوت وافتح Console. يثبّت npm مكتبة Telegraf عند أول تشغيل، ثم يطبع بوتك Logged in as @your_bot وتتحول الشارة في نظرة عامة إلى متصل في Telegram.
7. في صفحة بوت، قسم Telegram، انقر افتح في Telegram وأرسل إلى بوتك /start.

إنشاء البوت في @BotFather وخطوات اللوحة موضحة في كيف تستضيف بوت Telegram. تتناول هذه الصفحة Telegraf نفسها: ما تستهلكه على السيرفر وما يجدر بك معرفته قبل الاستضافة.

ما الذي قسناه

الطريقة: على عقدتنا الخاصة، وفي حاوية مؤقتة مُعدّة كباقة بوت بسعة 1 GB (صورة Node.js 22 وأمر التشغيل الخاص بنوع بوت Node.js لدينا، مع ضبط حد ذاكرة Node على 80 بالمئة)، استدعى كل بوت Telegram برمز مزيف رفضه Telegram. الذاكرة هي الذاكرة المقيمة بعد 15 ثانية من ذلك الرد، ويُحسب زمن التشغيل من launch حتى الرد، وكل رقم هو وسيط التشغيلات من 2 إلى 4.

هذه حدود دنيا: بوت بلا محادثات وبلا بيانات بعد. تُضاف إليها شيفرتك الخاصة وما تحتفظ به في الذاكرة وعدد المحادثات، فالمكتبة جزء صغير من 0.5 GB في باقة STARTER.

بوت Telegraf بسيط

يرد على /start ويقرأ الرمز الذي تمنحه اللوحة له ويطبع سطر الجاهزية. ضع الملفين في المجلد الرئيسي لبوتك.

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"));

تقرأ أمثلة Telegraf الرسمية process.env.BOT_TOKEN. تمنح اللوحة شيفرتك الرمز باسم TELEGRAM_BOT_TOKEN وكذلك باسم BOT_TOKEN وTOKEN وTELEGRAM_TOKEN وTELOXIDE_TOKEN، فتعمل تلك الأمثلة دون تعديل. السطر Logged in as @your_bot هو ما يحوّل الشارة إلى متصل في Telegram.

إذا كان الرمز خاطئًا

في اختبارنا، ومع رمز مزيف، فشل bot.launch() في Telegraf بخطأ TelegramError قيمة err.code فيه 401. وعند طباعته كاسم ورسالة يظهر هكذا:

Error: 401: Unauthorized

يظهر الاسم Error لأن فئة الخطأ في Telegraf لا تضبط اسمًا خاصًا بها. لا يعيد Telegraf المحاولة بعد رفض الرمز: يفشل bot.launch() فورًا، وكذلك الحال مع بوت لم يحصل على أي رمز (401: Bot Token is required). يلتقط البوت أعلاه الحالتين ويطبع بدلًا من ذلك Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.، وتعرض اللوحة التنبيه لم يقبل Telegram رمز بوتك فوق Console. للإصلاح، أرسل في @BotFather الأمر /mybots واختر بوتك ثم API Token وانسخ الرمز من جديد. في صفحة بوت، قسم Telegram، انقر استبدال الرمز والصقه وانقر حفظ الرمز ثم إعادة التشغيل الآن.

ما يجب معرفته عن Telegraf على السيرفر

• الإصدارات: أحدث إصدار من Telegraf هو 4.16.3، صدر في 29 فبراير 2024. أضاف الإصدار 4.16.0 (25 فبراير 2024) واجهتي Bot API 7.0 و7.1 من Telegram؛ وسجل تغييرات Telegram نفسه وصل إلى Bot API 10.3 (24 أغسطس 2026). آخر دفع إلى مستودع GitHub كان في 24 سبتمبر 2026. في اختبارنا ثُبّت 4.16.3 وبدأ العمل بشكل طبيعي على Node.js 22.
• سطر الجاهزية يوضع في دالة launch() المرتدة. لا يعود bot.launch() إلا عند توقف البوت، فلا يُطبع أي console.log بعد await bot.launch() ما دام البوت يعمل. منذ 4.16.0 تقبل launch() دالة مرتدة يستدعيها Telegraf بعد أن يقبل Telegram الرمز، ويكون bot.botInfo معبأً.
• يوقف الخطأ في أمر البوت ما لم تضبط bot.catch. يطبع المعالج الافتراضي في Telegraf الرسالة Unhandled error while processing مع التحديث ثم يعيد رمي الخطأ، فينتهي الاستطلاع وتتوقف العملية. تعيد لوحتنا تشغيل البوت المتعطل خلال دقيقة تقريبًا، لكنه يبقى خارج الاتصال حتى ذلك الحين. ومع bot.catch، كما في الشيفرة أعلاه، يُطبع الخطأ ويواصل البوت العمل.
• لكل تحديث 90 ثانية. يُبلَّغ عن التحديث الذي تستغرق معالجاته وقتًا أطول كخطأ (الخيار handlerTimeout، وقيمته الافتراضية 90,000 ms)، ثم ينتقل إلى bot.catch. مرّر new Telegraf(token, { handlerTimeout: ... }) للمهام الأطول.
• يُزال webhook المتروك على البوت نيابةً عنك. يستدعي bot.launch() دون الخيار webhook الدالة deleteWebhook قبل الاستطلاع، ويُبقي الرسائل المنتظرة ما لم تمرّر dropPendingUpdates: true. يحتاج bot.launch({ webhook: ... }) إلى عنوان HTTPS عام لا تتضمنه هذه الباقات بعد: استخدم bot.launch() العادي. للانتقال من مضيف يستخدم webhook: كيف تنقل بوت Telegram إلى PlayNHost.
• نسخة أخرى من البوت توقف هذه. عند ظهور 409 Conflict (الرمز نفسه يجري استطلاعه في مكان آخر) يرمي استطلاع Telegraf خطأً بدل إعادة المحاولة. تعرض اللوحة بوتك يعمل في مكان آخر أيضًا: أوقف النسخة على حاسوبك أو لدى مضيفك القديم. راجع إصلاح خطأ 409 Conflict في بوت Telegram. أثناء الاستطلاع تُعاد محاولة أخطاء الشبكة و429 وأخطاء 5xx الصادرة عن Telegram بعد مدة الانتظار التي يطلبها Telegram، أو 5 ثوانٍ.
• إصدار Node.js: يتطلب Telegraf 4.16.3 الإصدار Node.js 12.20 أو 14.13.1 وما بعدهما. توفر بيئة التشغيل في قسم الكود الإصدارات Node.js 20 و22 (recommended) و24 و25 و26.
• حد الذاكرة: يضبط سكربت التشغيل NODE_OPTIONS=--max-old-space-size على 80 بالمئة من ذاكرة باقتك ليبقى للجزء المتبقي من العملية متسع. تفاصيل سكربت تشغيل Node.js: كيف تستضيف بوت Discord بلغة Node.js.

استضفه بنفسك على VPS لينكس

على Debian 12 أو 13 أو Ubuntu 24.04 تكفي حزمة التوزيعة لتشغيل Telegraf (يأتي Debian 12 بـ Node.js 18.20، ويأتي Debian 13 بـ 20.19، ويأتي Ubuntu 24.04 بـ 18.19):

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

أنشئ مستخدمًا للبوت وانسخ ملفاتك وثبّت الحزم:

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

أبقِ الرمز خارج شيفرتك، في ملف لا يقرأه سوى root:

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

أنشئ الملف /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

شغّله الآن وعند كل إقلاع، ثم تابع مخرجاته:

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

يعيد Restart=always تشغيل البوت بعد تعطل أو بعد process.exit(1). يرسل systemctl stop mybot الإشارة SIGTERM، وتحوّلها أسطر process.once إلى bot.stop(). أوقف أي نسخة أخرى أولًا، وإلا ردّ Telegram على الاثنتين بـ 409 Conflict.

الاستضافة الذاتية أم باقة للبوتات

على VPS تديره بنفسك، تتولى:

• تحديثات نظام التشغيل وأمانه، وترقيات Node.js.
• تشغيل npm install بعد كل تغيير، وملف الخدمة، وملف الرمز وصلاحياته.
• قراءة journalctl لمعرفة سبب توقف البوت.
• النسخ الاحتياطية لبيانات البوت.

في المقابل يشغّل الـ VPS أي شيء، ويمكنك أن تمنحه نطاقًا مع HTTPS لاستخدام webhook.

في باقة بوتات PlayNHost تتولى اللوحة ذلك عنك:

• محدد لإصدار Node.js، وتشغيل npm install عند تغيّر package.json أو ملف القفل أو إصدار Node.js.
• الرمز، يُتحقق منه لدى Telegram قبل حفظه، ويُخزَّن مشفرًا ويُمنح لشيفرتك.
• إعادة تشغيل البوت بعد التعطل. إن تعطل مجددًا خلال دقيقة يبقى متوقفًا وتذكر Console السبب.
• تنبيهات فوق Console تسمّي السبب حين يرفض Telegram الرمز أو تعمل نسخة أخرى أو يكون webhook مضبوطًا، مع زر إزالة الـ webhook في قسم Telegram.
• الرفع ونشر Git والنسخ الاحتياطية من اللوحة.

أسئلة شائعة

لماذا لا يُطبع شيء بعد await bot.launch()؟

لأن bot.launch() ينتظر انتهاء الاستطلاع، ويستمر الاستطلاع ما دام البوت يعمل. لا تُنفَّذ الشيفرة التي بعده إلا عند توقف البوت. ضع رسائل البدء في الدالة المرتدة bot.launch(() => ...)، وسجّل الأوامر قبل استدعاء launch().

هل أستمر في استخدام Telegraf أم أنتقل إلى grammY؟

يعمل بوت Telegraf 4 السليم على باقاتنا كما هو: لا شيء يلزم تغييره لاستضافته. آخر إصدار له يعود إلى فبراير 2024، فلا اختصار في Telegraf للأساليب التي أضافها Telegram بعد Bot API 7.1. تدعم grammY 1.46.0 (26 أغسطس 2026) واجهة Bot API 10.3، ويستخدمها بوتنا الابتدائي لـ Node.js. انتقل حين تحتاج إلى ما هو أحدث مما يقدمه Telegraf.

توقف بوت Telegraf لدي بالخطأ 409: Conflict. ماذا أفعل؟

نسخة أخرى تجري الاستطلاع بالرمز نفسه، وغالبًا على حاسوبك أو لدى مضيفك القديم. يتوقف Telegraf بدل إعادة المحاولة. تعيد اللوحة تشغيله خلال دقيقة تقريبًا؛ فإن توقف مجددًا خلال دقيقة بعد ذلك يبقى متوقفًا. ابحث عن النسخة الأخرى وأوقفها، أو أنشئ رمزًا جديدًا في @BotFather والصقه عبر استبدال الرمز.

هل يمكنني تشغيل Telegraf على Bun؟

نعم. عند الطلب اختر Bun بدل Node.js: تدرج صفحة استضافة بوتات Telegram لدينا Telegraf له. الخطوات في هذه الصفحة خاصة بـ Node.js.

هل أنت مستعد لتشغيل بوت Telegraf على مدار الساعة؟ تعرّف على الباقات في استضافة بوتات Telegram.