Skip to content

DEPLOY.fa.md

Latest commit

 

History

History
194 lines (131 loc) · 13.7 KB

DEPLOY.fa.md

File metadata and controls

194 lines (131 loc) · 13.7 KB
Raw

ورود نسخه ۳٫۱: در نصب تازه رمز اولیه botpanel123 است؛ ساخت متغیر ورود لازم نیست. بعد از ورود، فرم تعیین رمز خصوصی نمایش داده می‌شود. جزئیات.

نسخه ۳: معماری Worker/SQLite حفظ شده است. برای خدمات Faoxima و ربات‌های مستقل، VAULT_KEY و راهنمای جدید را نیز بررسی کنید.

استقرار BotPanel v2 روی Cloudflare

این راهنما مخصوص نسخه ۲ است. دستورات استقرار، داده‌ها یا مخزن v1 را تغییر نمی‌دهند مگر خودتان binding/نام Worker یا وب‌هوک همان ربات را عوض کنید.

پیش‌نیاز

  • Node.js نسخه 22.16 یا جدیدتر؛
  • حساب Cloudflare با دسترسی Workers و Durable Objects SQLite؛
  • توکن ربات ساخته‌شده در BotFather؛
  • مجوزهای ادمین ربات در کانال‌ها/گروه‌های مورد نظر؛
  • برای پرداخت/پردازش ویدیو، حساب و سرویس بیرونی مربوطه.

۱. بررسی تنظیمات مخزن

در wrangler.toml نام Worker جدید است:

name = "telegram-bot-panel-v2"
main = "src/index.js"

binding و migration زیر ضروری هستند:

[[durable_objects.bindings]]
name = "BOT_STATE"
class_name = "BotCoordinator"

[[migrations]]
tag = "v2-durable-state"
new_sqlite_classes = ["BotCoordinator"]

[triggers]
crons = ["* * * * *"]

