لوگوی هاکان سرور
لوگوی هاکان سرور

اجرای ربات تلگرام روی سرور مجازی؛ ۲۴ ساعته با پایتون و systemd

ربات تلگرام با آنتن هواپیمای کاغذی روی رک سرور، کنار فلش ری‌استارت خودکار و قفل امنیتی
فهرست مطالب
  1. چرا ربات تلگرام باید روی سرور خارج از ایران باشد؟
  2. چرا سرور داخل ایران جواب نمی‌دهد؟
  3. هاست اشتراکی، هاست پایتون یا سرور مجازی؟
  4. Polling یا Webhook؛ ربات چطور پیام می‌گیرد؟
  5. انتخاب سرور و منابع لازم برای ربات
  6. ساخت ربات و آماده‌سازی سرور Ubuntu
  7. ساخت ربات در BotFather
  8. تست توکن روی سرور
  9. نصب پایتون، کاربر سرویس و کتابخانه
  10. کد ربات و نگهداری امن توکن
  11. ساخت فایل محیطی برای توکن
  12. اجرای ۲۴ ساعته ربات با systemd
  13. فعال‌سازی و تست بازیابی خودکار
  14. لاگ‌ها و به‌روزرسانی کد
  15. ربات Node.js با PM2
  16. راه‌اندازی Webhook با Nginx و HTTPS
  17. عیب‌یابی خطاهای رایج ربات روی سرور
  18. خطاهای زمان راه‌اندازی
  19. خطاهای حین کار
  20. عیب‌یابی Webhook
  21. امنیت توکن و محدودیت‌های ارسال تلگرام
  22. اگر توکن لو رفت
  23. محدود کردن دستورهای مدیریتی
  24. محدودیت‌های ارسال پیام (Rate Limit)
  25. امنیت خود سرور
  26. سرور مجازی برای ربات تلگرام در هاکان سرور
  27. پرسش‌های متداول
  28. آیا می‌توان ربات تلگرام را روی سرور ایران اجرا کرد؟
  29. برای ربات تلگرام چه مقدار رم و CPU لازم است؟
  30. آیا ربات تلگرام روی هاست اشتراکی اجرا می‌شود؟
  31. Polling بهتر است یا Webhook؟
  32. چطور چند ربات را روی یک سرور اجرا کنم؟
  33. چرا ربات بعد از بستن SSH خاموش می‌شود؟
  34. جمع‌بندی

برای اجرای ۲۴ ساعتهٔ ربات تلگرام روی سرور، کد را روی یک سرور مجازی لینوکس خارج از ایران، در کشوری که تلگرام را محدود نکرده، بگذارید و با systemd سرویسی بسازید که بعد از هر خطا یا ریبوت خودش دوباره بالا بیاید. در این راهنما همهٔ مراحل را با پایتون و کتابخانهٔ python-telegram-bot، از ساخت ربات در BotFather تا Webhook و عیب‌یابی، قدم‌به‌قدم می‌بینید.

بیشتر آموزش‌ها ربات را با screen یا اجرای دستی python bot.py روشن نگه می‌دارند؛ روشی که با اولین خطای شبکه یا ریبوت سرور ربات را خاموش می‌کند. خیلی از کدهای آماده هم هنوز برای نسخهٔ ۱۳ کتابخانه نوشته شده‌اند (Updater و use_context) و روی نسخه‌های فعلی اجرا نمی‌شوند. دستورهای این مقاله در آبان ۱۴۰۵ با مستندات رسمی python-telegram-bot 22.8، Bot API تلگرام و systemd روی Ubuntu 24.04 و 26.04 تطبیق داده شده‌اند.

به‌طور خلاصه: اجرای دائمی ربات تلگرام روی سرور در ۶ گام:

  1. یک سرور مجازی لینوکس خارج از ایران و در کشوری که تلگرام در آن محدود نیست؛ برای بیشتر ربات‌ها ۱ هسته و ۱ گیگابایت رم کافی است.
  2. ساخت ربات با دستور /newbot در BotFather و گرفتن توکن.
  3. نصب python3-venv، ساخت محیط مجازی و نصب python-telegram-bot==22.8.
  4. نگهداری توکن در فایل /etc/echobot/echobot.env با دسترسی 600، نه داخل کد.
  5. ساخت سرویس systemd با Restart=always و کاربر غیر root، سپس systemctl enable --now.
  6. دیدن لاگ‌ها با journalctl -u echobot -f؛ Webhook اختیاری است و HTTPS می‌خواهد.

چرا ربات تلگرام باید روی سرور خارج از ایران باشد؟

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

چرا سرور داخل ایران جواب نمی‌دهد؟

ربات هر پیام را با درخواست به api.telegram.org می‌فرستد. در روش Polling پیام‌های تازه را هم از همین آدرس می‌گیرد و در روش Webhook سرورهای تلگرام (رنج‌های 149.154.160.0/20 و 91.108.4.0/22) پیام‌ها را به سرور شما می‌فرستند. تلگرام از اردیبهشت ۱۳۹۷ در ایران فیلتر است و از سرورهای داخل ایران معمولاً هیچ‌کدام از این مسیرها برقرار نمی‌شود. پیش از نصب هر چیزی، دسترسی سرور را بسنجید:

curl -sS -o /dev/null -w '%{http_code}\n' --max-time 10 https://api.telegram.org/

