آموزش راه‌اندازی ربات تلگرام روی هاست cPanel

قبل از شروع؛ هدف این آموزش چیست؟

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

یک سرویس فعال و سازگار با اجرای پایتون، دسترسی به Telegram Bot API، فایل‌های ربات و توکن BotFather لازم دارید. برای شناخت محیط اجرا، راهنمای منابع میزبانی را ببینید. اگر فایل ربات ندارید، نمونهٔ کوتاه همین آموزش را برای یادگیری مراحل استقرار استفاده کنید. این نمونه با python-telegram-bot==22.8 و Python 3.10 یا بالاتر کار می‌کند.

نام پوشهٔ نمونه telegrambot و نام فایل اصلی bot.py است. هر جا USERNAME آمده، نام کاربری cPanel خودتان را بنویسید. نام فایل و پوشهٔ پروژهٔ موجودتان ممکن است متفاوت باشد؛ فرمان‌ها را با همان نام‌ها هماهنگ کنید.

۱. ورود به cPanel

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

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

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

دو ابزار این راهنما File Manager و Terminal هستند. File Manager برای انتقال و ویرایش فایل‌هاست؛ Terminal فرمان‌های پایتون را روی هاست اجرا می‌کند.

۲. ساخت پوشه و آپلود فایل‌های ربات

1. در cPanel، File Manager را باز کنید و از ستون کناری Home را انتخاب کنید.
2. با + Folder پوشه‌ای به نام telegrambot در Home بسازید و وارد آن شوید. این پوشه باید کنار public_html باشد، نه داخل آن.
3. اگر ربات آماده دارید، فایل‌های پروژه را روی رایانه ZIP کنید؛ پوشهٔ محیط مجازی، Git و توکن را داخل ZIP نگذارید.
4. Upload را بزنید و فایل را آپلود کنید. پس از تکمیل، به File Manager برگردید، ZIP را انتخاب و Extract را بزنید.

فایل شروع باید مستقیم داخل پوشهٔ پروژه باشد؛ در مثال ما /home/USERNAME/telegrambot/bot.py. اگر ZIP یک پوشهٔ اضافی ساخته، فایل‌های داخل آن را با Move به telegrambot منتقل کنید.

۳. آماده کردن bot.py و requirements.txt

اگر کد ربات آماده است، همان فایل اصلی را نگه دارید و به مرحلهٔ بعد بروید. اگر نمونهٔ ساده می‌خواهید، داخل پوشهٔ telegrambot با + File فایل bot.py را بسازید؛ آن را با Edit باز کنید، کد زیر را قرار دهید و Save Changes را بزنید.

import logging
import os
from pathlib import Path
from dotenv import load_dotenv
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if update.effective_message:
        await update.effective_message.reply_text("سلام! ربات پایتونی شما آماده است.")

def main():
    load_dotenv(Path(__file__).resolve().with_name(".env"))
    token = os.environ["TELEGRAM_BOT_TOKEN"]
    logging.basicConfig(level=logging.WARNING)
    app = Application.builder().token(token).build()
    app.add_handler(CommandHandler("start", start))
    app.run_polling()

if __name__ == "__main__":
    main()
    

این ربات به دستور /start پاسخ می‌دهد. خط load_dotenv توکن را از فایل خصوصی .env کنار bot.py می‌خواند؛ در هر اجرای تازه نیز همان فایل خوانده می‌شود. برای ساخت قابلیت‌های ربات خودتان، کد پروژه را جایگزین نمونه کنید.

فایل requirements.txt فهرست کتابخانه‌های موردنیاز است. برای همین نمونه، آن را با + File بسازید، دو خط زیر را در Edit قرار دهید و ذخیره کنید:

python-telegram-bot==22.8
python-dotenv
    

برای ربات موجود، requirements.txt خود پروژه را آپلود کنید. اگر به آن نیاز دارید، در محیط مجازیِ فعال پروژه روی رایانه، فرمان python -m pip freeze > requirements.txt فهرست پکیج‌های همان محیط را می‌سازد.

۴. ذخیرهٔ توکن در فایل خصوصی .env

توکن، کلید دسترسی برنامه به ربات شماست. اگر ربات را قبلاً در BotFather ساخته‌اید، توکن همان ربات را آماده کنید. در صورت نداشتن ربات، با /newbot نام و نام کاربری آن را ثبت و توکن را دریافت کنید.

1. در File Manager روی Settings بزنید، Show Hidden Files (dotfiles) را فعال و Save کنید تا فایل‌های شروع‌شده با نقطه دیده شوند.
2. داخل telegrambot، با + File فایلی به نام دقیق .env بسازید؛ نقطهٔ اول نام را حذف نکنید.
3. فایل را با Edit باز کنید، خط زیر را قرار دهید و مقدار نمونه را با توکن واقعی خود جایگزین و ذخیره کنید.

TELEGRAM_BOT_TOKEN=PASTE_YOUR_BOTFATHER_TOKEN_HERE
    

توکن را در Git، ZIP عمومی یا پیام پشتیبانی قرار ندهید. فایل .env باید در همین پوشهٔ خصوصی بیرون public_html بماند. اگر توکن منتشر شد، از BotFather توکن تازه بگیرید.

برای رباتی که کد آن آماده است، روش تنظیم توکن باید با کد همان پروژه هماهنگ باشد؛ ساخت .env به‌تنهایی کافی نیست. نمونهٔ بالا آن را با python-dotenv می‌خواند، اما پروژهٔ شما باید خواندن این فایل را پشتیبانی کند یا تنظیم ماندگار دیگری داشته باشد.

