كيف تستضيف بوت python-telegram-bot على مدار الساعة 24/7

لاستضافة بوت python-telegram-bot على مدار الساعة 24/7، شغّله على جهاز يبقى قيد التشغيل بدلًا من حاسوبك الشخصي: خادم Linux VPS مع خدمة systemd تعيد تشغيله بعد أي انهيار أو إعادة إقلاع، أو خطة بوتات من PlayNHost (ابتداءً من US$1.99 شهريًا، راجع استضافة بوتات Telegram)، حيث ترفع شيفرتك وتلصق الرمز المميز (token) وتضغط على Start. في اختبارنا استخدم بوت python-telegram-bot 22.8 نحو 44 MB من الذاكرة دون أي حمل، وأصغر خطة بوتات لدينا، STARTER، تتضمن 0.5 GB. يعتمد الطريقان على long polling: يطلب run_polling() الرسائل الجديدة من Telegram، لذا لا يحتاج البوت إلى عنوان عام. خطوات PlayNHost:

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

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

ما الذي قسناه

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

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

هذه الأرقام هي الحد الأدنى للمكتبة: بلا محادثات، وبلا معالجات (handlers) تعمل، وبلا شيء في الذاكرة المؤقتة. تُضاف فوقها شيفرتك الخاصة والبيانات التي تحتفظ بها في الذاكرة وعدد المحادثات التي تخدمها، لذا اختر الخطة بحسب ما يفعله بوتك. قاست صفحتنا الأقدم python-telegram-bot مقابل aiogram على PlayNHost إعدادًا مختلفًا (Python 3.13، وبوت مبني وجاهز للبدء)، لذا لا يمكن مقارنة أرقامها بهذه.

بوت python-telegram-bot بسيط

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

python-telegram-bot>=22,<23

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

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_message.reply_text("Hello! I am running on PlayNHost.")


async def post_init(application: Application) -> None:
    print(f"Logged in as @{application.bot.username}")


def main() -> None:
    application = (
        Application.builder()
        .token(os.environ["TELEGRAM_BOT_TOKEN"])
        .post_init(post_init)
        .build()
    )
    application.add_handler(CommandHandler("start", start))
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

يعمل post_init بعد تهيئة التطبيق، وهو الوقت الذي تتحقق فيه python-telegram-bot من الرمز المميز لدى Telegram، لذا لا يظهر Logged in as @your_bot إلا بعد أن يقبله Telegram. تقرأ اللوحة هذا السطر لتعرض متصل في Telegram. تعطي اللوحة الرمز المميز لشيفرتك باسم TELEGRAM_BOT_TOKEN، وكذلك باسم BOT_TOKEN وTOKEN وTELEGRAM_TOKEN، فيعمل os.environ["TOKEN"] أيضًا إذا بدأت من أمثلة المكتبة التي تستخدم العنصر النائب "TOKEN".

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

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

InvalidToken: The token `1000000000:AAFakeTokenForAMemoryTestNotReal00000` was rejected by the server.

تتحقق python-telegram-bot من الرمز المميز قبل بدء الـ polling، لذا يتوقف البوت أعلاه فورًا برمز الخروج 1. تعرض وحدة التحكم أولًا Network Retry Loop (Bootstrap Initialize Application): Invalid token. Aborting retry loop. مع traceback، ثم traceback الخطأ نفسه، وآخر سطر فيه هو telegram.error.InvalidToken: The token `...` was rejected by the server. في PlayNHost تعرض اللوحة فوق وحدة التحكم لم يقبل Telegram رمز بوتك مع استبدال الرمز. لاحظ أن كلا الـ traceback يحتويان على الرمز المميز نفسه: لا تلصق مخرجات وحدة التحكم هذه في أي مكان عام.

لإصلاح ذلك، انسخ الرمز المميز مجددًا: في @BotFather أرسل /mybots، واختر بوتك، ثم API Token. الصقه في صفحة بوت، قسم Telegram، تحت الرمز، ثم شغّل البوت من جديد. إذا أُلغي الرمز المميز بينما يعمل البوت بالفعل بالـ polling، تسجّل python-telegram-bot Network Retry Loop (Polling Updates): Invalid token. Aborting retry loop. وتتوقف عن الـ polling، لكن العملية تبقى قيد التشغيل، فيبدو البوت يعمل بينما لا شيء يردّ. تعرض اللوحة اللافتة نفسها.

ما الذي يجب أن يعرفه المضيف عن python-telegram-bot

