פתרון תקלות

סקירה

העמוד הזה מפרט את תקלות הפריסה הנפוצות וכיצד לפתור אותן. לאבחון בזמן ריצה, GET /health?deep=true מדווח על סטטוס בסיס נתונים, דיסק, gcloud ועמדת אבטחה, וכל תגובת שגיאה נושאת X-Correlation-ID שאפשר לצטט לתמיכה.

אתחול ותצורה

תקלה	סיבה	פתרון
ה-backend יוצא עם “production startup blocked — N security config errors”	תנאי fail-fast הופעל (חסר `HMAC_KEY`/`API_KEY`/`ENCRYPTION_KEY`,‏ `STORAGE_MODE=compat`, מצב פיתוח פעיל, דגל עקיפת-Tenant, סוד חלש, או בסיס נתונים לא נגיש)	תקנו את ההגדרה המדווחת (ראו תצורה). חירום בלבד: `SECURITY_PERMIT_INSECURE_BOOT=true` (מבוקר, לא-בטוח)
`python main.py` לא מפעיל את שרת הווב	`main.py` הוא סורק IAM ישן משורת הפקודה, לא ה-backend	הפעילו `python -m uvicorn api.app:app --host 0.0.0.0 --port 9900`
`ModuleNotFoundError` עבור `extension...`	`extension/` לא ב-`PYTHONPATH`	הפעילו משורש המאגר, או השתמשו במשגרים/קונטיינרים המצורפים שמגדירים `PYTHONPATH`
ה-backend נכשל בייבוא עם שגיאות מוזרות	קובצי stub נטושים בשורש הפרויקט שמסתירים חבילות אמיתיות	הסירו/בודדו כל `fastapi.py`,‏ `boto3/`,‏ `google/` נטוש בשורש

אישורים וסריקה

תקלה	סיבה	פתרון
סריקות נדחות לפני שהן מתחילות / timeout איטי	Application Default Credentials של GCP פגי-תוקף	`gcloud auth application-default login`, או הגדירו `GOOGLE_APPLICATION_CREDENTIALS`
סריקת AWS מעלה שגיאת ייבוא מיד	`boto3` / `botocore` לא מותקנים	`pip install boto3 botocore` (כבר ב-`requirements.txt`)
סריקת Azure מסתיימת אך המלאי ריק	חוסר ב-SDK של Azure ← תוצאה ריקה אלגנטית	התקינו את תלויות ה-SDK של Azure, וסרקו מחדש
הסריקה מסתיימת אך אין ממצאים	חסרות הרשאות קריאה או היקף שגוי	הריצו Pre-scan Permission Check; הרחיבו היקף או הענקו תפקידי קריאה

רשת ופורטים

תקלה	סיבה	פתרון
פורט כבר בשימוש (9900 / 8200 / 7700)	תהליך קודם עדיין מאזין	`start-servers.bat` / `stop-servers.sh` משחררים את הפורטים; או שנו את `PORT` / `LICENSE_PORT` / `DB_PORT`
שרת ה-Vite נכשל לעלות על 8200	פורט הפיתוח של ה-frontend קבוע (`strictPort`)	שחררו את פורט 8200 — הוא לא יעבור אוטומטית לאחר
שגיאות CORS בייצור	`FRONTEND_ORIGINS` לא מוגדר ← נופל ל-origins של פיתוח	הגדירו `FRONTEND_ORIGINS=https://your-host` (CSV). בפיתוח מקומי ה-proxy של Vite מונע CORS

רישוי

תקלה	סיבה	פתרון
הכול מחזיר שגיאת רישיון (`403`/`423`)	רישיון לא תקף או נעול	הפעילו רישיון תקף; ודאו ששרת הרישוי נגיש ב-HTTPS
אימות רישיון מושבת בשקט	`REDCLOUD_LICENSE_SECRET` לא מוגדר	הגדירו את אותו הסוד ב-backend ובשרת הרישוי

תפעול

תקלה	סיבה	פתרון
סריקות מתוזמנות לא מופעלות	אתחול אוטומטי של ה-Scheduler נכשל בעלייה	קראו ל-`POST /scheduler/start`, או בדקו ביומנים את אזהרת ה-scheduler
צריך בדיקת בריאות עמוקה	—	`GET /health?deep=true` לאבחון רכיבים; `GET /metrics` ל-Prometheus

קבלת עזרה

כשאתם פונים לתמיכה, כללו את מזהה הסריקה ואת ה-X-Correlation-ID מהשגיאה — הם מאפשרים לצוות לאתר את הבקשה המדויקת ביומן הביקורת. ראו תמיכה.