كيف تستضيف بوت telebot على مدار الساعة 24/7 (Go وTelegram)

لاستضافة بوت telebot على مدار الساعة 24/7 تشغّله على جهاز يبقى يعمل دائمًا: خادم VPS بنظام Linux مع خدمة systemd تعيد تشغيله عندما يتوقف، أو خطة بوتات في PlayNHost (من US$1.99 شهريًا)، حيث ترفع البرنامج الجاهز فتعطيه اللوحة الرمز المميز (token) وتعيد تشغيله إن تعطل. في اختبارنا استهلك بوت يعمل بـ telebot 3.3.8 (gopkg.in/telebot.v3) نحو 11 MB من الذاكرة. يُبنى بوت Go على جهازك الخاص كبرنامج واحد لنظام Linux x86-64: لا يُترجم شيء على الخادم. الخطوات في PlayNHost:

1. ابنِ بوتك على جهازك لنظام Linux x86-64 كما هو موضح أدناه تحت Build it for Linux.
2. في استضافة بوتات Telegram انقر أنشئ سيرفرًا على إحدى الخطط. في نافذة الطلب أجب عن لأي منصة بوتك؟ بـ Telegram واختر Go.
3. افتح سيرفرك في اللوحة. تفتح بطاقة إعداد بوتك في صفحة نظرة عامة عند الاتصال بـ Telegram؛ ويجب أن تعرض خطوتها الأولى ما الذي يعمل العبارة يشغّل هذا البوت Go Bot.
4. في الاتصال بـ Telegram الصق الرمز المميز من @BotFather تحت الصق رمز بوتك، وانقر الاتصال، وتحقق من اسم البوت المعروض وانقر نعم، متابعة.
5. في كودك انقر رفع الملفات، ثم في Files انقر رفع واختر برنامجك المسمى bot. أو دع السيرفر يجلبه: في صفحة بوت، قسم الكود، بطاقة الإعدادات، اضبط رابط التنزيل (اختياري) على رابط https للبرنامج وانقر حفظ.
6. انقر تشغيل البوت وافتح Console. بعد [PlayNHost] Starting your bot يطبع بوتك Logged in as @your_bot، وتتحول الشارة في نظرة عامة إلى متصل في Telegram.
7. في صفحة بوت، قسم Telegram، انقر افتح في Telegram وأرسل إلى بوتك /start.

إنشاء البوت في @BotFather وبطاقة الإعداد مشروحان في كيف تستضيف بوت Telegram. أما نوع Go Bot نفسه (ملف البدء ووسائط التشغيل (اختياري) ورابط التنزيل) فهو نفسه لبوتات Discord وTelegram: كيف تستضيف بوت Discord بلغة Go. تتناول هذه الصفحة telebot: ما الذي يستهلكه على السيرفر وما ينبغي معرفته قبل استضافته.

ما الذي قسناه

الطريقة: على عقدتنا الخاصة، في حاوية مؤقتة مهيأة كخطة بوتات بحجم 1 GB مع معالج واحد وصورة Debian التي يعمل عليها نوع Go Bot لدينا، استدعى برنامج كل مكتبة Telegram أو Discord برمز مميز مزيف فرُفض؛ أما البرنامج بلا مكتبة فلم يجرِ أي استدعاء. الذاكرة هي الذاكرة المقيمة بعد 15 ثانية من ذلك الرد، ويُحسب زمن البدء من الإطلاق حتى الرد، وكل رقم هو وسيط التشغيلات من 2 إلى 4. بُنيت البرامج بـ Go 1.23.12 وCGO_ENABLED=0.

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

بوت telebot بسيط

يرد على /start، ويقرأ الرمز المميز الذي تعطيه إياه اللوحة، ويطبع سطر الجاهزية، ويقول بوضوح عندما ترفض Telegram الرمز، ويتوقف بسلاسة عندما تضغط إيقاف. ضع الملفين في مجلد واحد ثم شغّل go mod tidy، الذي ينزّل telebot ويكتب go.sum.

go.mod

module bot

