كيفية استضافة بوت aiogram على مدار الساعة 24/7 بخطة بوت أو VPS لينكس

لاستضافة بوت aiogram على مدار الساعة 24/7، شغّله على جهاز يبقى قيد التشغيل بدلًا من حاسوبك الشخصي: إما VPS لينكس مع خدمة systemd تعيد تشغيله بعد أي تعطل أو إعادة إقلاع، وإما خطة بوت من PlayNHost (تبدأ من US$1.99 شهريًا، راجع استضافة بوتات Telegram) ترفع فيها شيفرتك وتلصق الرمز وتضغط تشغيل. في اختبارنا استخدم بوت يعمل بـ aiogram 3.31.0 نحو 173 ميغابايت من الذاكرة دون حمل؛ وأصغر خطط البوتات لدينا، STARTER، تتضمن 0.5 غيغابايت. يعتمد الطريقان على long polling: يطلب dp.start_polling(bot) الرسائل الجديدة من Telegram، فلا يحتاج البوت إلى عنوان عام. خطوات PlayNHost:

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

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

ما الذي قسناه

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

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

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

بوت aiogram بسيط

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

aiogram>=3,<4

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

import asyncio
import logging
import os
import sys

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("Hello! I am running on PlayNHost.")


async def main() -> None:
    bot = Bot(os.environ["BOT_TOKEN"])
    async with bot.context():
        await bot.delete_webhook()
        await dp.start_polling(bot)


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

يقرأ BOT_TOKEN، وهو الاسم الذي تستخدمه أمثلة aiogram نفسها؛ وتعطي اللوحة الرمز لشيفرتك بهذا الاسم وكذلك بالأسماء TELEGRAM_BOT_TOKEN وTOKEN وTELEGRAM_TOKEN. يجعل التسجيل عند مستوى INFO مكتبة aiogram تطبع سطرًا يبدأ بـ INFO:aiogram.dispatcher:Run polling for bot @your_bot ما إن يقبل Telegram الرمز، وتقرأ اللوحة هذا السطر لتعرض متصل في Telegram، فلا حاجة إلى print من عندك. تزيل delete_webhook() أي webhook تبقّى من مضيف آخر قبل بدء polling. يغلق async with bot.context() اتصال البوت بـ Telegram عندما تنتهي main()، حتى لو انتهت بخطأ.

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

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

TelegramUnauthorizedError: Telegram server says - Unauthorized

في traceback كامل يظهر اسم الصنف aiogram.exceptions.TelegramUnauthorizedError. يفشل أول استدعاء إلى Telegram (في البوت أعلاه delete_webhook()؛ ومن دونه استدعاء getMe الذي ينفّذه start_polling)، فيتوقف البوت فورًا برمز الخروج 1. في PlayNHost تعرض اللوحة لم يقبل Telegram رمز بوتك فوق وحدة التحكم مع استبدال الرمز.

للإصلاح انسخ الرمز مجددًا: في @BotFather أرسل /mybots واختر بوتك ثم API Token. الصقه في صفحة بوت، قسم Telegram، تحت الرمز، ثم شغّل البوت من جديد.

حالتان أخريان تبدوان مختلفتين. الرمز الذي يحوي مسافة، أو الذي يخلو من رقم البوت ونقطتين رأسيتين قبل الجزء السري، يفشل قبل أي طلب: تتحقق Bot() من الشكل وتُطلق TokenValidationError برسالة تبدأ بـ Token is invalid!. أما الرمز الذي يُلغى بينما البوت يعمل أصلًا بـ polling فلا يوقفه: تسجّل aiogram Failed to fetch updates - TelegramUnauthorizedError وتعيد المحاولة كل بضع ثوانٍ، فتبدو العملية قيد التشغيل بينما لا يرد شيء. شريط التنبيه في اللوحة هو ما ينبهك إلى ذلك.

ما يجب أن يعرفه المضيف عن aiogram

