كيف تستضيف بوت grammY على مدار الساعة 24/7

لاستضافة بوت grammY على مدار الساعة 24/7 تشغّله على جهاز يبقى قيد التشغيل دائمًا: خادم VPS بنظام لينكس مع خدمة systemd تعيد تشغيله عند توقفه، أو خطة بوتات لدى PlayNHost (ابتداءً من US$1.99 شهريًا)، حيث تثبّت اللوحة حزمك وتمنح شيفرتك الرمز (token) وتعيد تشغيل البوت إذا تعطل. في اختبارنا استخدم بوت grammY 1.46.0 نحو 60 MB من الذاكرة على Node.js 22. تعتمد الدالة bot.start() في grammY على 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. ليس لديك شيفرة بعد؟ إنشاء بوت تجريبي للبدء يكتب لك بوت grammY صغيرًا.
5. في صفحة بوت، قسم الكود، تأكد من أن ملف البدء هو الملف الذي يشغّل بوتك (index.js افتراضيًا). انقر حفظ إن غيّرته.
6. انقر تشغيل البوت وافتح Console. يثبّت npm مكتبة grammY عند أول تشغيل، ثم يطبع بوتك Logged in as @your_bot وتتحول الشارة في نظرة عامة إلى متصل في Telegram.
7. في صفحة بوت، قسم Telegram، انقر افتح في Telegram وأرسل إلى بوتك /start.

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

ما الذي قسناه

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

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

بوت grammY بسيط

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

package.json

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

index.js

const { Bot, GrammyError } = require("grammy");

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

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

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

// bot.start() only returns when the bot stops, so the ready line goes in onStart.
bot.start({
  onStart: (me) => console.log(`Logged in as @${me.username}`),
}).catch((err) => {
  if (err instanceof GrammyError && err.error_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);
});

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

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

في اختبارنا، ومع رمز مزيف، توقفت الدالة bot.start() في grammY بهذا الخطأ:

GrammyError: Call to 'deleteWebhook' failed! (401: Unauthorized)

ترسل bot.start() الطلبين getMe وdeleteWebhook في الوقت نفسه، لذا يذكر الخطأ الاستدعاء الذي رفضه Telegram أولًا: ففي بعض تشغيلاتنا كان Call to 'getMe' failed! (401: Unauthorized). لا تعيد grammY محاولة رمز مرفوض: تفشل bot.start() فورًا. يلتقط البوت أعلاه هذه الحالة ويطبع بدلًا من ذلك Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.، وتعرض اللوحة التنبيه لم يقبل Telegram رمز بوتك فوق Console. للإصلاح أرسل في @BotFather الأمر /mybots، واختر بوتك، ثم API Token، وانسخ الرمز من جديد. في صفحة بوت، قسم Telegram، انقر استبدال الرمز، والصقه، وانقر حفظ الرمز، ثم إعادة التشغيل الآن.

ما ينبغي معرفته عن grammY على الخادم

• سطر الجاهزية مكانه onStart. لا تعود bot.start() إلا عند توقف البوت، لذا فإن console.log الموضوع بعد await bot.start() لا يُطبع أبدًا أثناء تشغيل البوت. تستدعي grammY الدالة onStart مع بيانات بوتك قبيل طلب أول الرسائل من Telegram.
• يوقف الخطأ في أحد الأوامر البوت ما لم تضبط bot.catch. فبدونه تطبع grammY No error handler was set! وتوقف polling وتُطلق الخطأ فتنتهي العملية. تعيد لوحتنا تشغيل البوت المتعطل خلال نحو دقيقة، لكنه يبقى غير متصل حتى ذلك الحين. أما مع bot.catch كما في الشيفرة أعلاه فيُطبع الخطأ ويواصل البوت عمله.
• يُزال لك أي webhook متبقٍّ على البوت. تستدعي bot.start() الأمر deleteWebhook قبل polling وتبقي الرسائل المنتظرة ما لم تمرر drop_pending_updates: true. يهمك هذا عند نقل بوت من مضيف كان يستخدم webhook: كيف تنقل بوت Telegram إلى PlayNHost.
• نسخة أخرى من البوت توقف هذه النسخة. عند 409 Conflict (الرمز نفسه يجري polling في مكان آخر) تفشل bot.start() بدل إعادة المحاولة. تعرض اللوحة بوتك يعمل في مكان آخر أيضًا: أوقف النسخة على جهازك أو على مضيفك القديم. راجع إصلاح خطأ 409 Conflict في بوت Telegram.
• تُعاد محاولة أخطاء الشبكة عند البدء بصمت. إذا فشل أول استدعاء إلى Telegram بسبب الشبكة، تعيد grammY المحاولة بفترات انتظار تطول تدريجيًا (حتى 20 دقيقة بين المحاولات في الإصدار 1.46.0) ولا تطبع شيئًا. لرؤية هذه المحاولات، أضف في صفحة بوت، قسم البيئة، المتغير DEBUG بالقيمة grammy* (إضافة متغير) ثم أعد التشغيل.
• إصدار Node.js: تتطلب grammY 1.46.0 الإصدار 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 تكفي حزمة التوزيعة لتشغيل grammY (يأتي 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=grammY 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). أوقف أي نسخة أخرى أولًا، وإلا ردّ 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، والنسخ الاحتياطية من اللوحة.

اقرأ أيضًا كيفية استخدام قاعدة بيانات MySQL مع بوت grammY (mysql2).

أسئلة يطرحها الناس

هل هذا هو نفسه بوت البدء في اللوحة؟

قريب منه. على سيرفر Node.js ينشئ إنشاء بوت تجريبي للبدء الملفين index.js وpackage.json مع grammY ^1.46.0: يرد على /start باسمك الأول، ويطبع Logged in as @your_bot، ويلتقط الأخطاء بـ bot.catch، ويطبع سطرًا بسيطًا عندما يرفض Telegram الرمز. عدّله كما تشاء ثم أعد التشغيل.

هل يجب أن أزيل webhook قبل bot.start()؟

لا. تزيله bot.start() بالأمر deleteWebhook قبل polling، وتبقى الرسائل التي كانت منتظرة. إذا كانت شيفرتك القديمة تستخدم webhookCallback(bot, ...) مع خادم ويب، فاستبدل ذلك بـ bot.start(): ليس لهذه الخطط بعد عنوان HTTPS عام لـ webhook.

هل تكفي bot.start() لبوت كثير الاستخدام؟

في أغلب البوتات نعم. تعالج bot.start() الرسائل واحدة بعد أخرى؛ وتذكر ملاحظات grammY نفسها أنها تناسب نحو 5.000 رسالة في الساعة، وتحيل إلى حزمة @grammyjs/runner لما يزيد على ذلك أو للأوامر التي تستغرق وقتًا طويلًا مثل نقل الملفات الكبيرة. يستخدم runner أيضًا long polling، لذا يعمل على خططنا.

هل يمكنني تشغيل grammY على Bun أو Deno بدل Node.js؟

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

هل أنت مستعد لتشغيل بوت grammY على مدار الساعة؟ اطلع على الخطط في استضافة بوتات Telegram.