• أسماء الحزمة والاستيراد: تثبّت python-telegram-bot وتستورد telegram وtelegram.ext.
• إصدار Python: تتطلب python-telegram-bot 22.8 إصدار Python 3.10 أو أحدث. تعرض بيئة التشغيل في قسم الكود الإصدارات من 3.10 إلى 3.14، مع وسم 3.12 بأنه موصى به، لذا يحقق كل اختيار هذا الشرط.
• Webhook متبقٍ من مضيف آخر: قبل بدء الـ polling يحذف run_polling() أي webhook مضبوط للبوت، لذا يعمل البوت المنقول من مضيف يعتمد على webhook دون شيفرة إضافية. تبقى الرسائل المنتظرة لدى Telegram محفوظة ما لم تمرّر drop_pending_updates=True.
• التسجيل (Logging): تسجّل python-telegram-bot بدايتها عند المستوى INFO، ولا يعرضه Python حتى تعدّ التسجيل، لذا يطبع البوت أعلاه سطر الجاهزية الخاص به. مع logging.basicConfig(level=logging.INFO) تسجّل INFO:telegram.ext.Application:Application started، وتقرؤه اللوحة أيضًا على أنه جاهز. إذا فعلت ذلك فأضف أيضًا logging.getLogger("httpx").setLevel(logging.WARNING)، كما تفعل أمثلة المكتبة نفسها: عند INFO تسجّل مكتبة HTTP كل عنوان URL للطلبات، وتحتوي عناوين طلبات Telegram على رمزك المميز.
• المهام المجدولة: يحتاج JobQueue إلى إضافة. اكتب python-telegram-bot[job-queue]>=22,<23 في requirements.txt؛ وبدونها يكون application.job_queue هو None وتحذّر المكتبة No `JobQueue` set up.
• نسخة ثانية: عندما تعمل نسخة أخرى بالـ polling بالرمز المميز نفسه، يردّ Telegram بـ 409 Conflict. تسجّل python-telegram-bot Exception happened while polling for updates. وتواصل إعادة المحاولة، فيبدو البوت يعمل لكنه يفوّت الرسائل. تعرض اللوحة بوتك يعمل في مكان آخر أيضًا. راجع إصلاح خطأ 409 Conflict في بوت Telegram.

استضفه بنفسك على خادم Linux VPS

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

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 (python-telegram-bot)
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. يرسل systemctl stop tgbot الإشارة SIGTERM، ويعالجها run_polling() بإيقاف التشغيل بسلاسة. بعد تغيير الشيفرة نفّذ sudo systemctl restart tgbot. أوقف أي نسخة على حاسوبك أولًا، وإلا يردّ Telegram بـ 409 Conflict.

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

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

اقرأ أيضًا كيفية استخدام قاعدة بيانات MySQL مع بوت python-telegram-bot (aiomysql).

أسئلة شائعة

هل أحتاج إلى webhook لإبقاء بوت python-telegram-bot متصلًا؟

لا. يبقي run_polling() اتصالًا مفتوحًا مع Telegram ويطلب الرسائل الجديدة، فيردّ البوت ما دامت العملية تعمل. يحتاج الـ webhook إلى عنوان HTTPS عام، وهو غير متضمن في خطط البوتات لدينا حتى الآن. لنقل بوت كان يستخدم webhook: كيف تنقل بوت Telegram إلى PlayNHost.

لماذا ظهر الرمز المميز الخاص بي في وحدة التحكم؟

يظهر في موضعين شائعين: رسالة InvalidToken عندما يرفض Telegram الرمز المميز، وأسطر الطلبات في مكتبة HTTP عندما يكون التسجيل عند INFO. اضبط المسجِّل httpx على WARNING كما هو موضح أعلاه. كما يلتقط بوتنا التجريبي InvalidToken ويطبع بدلًا منه سطرًا بسيطًا.

هل يمكنني استخدام run_repeating وغيره من المهام المجدولة؟

نعم، مع الإضافة job-queue في requirements.txt. تثبّت الإضافة APScheduler عند التشغيل التالي، لأن ملف المتطلبات تغيّر. تعمل المهام داخل عملية البوت، لذا تستمر في العمل ما دام البوت يعمل.

هل يستخدم البوت التجريبي python-telegram-bot؟

نعم. على سيرفر Python، يكتب إنشاء بوت تجريبي للبدء الملف bot.py وملف requirements.txt يتضمن python-telegram-bot 22. يردّ على /start، ويطبع Logged in as @your_bot، ويُبقي الرمز المميز خارج أسطر سجله. عدّله كما تشاء ثم أعد التشغيل.

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