۵. باز کردن Terminal و نصب کتابخانه‌ها

از صفحهٔ اصلی cPanel، Terminal را جست‌وجو و باز کنید. در اولین ورود، پیام را بخوانید و I understand and want to proceed را بزنید. فرمان‌های زیر را یکی‌یکی وارد کنید و بعد از هر خط Enter بزنید:

cd /home/USERNAME/telegrambot
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -c "import sys; print(sys.executable)"
    

1. در خط اول USERNAME را با نام کاربری هاست جایگزین کنید؛ این فرمان وارد پوشهٔ ربات می‌شود.
2. خط دوم نسخهٔ Python را نشان می‌دهد. برای نمونهٔ این مقاله، شماره باید 3.10 یا بالاتر باشد؛ پیش از ساخت محیط، نسخه را ببینید.
3. فرمان venv یک محیط مجازی به نام .venv می‌سازد؛ کتابخانه‌های ربات داخل همین محیط نصب می‌شوند.
4. source محیط را فعال می‌کند. دو فرمان pip نصب پکیج‌ها را انجام می‌دهند؛ تا پایان نصب صبر کنید.
5. خط آخر مسیر دقیق Python را نشان می‌دهد؛ آن را برای مرحلهٔ ثبت در BotCTL یادداشت کنید.

اگر python3 قدیمی است، ابتدا مسیر نسخهٔ جدیدِ نصب‌شده روی هاست را از پشتیبانی بگیرید و در فرمان ساخت venv به‌جای python3 قرار دهید. نمونهٔ مسیر در CloudLinux می‌تواند /opt/alt/python311/bin/python3.11 باشد؛ فقط وقتی از وجود آن در حساب خود مطمئن هستید از آن استفاده کنید.

اگر نصب با خطا تمام شد، هنوز ربات را اجرا نکنید. پیام خطا مشخص می‌کند نسخهٔ پایتون، پکیج یا فایل requirements.txt کدام بخش را باید اصلاح کنید.

۶. اجرای اولیه و دیدن پاسخ ربات

پس از آماده شدن bot.py، .env و کتابخانه‌ها، در Terminal فرمان‌های زیر را اجرا کنید. خط chmod دسترسی فایل توکن را به مالک حساب محدود می‌کند.

cd /home/USERNAME/telegrambot
chmod 600 .env
.venv/bin/python bot.py
    

اکنون ربات را در تلگرام باز کنید و /start بفرستید. در نمونهٔ این مقاله باید پیام «سلام! ربات پایتونی شما آماده است.» دریافت کنید. اگر پاسخی نیامد، پیام Terminal را بخوانید؛ جدول خطاهای پایین مقاله به شما کمک می‌کند.

برای پایان این اجرا Ctrl+C بزنید. اجرای اولیه را حتماً متوقف کنید و سپس به BotCTL بروید؛ هم‌زمان دو پردازش polling با یک توکن اجرا نکنید.

۷. ثبت ربات و اجرای مداوم با BotCTL

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

botctl add telegram '/home/USERNAME/telegrambot/.venv/bin/python /home/USERNAME/telegrambot/bot.py' --workdir /home/USERNAME/telegrambot
    

telegram نام ربات در BotCTL است؛ این نام با نام کاربری تلگرام فرق دارد. مسیر Python باید همان خروجی مرحلهٔ نصب باشد. مسیر آخرِ فرمان، پوشهٔ کاری برنامه را مشخص می‌کند. اگر نام فایل شما main.py است، به‌جای bot.py همان را بنویسید.

فرمان ثبت را فقط یک بار برای همین نام اجرا کنید. سپس ربات را روشن کنید و راه‌اندازی خودکار را فعال کنید:

botctl start telegram
botctl enable telegram
botctl status telegram
    

Start ربات را اجرا می‌کند. Enable راه‌اندازی خودکار را فعال می‌کند و Status وضعیت فعلی را نشان می‌دهد. باید وضعیت اجرا را ببینید؛ اگر برنامه فوراً متوقف شد، لاگ را در مرحلهٔ بعد بخوانید.

توکن نمونه از فایل .env خوانده می‌شود و فرمان BotCTL از مسیر کامل Python استفاده می‌کند؛ بنابراین اجرای بعدی به فعال‌بودن محیط مجازی یا متغیر موقت در نشست Terminal وابسته نیست.

۸. لاگ، به‌روزرسانی و پایان کار

برای دیدن پیام‌های آخر و خطاهای برنامه، این فرمان را اجرا کنید:

botctl logs telegram -n 100
    

وقتی ربات پاسخ داد و Status اجرای آن را نشان داد، Terminal و مرورگر را ببندید و دوباره در تلگرام /start بفرستید. ربات باید از اجرای BotCTL پاسخ دهد؛ این مرحله پایان استقرار اولیه است.

برای انتشار نسخهٔ جدید، فایل‌های تغییرکرده را در File Manager آپلود یا ویرایش کنید. اگر requirements.txt تغییر کرده، وارد پوشه شوید و .venv/bin/python -m pip install -r requirements.txt را اجرا کنید. سپس فرمان زیر را بزنید و پاسخ ربات را دوباره ببینید:

botctl restart telegram
    

برای توقف، botctl stop telegram و برای غیرفعال‌کردن اجرای خودکار، botctl disable telegram را به کار ببرید. راهنمای همهٔ فرمان‌ها در آموزش BotCTL آمده است.

رفع خطاهای استقرار ربات روی cPanel