اگر 302 چاپ شد، سرور به API تلگرام دسترسی دارد. هر نتیجهٔ دیگر، مثلاً 000 همراه با خطای curl: (28) (Timeout)، (35) یا (7)، یعنی این سرور به تلگرام نمی‌رسد و برای ربات مناسب نیست. این تست را روی سرور خارجی هم بزنید، چون بعضی کشورهای دیگر هم دسترسی به تلگرام را محدود کرده‌اند.

دو نکتهٔ دیگر: اگر ربات باید با سرویسی داخلی کار کند که فقط به IP ایران پاسخ می‌دهد، آن بخش را به یک سرویس کوچک روی سرور داخل ایران بسپارید که نتیجه را با HTTPS به ربات برگرداند. همچنین در دوره‌های اختلال اینترنت بین‌الملل ممکن است دسترسی SSH خودتان به سرور قطع شود؛ پس ربات باید بدون دخالت شما بعد از هر خطا و ریبوت بالا بیاید، که systemd همین کار را می‌کند.

هاست اشتراکی، هاست پایتون یا سرور مجازی؟

«هاست ربات تلگرام» معمولاً یکی از این سه گزینه است. تفاوت اصلی این است که هاست معمولاً اجازهٔ پردازهٔ دائمی (Long-running Process) نمی‌دهد و فقط به درخواست‌های وب پاسخ می‌دهد:

گزینه مناسب برای محدودیت
هاست اشتراکی PHP ربات PHP ساده با Webhook Polling و پردازهٔ دائمی معمولاً مجاز نیست
هاست پایتون ربات Webhook به‌شکل اپ Flask یا Django سرور هاست باید به api.telegram.org برسد
سرور مجازی لینوکس هر ربات، Polling و Webhook، چند ربات مدیریت سرور با خودتان است

کرون‌جاب (Cron Job) پنج‌دقیقه‌ای که بعضی آموزش‌ها برای هاست پیشنهاد می‌کنند ربات را روشن نگه نمی‌دارد؛ فقط اسکریپت را هر چند دقیقه اجرا می‌کند و پاسخ‌ها دیر می‌رسد. کد همین مقاله (run_webhook با وب‌سرور داخلی) هم روی هاست پایتون اجرا نمی‌شود؛ آنجا ربات باید به‌شکل یک اپ WSGI (مثلاً Flask) نوشته شود که وب‌سرور هاست درخواست تلگرام را به آن بدهد.

Polling یا Webhook؛ ربات چطور پیام می‌گیرد؟

تلگرام دو روش برای رساندن پیام‌ها و رویدادها (Update) به ربات دارد و هم‌زمان فقط یکی فعال است:

  • Polling (دقیق‌تر: Long Polling): ربات با متد getUpdates مدام پیام تازه را از تلگرام می‌خواهد. هر درخواست چند ثانیه باز می‌ماند (در python-telegram-bot پیش‌فرض ۱۰ ثانیه) و به‌محض رسیدن پیام برمی‌گردد. اتصال را سرور شما برقرار می‌کند، پس دامنه، SSL و پورت باز لازم نیست.
  • Webhook: تلگرام هر پیام را با درخواست POST به یک آدرس HTTPS عمومی می‌فرستد. به گواهی با TLS 1.2 یا بالاتر و یکی از پورت‌های 443، 80، 88 یا 8443 نیاز دارد و فعلاً از IPv6 پشتیبانی نمی‌کند.
ویژگی Polling Webhook
HTTPS و دامنه لازم نیست HTTPS لازم است؛ با دامنه یا IP و گواهی Self-signed
پورت ورودی باز لازم نیست 443 (یا 80، 88، 8443)
سرعت پاسخ تقریباً فوری فوری
راه‌اندازی ساده معمولاً با Nginx و Certbot
مناسب برای بیشتر ربات‌ها ربات پرترافیک یا چند ربات پشت یک دامنه

پیشنهاد عملی: با Polling شروع کنید؛ برای ربات‌های معمولی تفاوت سرعت محسوس نیست. کد این مقاله هر دو حالت را پشتیبانی می‌کند و برای رفتن به Webhook فقط چند خط به تنظیمات اضافه می‌شود.

انتخاب سرور و منابع لازم برای ربات

سیستم‌عامل پیشنهادی Ubuntu 24.04 LTS یا 26.04 LTS است (به‌ترتیب با Python 3.12 و 3.14). Debian 12 و 13 هم با همین دستورها کار می‌کنند (نکتهٔ مخصوص Debian در بخش Webhook آمده است). python-telegram-bot 22.8 دست‌کم Python 3.10 می‌خواهد؛ پس Ubuntu 22.04 هم کافی است، اما نسخه‌های قدیمی‌تر نه. ربات به محیط گرافیکی نیاز ندارد و یک سرور لینوکس با Ubuntu ساده‌ترین انتخاب است.

نوع ربات منابع برای شروع نکته
متنی ساده، اعلان، ربات شخصی ۱ هسته، ۱ گیگابایت رم چند ربات سبک روی یک سرور جا می‌شوند
فروشگاهی یا عضویت با دیتابیس ۲ هسته، ۲ گیگابایت رم بیشتر رم را دیتابیس مصرف می‌کند
هوش مصنوعی با API مدل‌های خارجی ۱ تا ۲ هسته، ۱ تا ۲ گیگابایت پردازش سنگین سمت سرویس مدل است
دانلود و تبدیل ویدئو (ffmpeg) ۲ تا ۴ هسته، ۴ گیگابایت، دیسک بیشتر ترافیک ماهانه را هم حساب کنید

