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

فهرست مطالب
- چرا ربات تلگرام باید روی سرور خارج از ایران باشد؟
- چرا سرور داخل ایران جواب نمیدهد؟
- هاست اشتراکی، هاست پایتون یا سرور مجازی؟
- Polling یا Webhook؛ ربات چطور پیام میگیرد؟
- انتخاب سرور و منابع لازم برای ربات
- ساخت ربات و آمادهسازی سرور Ubuntu
- ساخت ربات در BotFather
- تست توکن روی سرور
- نصب پایتون، کاربر سرویس و کتابخانه
- کد ربات و نگهداری امن توکن
- ساخت فایل محیطی برای توکن
- اجرای ۲۴ ساعته ربات با systemd
- فعالسازی و تست بازیابی خودکار
- لاگها و بهروزرسانی کد
- ربات Node.js با PM2
- راهاندازی Webhook با Nginx و HTTPS
- عیبیابی خطاهای رایج ربات روی سرور
- خطاهای زمان راهاندازی
- خطاهای حین کار
- عیبیابی Webhook
- امنیت توکن و محدودیتهای ارسال تلگرام
- اگر توکن لو رفت
- محدود کردن دستورهای مدیریتی
- محدودیتهای ارسال پیام (Rate Limit)
- امنیت خود سرور
- سرور مجازی برای ربات تلگرام در هاکان سرور
- پرسشهای متداول
- آیا میتوان ربات تلگرام را روی سرور ایران اجرا کرد؟
- برای ربات تلگرام چه مقدار رم و CPU لازم است؟
- آیا ربات تلگرام روی هاست اشتراکی اجرا میشود؟
- Polling بهتر است یا Webhook؟
- چطور چند ربات را روی یک سرور اجرا کنم؟
- چرا ربات بعد از بستن SSH خاموش میشود؟
- جمعبندی
برای اجرای ۲۴ ساعتهٔ ربات تلگرام روی سرور، کد را روی یک سرور مجازی لینوکس خارج از ایران، در کشوری که تلگرام را محدود نکرده، بگذارید و با 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 تطبیق داده شدهاند.
بهطور خلاصه: اجرای دائمی ربات تلگرام روی سرور در ۶ گام:
- یک سرور مجازی لینوکس خارج از ایران و در کشوری که تلگرام در آن محدود نیست؛ برای بیشتر رباتها ۱ هسته و ۱ گیگابایت رم کافی است.
- ساخت ربات با دستور
/newbotدر BotFather و گرفتن توکن.- نصب
python3-venv، ساخت محیط مجازی و نصبpython-telegram-bot==22.8.- نگهداری توکن در فایل
/etc/echobot/echobot.envبا دسترسی 600، نه داخل کد.- ساخت سرویس systemd با
Restart=alwaysو کاربر غیر root، سپسsystemctl enable --now.- دیدن لاگها با
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
- در تلگرام حساب
@BotFatherرا باز کنید (حساب رسمی تیک تأیید آبی دارد) و/newbotرا بفرستید. - نام نمایشی ربات را بفرستید، مثلاً
Hakan Echo Test؛ این نام بعداً قابل تغییر است. - نام کاربری را بفرستید: ۵ تا ۳۲ کاراکتر از حروف لاتین، عدد و زیرخط که به
botختم شود، مثلhakan_echo_test_bot. نام کاربری بعداً عوض نمیشود. - BotFather توکنی شبیه
110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsawمیدهد. هر کس آن را داشته باشد کنترل کامل ربات را دارد؛ در چت، تیکت یا اسکرینشات نفرستید. - اختیاری: با
/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 مسدود نکرده است.
امنیت توکن و محدودیتهای ارسال تلگرام
اگر توکن لو رفت
- در BotFather مسیر
/mybots← انتخاب ربات ← API Token ← Revoke current token را بزنید (یا/revokeرا بفرستید). توکن قبلی همان لحظه باطل میشود. - توکن جدید را در
/etc/echobot/echobot.envبگذارید وsudo systemctl restart echobotرا بزنید. - توکن قدیمی را از مخزن 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 بزرگتر میشود.


