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

لاستضافة بوت pyTelegramBotAPI (telebot) على مدار الساعة 24/7، شغّله على جهاز يبقى قيد التشغيل بدل حاسوبك الشخصي: خادم VPS بنظام لينكس مع خدمة systemd تعيد تشغيله بعد أي تعطل أو إعادة إقلاع، أو خطة بوتات من PlayNHost (ابتداءً من US$1.99 شهريًا، راجع استضافة بوتات Telegram)، حيث ترفع شيفرتك وتلصق الرمز المميز وتضغط تشغيل. في اختبارنا استهلك بوت يعمل بـ pyTelegramBotAPI 4.37.1 نحو 40 MB من الذاكرة دون حمل؛ وأصغر خطة بوتات لدينا، STARTER، توفر 0.5 GB. يعتمد الطريقان على long polling: يطلب bot.infinity_polling() الرسائل الجديدة من Telegram، لذا لا يحتاج البوت إلى عنوان عام. خطوات PlayNHost:

1. في Telegram، أرسل /newbot إلى @BotFather وانسخ الرمز المميز الذي يعطيك إياه.
2. في استضافة بوتات Telegram، اضغط أنشئ سيرفرًا على إحدى الخطط. في نافذة الطلب، أجب عن لأي منصة بوتك؟ بـ Telegram واختر Python.
3. افتح سيرفرك في اللوحة. تفتح بطاقة إعداد بوتك في نظرة عامة عند الاتصال بـ Telegram؛ وخطوتها الأولى، ما الذي يعمل، يجب أن تعرض يشغّل هذا البوت Python Bot.
4. عند الاتصال بـ Telegram، الصق الرمز المميز واضغط الاتصال. تحقق من اسم البوت الظاهر واضغط نعم، متابعة.
5. عند كودك، اضغط رفع الملفات لفتح Files وارفع bot.py وrequirements.txt، أو اضغط ربط Git. في requirements.txt اسم الحزمة pyTelegramBotAPI وليس telebot.
6. في صفحة بوت، قسم الكود، تأكد أن ملف البدء هو الملف الذي يستدعي infinity_polling() (وهو bot.py افتراضيًا)، وأن بيئة التشغيل هي Python 3.11 أو أحدث.
7. اضغط تشغيل البوت وافتح Console وانتظر ظهور Logged in as @your_bot. تتحول الشارة في نظرة عامة إلى متصل في Telegram. أرسل /start إلى بوتك.

يستغرق التشغيل الأول وقتًا أطول أثناء تثبيت pip لـ pyTelegramBotAPI. بعد ذلك لا يعيد التثبيت إلا عند تغير ملف المتطلبات أو الحزم الإضافية أو إصدار Python، أو مرة كل يوم. شرح خطوة بخطوة مع لقطات شاشة: كيف تستضيف بوت Telegram.

ما الذي قسناه

شغّلنا مكتبات Python الثلاث الخاصة بـ Telegram على أحد خوادمنا، داخل حاويات مؤقتة مهيأة كما تشغّل اللوحة بوت Python: Python 3.12 (بيئة التشغيل الموسومة بأنها موصى بها)، وحزم مثبتة بأمر pip نفسه، وحد ذاكرة 1 GB ونواة معالج واحدة.

حمّل كل بوت المكتبة وسأل Telegram من يكون برمز مميز مزيف (في pyTelegramBotAPI: bot.get_me() على TeleBot العادي). الذاكرة هي ما شغلته عمليات البوت بعد 15 ثانية من رفض Telegram للرمز؛ ويُحتسب زمن التشغيل من إطلاق Python حتى تُبلغ المكتبة بهذا الرد، لذلك يشمل رحلة ذهاب وإياب واحدة إلى Telegram. القيمتان هما الوسيط لثلاث تشغيلات بعد تشغيلة إحماء.

هذه الأرقام هي الحد الأدنى للمكتبة: بلا محادثات، وبلا معالجات تعمل، وبلا شيء في الذاكرة المؤقتة. تُضاف إليها شيفرتك والبيانات التي تحتفظ بها في الذاكرة وعدد المحادثات التي تخدمها، لذا اختر الخطة بحسب ما يفعله بوتك. يشمل الحجم المثبت مكتبتي HTTP اللتين تعتمد عليهما pyTelegramBotAPI، وهما requests وaiohttp، حتى لو استخدمت TeleBot العادي فقط.

بوت pyTelegramBotAPI بسيط

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

pyTelegramBotAPI>=4,<5

والشيفرة في bot.py:

import os

import telebot

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "Hello! I am running on PlayNHost.")


bot.delete_webhook()
print(f"Logged in as @{bot.user.username}")
bot.infinity_polling()

