مستندات فنی پروژه
SCRIPTS · KAFKA TOPICS

infra/create_topics.sh — ساخت و عریض‌کردن تاپیک‌ها

← بازگشت به فهرست اسکریپت‌ها

مسیر فایل: scripts/infra/create_topics.sh

۱. کاراییش به زبان ساده

سه تاپیک اصلی PlayPulse را با تعداد پارتیشن انتخابی (پیش‌فرض ۳) می‌سازد و گزارش می‌دهد کدام‌ها باریک‌تر از هدف هستند. اگر تاپیک از قبل وجود داشته باشد و بخواهید پارتیشن‌ها را زیاد کنید، باید صریحاً --alter بزنید — چون عریض‌کردن partitioning یک تاپیک زنده تصمیم حساسی است.

۲. کجا در پروژه کلی استفاده می‌شود؟

  • سرویس Compose به نام kafka-init در هر up تقریباً همین کار را برای ساخت اولیه انجام می‌دهد.
  • این اسکریپت برای سناریویی است که kafka-init پوشش نمی‌دهد: عریض‌کردن تاپیک‌های از قبل موجود وقتی ترافیک reviews/network از یک consumer فعال بیشتر شود.
  • در docker-compose.yml صریحاً به این اسکریپت برای عملیات --alter ارجاع داده شده است.
  • تولیدکنندگان (Crawler، Network Analyzer) و مصرف‌کننده (Storage Consumer) همگی به همین سه تاپیک وابسته‌اند: app-stats، reviews، network-metrics.

۳. چیکارا می‌کند؟

  1. به کانتینر project_kafka وصل می‌شود.
  2. برای هر تاپیک هدف (پیش‌فرض هر سه، یا فقط آن‌هایی که با --topic تکرار شده‌اند):
    • اگر نباشد → با --partitions N می‌سازد.
    • اگر باشد و پارتیشن‌ها کافی باشند → OK.
    • اگر باشد و باریک‌تر باشد → هشدار می‌دهد؛ فقط با --alter واقعاً عریض می‌کند.
  3. گزارش نهایی و exit code بر اساس شکست/موفقیت چاپ می‌شود.

۴. تصمیمات معماری

  • چرا auto-create کافی نیست؟ تاپیک auto-created معمولاً یک پارتیشن می‌گیرد. تعداد پارتیشن را بعداً نمی‌شود کم کرد؛ با یک پارتیشن، هر consumer group حداکثر یک عضو فعال دارد. روزی که ترافیک reviews بترکد، به‌جای اضافه کردن کانتینر دوم باید تاپیک را از نو بسازید.
  • ساخت عریض از ابتدا رایگان است — هزینهٔ عملیاتی ناچیز در برابر قفل مقیاس‌پذیری.
  • --alter پیش‌فرض خاموش: تغییر partitioning روی تاپیک زنده می‌تواند توزیع کلیدها و lag را جابه‌جا کند؛ اپراتور باید آگاهانه فعالش کند.
  • تکرارپذیری با kafka-init: مسیر Compose برای روز اول؛ این اسکریپت برای روز مقیاس و عملیات دستی.

۵. دستورات

# ساخت / اطمینان از سه تاپیک با ۳ پارتیشن
./scripts/infra/create_topics.sh

# عریض‌کردن reviews به ۶ پارتیشن
./scripts/infra/create_topics.sh --topic reviews --partitions 6 --alter

# فقط گزارش وضعیت، بدون alter
./scripts/infra/create_topics.sh --partitions 3

./scripts/infra/create_topics.sh --help

پیش‌نیاز: کانتینر Kafka در حال اجرا:

docker compose up -d zookeeper kafka

← check_infra.sh · فهرست اسکریپت‌ها · verify_storage_consumer.sh →