• اسما الحزمة والاستيراد: كلاهما aiogram. وتثبّت معها aiohttp وpydantic وmagic-filter وaiofiles وcertifi.
• إصدار Python: تحتاج aiogram 3.31 إلى Python من 3.10 إلى 3.14. تعرض بيئة التشغيل في قسم الكود الإصدارات من 3.10 إلى 3.14 بالضبط، ويُوسم 3.12 بأنه موصى به.
• شيفرة aiogram 2 لا تعمل على aiogram 3: فقد أُزيل Executor، فيصبح executor.start_polling(dp) هو await dp.start_polling(bot). أي شرح يثبّت فيه requirements.txt إصدارًا من سلسلة 2.x، مثل aiogram==2.25.2، هو شيفرة للإصدار 2؛ راجع السؤال أدناه.
• webhook متبقٍّ من مضيف آخر: لا يزيله start_polling، ويرفض Telegram polling ما دام هناك webhook مضبوط، فتسجّل aiogram TelegramConflictError وتعيد المحاولة. أبقِ await bot.delete_webhook() كما في الأعلى، أو انقر إزالة الـ webhook في صفحة بوت، قسم Telegram.
• التسجيل: من دون logging.basicConfig لا تظهر أسطر INFO الخاصة بـ aiogram، ومنها سطر الجاهزية. وعند INFO تسجّل أيضًا سطرًا لكل تحديث (Update id=... is handled)؛ وفي بوت كثير الحركة أضف logging.getLogger("aiogram.event").setLevel(logging.WARNING)، وهذا يُبقي سطر الجاهزية.
• أي التحديثات تصل: ما لم تمرر allowed_updates، يطلب start_polling من Telegram أنواع التحديثات التي لديك لها handlers فقط.
• نسخة ثانية: عندما تعمل نسخة أخرى بـ polling بالرمز نفسه، يرد Telegram بـ 409 Conflict وتعيد aiogram المحاولة ما دامت تعمل. تعرض اللوحة بوتك يعمل في مكان آخر أيضًا. راجع إصلاح خطأ 409 Conflict في بوت Telegram.

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

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

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:

BOT_TOKEN=123456789:your-token-from-botfather

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

[Unit]
Description=Telegram bot (aiogram)
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

تصل أسطر التسجيل إلى journal لحظة حدوثها؛ ويفعل PYTHONUNBUFFERED=1 الشيء نفسه مع أي print() تضيفه، وهو ما يحتفظ به Python في مخزن مؤقت عادةً حين لا يكتب إلى طرفية. يرسل systemctl stop tgbot الإشارة SIGTERM التي يعالجها start_polling بإيقاف polling وإغلاق جلسة البوت. بعد تغيير الشيفرة نفّذ sudo systemctl restart tgbot. أوقف أي نسخة على حاسوبك أولًا، وإلا يرد Telegram بـ 409 Conflict.

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

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

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

أسئلة شائعة

هل يمكنني تشغيل بوت aiogram 2؟

انقله إلى aiogram 3 إن استطعت: يسرد دليل الترحيل الخاص بـ aiogram التغييرات، بدءًا بـ Executor المحذوف. صدر آخر إصدار من aiogram 2، وهو 2.25.2، في 6 أكتوبر 2023. وهو يذكر دعم Python من 3.7 إلى 3.10 ويحتاج إلى aiohttp أقدم من 3.9، وهي لا تقدّمها PyPI حزمًا جاهزة إلا حتى Python 3.11. إذا احتجت إلى تشغيل الشيفرة القديمة قبل نقلها، فثبّت aiogram==2.25.2 في requirements.txt واضبط بيئة التشغيل على Python 3.10، وهو أحدث إصدار يذكره.

لماذا يبدو بوت aiogram قيد التشغيل لكنه لا يرد أبدًا؟

تواصل aiogram إعادة المحاولة بعد بدء polling: عند رمز أُلغي في @BotFather، أو نسخة أخرى تستخدم الرمز نفسه، أو webhook تُرك على البوت. اقرأ الأسطر التي تبدأ بـ Failed to fetch updates في Console؛ وتحوّل اللوحة كل حالة من الثلاث إلى شريط تنبيه يسمّي السبب، مع زر للرمز وللـ webhook.

أين توجد حالات FSM في aiogram؟

مع تخزين الذاكرة الافتراضي توجد داخل عملية البوت: فتُفقد عند إعادة تشغيل البوت، مثلًا بعد تغيير الشيفرة. للاحتفاظ بها استخدم تخزينًا خارج العملية، مثل تخزين Redis الخاص بـ aiogram مع خادم Redis يمكنك الوصول إليه.

هل أحتاج إلى webhook لإبقاء بوت aiogram متصلًا؟

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

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