با استقرار، Cloudflare فضای Durable Object را می‌سازد؛ نیازی به ساخت دستی D1 نیست. تنظیم ASSETS و run_worker_first برای /api/*، /telegram/*، /pay/* و /internal/* را نگه دارید. مسیرهای داخلی از درخواست عمومی قابل اجرا نیستند.

اتصال اطلاعات v1

binding فعلی BOT_KV به namespace قبلی اشاره دارد. در v2 از آن فقط خوانده می‌شود و داده‌های استفاده‌شده به SQLite وارد می‌شوند. تغییرات v2 به آن namespace برنمی‌گردند.

  • تنظیمات، کاربران و محتوای قبلی به‌تدریج وارد می‌شوند.
  • نشست‌های قدیمی وارد نمی‌شوند؛ دوباره وارد پنل شوید.
  • ارسال‌های ناتمام قدیمی متوقف/نیازمند بررسی وارد می‌شوند تا دو Worker هم‌زمان همان ارسال را اجرا نکنند.
  • پس از ورود یک داده، نسخه SQLite مرجع است؛ تغییر بعدی آن در v1 به v2 همگام نمی‌شود.

اگر ربات کاملاً تازه و بدون داده قبلی می‌خواهید، یک KV namespace خالی بسازید و ID آن را در BOT_KV قرار دهید. برای هر ربات مستقل، فضای حالت مستقل لازم است؛ نسخه ۳ این کار را از «ربات‌های من» با Durable Object جدا در همان Worker انجام می‌دهد. استقرار Worker جدا هم ممکن است. نام Worker قبلی را جایگزین نکنید مگر قصد ارتقای همان استقرار را دارید.

۲. نصب و ورود Cloudflare

npm ci
npx wrangler login
npm run build

npm run build فایل CSS ثابت و فونت/آیکون محلی را آماده می‌کند؛ پنل در زمان اجرا به Tailwind CDN یا Google Fonts نیاز ندارد. فایل‌های تولیدشده داخل public/ در مخزن هم موجودند.

۳. secretهای ضروری

npx wrangler secret put WEBHOOK_SECRET
npx wrangler secret put BOT_TOKEN
  • ADMIN_PASSWORD فقط یک جایگزین اختیاری است. بدون آن و بدون رمز خصوصی قبلی، ورود اولیه با botpanel123 انجام می‌شود؛ تغییر رمز از داخل پنل است. رکورد رمز ذخیره‌شده بر متغیر اختیاری اولویت دارد.
  • WEBHOOK_SECRET: مقدار تصادفی با حروف لاتین، اعداد، _ یا -؛ پیشنهاد ۳۲ کاراکتر یا بیشتر. باید برای ثبت وب‌هوک موجود باشد.
  • BOT_TOKEN: توکن BotFather. ثبت توکن از تنظیمات پنل هم ممکن است؛ مقدار ثبت‌شده در پنل بر متغیر محیطی اولویت دارد.

secretها را در سورس، wrangler.toml، کامیت یا آدرس Git remote نگذارید.

هیچ پرچم ALLOW_DEFAULT_PASSWORD لازم نیست. نشست رمز اولیه فقط به راه‌اندازی رمز خصوصی دسترسی دارد. پس از استقرار عمومی، این مرحله را بلافاصله انجام دهید؛ رمز اولیه شناخته‌شده است. برای محافظت بیشتر می‌توان انتشار اولیه را پشت Cloudflare Access انجام داد.

۴. استقرار

npm run deploy

برای کنترل خروجی بدون استقرار:

npm run build
npx wrangler deploy --dry-run

اگر از اتصال Git در Cloudflare استفاده می‌کنید، آن پروژه باید مخزن v2 و شاخه main را دنبال کند، فرمان build/deploy مناسب داشته باشد و secretها در همان محیط تنظیم شده باشند. صرف ساخت مخزن جدید اتصال Git قدیمی را جابه‌جا نمی‌کند.

۵. اتصال ربات از پنل

۱. نشانی Worker جدید را باز و وارد شوید. ۲. در تنظیمات عمومی، توکن و زبان ربات را کنترل کنید. ۳. در بخش رسانه، آزمایش اتصال و دریافت یوزرنیم را بزنید؛ یوزرنیم برای دیپ‌لینک‌ها لازم است. ۴. در مدیریت وب‌هوک، «ثبت وب‌هوک» را بزنید. این کار URL جدید، secret و انواع updateهای لازم از جمله chat_member و channel_post را ثبت می‌کند. ۵. با یک کاربر آزمایشی، /start را در ربات بفرستید.

هر توکن تلگرام فقط یک وب‌هوک فعال دارد. ثبت وب‌هوک v2 برای همان توکن، دریافت update در Worker قبلی را متوقف می‌کند؛ این تغییر باید آگاهانه باشد. این مخزن هنگام صرف استقرار، خودکار وب‌هوک را جابه‌جا نمی‌کند.

برای گروه‌ها، ربات را ادمین کنید و دسترسی حذف/محدودسازی بدهید. تنظیم Privacy Mode در BotFather و مجوز دریافت updateهای گروه را بررسی کنید. گروه کشف‌شده در پنل تا فعال‌سازی مدیر خاموش می‌ماند.

۶. فعال‌کردن آپلود مستقیم

در تنظیمات فایل و رسانه:

  • آیدی مدیر برای چت ذخیره‌سازی: مدیر باید قبلاً ربات را شروع کرده باشد؛ یا
  • کانال/گروه اختصاصی رسانه: ربات مجوز ارسال و ترجیحاً حذف پیام داشته باشد.

فایل به این چت موقت فرستاده، file_id ذخیره و پیام موقت حذف می‌شود. مسیر دریافت فایل برای مرورگر نیازمند نشست مدیر است. اگر حذف پیام موقت مجوز نداشته باشد، فایل در چت ذخیره‌سازی باقی می‌ماند؛ چت را خصوصی و فقط در اختیار افراد مورد اعتماد نگه دارید.

بعد از انتخاب فایل، پایان آپلود را منتظر بمانید. حد این نسخه عکس ۱۰ MiB و سایر رسانه‌ها/فایل‌ها ۲۰ MiB است. در صورت تغییر ربات، فایل‌های متعلق به توکن قبلی را دوباره آپلود کنید.

۷. پرداخت فروشگاه

کارت‌به‌کارت

در تنظیمات فروشگاه، شماره کارت، صاحب کارت، چت اعلان مدیر و مهلت رزرو را وارد کنید. با سفارش آزمایشی، عکس/PDF فیش را بفرستید و دستی بررسی کنید. محصول آماده فقط پس از تأیید و عبور از قفل عضویت تحویل می‌شود.

زرین‌پال اختیاری

npx wrangler secret put ZARINPAL_MERCHANT_ID
npx wrangler secret put PUBLIC_BASE_URL

PUBLIC_BASE_URL مثل https://telegram-bot-panel-v2.YOUR-SUBDOMAIN.workers.dev، بدون مسیر اضافی باشد. ثبت موفق وب‌هوک نیز مبدأ همین پنل را برای ساخت callback ذخیره می‌کند؛ متغیر محیطی بر آن اولویت دارد.

برای محیط آزمایشی ارائه‌دهنده، در محیط مربوطه ZARINPAL_SANDBOX=true تنظیم کنید. در محیط واقعی این مقدار نباید فعال باشد. برنامه مبلغ را به ریال تبدیل و در سرور verify می‌کند. URL بازگشت به تنهایی اثبات پرداخت نیست.

پس از اتصال merchant، پرداخت موفق/ناموفق، callback تکراری، پرداخت دیرهنگام، موجودی تمام‌شده و تحویل ناموفق را با تراکنش آزمایشی کنترل کنید. تست خودکار مخزن، سرویس درگاه را شبیه‌سازی می‌کند؛ merchant واقعی در این محیط استفاده نشده است.

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

۸. پردازش ویدیو اختیاری

npx wrangler secret put MEDIA_PROCESSOR_URL
npx wrangler secret put MEDIA_PROCESSOR_SECRET

آدرس باید HTTPS و سرویس مورد اعتماد خودتان باشد. قرارداد ورودی/خروجی در راهنمای v2 آمده است. خود FFmpeg/سرویس پردازشگر در این مخزن مستقر نمی‌شود. تا اتصال آن، تبدیل ویدیو، فشرده‌سازی و واترمارک ویدیو خطای «سرویس تنظیم نشده» می‌دهند؛ واترمارک عکس آپلودی پنل مستقل و در مرورگر کار می‌کند.

۹. تست و پایش

npm test
npm run smoke
npm run build
npx wrangler tail

برای مرورگر فقط روی محیط محلی جدا:

cp .dev.vars.example .dev.vars
npx playwright install --with-deps chromium
npm run dev
# در ترمینال دیگر:
npm run test:ui

این آزمون محصول/دسته/تخفیف آزمایشی می‌سازد و ارتباط رسانه تلگرام را در مرورگر شبیه‌سازی می‌کند. برای اجرای تست روی رمز متفاوت:

E2E_BASE_URL=http://127.0.0.1:8787 E2E_ADMIN_PASSWORD='LOCAL-TEST-PASSWORD' npm run test:ui

در توسعه محلی، Cron خودکار Cloudflare اجرا نمی‌شود؛ Alarm مربوط به Durable Object وجود دارد و برای آزمایش Cron می‌توان مسیر محلی زیر را فراخواند:

curl http://127.0.0.1:8787/cdn-cgi/local/scheduled

در استقرار واقعی، cron یک‌دقیقه‌ای و alarm صف را جلو می‌برند. تأخیر شبکه، محدودیت نرخ تلگرام و سقف منابع Cloudflare روی زمان واقعی اثر دارند. خطاهای ارسال، گزارش‌های مدیریت، صف‌ها و اعلان‌های سفارش را پایش کنید. برای چند گروه پرترافیک، قبل از استفاده گسترده آزمون بار و سیاست پشتیبان‌گیری/نگهداری داده تعیین کنید.

عیب‌یابی کوتاه

خطا اقدام
durable_object_binding_required binding و migration مربوط به BOT_STATE وجود ندارد؛ wrangler.toml v2 را کامل مستقر کنید.
password_change_required با رمز اولیه وارد شده‌اید؛ رمز خصوصی را از فرم راه‌اندازی داخلی تعیین کنید.
upload_chat_required چت موقت آپلود را در تنظیمات رسانه ثبت کنید.
media_belongs_to_another_bot فایل برای توکن دیگری است؛ دوباره آپلود کنید.
قفل عضویت باز نمی‌شود آیدی‌ها، لینک دعوت و ادمین‌بودن ربات در همه مقصدها را بررسی کنید.
فیش تأیید شده ولی فایل نرسیده عضویت خریدار، وضعیت تحویل هر قلم و خطای تلگرام را در جزئیات سفارش ببینید.
needs_review در ارسال مقصد را بررسی کنید؛ نتیجه شبکه نامشخص بوده و ارسال خودکار تکرار نشده است.
حالت شب باز نمی‌شود ربات باید مجوز تغییر دسترسی داشته باشد؛ خطاهای گروه و نوبت سرور را بررسی کنید.
منبع خودکار چیزی نفرستاد اسکن اول خط مبناست؛ پست جدید، نوع فید و دسترسی ربات در مبدأ/مقصد را بررسی کنید.

توکن دسترسی GitHub برای استقرار یا کارکرد ربات لازم نیست؛ آن را به Worker ندهید.