پیکربندی¶
همه‌چیز یک بار، موقع بالا آمدن، از محیط خوانده می‌شود، در shared/settings.py.
روی سرور آن فایل /opt/kasbbook/.env است، با دسترسی 600، نوشتهٔ نصب‌کننده.
هر مقدار پیش‌فرض امنی دارد جز آن دوتایی که نمی‌توانند داشته باشند: توکن ربات و کلید امضا.
هسته¶
| متغیر | پیش‌فرض | توضیح |
|---|---|---|
KASBBOOK_DATABASE_URL |
sqlite+aiosqlite:///kasbbook.db |
پیش‌فرض SQLite است تا برنامه‌نویس بتواند بدون بالا آوردن پستگرس ربات را اجرا کند. محیط عملیاتی بازنویسی‌اش می‌کند. |
REDIS_URL |
(تنظیم‌نشده) | بدونش، وضعیت گفتگو و محدودیت نرخ درون‌پروسه‌اند — روی یک کارگر درست، روی چندتا غلط. |
KASBBOOK_LOG_LEVEL |
INFO |
httpx و httpcore در هر حال روی WARNING قفل‌اند، چون نشانی کامل درخواست را لاگ می‌کنند و در همهٔ این APIها توکن داخل مسیر است. |
این پروسه کدام پیام‌رسان را اجرا می‌کند¶
یک پروسه، یک پیام‌رسان.
| متغیر | پیش‌فرض | توضیح |
|---|---|---|
KASBBOOK_PROVIDER |
telegram |
telegram، bale یا rubika. مقدار ناشناخته موقع بالا آمدن با فهرست گزینه‌ها شکست می‌خورد. |
هر پیام‌رسان اعتبارنامهٔ خودش را می‌خواند، پس پروسهٔ بله نمی‌تواند بی‌سروصدا با توکن تلگرام بالا بیاید:
| پیام‌رسان | توکن | نام‌کاربری | راز وب‌هوک |
|---|---|---|---|
| تلگرام | TELEGRAM_BOT_TOKEN |
TELEGRAM_BOT_USERNAME |
TELEGRAM_WEBHOOK_SECRET |
| بله | BALE_BOT_TOKEN |
BALE_BOT_USERNAME |
— |
| روبیکا | RUBIKA_BOT_TOKEN |
RUBIKA_BOT_USERNAME |
— |
نام‌کاربری فقط برای ساختن پیوند عمیق لازم است (t.me/…?start=…). بدونش
create_deep_link خطا می‌دهد، به‌جای ساختن پیوندی که به جایی نمی‌رسد.
فقط تلگرام راز وب‌هوک دارد؛ توکنی را که ثبت کرده‌ایم در یک هدر بازتاب می‌دهد. بله و روبیکا هیچ چیزی را امضا نمی‌کنند — برای اینکه به‌جایش چه می‌کنیم امنیت را ببین.
برای اجرای پیام‌رسان دوم: یونیت و فایل محیط را کپی کن.
sudo cp /etc/systemd/system/kasbbook-bot.service /etc/systemd/system/kasbbook-bale.service
# EnvironmentFile را به /opt/kasbbook/.env.bale اشاره بده
# در آن فایل: KASBBOOK_PROVIDER=bale و BALE_BOT_TOKEN=...
هر دو پروسه یک دیتابیس دارند، و نکته هم همین است: حسابی که به هر دو پیام‌رسان وصل باشد یک مجموعه دفتر دارد.
رابط برنامه‌نویسی¶
| متغیر | پیش‌فرض | توضیح |
|---|---|---|
KASBBOOK_SECRET_KEY |
ندارد | توکن دسترسی را امضا می‌کند. API بدونش بالا نمی‌آید. تولیدش کن، هرگز تایپش نکن. |
KASBBOOK_ACCESS_MINUTES |
30 |
توکن دسترسی قابل باطل‌کردن نیست، پس کوتاه است. |
KASBBOOK_REFRESH_DAYS |
30 |
توکن تازه‌سازی در هر استفاده از دیتابیس خوانده می‌شود، پس می‌شود باطلش کرد. |
KASBBOOK_CORS_ORIGINS |
(تنظیم‌نشده) | با ویرگول جدا شده. هرگز *: این نقاط پایانی اعتبارنامه حمل می‌کنند. |
KASBBOOK_TRUSTED_PROXY |
(تنظیم‌نشده) | فقط وقتی تنظیمش کن که پراکسی خودت جلوی برنامه باشد. باعث می‌شود X-Forwarded-For برای محدودیت نرخ معتبر شمرده شود — بدون پراکسی واقعی، هر کسی می‌تواند آن هدر را بگذارد و محدودیت نرخ تزئینی می‌شود. |
KASBBOOK_WEB_URL |
(تنظیم‌نشده) | نشانی پایه در پیوندهایی که ربات می‌فرستد. |
KASBBOOK_DOCS_URL |
(سایت همین پروژه) | راهنمای نوشتاری‌ای که ربات کنار مرجع API به آن پیوند می‌دهد. نرم‌افزار را مستند می‌کند نه استقرار تو را، و به همین دلیل اصلاً پیش‌فرض دارد؛ اگر نسخه‌ات جدا افتاده به مال خودت اشاره بده، یا خالی بگذار تا دکمه حذف شود. |
KASBBOOK_UPDATE_MODE |
polling |
polling یا webhook. پولینگ یک اتصال خروجی نگه می‌دارد و لازم نیست چیزی از بیرون در دسترس باشد. وب‌هوک نقطهٔ پایانی HTTPS عمومی می‌خواهد و به‌روزرسانی‌هایی را که هنگام راه‌اندازی مجدد API می‌رسند از دست می‌دهد، چون سرویس‌دهنده مدتی تلاش می‌کند و بعد رها می‌کند. |
KASBBOOK_WEBHOOK_PATH |
(تنظیم‌نشده) | بخش غیرقابل‌حدس در /webhooks/<provider>/<secret>. در حالت وب‌هوک اجباری است. تولیدش کن، هرگز انتخابش نکن. |
KASBBOOK_API_URL |
(تنظیم‌نشده) | جایی که API منتشر شده، مثلاً https://kasbbook.example.com. ربات از صفحهٔ APIاش به <url>/docs پیوند می‌دهد؛ تنظیم‌نبودنش یعنی بی‌پیوند، نه پیوند مرده. |
برای تولید کلید:
انبارهای داده¶
deploy/.env، که docker compose می‌خواندش. آن را هم نصب‌کننده می‌نویسد.
| متغیر | پیش‌فرض |
|---|---|
POSTGRES_DB |
kasbbook |
POSTGRES_USER |
kasbbook |
POSTGRES_PASSWORD |
(تولیدشده) |
POSTGRES_PORT |
5435 |
REDIS_PORT |
6382 |
هر دو فقط به 127.0.0.1 گوش می‌دهند. پورت‌ها غیرمعمول‌اند چون روی سروری نوشته
شدند که ۵۴۳۲ تا ۵۴۳۴ و ۶۳۸۰ تا ۶۳۸۱ در آن اشغال بود؛ راحت عوضشان کن.
این‌ها عمداً پستگرس خودِ سرور نیستند. آن نمونه ناوگانی از سرویس‌های بی‌ربط را حمل می‌کند، و اشتراکش یک مهاجرت بی‌احتیاط را مسئلهٔ همه می‌کرد.
عملیاتی¶
اسکریپت‌ها می‌خوانندشان، نه خود برنامه.
| متغیر | پیش‌فرض |
|---|---|
KASBBOOK_HOME |
/opt/kasbbook |
KASBBOOK_BRANCH |
main |
KASBBOOK_BACKUP_DIR |
/var/backups/kasbbook |
KASBBOOK_BACKUP_KEEP |
14 |
آزمون¶
| متغیر | اثر |
|---|---|
KASBBOOK_TEST_POSTGRES_URL |
tests/test_migrations_postgres.py را فعال می‌کند. بدونش آن شش تست رد می‌شوند، و به همین دلیل لپ‌تاپی بدون پستگرس هم بقیهٔ مجموعه را اجرا می‌کند. |
یک فایل کامل عملیاتی¶
KASBBOOK_PROVIDER=telegram
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_BOT_USERNAME=KasbBook_BOT
KASBBOOK_DATABASE_URL=postgresql+asyncpg://kasbbook:PASSWORD@127.0.0.1:5435/kasbbook
REDIS_URL=redis://127.0.0.1:6382/0
KASBBOOK_SECRET_KEY=GENERATED-48-BYTES
KASBBOOK_ACCESS_MINUTES=30
KASBBOOK_REFRESH_DAYS=30
KASBBOOK_LOG_LEVEL=INFO
اگر توکنی درز کرد¶
اینجا اتفاق افتاده. httpx نشانی کامل درخواست را در سطح INFO لاگ می‌کند، و
نشانی تلگرام توکن را در خود دارد، پس یک جلسهٔ اشکال‌زدایی یکی را در ژورنال
گذاشت.
در @BotFather بچرخانش (/revoke)، تازه را در .env بگذار و سرویس را دوباره
راه بینداز. توکن قدیمی بلافاصله ۴۰۴ برمی‌گرداند، و از همان می‌فهمی.
سطح‌های لاگری که جلوی این را می‌گیرند در apps/bot/runner.py تنظیم شده‌اند و
اختیاری نیستند.