پیش‌نیازهای این آموزش
- نام پروژه، نسخه ناموفق، زمان و نخستین پیام خطای مرتبط را مشخص کنید.
آموزش مرحله‌به‌مرحله
- ابتدا مشخص کنید خطا در بررسی منبع، ساخت یا اجرای برنامه رخ داده است.
- در خطای ساخت، نخستین خطای ابزار ساخت و فایل یا وابستگی مربوط را پیدا کنید.
- در خطای اجرا، فرمان شروع، متغیرها، پورت، حافظه و اتصال دیتابیس را بررسی کنید.
- علت را اصلاح کنید و متناسب با آن نسخه جدید بسازید یا همان نسخه را راه‌اندازی مجدد کنید.
- پس از اصلاح، همان مسیر گزارش‌شده را آزمایش کنید و لاگ‌ها را برای تکرار خطا ببینید.
توضیحات تکمیلی
استک تشخیص داده نمی‌شود
ZIP را باز کنید و مطمئن شوید manifest اصلی، Dockerfile یا compose.yaml داخل آن است. فایل پروژه نباید یک ZIP دیگر داخل ZIP باشد.
Build وابستگی یا Image پایه شکست می‌خورد
در Python، requirements.txt یا pyproject.toml باید همه وابستگی‌های مستقیم را داشته باشد؛ Build استاندارد چند import رایج و بدون ابهام مانند requests، dotenv و yaml را در فایل‌های تو‌در‌تو هم بررسی و در صورت جاافتادن نصب می‌کند، اما سورس یا manifest شما را تغییر نمی‌دهد. lockfile و نسخه runtime را بررسی کنید. خط اول خطای واقعی را در جزئیات Build پیدا کنید. Imageهای Docker Hub و docker.n8n.io در ناحیه ایران خودکار از cache داخلی و mirror داخلی کشور دریافت می‌شوند؛ cache پروژه نیز در Build بعدی استفاده می‌شود.
اپ پس از Build بالا نمی‌آید
صفحه استقرار خطاهایی مانند OOMKilled، CrashLoopBackOff، ErrImagePull، مشکل Permission، دیتابیس، پورت و Health Check را تشخیص می‌دهد و چک‌لیست مرتبط نشان می‌دهد. خطای موقت Pull تا دو دقیقه و Crash اولیه تا سه Restart فرصت بازیابی خودکار دارد؛ سپس در صورت ادامه مشکل، Retry مرحله اجرا بدون تکرار Build نمایش داده می‌شود.
Health Check ناموفق است
مسیر باید بدون احراز هویت پاسخ 2xx/3xx بدهد. اگر برنامه مسیر سلامت ندارد، فیلد را خالی بگذارید تا TCP بررسی شود.
دامنه شخصی تأیید نمی‌شود
رکورد TXT را دقیقاً روی نام نمایش‌داده‌شده بسازید، تا انتشار DNS صبر کنید و دوباره تأیید را بزنید. سپس وضعیت صدور TLS را بررسی کنید.
نتیجه را چگونه بررسی کنید؟
عملیات یا صفحه مشکل‌دار درست کار می‌کند و خطای قبلی در اجرا تکرار نمی‌شود.
اگر به مشکل خوردید
- ساخت موفق یا وضعیت آماده لحظه‌ای برای تأیید رفع مشکل کافی نیست.
- اگر علت مشخص نیست، تیکت شامل نسخه، زمان و لاگ بدون اطلاعات محرمانه بفرستید.
آموزش‌های مرتبط
ساخت موفق است اما نسخه جدید آماده نمی‌شود
ساخت ایمیج و آماده‌شدن برنامه دو مرحله جدا هستند. پاستا پیش از بازگشت از نسخه ناموفق، شواهد موجود بررسی سلامت و لاگ اجرا را در همان استقرار نگه می‌دارد. خطای HTTPS، پاسخ ۴۰۴ و پاسخ ۴۰۱ یا ۴۰۳ راهنمای جدا دارند.
مسیر مستقلی مثل /healthz بسازید و در Health Check تنظیم کنید. این مسیر باید روی پورت داخلی برنامه، بدون ورود، تشخیص دامنه یا هدایت به HTTPS، مستقیم پاسخ ۲۰۰ بدهد. فقط این مسیر را از هدایت مستثنا کنید و HTTPS عمومی کاربران را حفظ کنید. پیش از استقرار بعدی همین درخواست داخلی را آزمایش کنید؛ تکرار بدون تغییر، خطای ثابت مسیر سلامت را برطرف نمی‌کند.