go 1.23

require gopkg.in/telebot.v3 v3.3.8

main.go

package main

import (
	"errors"
	"fmt"
	"os"
	"os/signal"
	"strings"
	"syscall"
	"time"

	tele "gopkg.in/telebot.v3"
	"gopkg.in/telebot.v3/middleware"
)

func main() {
	token := os.Getenv("TELEGRAM_BOT_TOKEN")
	if token == "" {
		fmt.Println("TELEGRAM_BOT_TOKEN is not set. Paste your token on the Bot page, Telegram, then restart.")
		os.Exit(1)
	}
	// Network errors contain the request address, and the address contains the token.
	hide := func(err error) string { return strings.ReplaceAll(err.Error(), token, "<token>") }

	b, err := tele.NewBot(tele.Settings{
		Token:  token,
		Poller: &tele.LongPoller{Timeout: 10 * time.Second},
	})
	if errors.Is(err, tele.ErrUnauthorized) {
		fmt.Println("Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.")
		os.Exit(1)
	}
	if err != nil {
		fmt.Println("Could not start the bot:", hide(err))
		os.Exit(1)
	}

	// Without this, a panic in one handler stops the whole program.
	b.Use(middleware.Recover())

	b.Handle("/start", func(c tele.Context) error {
		return c.Send("Hello! I am running on PlayNHost.")
	})

	// A webhook left on the bot blocks polling. Remove it and keep the messages that are waiting.
	if err := b.RemoveWebhook(); err != nil {
		fmt.Println("Could not remove the webhook:", hide(err))
	}

	fmt.Println("Logged in as @" + b.Me.Username)
	go b.Start()

	// The panel stops the bot with Ctrl+C (SIGINT).
	stop := make(chan os.Signal, 1)
	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
	<-stop
	b.Stop()
}

السطر Logged in as @your_bot هو ما يحوّل الشارة إلى متصل في Telegram. تعطي اللوحة برنامجك الرمز المميز باسم TELEGRAM_BOT_TOKEN، وكذلك باسم TOKEN وBOT_TOKEN وTELEGRAM_TOKEN وTELOXIDE_TOKEN. ومثال README الخاص بـ telebot يقرأ os.Getenv("TOKEN")، فيعمل سطر الرمز فيه دون تعديل أيضًا.

البناء لنظام Linux

من مجلد مشروعك، على أي جهاز:

# macOS or Linux
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o bot

# Windows PowerShell
$env:GOOS="linux"; $env:GOARCH="amd64"; $env:CGO_ENABLED="0"; go build -o bot

يُنتج CGO_ENABLED=0 ملفًا واحدًا مكتفيًا بذاته لا يعتمد على مكتبات النظام في السيرفر، فيعمل على صورة Debian لدينا أيًا كان النظام الذي تبني عليه. الناتج ملف اسمه bot بلا امتداد. ملف Windows بامتداد .exe أو بناء macOS لا يعمل على السيرفر: عندها تعرض وحدة التحكم [PlayNHost] bot is not a Linux program. Build it for Linux x86-64 (not Windows or macOS) and upload it again.

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

في اختبارنا، ومع رمز مميز مزيف، أعاد tele.NewBot هذا الخطأ (طبعه برنامج الاختبار بعد نوع الخطأ):

*telebot.Error: telegram: Unauthorized (401)

يسأل NewBot منصة Telegram عن هوية البوت (getMe) قبل أن يعيد النتيجة، لذا فالرمز المرفوض يوقف البرنامج قبل أن يبدأ الاستعلام الدوري. يعيد telebot الخطأ ErrUnauthorized عند رد Telegram بـ Unauthorized. ينهي مثال README البرنامج بـ log.Fatal(err)؛ أما البوت أعلاه فيطبع بدلًا من ذلك Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.، وهو سطر تتعرف عليه اللوحة: فتعرض التنبيه لم يقبل Telegram رمز بوتك فوق Console.

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

ما ينبغي معرفته عن telebot على السيرفر