این اعداد نقطهٔ شروع‌اند. یک ربات ساده با python-telegram-bot معمولاً چند ده مگابایت رم مصرف می‌کند؛ بعد از راه‌اندازی، عدد واقعی را در خط Memory خروجی systemctl status ببینید. جز شرط دسترسی به تلگرام، مکان سرور اهمیت کمی دارد، چون کاربران به سرورهای تلگرام وصل می‌شوند نه به سرور شما؛ اگر ربات مدام به API خاصی درخواست می‌فرستد، لوکیشنی نزدیک به همان سرویس بگیرید.

ربات از طریق Bot API عمومی فقط فایل‌های تا ۲۰ مگابایت را دانلود و تا ۵۰ مگابایت را ارسال می‌کند. برای فایل‌های بزرگ‌تر باید سرور محلی Bot API (Local Bot API Server) را اجرا کنید که ارسال تا ۲۰۰۰ مگابایت را ممکن می‌کند و به api_id و api_hash از my.telegram.org نیاز دارد.

ساخت ربات و آماده‌سازی سرور Ubuntu

ساخت ربات در BotFather

  1. در تلگرام حساب @BotFather را باز کنید (حساب رسمی تیک تأیید آبی دارد) و /newbot را بفرستید.
  2. نام نمایشی ربات را بفرستید، مثلاً Hakan Echo Test؛ این نام بعداً قابل تغییر است.
  3. نام کاربری را بفرستید: ۵ تا ۳۲ کاراکتر از حروف لاتین، عدد و زیرخط که به bot ختم شود، مثل hakan_echo_test_bot. نام کاربری بعداً عوض نمی‌شود.
  4. BotFather توکنی شبیه 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw می‌دهد. هر کس آن را داشته باشد کنترل کامل ربات را دارد؛ در چت، تیکت یا اسکرین‌شات نفرستید.
  5. اختیاری: با /setcommands فهرست دستورها و با /setprivacy رفتار ربات در گروه‌ها را تنظیم کنید.

برای دیدن دوبارهٔ توکن، مسیر /mybots ← انتخاب ربات ← API Token را بزنید. همین تنظیمات در مینی‌اپ BotFather هم هست.

تست توکن روی سرور

با کاربری که دسترسی sudo دارد وارد سرور شوید (راهنما: آموزش اتصال به سرور لینوکسی از طریق SSH). دستورهای این بخش روی Ubuntu 24.04 و 26.04 و Debian 12 و 13 یکسان است:

sudo apt update && sudo apt upgrade -y && sudo apt install -y curl
read -rs BOT_TOKEN
curl -s --max-time 15 "https://api.telegram.org/bot${BOT_TOKEN}/getMe"; echo
unset BOT_TOKEN

بعد از read -rs توکن را بچسبانید (Paste) و Enter بزنید؛ توکن نه نمایش داده می‌شود نه در تاریخچهٔ shell می‌ماند. خروجی درست شبیه این است:

{"ok":true,"result":{"id":110201543,"is_bot":true,"first_name":"Hakan Echo Test","username":"hakan_echo_test_bot",...}}

پاسخ 401 Unauthorized یا 404 Not Found یعنی توکن اشتباه یا ناقص کپی شده یا باطل (Revoke) شده است.

نصب پایتون، کاربر سرویس و کتابخانه

sudo apt install -y python3 python3-venv
python3 --version
sudo useradd --system --shell /usr/sbin/nologin echobot
sudo mkdir -p /opt/echobot
sudo python3 -m venv /opt/echobot/.venv
echo 'python-telegram-bot==22.8' | sudo tee /opt/echobot/requirements.txt
sudo /opt/echobot/.venv/bin/pip install -r /opt/echobot/requirements.txt
/opt/echobot/.venv/bin/python -c "import telegram; print(telegram.__version__)"

خروجی python3 --version روی Ubuntu 24.04 به شکل Python 3.12.x و روی 26.04 به شکل Python 3.14.x است و دستور آخر باید 22.8 چاپ کند. چند توضیح:

  • کاربر سیستمی echobot رمز و shell ورود ندارد؛ اگر کد ربات یا یک کتابخانه آسیب‌پذیر باشد، مهاجم به root نمی‌رسد.
  • محیط مجازی (venv) لازم است، چون در Ubuntu و Debian جدید pip install روی پایتون سیستم با خطای externally-managed-environment متوقف می‌شود (PEP 668).
  • نسخه عمداً ثابت (Pin) شده تا یک به‌روزرسانی ناخواسته ربات را از کار نیندازد.
  • نام بستهٔ درست python-telegram-bot است؛ بستهٔ بی‌ربطی به نام telegram هم در PyPI هست که نصبش خطای import می‌دهد.
مسیر مالک و دسترسی کاربرد
/opt/echobot/bot.py root، برای ربات فقط‌خواندنی کد ربات
/opt/echobot/.venv root پایتون و کتابخانه‌ها
/etc/echobot/echobot.env root، 600 توکن و تنظیمات محرمانه
/var/lib/echobot echobot (ساخت خودکار) داده‌ها، مثلاً SQLite

