check_infra.sh | مستندات اسکریپت‌ها

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

مستند سطح بالاتر زیرساخت نیز در Infrastructure Setup آمده است؛ این صفحه روی خودِ اسکریپت تمرکز دارد.

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

این اسکریپت فقط می‌پرسد: «Postgres، Kafka و Metabase واقعاً زنده‌اند و می‌شود به آن‌ها وصل شد و write/read کرد؟» هیچ فرضی دربارهٔ صحت دادهٔ اپلیکیشن (ردیف‌های crawl، reviews و …) ندارد. اگر مشکلی در استک باشد، قبل از متهم کردن Crawler یا Storage Consumer، همین‌جا مشخص می‌شود.

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

به‌صورت خودکار در انتهای bring_up.sh (مگر --skip-check).
دستی پس از restart زیرساخت، یا وقتی مشکوکید مشکل از infra است نه از منطق اپ.
پیش‌شرط قابل اتکا برای اسکریپت‌ها/جریان‌های بعدی که به exit code معنادار نیاز دارند.
مرجع مفهومی همان Smoke Testای است که در docs/html/infra-setup.html شرح داده شده.

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

PostgreSQL

مرحله	هدف
اجرا بودن کانتینر	کانتینر `project_postgres` crash یا stop نباشد.
`pg_isready`	فاصلهٔ بین «بالا آمدن کانتینر» و «آماده بودن دیتابیس» پوشش داده شود.
نوشتن و خواندن واقعی	جدول موقت، insert، select، drop — فراتر از ping ساده؛ کاربر و DB تعریف‌شده در `.env` واقعاً کار می‌کنند.

Kafka

مرحله	هدف
اجرا بودن کانتینر	کانتینر `project_kafka` بالا باشد.
در دسترس بودن بروکر	API بروکر پاسخ دهد (اتصال به ZooKeeper و آمادگی کامل).
ساخت Topic تستی	عملیات مدیریتی Topic بدون خطا انجام شود.
Produce / Consume و تطبیق محتوا	شبیه‌سازی مسیر Crawler → Consumer؛ پیام دریافتی دقیقاً همان ارسالی باشد.
پاکسازی Topic تستی	دادهٔ تستی روی بروکر باقی نماند.

Metabase

اجرا بودن کانتینر Metabase نیز بررسی می‌شود تا داشبورد ops بخشی از «زیرساخت قابل استفاده» باشد، نه صرفاً یک سرویس جانبی فراموش‌شده.

وضعیت‌های خروجی هر مرحله:

[OK] — موفق
[FAIL] — ناموفق (+ جزئیات)
[..] — در حال انجام

در پایان: همه موفق → exit code 0؛ حداقل یک شکست → exit code 1 با شمارش خطاها.

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

مقاوم در برابر خطای جزئی: با اولین FAIL متوقف نمی‌شود؛ همهٔ چک‌ها تا آخر می‌روند تا گزارش کامل بماند.
Retry: بین بالا آمدن کانتینر و آمادگی سرویس چند ثانیه فاصله طبیعی است؛ بدون retry نویز کاذب زیاد می‌شود.
عدم وابستگی به کد پایتون پروژه: فقط ابزار داخل imageها (psql، CLI کافکا). قبل از نوشته شدن هر خط اپ هم قابل اجراست.
پاکسازی خودکار: جدول موقت و Topic تستی حذف می‌شوند تا infra پس از تست تمیز بماند.
جدا از کیفیت داده: عمداً به ردیف‌های business نگاه نمی‌کند؛ آن کار مال verify_storage_consumer.sh و مشابهات است.

۵. دستورات

# پیش‌نیاز: .env ریشه + سرویس‌های infra بالا
cp .env.example .env   # در صورت نیاز
docker compose up -d postgres zookeeper kafka

./scripts/infra/check_infra.sh

پیش‌نیاز: فایل .env در ریشه؛ کانتینرهای postgres، zookeeper، kafka (و در صورت بررسی Metabase، کانتینر مربوطه) در حال اجرا.

← bring_up.sh · seed_apps.sh · فهرست اسکریپت‌ها · create_topics.sh →

infra/check_infra.sh — Smoke Test زیرساخت