• الأخطاء أثناء الاستعلام الدوري صامتة. عندما يفشل طلب الرسائل من Telegram، يعيد LongPoller في telebot المحاولة فورًا ودون توقف، ولا يطبع الخطأ إلا عندما يكون Verbose مفعّلًا. فإذا كانت نسخة أخرى من البوت تستعلم بالرمز نفسه (409 Conflict)، أو كان webhook مضبوطًا، أو أُلغي الرمز أثناء عمل البوت، يستمر بوتك في العمل لكنه يتلقى رسائل قليلة أو لا يتلقى شيئًا، وتبقى وحدة التحكم صامتة. أوقف كل نسخة أخرى قبل أن تشغّله هنا، وراجع إصلاح خطأ 409 Conflict في بوت Telegram.
• رؤية ما يفعله الاستعلام الدوري. يسجّل Verbose: true في tele.Settings كل طلب ورد Telegram، فيظهر نص 409 Conflict في Console وتستطيع اللوحة عرض بوتك يعمل في مكان آخر أيضًا. كما يسجّل الرسائل التي يرسلها الناس إلى بوتك، لذا فعّله لاختبار وليس بشكل دائم.
• webhook متروك على البوت. لا يزيل b.Start() أي webhook، وما دام واحد مضبوطًا يفشل الاستعلام الدوري بصمت. يستدعي البوت أعلاه b.RemoveWebhook() قبل أن يبدأ، مما يحفظ الرسائل المنتظرة. ويمكنك أيضًا النقر على إزالة الـ webhook في قسم Telegram. يحتاج مستعلم Webhook في telebot إلى عنوان HTTPS عام، وخططنا لا تتضمنه بعد: استخدم LongPoller.
• الذعر (panic) في معالج ينهي البرنامج. يشغّل telebot كل معالج في goroutine خاص به (ما لم يكن Synchronous مفعّلًا)، وأي panic هناك يوقف كل شيء. يحوّل b.Use(middleware.Recover()) الـ panic إلى خطأ يُطبع بدلًا من ذلك. استدعِ b.Use قبل b.Handle: يُربط الـ middleware عند إضافة المعالج.
• أخطاء المعالجات تُطبع نيابةً عنك. الخطأ الذي يعيده معالجك يذهب إلى معالج الأخطاء الافتراضي في telebot، الذي يطبع رقم التحديث والخطأ. اضبط OnError في tele.Settings لتغيير ذلك.
• رمزك المميز في رسائل الخطأ. يضع telebot الرمز في عنوان كل طلب (/bot يليه الرمز)، وتتضمن أخطاء الشبكة في Go هذا العنوان. يستبدل البوت أعلاه الرمز قبل أن يطبع أي خطأ. لا تشارك مخرجات وحدة التحكم الخام لبوت يطبع الأخطاء كما هي.
• إيقاف سلس. توقف اللوحة بوت Go بالضغط على Ctrl+C (SIGINT). يستمر b.Start() في العمل حتى يُستدعى b.Stop()، لذا يبدؤه البوت أعلاه في goroutine وينتظر الإشارة ثم يستدعي b.Stop()، الذي يلغي الطلب الجاري.
• التحديثات. لا يحتوي نوع Go Bot على حقل الحزم ولا على مصدر Git: وحداتك داخل البرنامج. للتحديث احذف البرنامج القديم في Files وارفع البناء الجديد ثم أعد التشغيل. مع رابط التنزيل انشر البناء الجديد على ذلك الرابط واحذف البرنامج في Files واضغط تشغيل.

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

انسخ البرنامج الذي بنيته إلى الخادم VPS؛ لا يحتاج إلى Go هناك، ولا يعتمد بناء بـ CGO_ENABLED=0 على مكتبات النظام في الخادم. أنشئ مستخدمًا للبوت وضع البرنامج في مجلده واحتفظ بالرمز المميز في ملف لا يقرؤه إلا root:

sudo useradd --system --create-home --home-dir /opt/mybot mybot
sudo install -o mybot -m 755 bot /opt/mybot/bot
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=telebot Telegram bot
Wants=network-online.target
After=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/bot
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

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

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

