آموزش استفاده از ابزار BotCTL

۱. ورود به cPanel و باز کردن Terminal

cPanel پنل مدیریت هاست شماست؛ فایل‌ها، دیتابیس و ترمینال را از همین صفحه مدیریت می‌کنید. برای ورود، اطلاعات سرویس فعال خود را آماده داشته باشید.

1. وارد ناحیهٔ کاربری پایتون هاست شوید؛ از حسابی استفاده کنید که هاست را با آن تهیه کرده‌اید.
2. در بخش سرویس‌ها، هاست فعال خود را باز کنید و گزینهٔ ورود به cPanel را بزنید. اگر لینک ورود مستقیم ندارید، از آدرس و اطلاعات ورودِ پیام فعال‌سازی سرویس استفاده کنید.
3. پس از ورود، صفحهٔ اصلی cPanel را می‌بینید. نام ابزار موردنیاز، مثل File Manager یا Terminal را در کادر جست‌وجوی پنل بنویسید.

نام کاربری cPanel را از اطلاعات سرویس پیدا کنید. هر جا در فرمان‌ها USERNAME دیدید، همین نام را جایگزین کنید؛ این مقدار، ایمیل یا نام نمایشی حساب شما نیست.

این راهنما برای رباتی است که فایل‌ها و کتابخانه‌های آن روی هاست آماده‌اند. اگر هنوز آن‌ها را منتقل نکرده‌اید، ابتدا آموزش استقرار ربات روی cPanel را از ورود به پنل تا نصب پکیج‌ها انجام دهید.

1. در جست‌وجوی cPanel، Terminal را پیدا و باز کنید.
2. اگر پیام اولین ورود نمایش داده شد، آن را بخوانید و I understand and want to proceed را بزنید.
3. فرمان‌های این مقاله را یکی‌یکی در Terminal وارد کنید و بعد از هر کدام Enter بزنید.

برای دیدن فایل‌ها، File Manager را باز کنید و به پوشهٔ ربات در Home بروید. نام فایل شروع، مثلاً bot.py، و مسیر همین پوشه را یادداشت کنید. اگر BotCTL در سرویس شما فعال نیست، پشتیبانی دسترسی آن را بررسی می‌کند.

۲. افزودن ربات به BotCTL

BotCTL ابزار مدیریت اجرای ربات است؛ به آن فرمان شروع و پوشهٔ پروژه را می‌دهیم تا بتوانیم اجرا، توقف و لاگ‌ها را کنترل کنیم. مثال اصلی این مقاله با نام دلخواه mybot ثبت می‌شود؛ در مراحل بعد از همین نام استفاده کنید.

وارد پوشهٔ پروژه شوید. USERNAME نام کاربری هاست و path/to/bot مسیر ربات شماست:

cd /home/USERNAME/path/to/bot
    

سپس ربات را اضافه کنید. mybot نام دلخواه شما در BotCTL است و --workdir پوشهٔ کاری برنامه را تعیین می‌کند.

botctl add mybot 'python3 bot.py' --workdir /home/USERNAME/path/to/bot
    

نمونهٔ بالا از python3 استفاده می‌کند؛ فقط وقتی آن را انتخاب کنید که پکیج‌ها برای همین Python نصب شده‌اند. اگر محیط مجازی دارید، از الگوی زیر به‌جای فرمان قبلی استفاده کنید. مسیر .venv/bin/python را با مسیر واقعی محیط پروژه هماهنگ کنید:

botctl add mybot '/home/USERNAME/path/to/bot/.venv/bin/python bot.py' --workdir /home/USERNAME/path/to/bot
    

یک مثال با نام و مسیر متفاوت

botctl add telegram 'python3 bot.py' --workdir /home/myuser/telegrambot
    

در مثال آخر، نام حساب myuser و نام ثبت‌شدهٔ ربات telegram است. لازم نیست همهٔ مثال‌ها را اجرا کنید؛ یک فرمان ثبتِ متناسب با پروژهٔ خود انتخاب کنید و فقط یک بار آن را اجرا کنید.

۳. مشاهدهٔ لیست ربات‌ها

با دستور list، ربات‌های ثبت‌شده را ببینید. خروجی، وضعیت اجرا، شناسهٔ پردازش یا PID و وضعیت Autostart را نشان می‌دهد.