الاستدعاءان قبل بدء polling مهمان على الاستضافة. يزيل delete_webhook() أي webhook تُرك من استضافة أخرى، ويسأل bot.user تطبيق Telegram من يكون البوت، لذلك يظهر Logged in as @your_bot فقط مع رمز مميز يقبله Telegram. تقرأ اللوحة هذا السطر لتعرض متصل في Telegram. كما يوقف الاستدعاءان البوت فورًا بخطأ واضح إذا كان الرمز خاطئًا، بدل أن يتركا polling يعيد المحاولة في الخلفية. تمرر اللوحة الرمز المميز إلى شيفرتك باسم TELEGRAM_BOT_TOKEN، وأيضًا باسم BOT_TOKEN وTOKEN وTELEGRAM_TOKEN.

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

في اختبارنا، مع رمز مميز يرفضه Telegram، طبع بوت الاختبار لدينا:

ApiTelegramException: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized

في traceback كامل يظهر اسم الصنف telebot.apihelper.ApiTelegramException. مع البوت أعلاه يفشل الاستدعاء الأول ويتوقف البوت برمز الخروج 1؛ وفي PlayNHost تعرض اللوحة لم يقبل Telegram رمز بوتك فوق وحدة التحكم، مع استبدال الرمز. للإصلاح انسخ الرمز مجددًا: في @BotFather أرسل /mybots ثم اختر بوتك ثم API Token. الصقه في صفحة بوت، قسم Telegram، ضمن الرمز، ثم شغّل البوت من جديد.

أما البوت الذي يستدعي infinity_polling() مباشرة، كما تفعل معظم الأمثلة، فيتصرف بشكل مختلف: لا يتوقف. يسأل polling أولًا Telegram من يكون البوت؛ ومع رمز مرفوض يفشل ذلك، فيسجل البوت Infinity polling exception: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized ويعيد المحاولة كل 3 ثوانٍ ما دامت العملية تعمل. أما الرمز الذي يُلغى والبوت يعمل بـ polling بالفعل فيعطي Threaded polling exception: بالرسالة نفسها، وتُعاد المحاولة بعد انتظار يتضاعف في كل مرة حتى دقيقة. في الحالتين يبدو البوت قيد التشغيل بينما لا شيء يرد. تتعرف اللوحة على السطرين وتعرض التنبيه نفسه.

ما ينبغي أن تعرفه الاستضافة عن pyTelegramBotAPI

• أسماء الحزمة والاستيراد: تثبّت pyTelegramBotAPI وتستورد telebot. حزمة PyPI المسماة telebot مشروع آخر صغير؛ ضع pyTelegramBotAPI في requirements.txt.
• إصدار Python: يحتاج pyTelegramBotAPI 4.37.1 إلى Python 3.11 أو أحدث. على Python 3.10 لا يفشل pip: بل يثبّت 4.37.0، وهو آخر إصدار سمح بـ 3.10. أبقِ بيئة التشغيل في قسم الكود على 3.11 أو أحدث (3.12 موسوم بأنه موصى به) لتحصل على الإصدار الحالي.
• infinity_polling() أو polling(): استخدم infinity_polling(). يتوقف polling() العادي عند أول خطأ من Telegram، كما ينهيه أي استثناء في أحد معالجاتك، فيخرج البوت. مع infinity_polling() تُعاد محاولة أخطاء Telegram، ويُسجَّل أي استثناء آخر في معالج على هيئة Infinity polling exception: ... قبل أن يبدأ polling من جديد بعد 3 ثوانٍ.
• السجلات: لدى pyTelegramBotAPI مسجّل خاص به، TeleBot، مضبوط على ERROR، لذلك لا يطبع شيئًا عند البدء؛ ولهذا يطبع البوت أعلاه سطر الجاهزية الخاص به. تظهر الأخطاء في سطر واحد بلا traceback. لمعرفة أين فشل معالج، شغّل مع bot.infinity_polling(logger_level=logging.DEBUG) (وimport logging)، فيضيف ذلك الـ traceback. تخفي هذه الأسطر الجزء السري من رمزك المميز.
• webhook تُرك من استضافة أخرى: لا يزيله polling، ويرفض Telegram الـ polling ما دام هناك webhook مضبوط. أبقِ bot.delete_webhook() كما في الأعلى، أو اضغط إزالة الـ webhook في صفحة بوت، قسم Telegram.
• الخيوط أو asyncio: يستخدم TeleBot مكتبة requests ويشغّل المعالجات في خيطي عمل افتراضيًا (num_threads=2)؛ والمعالج البطيء يحتجز أحدهما. يستخدم AsyncTeleBot من telebot.async_telebot مكتبة aiohttp ويعمل عبر asyncio.run(bot.polling()). كلاهما يعمل بالطريقة نفسها على اللوحة.
• نسخة ثانية: عندما تعمل نسخة أخرى بـ polling بالرمز المميز نفسه، يرد Telegram بـ 409 Conflict ويعيد infinity_polling() المحاولة ما دام يعمل. تعرض اللوحة بوتك يعمل في مكان آخر أيضًا. راجع إصلاح خطأ 409 Conflict في بوت Telegram.

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

