זרימת גיבוי ושחזור (Backup Flow)
סקירה כללית
מערכת הגיבויים מאפשרת: - יצירת גיבוי מלא של כל קבצי המשתמש - שחזור מגיבוי - ניהול גיבויים (הורדה, מחיקה, דירוג) - גיבויים אוטומטיים ל-Google Drive
סוגי גיבויים
סוג |
מזהה |
תיאור |
|---|---|---|
Full Backup |
|
גיבוי מלא של כל הקבצים |
GitHub Repo Backup |
|
גיבוי של repository מ-GitHub |
העלאה ל-Google Drive אינה גיבוי שנשמר ברשימת הגיבויים של הבוט, ולכן אינה בטבלה. ה-ZIP שנבנה לה ב-create_full_backup_zip_bytes נושא metadata.json עם backup_type בצורה drive_manual_<קטגוריה> — ראו גיבוי ל-Google Drive.
מבנה ה-ZIP של גיבוי ריפו
``github_repo_zip`` אינו ארכיון שהבוט בונה בעצמו. הוא ה-zipball הרשמי של GitHub — שכל תוכנו יושב תחת תיקייה אחת בשם owner-repo-sha — ואליו מתווסף metadata.json בשורש הארכיון:
metadata.json
owner-repo-6dfaac9/README.md
owner-repo-6dfaac9/src/main.py
השחזור לריפו סופר תיקיות בלבד. קובץ בשורש אינו מכיל /, ולכן אינו משתתף בספירה: נשארת תיקייה אחת, היא נחתכת, והתוכן נוחת בשורש הריפו. metadata.json עולה לריפו יחד עם התוכן — כך זה תמיד היה, וקובץ בשם הזה בשורש אינו מפריע.
והמחיר של הכלל הזה, שהוא מכוון: ZIP שאינו גיבוי — למשל README.md בשורש לצד src/ — יאבד רובד, ו-src/main.py ייכתב כ-main.py. המסך שמבקש את הקובץ מתריע על כך לפני ההעלאה, ב-RESTORE_ZIP_PROMPT שב-github_menu_handler.py.
אזהרה
``detect_zip_common_root`` אינה מתאימה למסלול הזה, ואין לאחד ביניהם. היא מבטלת את זיהוי השורש ברגע שיש קובץ בשורש — כלל נכון לייבוא ZIP, שמונע חיתוך שגוי של ארכיון כמו README.md לצד src/ — אבל כאן metadata.json מפעיל אותו, והריפו כולו נפרס בתוך תיקייה בשם owner-repo-sha. האיחוד הזה כבר נעשה פעם אחת ושבר את השחזור.
יצירת גיבוי מלא
sequenceDiagram
participant U as User
participant B as Bot
participant H as Backup Handler
participant BS as BackupService
participant DB as MongoDB
participant ZIP as ZIP Creator
U->>B: 📦 גיבוי ושחזור → יצירת גיבוי
B->>H: handle_create_backup()
H->>DB: שליפת כל הקבצים של המשתמש
DB-->>H: files[]
H->>BS: create_backup(user_id, files)
BS->>ZIP: יצירת ZIP
loop לכל קובץ
ZIP->>ZIP: הוספת קובץ ל-ZIP
ZIP->>ZIP: הוספת metadata
end
ZIP->>ZIP: הוספת metadata.json
ZIP-->>BS: zip_bytes
BS->>DB: שמירת metadata גיבוי
DB-->>BS: backup_id
BS-->>H: backup_info
H->>U: הורדת קובץ ZIP
מבנה metadata.json:
{
"version": "1.0",
"created_at": "2025-01-15T10:30:00Z",
"user_id": 123456789,
"total_files": 150,
"total_size": 5242880,
"files": [
{
"file_name": "example.py",
"programming_language": "python",
"code": "...",
"note": "Example file",
"tags": ["example"],
"version": 3,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-12T14:30:00Z"
}
]
}
שחזור מגיבוי
sequenceDiagram
participant U as User
participant B as Bot
participant H as Backup Handler
participant BS as BackupService
participant ZIP as ZIP Extractor
participant DB as MongoDB
U->>B: 📦 גיבוי ושחזור → שחזור מגיבוי
B->>H: handle_restore_backup()
H->>U: רשימת גיבויים זמינים
U->>H: בחירת גיבוי
H->>BS: get_backup(backup_id)
BS->>DB: שליפת metadata
DB-->>BS: backup_metadata
BS->>ZIP: פתיחת ZIP
ZIP->>ZIP: קריאת metadata.json
ZIP->>ZIP: חילוץ קבצים
ZIP-->>BS: files[]
BS->>BS: בדיקת כפילויות
loop לכל קובץ
alt קובץ קיים
BS->>U: "החלף {filename}? (כן/לא/דלג)"
U->>BS: החלטה
end
BS->>DB: שמירת קובץ
end
BS-->>H: restore_result
H->>U: "שוחזרו {count} קבצים"
גיבוי ל-Google Drive
לבוט ולוובאפ יש חיבור Drive נפרד, ולכל אחד תזמון ומתזמן משלו — ראו חיבור נפרד לכל שירות (owner). הפונקציות שמוזכרות כאן מתועדות ב-Google Drive Service.
בבוט (handlers/drive/menu.py, עם drive_owner.BOT):
התחברות — ב-Device Flow:
start_device_authorizationמחזיר קוד שהמשתמש מקליד בדף של גוגל, והבוט בודק אם האישור הגיע (poll_device_token) בשלוש דרכים: בדיקה ברקע, הכפתורdrive_poll_once, והודעה שהמשתמש שולח בצ’אט בזמן ההמתנה (handle_text). בשלושתן החיבור מוצג כ“הושלם“ רק אחרי שהטוקנים נשמרו (_save_auth_tokens).גיבוי ידני — בחירת קטגוריה ואישור (
drive_simple_confirm). בקטגוריהzipעולים קבצי ה-ZIP השמורים בבוט שעוד לא הועלו (upload_all_saved_zip_backups); בקטגוריהallנבנה ZIP מלא (create_full_backup_zip_bytes) ועולה (upload_bytes) לתת-התיקייה של הקטגוריה (compute_subpath), בשם מ-compute_friendly_name.תזמון —
drive_set_schedule:<key>שומר בהעדפות של הבוט את התזמון (schedule) ואת הקטגוריה (schedule_category), ויוצר job ב-job queue של הבוט (_ensure_schedule_job). כל הרצה קוראת ל-perform_scheduled_backup, שמעלה לפי הקטגוריה:zip, ``by_repo`` (ZIP לכל ריפו,create_repo_grouped_zip_bytes), או ZIP אחד ל-all/large/other. אחרי עלייה מחדש ה-jobdrive_rescheduleב-main.pyמשחזר את ה-jobs של מי שיש לו תזמון פעיל (get_users_with_active_drive_schedule).
בוובאפ (עם drive_owner.WEBAPP):
התחברות — בהפניה לגוגל (
webapp/drive_auth.py), ראו החיבור בוובאפ: קוד ה-state נשמר בשרת.מה עולה — הגיבוי האישי המלא (
PersonalBackupService.export_user_data), כ-ZIP אחד לתיקיית היעד (upload_bytesבלי תת-תיקייה), ב-_perform_drive_backupשב-webapp/backup_scheduler.py. מכל קובץ נשמרת הגרסה שרשימת הקבצים בוובאפ מציגה: אותו כלל,LATEST_VERSION_SORT_BYשב-file_versions.py. הקבצים נקראים מהמסד ונכתבים ל-ZIP אחד-אחד (iter_latest_active_snippetsו-iter_latest_active_large_filesב-Repository), בלי מיון במסד ובלי תקרת כמות. כשל בשליפה מכשיל את כל הגיבוי, וגיבוי חלקי לא עולה כהצלחה — וגם כשאין מסד אמיתי (מצב NoOp), במקום ZIP ריק.”גבה עכשיו“ —
POST /api/drive/backup-nowמסמןmanual_backup_statusכ-running, רק במסמך של משתמש מחובר, ומריץ את הגיבוי ברקע. הדף קורא את המצב מ-GET /api/drive/backup-status.תזמון —
POST /api/drive/scheduleשומרschedule_keyו-schedule_next_at. ה-thread שלwebapp/backup_scheduler.pyסורק כלSCAN_INTERVAL_SECONDS, תופס אטומית משתמש שהגיע זמנו (_drive_claim_filter, עם אינדקס משלו) ומריץ את הגיבוי.
גיבוי ידני של ”הכל“ בבוט:
sequenceDiagram
participant U as משתמש
participant M as GoogleDriveMenuHandler
participant GDS as google_drive_service
participant GD as Google Drive API
U->>M: drive_sel_all, ואז drive_simple_confirm
M->>GDS: get_drive_service(owner=BOT)
M->>GDS: create_full_backup_zip_bytes(user_id, "all")
M->>GDS: upload_bytes(..., sub_path=compute_subpath("all"), owner=BOT)
GDS->>GD: files().create() ו-next_chunk()
GD-->>GDS: file id
GDS-->>M: file id, או None בכשל
M->>U: הודעת הצלחה, או הודעת כשל
ניהול גיבויים
רשימת גיבויים:
backups = await db.get_user_backups(user_id, limit=10, offset=0)
# כל גיבוי כולל:
{
'backup_id': ObjectId(...),
'user_id': 123456789,
'backup_type': 'full_backup',
'created_at': datetime(...),
'file_count': 150,
'total_size': 5242880,
'version': '1.0',
'rating': '🏆 מצוין', # אופציונלי
'note': 'גיבוי לפני שינוי גדול', # אופציונלי
'repo': 'owner/repo' # רק ל-github_repo_zip
}
פעולות:
הורדה:
handle_download_backup(backup_id)מחיקה:
handle_delete_backup(backup_id)דירוג:
handle_rate_backup(backup_id, rating)הוספת הערה:
handle_add_backup_note(backup_id, note)
מחיקה מרובה:
# בחירת מספר גיבויים
selected_backups = [backup_id1, backup_id2, ...]
# אישור מחיקה
await db.delete_backups(selected_backups)
# לוג event
emit_event("backups_deleted",
severity="info",
user_id=user_id,
count=len(selected_backups))
ייבוא ZIP חיצוני
async def handle_import_zip(update, context):
# קבלת קובץ ZIP
zip_file = await context.bot.get_file(update.message.document.file_id)
# פתיחת ZIP
with zipfile.ZipFile(zip_file, 'r') as zip_ref:
# קריאת metadata
metadata = json.loads(zip_ref.read('metadata.json'))
# זיהוי repository (אם קיים)
repo = metadata.get('repo') or _detect_repo_from_structure(zip_ref)
# חילוץ קבצים
for file_info in zip_ref.infolist():
if file_info.filename.endswith('.py'):
code = zip_ref.read(file_info.filename).decode('utf-8')
await db.save_file(
user_id=user_id,
file_name=file_info.filename,
code=code,
tags=[repo] if repo else []
)
Edge Cases
גיבוי ריק (אין קבצים): - נוצר ZIP עם metadata.json בלבד - המשתמש מקבל הודעה
שגיאת יצירת ZIP: - המשתמש מקבל הודעת שגיאה - האירוע נרשם ב-Observability
גיבוי גדול מאוד (>100MB): - מוצע להשתמש ב-Google Drive - או חלוקה למספר גיבויים
שחזור עם כפילויות: - המשתמש מקבל תפריט לכל קובץ - יכול לבחור: החלף/דלג/שנה שם
שגיאת Google Drive:
- אין שמירה מקומית כגיבוי חלופי. בקטגוריות שבונות את ה-ZIP בזיכרון (all, ``by_repo``, ``large``, ``other``, וגם הגיבוי של הוובאפ) מה שלא עלה לא נשמר במקום אחר. בקטגוריה zip (קבצי גיבוי) מועלים ZIPים שכבר שמורים בבוט (backup_manager), והם נשארים במקומם. ב-uploaded_backup_ids נרשם ZIP שעלה, וגם ZIP שלא הועלה כי קובץ עם אותו תוכן (לפי md5) כבר נמצא בתיקיית ה-zip ב-Drive (_upload_all_saved_zip_backups_detailed). ZIP שההעלאה שלו נכשלה לא נרשם, ולכן בפעם הבאה שהקטגוריה מועלית — ידנית או בתזמון — הוא מועלה שוב, אלא אם נמצא בתיקייה קובץ עם אותו תוכן.
- בבוט, בגיבוי ידני: המשתמש מקבל הודעת כשל, ואין ניסיון חוזר.
- בבוט, בגיבוי מתוזמן: נשלח drive_scheduled_backup_result עם ok שקר. כשאי אפשר לבנות שירות Drive מהטוקנים השמורים, המשתמש מקבל בקשה להתחבר מחדש (drive_scheduled_backup_auth_required). ההרצה הבאה היא במועד הבא של התזמון.
- בוובאפ: החיבור נבדק מול גוגל לפני שה-ZIP נבנה (בדיקת חיבור לפני גיבוי (check_connection)), וכל כשל נשלח כ-webapp_drive_backup_failed עם הסיבה. כשגוגל דחה את החיבור (auth_required), מסך ההגדרות מבקש להתחבר מחדש, ”גבה עכשיו“ אומר זאת, וגיבוי מתוזמן מושהה עד החיבור מחדש — במקום לבנות ZIP ולנסות שוב בכל סריקה. בכל כשל אחר, ב“גבה עכשיו“ המצב הופך ל-error, וגיבוי מתוזמן מנוסה שוב אחרי המתנה שגדלה בכל ניסיון (_retry_delay_seconds). אחרי RETRY_MAX_ATTEMPTS ניסיונות הוא עובר למועד הרגיל הבא של התזמון, ונשלח webapp_backup_retries_exhausted. כך גם בגיבוי לדיסק. בסוף כל גיבוי מתוזמן המועד הבא נכתב רק אם המשתמש לא שינה את התזמון בזמן שהגיבוי רץ (_finish_claim).
- העלאה שנכשלה נרשמת בלוג בשורת drive_call_failed (_log_drive_call_failed ב-services/google_drive_service.py), עם הפעולה שנכשלה וסטטוס ה-HTTP.
גיבוי פגום: - בדיקת תקינות ZIP לפני שחזור - אם פגום, המשתמש מקבל הודעת שגיאה