هذه نسخة منفصلة ومبسطة مخصصة لاستضافة وإدارة بوتات Telegram فقط. تم حذف كود بوت المذاكرة والقوالب والصور والجلسات والدعاء والفيديوهات بالكامل. البوت الحالي هو بوت تحكم يستقبل ملفات بوتات Telegram، يحفظها في مساحة منفصلة، ويتيح تشغيلها وإيقافها وإعادة تشغيلها ومراجعة سجلاتها واستهلاك مواردها.
| الخاصية | الوصف |
|---|---|
| إضافة بوت | يكتب المستخدم اسمًا ثم يرسل أرشيف ZIP يحتوي على كود البوت. |
| فحص الرفع | يُرفض الملف غير ZIP، ويتحقق النظام من الحجم، وعدد الملفات، ومسارات Zip Slip، وحجم الاستخراج، ووجود ملف Python صالح نحويًا. |
| تشغيل مستقل | ينشئ النظام virtual environment لكل بوت ويثبت requirements.txt الخاص به عند الحاجة. |
| التحكم | تشغيل، إيقاف، إعادة تشغيل، حذف، وعرض حالة كل بوت. |
| السجلات | يحفظ run.log لكل بوت ويعرض آخر الأسطر من داخل Telegram. |
| الموارد | يعرض CPU وRAM ومدة التشغيل للبوتات العاملة. |
| الفحص التلقائي | يراقب البوتات العاملة ويكتشف التوقف ويحاول إعادة التشغيل مع تأخير تصاعدي وحد أقصى لمحاولات الفشل. |
| الفحص الصحي | يمكنه اختبار توكن البوت المستضاف عبر Telegram getMe إذا حفظه المستخدم باسم BOT_TOKEN. |
| الإدارة | تعرض لوحة /admin المستخدمين والبوتات والإحصائيات وسجل التدقيق، مع الإذاعة والحظر وحدود الأعضاء وإيقاف شامل مؤكد. |
| الصحة الخارجية | يجيب الخادم على /health و/healthz ليتحقق Railway من أن الخدمة تعمل. |
| تجربة الاستخدام | واجهة عربية قائمة على الأزرار، شريط تقدم للرفع والتشغيل والإيقاف، رسائل حالة منظمة، وإيموجي دال على نوع العملية. |
يبدأ المستخدم من /start أو /help، ويمكنه تنفيذ كل الخطوات الأساسية من الأزرار. يضيف بوتًا من زر «إضافة بوت»، ويرى بوتاته من «بوتاتي»، ويلغي عملية رفع معلقة من زر الرجوع أو /cancel. أثناء الرفع تظهر مراحل تقدم مرئية، وبعده تظهر بطاقة منظمة للبوت مع أزرار التشغيل والإيقاف وإعادة التشغيل والسجل والموارد والبيئة والذاكرة وإعادة التشغيل التلقائي والجدولة والحذف. الأوامر النصية متاحة كمسار احتياطي: /newbot و/mybots و/setenv و/setmemory و/schedule.
يستطيع المستخدم الموجود في ADMIN_IDS فتح /admin لمراجعة إحصائيات المنصة، كل المستخدمين، كل البوتات، وسجل التدقيق. يستطيع المشرف حظر عضو أو فك حظره، ضبط حد بوتاته، إيقاف كل البوتات بعد تأكيد، وإيقاف بوتات العضو العاملة عند الحظر، وبدء إذاعة حقيقية على دفعات مع تقرير تقدم وإعادة محاولة محدودة وإيقاف يدوي. لا يمكن للمستخدم العادي إدارة بوت يخص مستخدمًا آخر.
ضع ملف التشغيل في الجذر وسمّه أحد الأسماء التالية: main.py أو bot.py أو app.py أو run.py أو start.py. يمكن وضع requirements.txt بجانبه. مثال:
my-bot.zip
├── main.py
├── requirements.txt
└── package_or_local_module/
توكن البوت المستضاف لا يوضع في الأرشيف. يمكن للمنصة حقن متغيرات البيئة الخاصة بالبوت من خلال قاعدة البيانات، ويُستخدم الاسم BOT_TOKEN لفحص Telegram الصحي إذا تم توفيره. بعد تغيير متغير بيئة من خلال /setenv أعد تشغيل البوت المستضاف حتى تصل القيمة الجديدة إلى العملية.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export HOST_BOT_TOKEN="توكن_بوت_التحكم"
export ADMIN_IDS="123456789"
python main.pyسيُنشأ مجلد uploaded_bots/ تلقائيًا. في الإنتاج استخدم PostgreSQL وRedis، واحفظ ملفات البوتات والنسخ الاحتياطية على Volume دائم عند الحاجة.
للنشر استخدم infra/docker/Dockerfile واترك Start Command فارغًا حتى يستخدم Railway ENTRYPOINT وCMD اللذين يهيئان الصلاحيات ويشغّلان التطبيق. أضف HOST_BOT_TOKEN وADMIN_IDS وDATABASE_URL وREDIS_URL وSECRET_KEY وENCRYPTION_KEY كمتغيرات سرية من Railway Variables، واضبط BOTS_DIR وBACKUP_DIR على مسارات Volume دائم إذا لزم الأمر. استخدم /health كمسار Healthcheck مع مهلة 300 ثانية، ولا تشغّل أكثر من نسخة واحدة من بوت التحكم بالتوكن نفسه. راجع DEPLOYMENT.md وdocs/RAILWAY_DEPLOYMENT.md للخطوات التفصيلية.
هذه النسخة تشغّل كود البوتات المرفوعة كعمليات Python منفصلة على نفس الجهاز، وتطبق حدودًا للذاكرة والمعالج وتمنع بعض مفاتيح البيئة الخطرة وتحمي استخراج ZIP. هذا ليس عزلًا أمنيًا كاملًا مثل Docker rootless أو آلة افتراضية؛ لذلك لا تستخدمها لاستضافة كود غير موثوق أو مستخدمين مجهولين قبل إضافة عزل حقيقي على مستوى الحاويات أو الآلة.
يجب الاحتفاظ بنسخ احتياطية من قاعدة البيانات ومجلدات البوتات. لا تُرفع ملفات .env أو قواعد البيانات أو توكنات Telegram إلى Git.
| الملف | الوظيفة |
|---|---|
main.py |
بوت التحكم، الأوامر، الأزرار، الرفع، الإدارة، وخادم الصحة. |
process_manager.py |
تشغيل وإيقاف ومراقبة وإعادة تشغيل البوتات المستضافة. |
database.py |
حفظ المستخدمين والبوتات ومتغيرات البيئة وسجل الاستخدام والتدقيق. |
utils.py |
حماية ZIP، اكتشاف ملف التشغيل، فحص syntax، virtual environments، والسجلات. |
config.py |
متغيرات البيئة وحدود المنصة. |
infra/docker/Dockerfile |
صورة التشغيل مع entrypoint يهيئ Volume ثم يخفض الصلاحيات. |
infra/docker/entrypoint.sh |
تهيئة /app/data وتشغيل التطبيق كمستخدم غير جذري. |
railway.json |
إعداد Railway للبناء والـHealthcheck وسياسة إعادة التشغيل، ويُقرأ تلقائيًا من جذر المستودع. |
docs/RAILWAY_DEPLOYMENT.md |
خطوات النشر وإعداد Variables وVolume وHealthcheck. |
هذه النسخة تفصل بوت الاستضافة عن بوت المذاكرة على مستوى الملفات ونقطة التشغيل والتبعيات. تم اختبار مسارات البناء، حماية ZIP، إنشاء البيئة الافتراضية، تشغيل بوت فرعي وإيقافه، والتحكم في الأزرار. قبل الإطلاق العام يجب إضافة عزل Docker فعلي، تشفير متغيرات البيئة الحساسة بدل تخزينها كنص صريح، واختبارات Telegram تكاملية.