على Debian أو Ubuntu، ثبّت Python وأنشئ مستخدمًا للبوت وثبّت المكتبة في بيئة افتراضية. تحقق أولًا من python3 --version: أقل من 3.11 سيثبّت pip نسخة أقدم من pyTelegramBotAPI.

sudo apt update
sudo apt install -y python3 python3-venv
sudo useradd --system --create-home --home-dir /opt/tgbot --shell /usr/sbin/nologin tgbot
sudo cp bot.py requirements.txt /opt/tgbot/
sudo -u tgbot python3 -m venv /opt/tgbot/venv
sudo -u tgbot /opt/tgbot/venv/bin/pip install -r /opt/tgbot/requirements.txt

ضع الرمز المميز في ملف لا يقرؤه إلا root. افتحه بالأمر sudo nano /etc/tgbot.env واكتب سطرًا واحدًا واحفظ، ثم نفّذ sudo chmod 600 /etc/tgbot.env:

TELEGRAM_BOT_TOKEN=123456789:your-token-from-botfather

أنشئ /etc/systemd/system/tgbot.service:

[Unit]
Description=Telegram bot (pyTelegramBotAPI)
Wants=network-online.target
After=network-online.target

[Service]
User=tgbot
WorkingDirectory=/opt/tgbot
EnvironmentFile=/etc/tgbot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/opt/tgbot/venv/bin/python /opt/tgbot/bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

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

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

يهم PYTHONUNBUFFERED=1 هنا: عندما لا تذهب مخرجات Python إلى طرفية فإنها تُخزَّن مؤقتًا على شكل كتل، فبدونه قد يبقى Logged in as في ذاكرة مؤقتة بدل أن يصل إلى journal. كما يعيد Restart=always تشغيل البوت بعد 5 ثوانٍ من توقفه بسبب رمز خاطئ، فراجع journal إذا ظل يعيد التشغيل. بعد تغيير الشيفرة نفّذ sudo systemctl restart tgbot. أوقف أي نسخة على حاسوبك أولًا، وإلا يرد Telegram بـ 409 Conflict.

الاستضافة الذاتية أو خطة بوتات

• على VPS تديره بنفسك: تحديثات النظام وإصدار Python والبيئة الافتراضية وإعادة تثبيت الحزم وملف الوحدة وقراءة journal وملاحظة توقف البوت عن الرد. في المقابل لديك root ويمكنك تشغيل webhook إذا أضفت نطاقًا وHTTPS.
• على خطة بوتات تتولى اللوحة: تثبيت requirements.txt عند تغيره، وإعادة تشغيل البوت بعد أي تعطل، والتحقق من الرمز المميز لدى Telegram قبل حفظه، وتمريره إلى شيفرتك بخمسة أسماء، وقراءة وحدة التحكم وتسمية السبب عند توقف البوت عن الرد (رمز مرفوض أو نسخة ثانية أو webhook)، مع زر للرمز وللـ webhook. لا تتضمن خطط البوتات لدينا عنوان HTTPS عامًا بعد، لذلك تستخدم البوتات هناك long polling، وهو ما يفعله infinity_polling().

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

لماذا يعمل بوت telebot لدي لكنه لا يرد أبدًا؟

لأن infinity_polling() يعيد محاولة كل خطأ من Telegram دون أن يتوقف: رمز مرفوض، أو نسخة أخرى تستخدم الرمز نفسه، أو webhook متروك على البوت. ابحث عن أسطر تحتوي Infinity polling exception (رمز رُفض عند البدء) أو Threaded polling exception (بعد أن يعمل polling) في Console؛ وتحول اللوحة كل سبب من الأسباب الثلاثة إلى تنبيه يسميه.

تظهر لي رسالة ModuleNotFoundError: No module named 'telebot'. ما الذي ينقص؟

الحزمة. أضف pyTelegramBotAPI إلى requirements.txt وشغّل البوت من جديد: لقد تغير ملف المتطلبات، لذا يثبّتها pip عند هذا التشغيل. يبقى الاستيراد import telebot.

هل يحتاج pyTelegramBotAPI إلى webhook ليبقى متصلًا؟

لا. يواصل infinity_polling() طلب الرسائل الجديدة من Telegram، لذلك يرد البوت ما دامت العملية تعمل. لنقل بوت كان يستخدم webhook: كيف تنقل بوت Telegram إلى PlayNHost.

هل أستخدم TeleBot أم AsyncTeleBot؟

كلاهما يعمل على خطة بوتات. استخدم ما تستخدمه شيفرتك أو الدرس الذي تتبعه: مع TeleBot المعالجات دوال عادية، ومع AsyncTeleBot هي دوال async def تنتظر دوال البوت بـ await. قياسنا أعلاه خاص بـ TeleBot العادي.

يعمل pyTelegramBotAPI على كل خطط بوتات PlayNHost، بدءًا من STARTER (0.5 GB). قارن الخطط واضغط أنشئ سيرفرًا في استضافة بوتات Telegram.