يرسل systemctl stop الإشارة SIGTERM افتراضيًا، والبوت أعلاه يستمع إليها أيضًا، فيتوقف بسلاسة. يعيد Restart=always تشغيل البوت بعد الانهيار أو الخروج. أوقف أي نسخة أخرى أولًا: مع telebot لا يُظهر 409 Conflict شيئًا في journalctl أيضًا.

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

على VPS تديره بنفسك تتولى:

• تحديثات نظام التشغيل وأمانه.
• نسخ كل بناء جديد وملف الخدمة وملف الرمز المميز وصلاحياته.
• قراءة journalctl لمعرفة سبب توقف البوت.
• النسخ الاحتياطية لبيانات البوت.

في المقابل يشغّل VPS أي شيء، ويمكنك أن تمنحه نطاقًا بـ HTTPS من أجل webhook.

في خطة بوتات PlayNHost تتولى اللوحة ذلك عنك:

• صورة Debian تشغّل برنامج Linux x86-64، وفحص عند البدء يخبرك إذا كان الملف بناءً لنظام Windows أو macOS.
• الرفع في Files، أو رابط تنزيل يجلبه السيرفر عند البدء.
• الرمز المميز، يُتحقق منه مع Telegram ويُخزَّن مشفرًا ويُعطى لبرنامجك باسم TELEGRAM_BOT_TOKEN وTOKEN.
• إعادة تشغيل البوت بعد الانهيار. وإذا انهار مرة أخرى خلال دقيقة يبقى متوقفًا وتذكر Console السبب.
• زر إزالة الـ webhook في قسم Telegram، وتنبيه فوق Console عندما يطبع بوتك أن Telegram رفضت الرمز.

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

هل أستخدم telebot v3 أم v4؟

الإصدار v3.3.8 (6 أغسطس 2024) هو أحدث إصدار مستقر، وهو الذي قسناه. انتقل العمل إلى v4: فهو الفرع الافتراضي للمستودع ويثبّت README الخاص به gopkg.in/telebot.v4، لكنه ما زال نسخة تجريبية (v4.0.0-beta.10، 16 يونيو 2026). تضيف النسخ التجريبية من v4 إصدارات أحدث من واجهة Telegram Bot API، حتى Bot API 10.1 في v4.0.0-beta.10، وهو ما لا يتوفر في v3.3.8. مثال البدء في README هو نفسه في الاثنين عدا مسار الاستيراد. يعمل كلاهما بالطريقة نفسها على سيرفراتنا: ابنِ وارفع وشغّل.

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

في أغلب الأحيان تكون نسخة أخرى تستعلم بالرمز المميز نفسه، على حاسوبك أو على استضافة قديمة، أو يكون webhook مضبوطًا. لا يطبع telebot أيًا من المشكلتين، فتبدو وحدة التحكم طبيعية. أوقف النسخة الأخرى، أو ألغِ الرمز في @BotFather والصق الجديد في قسم Telegram؛ وتحقق في القسم نفسه من وجود webhook. ولرؤية السبب أعد التشغيل مرة واحدة مع Verbose: true.

هل يمكنني استخدام webhook في telebot بدل الاستعلام الدوري؟

ليس بعد. يحتاج الـ webhook إلى عنوان HTTPS عام، وخططنا لا تتضمنه بعد. لا يحتاج LongPoller إلى عنوان: يطلب البوت الرسائل الجديدة من Telegram، مع انتظار مدته 10 ثوانٍ في البوت أعلاه.

telebot أم go-telegram/bot؟

كلاهما يعمل بالطريقة نفسها على نوع Go Bot. في اختبارنا استهلك go-telegram/bot مقدار 11 MB مقابل 11 MB لـ telebot، فلا تحسم الذاكرة الاختيار بينهما. أحدث إصدار من go-telegram/bot هو v1.27.0 بتاريخ 11 سبتمبر 2026. وإن كنت تتبع شرحًا تعليميًا فاستخدم المكتبة التي يستخدمها.

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