با این چیدمان، فرایند ربات نمی‌تواند کد خودش را تغییر دهد و فقط در پوشهٔ داده‌اش می‌نویسد.

کد ربات و نگهداری امن توکن

با sudo nano /opt/echobot/bot.py فایل را بسازید و کد زیر را در آن بگذارید. این ربات هر متن را تکرار می‌کند، اما اسکلتش همان چیزی است که ربات واقعی لازم دارد:

#!/usr/bin/env python3
"""Echo bot for python-telegram-bot 22.x: polling by default, webhook if configured."""
import logging
import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters

logging.basicConfig(
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
    level=logging.INFO,
)
# httpx logs every request URL at INFO level, and that URL contains the token
logging.getLogger("httpx").setLevel(logging.WARNING)
log = logging.getLogger("echobot")

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_message.reply_text("Hi! Send me a text and I will echo it.")

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    msg = update.effective_message
    await msg.reply_text(msg.text)

async def on_error(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
    log.error("Error while handling an update", exc_info=context.error)

def main() -> None:
    token = os.environ.get("BOT_TOKEN")
    if not token:
        raise SystemExit("BOT_TOKEN is not set")

    app = Application.builder().token(token).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.add_error_handler(on_error)

    domain = os.environ.get("WEBHOOK_DOMAIN")
    if domain:
        path = os.environ.get("WEBHOOK_PATH", "tg-hook")
        app.run_webhook(
            listen="127.0.0.1",
            port=int(os.environ.get("WEBHOOK_PORT", "8080")),
            url_path=path,
            webhook_url=f"https://{domain}/{path}",
            secret_token=os.environ["WEBHOOK_SECRET"],
        )
    else:
        app.run_polling()

if __name__ == "__main__":
    main()

چهار نکته در این کد که در بیشتر نمونه‌ها نیست:

  • لاگ httpx روی WARNING است. httpx آدرس هر درخواست را در سطح INFO لاگ می‌کند و این آدرس شامل توکن است (https://api.telegram.org/bot<TOKEN>/getUpdates). بدون این خط، توکن هر چند ثانیه در لاگ سیستم نوشته می‌شود.
  • effective_message به‌جای update.message. هندلرها پیام‌های ویرایش‌شده را هم می‌گیرند و در آن‌ها update.message برابر None است؛ کد معمولی با ویرایش یک پیام خطا می‌دهد.
  • Error Handler خطای هر پیام را با جزئیات لاگ می‌کند و ربات به کارش ادامه می‌دهد.
  • توکن و حالت اجرا از متغیرهای محیطی می‌آیند: بدون WEBHOOK_DOMAIN ربات Polling اجرا می‌کند و با آن، Webhook.

ساخت فایل محیطی برای توکن

sudo install -d -m 700 /etc/echobot
sudo install -m 600 /dev/null /etc/echobot/echobot.env
sudo nano /etc/echobot/echobot.env

محتوای فایل فعلاً یک خط است؛ توکن خودتان را جایگزین کنید:

BOT_TOKEN=110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

هر متغیر را در یک خط و به شکل KEY=value بنویسید؛ گیومه لازم نیست. فایل فقط برای root خواندنی است: systemd آن را پیش از اجرای ربات می‌خواند و مقدار را به فرایند می‌دهد، بی‌آنکه کاربر echobot به خود فایل دسترسی داشته باشد. اگر کد در Git است، فایل‌های .env را در .gitignore بگذارید و هرگز توکن را commit نکنید.

اجرای ۲۴ ساعته ربات با systemd

سرویس systemd با بوت سرور اجرا می‌شود، بعد از کرش دوباره بالا می‌آید و لاگ‌هایش یک‌جا جمع می‌شود. فایل /etc/systemd/system/echobot.service را با این محتوا بسازید:

[Unit]
Description=Echo Telegram bot (python-telegram-bot)
Wants=network-online.target
After=network-online.target

[Service]
Type=exec
User=echobot
WorkingDirectory=/opt/echobot
EnvironmentFile=/etc/echobot/echobot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/opt/echobot/.venv/bin/python /opt/echobot/bot.py
Restart=always
RestartSec=5
SyslogIdentifier=echobot
StateDirectory=echobot
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
  • Type=exec: مستندات systemd آن را برای سرویس‌های دائمی توصیه می‌کند، چون خطاهایی مثل نبودن فایل اجرایی را درست گزارش می‌دهد.
  • ExecStart: پایتونِ داخل venv؛ با /usr/bin/python3 کتابخانه‌ها پیدا نمی‌شوند.
  • Restart=always و RestartSec=5: ربات بعد از هر نوع خروج، با خطا یا بدون خطا، ۵ ثانیه بعد دوباره اجرا می‌شود؛ فقط systemctl stop آن را خاموش نگه می‌دارد.
  • PYTHONUNBUFFERED=1 خروجی print را فوراً به لاگ می‌فرستد و SyslogIdentifier خطوط لاگ را با نام echobot ثبت می‌کند.
  • StateDirectory پوشهٔ /var/lib/echobot را می‌سازد. ProtectSystem=strict، ProtectHome، PrivateTmp و NoNewPrivileges ربات را از تغییر بقیهٔ دیسک، دیدن پوشه‌های خانگی و گرفتن دسترسی بیشتر بازمی‌دارند.

نکته: systemd به‌طور پیش‌فرض سرویسی را که بیش از ۵ بار در ۱۰ ثانیه شروع شود دیگر اجرا نمی‌کند. با RestartSec=5 در هر ۱۰ ثانیه حداکثر ۳ تلاش انجام می‌شود، پس ربات در قطعی طولانی شبکه هم هر ۵ ثانیه دوباره تلاش می‌کند. اگر RestartSec را حذف کنید (پیش‌فرض ۱۰۰ میلی‌ثانیه)، ممکن است در چند ثانیه به این سقف برسد و خاموش بماند.

فعال‌سازی و تست بازیابی خودکار

sudo systemd-analyze verify /etc/systemd/system/echobot.service
sudo systemctl daemon-reload
sudo systemctl enable --now echobot
systemctl status echobot --no-pager

systemd-analyze verify در حالت سالم چیزی چاپ نمی‌کند و enable --now سرویس را برای بوت فعال و همین حالا اجرا می‌کند. خروجی status شبیه این است (اعداد روی سرور شما فرق می‌کند):

● echobot.service - Echo Telegram bot (python-telegram-bot)
     Loaded: loaded (/etc/systemd/system/echobot.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-10-28 10:15:02 UTC; 12s ago
   Main PID: 2345 (python)
     Memory: 41.2M
...
Oct 28 10:15:03 vps echobot[2345]: 2026-10-28 10:15:03,871 INFO telegram.ext.Application: Application started

در تلگرام به ربات /start بفرستید تا جواب بدهد. بعد فرایند را عمداً از بین ببرید:

sudo kill -9 "$(systemctl show -p MainPID --value echobot)"
sleep 7
journalctl -u echobot -n 20 --no-pager

باید خطوط Main process exited, code=killed, status=9/KILL، سپس Scheduled restart job, restart counter is at 1 و دوباره Application started را ببینید.

لاگ‌ها و به‌روزرسانی کد

# follow live / last 100 lines / last hour / errors since boot
journalctl -u echobot -f
journalctl -u echobot -n 100 --no-pager
journalctl -u echobot --since "1 hour ago"
journalctl -u echobot -b -g "ERROR|Traceback"

# update the code safely
sudo cp /opt/echobot/bot.py /opt/echobot/bot.py.bak
sudo nano /opt/echobot/bot.py            # or: sudo git -C /opt/echobot pull
sudo /opt/echobot/.venv/bin/python -m py_compile /opt/echobot/bot.py
sudo /opt/echobot/.venv/bin/pip install -r /opt/echobot/requirements.txt
sudo systemctl restart echobot
journalctl -u echobot -n 30 --no-pager

خروجی پایتون در ژورنال با اولویت info ثبت می‌شود، پس -p err خطاهای ربات را نشان نمی‌دهد؛ به‌جای آن با -g دنبال کلمهٔ ERROR بگردید. اگر کاربرتان عضو گروه adm یا systemd-journal نیست، journalctl را با sudo بزنید. حجم ژورنال به‌طور پیش‌فرض به ۱۰ درصد دیسک و حداکثر ۴ گیگابایت محدود است (journalctl --disk-usage). py_compile خطای نگارشی را پیش از ری‌استارت نشان می‌دهد؛ اگر نسخهٔ جدید مشکل داشت، فایل .bak را برگردانید. بعد از تغییر خود فایل سرویس، sudo systemctl daemon-reload لازم است و پیش از ارتقای نسخهٔ کتابخانه، Changelog آن را بخوانید.

ربات Node.js با PM2

برای ربات Node.js (مثلاً با grammY یا Telegraf) همین سرویس systemd با ExecStart=/usr/bin/node /opt/nodebot/bot.js کار می‌کند (مسیر را با which node ببینید). گزینهٔ رایج‌تر در دنیای Node، مدیر پردازهٔ PM2 است.

بستهٔ nodejs مخزن پیش‌فرض Ubuntu 24.04 و Debian 12 نسخهٔ 18 است که پشتیبانی‌اش تمام شده و گزینهٔ --env-file را ندارد (نسخهٔ 20 در Debian 13 هم دیگر پشتیبانی نمی‌شود). یک نسخهٔ LTS، مثلاً Node.js 24، را با یکی از روش‌های صفحهٔ دانلود رسمی nodejs.org (مثل nvm) یا مخزن NodeSource نصب کنید و بعد با کاربر معمولی (نه root):

node -v
sudo npm install -g pm2@latest
cd ~/nodebot && chmod 600 .env
pm2 start bot.js --name nodebot --node-args="--env-file=$HOME/nodebot/.env"
pm2 logs nodebot
pm2 startup
pm2 save
  • --env-file (از Node.js 20.6) توکن را از فایل .env می‌خواند.
  • pm2 startup دستوری شبیه sudo env PATH=... pm2 startup systemd -u USER --hp /home/USER چاپ می‌کند؛ همان را اجرا کنید. pm2 save فهرست برنامه‌ها را برای بعد از ریبوت ذخیره می‌کند.
  • بعد از ارتقای Node.js، pm2 unstartup و دوباره pm2 startup را بزنید. اگر Node را با nvm نصب کرده‌اید، npm install -g را بدون sudo اجرا کنید.
روش بعد از ریبوت بعد از کرش مناسب برای
screen یا tmux خاموش می‌ماند خاموش می‌ماند تست و اشکال‌زدایی
nohup … & خاموش می‌ماند خاموش می‌ماند تست کوتاه
systemd اجرا می‌شود دوباره اجرا می‌شود پایتون و هر زبان دیگر
PM2 با startup و save دوباره اجرا می‌شود ربات Node.js
Docker با restart: unless-stopped دوباره اجرا می‌شود وقتی بقیهٔ سرویس‌ها هم کانتینری‌اند

راه‌اندازی Webhook با Nginx و HTTPS

این بخش اختیاری است. روش پیشنهادی این بخش یک زیردامنه می‌خواهد، مثلاً bot.example.com، با رکورد A به IPv4 سرور (رکورد AAAA به‌تنهایی کافی نیست). Nginx روی پورت 443 گواهی HTTPS را مدیریت می‌کند و درخواست‌ها را به وب‌سرور داخلی ربات روی 127.0.0.1:8080 می‌فرستد؛ پورت 8080 از بیرون دیده نمی‌شود.

گام ۱. Nginx را نصب و پورت‌های 80 و 443 را باز کنید (درباره ufw: فعال‌سازی فایروال در لینوکس). سپس در requirements.txt خط کتابخانه را به python-telegram-bot[webhooks]==22.8 تغییر دهید تا وب‌سرور tornado هم نصب شود:

sudo apt install -y nginx
sudo ufw allow 'Nginx Full'
sudo nano /opt/echobot/requirements.txt
sudo /opt/echobot/.venv/bin/pip install -r /opt/echobot/requirements.txt

نکته: روی Debian، ufw و snapd به‌طور پیش‌فرض نصب نیستند. ufw را با sudo apt install -y ufw نصب کنید. Certbot را هم می‌توانید از مخزن Debian بگیرید (sudo apt install -y certbot python3-certbot-nginx)؛ در این حالت دو دستور اول گام ۴ لازم نیست.

گام ۲. با openssl rand -hex 32 یک رمز تصادفی بسازید و این سه خط را به /etc/echobot/echobot.env اضافه کنید:

WEBHOOK_DOMAIN=bot.example.com
WEBHOOK_PATH=tg-hook-7f3a9c
WEBHOOK_SECRET=paste-the-openssl-output-here

تلگرام این رمز را در هدر X-Telegram-Bot-Api-Secret-Token هر درخواست می‌فرستد و python-telegram-bot درخواست‌های بدون آن را با 403 رد می‌کند. رمز باید ۱ تا ۲۵۶ کاراکتر از حروف لاتین، عدد، _ و - باشد. به‌جای مسیر نمونه هم یک رشتهٔ حدس‌نزدنی بگذارید.

گام ۳. فایل /etc/nginx/sites-available/echobot را بسازید و فعال کنید:

server {
    listen 80;
    server_name bot.example.com;

    location /tg-hook-7f3a9c {
        proxy_pass http://127.0.0.1:8080;
    }

    location / {
        return 404;
    }
}
sudo ln -s /etc/nginx/sites-available/echobot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

گام ۴. گواهی رایگان Let’s Encrypt را به روش رسمی Certbot بگیرید؛ Certbot بخش listen 443 ssl را به همین فایل اضافه و تمدید را خودکار می‌کند:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --nginx -d bot.example.com
sudo certbot renew --dry-run

گام ۵. ربات را ری‌استارت کنید و وضعیت Webhook را بپرسید، سپس با یک درخواست بدون رمز مطمئن شوید پاسخ 403 است:

sudo systemctl restart echobot
read -rs BOT_TOKEN
curl -s --max-time 15 "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"; echo
unset BOT_TOKEN
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'Content-Type: application/json' -d '{}' https://bot.example.com/tg-hook-7f3a9c
{"ok":true,"result":{"url":"https://bot.example.com/tg-hook-7f3a9c","has_custom_certificate":false,"pending_update_count":0,"max_connections":40,"ip_address":"203.0.113.10"}}

برای برگشتن به Polling، سه خط WEBHOOK_ را حذف و ربات را ری‌استارت کنید؛ python-telegram-bot هنگام شروع Polling، Webhook قبلی را خودش حذف می‌کند.

عیب‌یابی خطاهای رایج ربات روی سرور

قدم اول همیشه journalctl -u echobot -n 50 --no-pager است؛ متن خطا معمولاً علت را مستقیم می‌گوید.

خطاهای زمان راه‌اندازی

نشانه در لاگ علت راه‌حل
TimedOut یا NetworkError سرور به api.telegram.org نمی‌رسد تست curl؛ سرور خارج از ایران
InvalidToken: The token ... was rejected توکن اشتباه یا ناقص کپی شده، یا باطل (Revoke) شده کپی دوبارهٔ توکن از BotFather
BOT_TOKEN is not set مسیر EnvironmentFile یا نام متغیر غلط مقایسهٔ فایل محیطی با فایل سرویس
No module named 'telegram' ExecStart پایتون سیستم را اجرا می‌کند مسیر .venv/bin/python
cannot import name 'Filters' یا خطای use_context کد برای نسخهٔ ۱۳ کتابخانه است بازنویسی با Application و توابع async
status=203/EXEC مسیر ExecStart وجود ندارد بررسی مسیرها با ls
start-limit-hit کرش‌های پشت سر هم رفع علت، سپس systemctl reset-failed echobot

خطاهای حین کار

نشانه علت راه‌حل
Conflict: terminated by other getUpdates request دو نسخهٔ ربات با یک توکن pgrep -af bot.py روی همین سرور؛ اگر چیزی نبود، نسخهٔ لپ‌تاپ یا سرور قبلی را خاموش یا توکن را Revoke کنید
can't use getUpdates method while webhook is active ابزار دیگری Webhook ثبت کرده deleteWebhook؛ python-telegram-bot در Polling خودش این کار را می‌کند
'NoneType' object has no attribute 'reply_text' پیام ویرایش‌شده یا پست کانال update.effective_message
Forbidden: bot was blocked by the user کاربر ربات را بلاک کرده گرفتن خطا و حذف کاربر از فهرست ارسال
RetryAfter یا خطای 429 ارسال بیش از حد مجاز محدودکنندهٔ نرخ (بخش بعد)
ربات پیام‌های گروه را نمی‌بیند حالت Privacy که پیش‌فرض روشن است /setprivacy ← Disable و افزودن دوبارهٔ ربات

دو دام دیگر: اگر همان توکن را هم‌زمان در n8n یا سرویس دیگری به کار ببرید، هر کدام دیگری را از کار می‌اندازد؛ برای کار دوم ربات جدا بسازید. اگر ربات چند ساعت خاموش بوده و نمی‌خواهید پیام‌های قدیمی پردازش شوند، از app.run_polling(drop_pending_updates=True) استفاده کنید.

عیب‌یابی Webhook

در خروجی getWebhookInfo، pending_update_count تعداد پیام‌های در صف و last_error_message آخرین خطای تحویل است:

  • Wrong response from the webhook: 502 Bad Gateway: ربات روی پورت داخلی (پیش‌فرض 8080) بالا نیست؛ وضعیت سرویس را ببینید.
  • 404 Not Found: مسیر location در Nginx با WEBHOOK_PATH یکی نیست.
  • 403 Forbidden: Webhook را ابزار دیگری بدون همان رمز ثبت کرده؛ ری‌استارت ربات آن را درست ثبت می‌کند.
  • خطای SSL یا Timeout: رکورد A، پورت 443 و کامل بودن زنجیرهٔ گواهی را بررسی کنید و مطمئن شوید فایروال یا محدودیت جغرافیایی، رنج‌های 149.154.160.0/20 و 91.108.4.0/22 را روی پورت 443 مسدود نکرده است.

امنیت توکن و محدودیت‌های ارسال تلگرام

اگر توکن لو رفت

  1. در BotFather مسیر /mybots ← انتخاب ربات ← API Token ← Revoke current token را بزنید (یا /revoke را بفرستید). توکن قبلی همان لحظه باطل می‌شود.
  2. توکن جدید را در /etc/echobot/echobot.env بگذارید و sudo systemctl restart echobot را بزنید.
  3. توکن قدیمی را از مخزن Git و تاریخچهٔ آن، لاگ‌ها و اسکرین‌شات‌ها پاک کنید.

لاگ‌ها را بدون بازبینی منتشر نکنید؛ پیام خطای InvalidToken در python-telegram-bot خود توکن را چاپ می‌کند.

محدود کردن دستورهای مدیریتی

هر کسی می‌تواند به ربات پیام بدهد. دستورهایی مثل آمار یا ارسال همگانی را فقط برای شناسهٔ عددی مدیران فعال کنید؛ مثلاً ADMIN_IDS=123456789,987654321 را به فایل محیطی اضافه کنید و در کد:

ADMIN_IDS = {int(x) for x in os.environ.get("ADMIN_IDS", "").split(",") if x}

async def stats(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.effective_user.id not in ADMIN_IDS:
        return
    await update.effective_message.reply_text("Admin only: stats here")

# in main(), next to the other handlers:
# app.add_handler(CommandHandler("stats", stats))

ورودی کاربر را نامعتبر فرض کنید: حجم فایل‌ها را محدود کنید و متن کاربر را مستقیم در دستور shell یا کوئری SQL نگذارید.

محدودیت‌های ارسال پیام (Rate Limit)

طبق راهنمای رسمی ربات‌های تلگرام، در یک چت بیش از یک پیام در ثانیه نفرستید، در یک گروه حداکثر ۲۰ پیام در دقیقه و در ارسال انبوه حدود ۳۰ پیام در ثانیه؛ فقط ربات‌های بزرگ (دست‌کم ۱۰۰ هزار کاربر فعال ماهانه) می‌توانند با Paid Broadcasts در BotFather و پرداخت Stars این سقف را تا ۱۰۰۰ پیام در ثانیه بالا ببرند. بیش از این خطای 429 می‌گیرید که در python-telegram-bot با استثنای RetryAfter گزارش می‌شود. برای ارسال همگانی، محدودکنندهٔ داخلی کتابخانه را فعال کنید: در requirements.txt بنویسید python-telegram-bot[rate-limiter]==22.8 (با Webhook: [webhooks,rate-limiter])، pip را دوباره اجرا و کد را این‌طور تغییر دهید:

from telegram.ext import AIORateLimiter

app = Application.builder().token(token).rate_limiter(AIORateLimiter()).build()

امنیت خود سرور

  • ورود SSH با کلید و بستن ورود با رمز برای root.
  • در حالت Polling هیچ پورت ورودی جز SSH لازم نیست: sudo ufw allow OpenSSH و بعد sudo ufw enable.
  • نصب منظم به‌روزرسانی‌های امنیتی و ارتقای کتابخانه‌ها پس از تست.
  • بکاپ از کد، فایل محیطی و پوشهٔ /var/lib/echobot.

هشدار: پروفایل OpenSSH در ufw فقط پورت 22 را باز می‌کند. اگر SSH روی پورت دیگری است، پیش از ufw enable همان پورت را باز کنید (مثلاً sudo ufw allow 2222/tcp) و تا ورود موفق در یک نشست SSH تازه، نشست فعلی را نبندید. اگر Webhook دارید، قانون Nginx Full هم باید از قبل اضافه شده باشد.

فهرست کامل‌تر در مقالهٔ ۹ راهکار برای افزایش امنیت سرور لینوکس آمده است.

سرور مجازی برای ربات تلگرام در هاکان سرور

برای بیشتر ربات‌ها یک سرور مجازی خارجی کوچک با Ubuntu کافی است و چند ربات سبک، هر کدام با سرویس systemd خودش، روی همان سرور جا می‌شوند؛ لازم نیست برای هر ربات سرور جدا بگیرید. سرور مجازی هاکان سرور در ۵۲ لوکیشن ارائه می‌شود. برای ربات تلگرام لوکیشنی خارج از ایران و در کشوری انتخاب کنید که تلگرام را محدود نکرده باشد (مثلاً روسیه از سال ۲۰۲۶ دسترسی به تلگرام را محدود کرده است) و بعد از تحویل، دسترسی را با همان دستور curl بخش اول بسنجید. سیستم‌عامل‌های قابل تحویل بسته به لوکیشن فرق می‌کند؛ لینوکس روی همهٔ لوکیشن‌ها هست و اگر ویندوز یا سیستم‌عامل خاصی لازم دارید، پیش از خرید با تیکت بپرسید. تحویل سرویس خودکار و کمتر از یک ساعت است. برای Webhook هم بدانید که IP سرویس تا زمانی که سرویس تمدید شود ثابت می‌ماند.

اگر ربات شما Webhook است و به‌شکل اپ Flask یا Django نوشته شده، شاید هاست پایتون کافی باشد؛ پیش از خرید از پشتیبانی بپرسید که سرور هاست به api.telegram.org دسترسی دارد یا نه. پشتیبانی فنی ۲۴ ساعته از طریق تیکت در دسترس است.

پرسش‌های متداول

آیا می‌توان ربات تلگرام را روی سرور ایران اجرا کرد؟

در عمل نه. تلگرام در ایران فیلتر است و سرورهای داخل ایران معمولاً به api.telegram.org دسترسی ندارند؛ پس ربات نه پیام می‌گیرد نه می‌فرستد. ربات پیام‌رسان‌های داخلی را اما می‌توان روی سرور داخل ایران اجرا کرد.

برای ربات تلگرام چه مقدار رم و CPU لازم است؟

برای ربات متنی ساده ۱ هسته و ۱ گیگابایت رم کافی است. ربات دارای دیتابیس را با ۲ گیگابایت و ربات پردازش ویدئو را با ۴ گیگابایت شروع کنید.

آیا ربات تلگرام روی هاست اشتراکی اجرا می‌شود؟

فقط ربات‌های Webhook که به‌شکل اپ وب (PHP یا WSGI) نوشته شده‌اند، به‌شرطی که سرور هاست به API تلگرام برسد. ربات‌های Polling پردازهٔ دائمی می‌خواهند که هاست‌ها معمولاً اجازه نمی‌دهند.

Polling بهتر است یا Webhook؟

برای بیشتر ربات‌ها Polling ساده‌تر است و دامنه و SSL نمی‌خواهد. Webhook وقتی ارزش دارد که ترافیک بالا دارید، چند ربات را پشت یک دامنه اجرا می‌کنید یا ربات بخشی از یک اپ وب است.

چطور چند ربات را روی یک سرور اجرا کنم؟

برای هر ربات پوشه، venv، فایل محیطی و فایل سرویس جدا بسازید، مثلاً shopbot.service و newsbot.service. در حالت Webhook برای هر ربات یک مسیر جدا در Nginx بسازید و در فایل محیطی هر ربات WEBHOOK_PORT جدا بگذارید (مثلاً 8081 و 8082)؛ در proxy_pass هر مسیر هم همان پورت را بنویسید.

چرا ربات بعد از بستن SSH خاموش می‌شود؟

چون مستقیم در ترمینال اجرا شده و با بسته شدن نشست SSH فرایندش هم بسته می‌شود. ربات را به سرویس systemd تبدیل کنید تا مستقل از نشست شما و بعد از ریبوت هم اجرا شود.

جمع‌بندی

برای اجرای ربات تلگرام روی سرور سه چیز لازم است: سروری خارج از ایران که به api.telegram.org برسد، کدی که توکن را از فایل محیطی بخواند و سرویس systemd با Restart=always که ربات را بعد از هر خطا و ریبوت بدون دخالت شما بالا بیاورد. با Polling شروع کنید و Webhook را فقط با دلیل مشخص اضافه کنید.

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