botctl list
    

در خروجی، نام mybot را پیدا کنید. PID شمارهٔ پردازشِ در حال اجراست؛ Autostart یعنی اجرای خودکار. ثبت بودن نام به‌تنهایی کافی نیست؛ در مرحلهٔ کنترل، ربات را با start روشن می‌کنیم.

۴. مشاهدهٔ وضعیت یک ربات

برای دیدن وضعیت یک ربات، نامی را که هنگام افزودن انتخاب کرده‌اید در دستور status بنویسید. در مثال‌های این راهنما، نام ربات mybot است.

botctl status mybot
    

۵. خواندن لاگ‌ها

لاگ، پیام‌های برنامه و جزئیات خطا را نشان می‌دهد. با این سه فرمان، آخرین خروجی، نمایش زنده و ۱۰۰ خط آخر را در اختیار دارید.

آخرین لاگ‌ها

botctl logs mybot
    

نمایش زنده با -f

botctl logs mybot -f
    

۱۰۰ خط آخر با -n

botctl logs mybot -n 100
    

در نمایش زنده، فرمان منتظر پیام‌های تازه می‌ماند. برای برگشتن به محل ورود فرمان، Ctrl+C بزنید؛ با این کار فقط دنبال‌کردن لاگ پایان می‌یابد، نه اجرای ربات.

در برنامهٔ خود، توکن یا رمز را در خروجی چاپ نکنید. برای ارسال گزارش به پشتیبانی نیز اطلاعات محرمانه را از متن لاگ حذف کنید.

۶. اجرا، توقف و ری‌استارت

Start برنامه را اجرا می‌کند، Stop آن را متوقف می‌کند و Restart اجرای فعلی را دوباره راه‌اندازی می‌کند. در هر فرمان، نام ربات خودتان را جایگزین mybot کنید.

اجرا — Start

botctl start mybot
    

توقف — Stop

botctl stop mybot
    

اجرای مجدد — Restart

botctl restart mybot
    

پس از start، فرمان botctl status mybot را اجرا کنید و سپس در تلگرام به ربات پیام بفرستید. اگر برنامه متوقف شد یا پاسخ نداد، ۱۰۰ خط آخر لاگ را ببینید. قبل از start، اجرای مستقیم همان ربات در Terminal را با Ctrl+C متوقف کرده باشید.

۷. تنظیم راه‌اندازی خودکار

با فعال‌بودن Autostart، برنامه پس از ریبوت سرور و در صورت Crash شدن دوباره اجرا می‌شود. فرمان enable این قابلیت را فعال و disable آن را غیرفعال می‌کند.

فعال‌کردن Autostart

botctl enable mybot
    

غیرفعال‌کردن Autostart

botctl disable mybot
    

برای ادامهٔ کار معمولاً start و سپس enable را انجام می‌دهید. بعد از دیدن وضعیت اجرا، Terminal و cPanel را ببندید و دوباره در تلگرام پیام بفرستید؛ پاسخ ربات نشان می‌دهد اجرای آن مستقل از نشست ترمینال ادامه دارد.

۸. حذف ربات از BotCTL

برای حذف تعریف ربات از BotCTL از فرمان remove استفاده کنید:

botctl remove mybot
    

برای حذف همراه با فایل لاگ، گزینهٔ --purge-log را اضافه کنید. قبل از حذف لاگ، اطلاعات موردنیاز برای عیب‌یابی را نگه دارید.

botctl remove mybot --purge-log
    

۹. فرمان اجرای درست برای BotCTL

BotCTL خودش برنامه را در پس‌زمینه مدیریت می‌کند؛ فرمانی که به آن می‌دهید باید در حالت Foreground اجرا شود. یعنی فرمان تا وقتی برنامه فعال است، همان پردازش را نگه دارد.

نمونهٔ صحیح

botctl add telegram 'python3 bot.py' --workdir /home/myuser/telegrambot
    

نمونهٔ اشتباه — اجرا نکنید

افزودن nohup یا & به فرمان، با این روش مدیریت سازگار نیست. از screen یا tmux نیز داخل فرمان ثبت ربات استفاده نکنید.

botctl add telegram 'nohup python3 bot.py &'