راهنمای تصویری گام‌به‌گام
مقاله آموزشی Telegram Bot Expert Installer
با Telegram Bot Expert Installer از طریق مرورگر محلی ویندوز به سرور لینوکس متصل شوید، ربات تلگرام را با Webhook یا Polling نصب کنید و وضعیت، لاگ، سلامت و بکاپ‌های آن را کنترل نمایید.
معماری و امکانات هسته برنامه
- اجرای محلی ایمن: برنامه پس از اجرای
Start-Expert.bat(یا نصب PowerShell) رویhttp://127.0.0.1:4780/بالا می‌آید و ارتباط مستقیم SSH با VPS برقرار می‌کند. - تشخیص خودکار پشته پروژه: پس از اتصال به Ubuntu، Debian، AlmaLinux یا Rocky Linux، پیش‌نیازهای
Python،Node.js،Go،PHPیاDockerرا تشخیص داده و سرویسsystemdرا می‌سازد. - پشتیبانی ۴ زبانه و پوسته دوگانه: از منوی بالای صفحه همیشه می‌توانید زبان را بین فارسی، انگلیسی، روسی و چینی و حالت را بین روشن و تیره تغییر دهید.
مسیر سریع استفاده از ویزارد تا نگهداری
- ۱. اجرا روی ویندوز: نصب با
install-expert.ps1یا استخراج ZIP و باز کردنStart-Expert.bat(در اولین اجرا چند دقیقه برای نصب پکیج‌ها صبر کنید). - ۲. نصب با ویزارد ۶ مرحله‌ای: انتخاب
WebhookیاPolling← اتصال SSH ← اسکن سرور ← اطلاعات ربات (@BotFather) ← انتخاب Git یا مسیر موجود ← نصب نهایی. - ۳. نگهداری و بازیابی: مدیریت سرویس در
Dashboard، مشاهدهLogs، تعمیر درHealthو پشتیبان‌گیری منظم درBackup.
۱. داشبورد و کنترل سرویس ربات (Dashboard)
پس از باز شدن http://127.0.0.1:4780/، صفحه Dashboard نمای لحظه‌ای وضعیت ربات و منابع VPS را در ۴ کارت اصلی نشان می‌دهد:
- کارت‌های وضعیت: نمایش زنده
Bot status(در حال اجرا یا متوقف)،Mode(حالت Polling یا Webhook)،VPS(میزان مصرف و مشخصاتCPU · RAM · Disk)، نام و یوزرنیم ربات (@) و وضعیت بوت خودکار (Service / Start on boot). - دکمه‌های کنترلی سرویس: با یک کلیک ربات را
Start،StopیاRestartکنید و باEnable on Boot/Disable on Bootاجرای خودکار بعد از ریستارت VPS را تعیین نمایید. - نوار زبان و پوسته: در بالای صفحه دکمه
Languageبرای تغییر بین فارسی/انگلیسی/روسی/چینی و دکمهThemeبرای پوسته تیره یا روشن قرار دارد.
نکته شروع: در اولین نصب تا زمانی که مراحل ویزارد تمام نشود وضعیت ربات
Stopped یا Offline نمایش داده می‌شود؛ پس از پایان ویزارد خودکار به داشبورد متصل هدایت می‌شوید.
۲. نصب ربات با ویزارد ۶ مرحله‌ای (Install bot — Webhook / Polling)
در تب Install bot ابتدا یکی از دو مسیر نصب را انتخاب کرده و Start install steps را بزنید:
- انتخاب مسیر نصب:
Install with Webhookبرای سرورهای دارای دامنه، ایمیل گواهی SSL و Nginx (با پیش‌نمایش تنظیمات دامنه و پورت داخلی پیش‌فرض8080)؛ یاInstall without Webhook(حالتPolling) بدون نیاز به دامنه و SSL. - گام‌های ۱ و ۲ — اتصال SSH به VPS: آی‌پی سرور (
Host)، پورت (22)، نام کاربری (root) و روش احراز هویت با رمز عبور یا کلید خصوصی SSH را وارد و دکمه تست اتصال را بزنید. - گام ۳ — شناسایی خودکار سرور: سیستم‌عامل، معماری، هسته‌های CPU، حافظه RAM، فضای دیسک، آی‌پی عمومی، نسخه کرنل، پورت‌های باز و آماده بودن پیش‌نیازها به‌طور خودکار بررسی و نمایش داده می‌شود.
- گام‌های ۴ و ۵ — تنظیمات ربات و منبع کد: توکن ربات از
@BotFather، نام، یوزرنیم، شناسه ادمین، شناسه پشتیبانی، زبان، منطقه زمانی و مسیر نصب (پیش‌فرض/opt/telegram-bot) را ثبت کنید؛ سپس منبع کد را از مخزنGit(آدرس + شاخهmain) یا پوشه موجود روی سرور مشخص و نصب واقعی را اجرا نمایید.
توصیه کاربردی: اگر هنوز دامنه متصل به سرور ندارید، بدون تردید مسیر
Install without Webhook (Polling) را انتخاب کنید تا در سریع‌ترین زمان ربات فعال شود.
۳. مشاهده و دانلود گزارش‌های زنده سرویس (Logs)
برای پیگیری عملکرد ربات، خطاهای کد یا بررسی پاسخ‌های تلگرام وارد تب Logs شوید:
- خواندن مستقیم لاگ سرور: تمام خروجی سرویس ربات روی VPS را با یک کلیک و دکمه
Refreshبه‌صورت زنده بخوانید. - پاک‌سازی نمای فعلی: دکمه
Clearصفحه نمایش لاگ را برای بررسی رویدادهای جدید خلوت می‌کند. - خروجی فایل متنی (
Download log): گزارش‌های فعلی را در فایلbot.logروی سیستم ویندوز ذخیره کنید تا در عیب‌یابی یا اشتراک با توسعه‌دهنده استفاده شود.
۴. پایش سلامت و تعمیر خودکار (Health & Repair)
بخش‌های Health و Repair وضعیت سرویس، وابستگی‌ها و اتصالات را از نگاه فنی بررسی می‌کنند:
- بررسی سلامت (
Health check): هر مورد حیاتی (اتصال، سرویس systemd، پورت‌ها یا پیکربندی) با وضعیت واضحOKیا نیازمند بررسی نمایش داده می‌شود. - تعمیر تک‌کلیکی (
Auto-Fix / Repair): برای مواردی که قابلیت تعمیر خودکار دارند، دکمه اصلاح کنار همان خطا ظاهر می‌شود و پس از اجرا دوباره سلامت را تست می‌کند.
قبل از حذف نصب یا نصب مجدد: همیشه یک‌بار بخش
Health را اجرا کنید؛ بسیاری از خطاهای سرویس یا پورت با دکمه Auto-Fix بلافاصله برطرف می‌شوند.
۵. پشتیبان‌گیری و بازگردانی (Backup & Restore)
پیش از هر بروزرسانی عمده کد یا تغییر تنظیمات سرور، در تب Backup یک نقطه امن بسازید:
- ساخت بکاپ جدید (
Create Backup): از فایل‌های برنامه و پیکربندی ربات روی سرور فایل فشرده.tgzهمراه با فایل مشخصات.meta.jsonایجاد می‌شود. - بازگردانی سریع (
Restore): در صورت بروز مشکل پس از تغییر کد، کنار بکاپ دلخواه دکمهRestoreرا بزنید و پس از تایید، ربات به وضعیت قبل بازمی‌گردد. - مدیریت فضا (
Delete): بکاپ‌های قدیمی و غیرضروری را مستقیماً از همین جدول حذف کنید.
۶. حذف کنترل‌شده نصب و ارتباط و آپدیت (Uninstall & Contact)
در دو تب پایانی کنترل کامل پاک‌سازی سرویس و دریافت بروزرسانی‌های برنامه را در اختیار دارید:
- سه سطح حذف در تب
Uninstall: گزینه‌های مجزایRemove app(فقط حذف برنامه و حفظ داده‌ها)،Remove app and data(حذف برنامه و داده‌ها) و دکمه قرمزRemove everything(پاک‌سازی کامل سرویس، برنامه، تنظیمات Nginx و داده‌ها). - تب
Contact: دسترسی مستقیم به وب‌سایت رسمی، صفحه گیت‌هابBlackFoxGroupو دکمهUpdateبرای بررسی بروزرسانی ابزار.
هشدار ایمنی: قبل از زدن
Remove everything مطمئن شوید فایل‌های data/ یا بکاپ‌های مورد نیاز خود را قبلاً دانلود یا ذخیره کرده‌اید.
۷. سوالات متداول و عیب‌یابی (FAQ)
| سوال یا خطا | علت احتمالی | راه‌حل پیشنهادی |
|---|---|---|
| خطای Test the VPS connection first در بخش Logs یا Health | هنوز نشست فعالی با سرور VPS متصل نشده است. | وارد تب Install bot شده و اطلاعات SSH را ثبت یا اتصال را برقرار کنید. |
| در حالت Webhook خطای بررسی دامنه می‌دهد | رکورد DNS دامنه به آی‌پی سرور اشاره نمی‌کند یا پورت ۸۰/۴۴۳ بسته است. | رکورد A دامنه را بررسی کنید یا برای نصب فوری گزینه Install without Webhook (Polling) را بزنید. |
| بعد از Start-Expert.bat صفحه مرورگر دیر باز می‌شود | در اولین اجرا ابزار در حال نصب پکیج‌ها و بیلد پروژه با npm است. | پنجره مشکی ترمینال را نبندید و چند دقیقه صبر کنید تا http://127.0.0.1:4780/ باز شود. |
| نیازمند انتقال یا ارتقای ربات بدون از دست دادن داده‌ها هستم | نیاز به نسخه پشتیبان پیش از تغییر تنظیمات یا حذف کد دارید. | در تب Backup یک .tgz بسازید و در صورت حذف جزئی از گزینه Remove app استفاده کنید. |
| چگونه از افشای توکن ربات و کلید SSH جلوگیری کنم؟ | پوشه‌های محلی برنامه حاوی کلیدهای رمزنگاری‌شده هستند. | هرگز فایل‌های data/، .env و master.key را در گیت یا فضای عمومی آپلود نکنید. |