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

> آموزش اجرای ربات تلگرام روی سرور مجازی لینوکس: ساخت ربات، python-telegram-bot 22.8، توکن امن، سرویس systemd، لاگ، Webhook با Nginx و رفع خطاهای رایج.

- صفحه: https://hakanserver.com/run-telegram-bot-on-vps/
- تاریخ انتشار: ۲۱ آبان ۱۴۰۵ (2026-11-12)
- دسته: سرور
- زمان مطالعه: حدود 22 دقیقه

![ربات تلگرام با آنتن هواپیمای کاغذی روی رک سرور، کنار فلش ری‌استارت خودکار و قفل امنیتی](https://hakanserver.com/wp-content/uploads/2026/11/run-telegram-bot-on-vps.jpg)

برای اجرای ۲۴ ساعتهٔ ربات تلگرام روی سرور، کد را روی یک سرور مجازی لینوکس خارج از ایران، در کشوری که تلگرام را محدود نکرده، بگذارید و با 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 هم کافی است، اما نسخه‌های قدیمی‌تر نه. ربات به محیط گرافیکی نیاز ندارد و یک [سرور لینوکس](https://hakanserver.com/buy-a-virtual-server/linux-server/) با 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](https://hakanserver.com/connect-to-linux-server-via-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/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: [فعال‌سازی فایروال در لینوکس](https://hakanserver.com/enabling-firewall-in-linux/)). سپس در `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` هم باید از قبل اضافه شده باشد.

فهرست کامل‌تر در مقالهٔ [۹ راهکار برای افزایش امنیت سرور لینوکس](https://hakanserver.com/%D8%A7%D9%81%D8%B2%D8%A7%DB%8C%D8%B4-%D8%A7%D9%85%D9%86%DB%8C%D8%AA-%D8%B3%D8%B1%D9%88%D8%B1-%D9%84%DB%8C%D9%86%D9%88%DA%A9%D8%B3/) آمده است.

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

برای بیشتر ربات‌ها یک [سرور مجازی خارجی](https://hakanserver.com/buy-a-virtual-server/buying-a-foreign-virtual-server/) کوچک با Ubuntu کافی است و چند ربات سبک، هر کدام با سرویس systemd خودش، روی همان سرور جا می‌شوند؛ لازم نیست برای هر ربات سرور جدا بگیرید. سرور مجازی هاکان سرور در ۵۲ لوکیشن ارائه می‌شود. برای ربات تلگرام لوکیشنی خارج از ایران و در کشوری انتخاب کنید که تلگرام را محدود نکرده باشد (مثلاً روسیه از سال ۲۰۲۶ دسترسی به تلگرام را محدود کرده است) و بعد از تحویل، دسترسی را با همان دستور curl بخش اول بسنجید. سیستم‌عامل‌های قابل تحویل بسته به لوکیشن فرق می‌کند؛ لینوکس روی همهٔ لوکیشن‌ها هست و اگر ویندوز یا سیستم‌عامل خاصی لازم دارید، پیش از خرید با تیکت بپرسید. تحویل سرویس خودکار و کمتر از یک ساعت است. برای Webhook هم بدانید که IP سرویس تا زمانی که سرویس تمدید شود ثابت می‌ماند.

اگر ربات شما Webhook است و به‌شکل اپ Flask یا Django نوشته شده، شاید [هاست پایتون](https://hakanserver.com/buy-hosting-and-domain/python-host/) کافی باشد؛ پیش از خرید از پشتیبانی بپرسید که سرور هاست به 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` بزرگ‌تر می‌شود.

- مطلب قبلی: [اتصال دامنه به کلودفلر: تغییر نیم‌سرور، SSL، کش و رفع خطای 522](https://hakanserver.com/connect-domain-to-cloudflare/index.md)
- مطلب بعدی: [خطای 504 Gateway Timeout؛ علت‌یابی و رفع در Nginx، Apache و وردپرس](https://hakanserver.com/504-gateway-timeout/index.md)

## مقاله‌های مرتبط

- [چگونه از سرور ابری ایران استفاده کنیم؟ کاربرد، محدودیت و راه‌اندازی](https://hakanserver.com/%DA%86%DA%AF%D9%88%D9%86%D9%87-%D8%A7%D8%B2-%D8%B3%D8%B1%D9%88%D8%B1-%D8%A7%D8%A8%D8%B1%DB%8C-%D8%A7%DB%8C%D8%B1%D8%A7%D9%86-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%DA%A9%D9%86%DB%8C%D9%85%D8%9F/index.md)
- [سرور مجازی لینوکس چیست؟ تفاوت با ویندوز و شروع کار با VPS لینوکس](https://hakanserver.com/%D8%B3%D8%B1%D9%88%D8%B1-%D9%85%D8%AC%D8%A7%D8%B2%DB%8C-%D9%84%DB%8C%D9%86%D9%88%DA%A9%D8%B3-%DA%86%DB%8C%D8%B3%D8%AA/index.md)
- [نصب n8n روی سرور مجازی با داکر و دامنه؛ از HTTPS تا بکاپ](https://hakanserver.com/install-n8n-on-vps/index.md)

## سرویس‌های مرتبط هاکان سرور

- [سرور مجازی](https://hakanserver.com/buy-a-virtual-server/index.md): ۵۲ لوکیشن در ایران و خارج
- [سرور اختصاصی](https://hakanserver.com/dedicatedserver/index.md): ایران و ۸ کشور دیگر
- [هاست و دامنه](https://hakanserver.com/buy-hosting-and-domain/index.md): هاست سی‌پنل ایران و اروپا

فهرست همهٔ مقاله‌ها: https://hakanserver.com/blog/index.md
فهرست همهٔ صفحه‌ها و راهنمای سایت: https://hakanserver.com/llms.txt
