אינטגרציה עם Pinata ל-IPFS: העלאה וניהול קבצים

מדוע קבצים ב-IPFS נעלמים בלי pinning

IPFS מפנה לנתונים לפי תוכן: לקובץ אין נתיב בשרת מסוים, יש טביעת אצבע שמתארת באופן חד-משמעי את הבתים. צומת שקיבל את האובייקט מניח אותו באחסון המקומי ומגיש אותו למשתתפים אחרים ברשת, כל עוד יש ביקוש לתוכן. הביקוש נעלם — האובייקט הופך למטמון רגיל, ולמטמון כל צומת רשאי לנקות.

כאן מתפצלים "הקובץ הועלה" ו"הקובץ זמין". IPFS pinning הוא סימון מפורש "לא למחוק, אני אחראי לזמינות": הוא מוציא את האובייקט מניקוי אוטומטי ומחזיק אותו באחסון הצומת באופן קבוע.

בלי סימון כזה, הצומת מפעיל לאחר זמן מה איסוף אשפה באחסון המבוזר ומפנה מקום לבלוקים חדשים — זו אינה תקלה, אלא התנהגות תקנית של הרשת.

הדבר המעצבן ביותר: הקישור נשאר תקף. טביעת האצבע בחוזה החכם, המטא-נתונים של הטוקן, כתובת התמונה בממשק הווב — הכול במקום ובאופן תחבירי תקין. אבל לפי הבקשה אף צומת לא מוצא אף עותק ומחזיר ריק.

זהו בדיוק אובדן הקישורים לתוכן: הקוד עובד, והקבצים אינם זמינים ב-IPFS לחלוטין — מתמונה ועד תיאור JSON.

בקנה מידה זה נראה כך: הקולקציה מאבדת בבת אחת את כל הגרפיקה, המרקטפלייס לא מצליח לרנדר כרטיסים, והשחזור נתקל במקורות שאולי כבר אין בידי הצוות. נמשיך לפרק כיצד בנוי pinning: היכן שמים אותו, במה הוא שונה מהעלאה חד-פעמית וכיצד בודקים שהאובייקט באמת חי.

מה נותן IPFS pinning מנוהל בעבודה בפועל

IPFS מפנה לקובץ לפי תוכן: במקום נתיב — האש המחושב מהנתונים עצמם. כל עוד הצומת מחזיק את הבלוקים ולא עבר ניקוי של מה שלא הוצמד, האובייקט מוגש לפי בקשה; לאחר אתחול או איסוף אשפה הוא נעלם מהרשת, ופנייה לאותה כתובת מחזירה שגיאה. לא האחסון נשבר, אלא הקישור בחוזה או במטא-נתונים — זה שכבר אי אפשר לשנות.

ההצמדה מקבעת את הכתובת ומחזיקה את הבלוקים אצל ספק האחסון — אצלנו זה Pinata עם מדיניות הצמדה לכל ארטיפקט שמועלה. שיעור האובייקטים הבלתי-זמינים מפסיק להיות משתנה מקרי: הרשומה או נמצאת במרשם ההצמדות או לא, והדבר נראה לפני השחרור, ולא לפי תלונה על תמונה שבורה אצל המשתמש.

האפקט השני — מהירות הרכבת הארטיפקטים. כתובת בלתי-משתנה מאפשרת למשוך נתונים מהמטמון של השער הקרוב, במקום להעלות אותם מחדש בשלמותם בכל בנייה; בנייה חוזרת של אותה גרסה מניבה את אותה כתובת, ולכן התוצאה משוחזרת ואינה תלויה במצב המכונה של מהנדס מסוים.

השלישי — צמצום האימות הידני. מרשם ההצמדות הופך למקור האמת: הדוח בונה את הפערים בין טבלת הארטיפקטים לבין מצב הרשת בפועל, והמהנדס מסתכל רק על השורות עם שגיאות, ולא עובר ידנית על כל הרשימה לפני כל פריסה.

בסך הכול אלה שלושה פרמטרים שאנו עוקבים אחריהם: שיעור האובייקטים הבלתי-זמינים, זמן הבנייה ומספר הבדיקות הידניות לשחרור. הראשון שואף לאפס, השני מפסיק להיות תלוי בגודל עץ התלויות, השלישי נמדד בשורות בודדות במקום מעבר מלא — ובמדדים האלה בדיוק נראה אם ההצמדה השתלמה.

אפשרויות הצמדת קבצים: צומת, שער, שירות

כתובת הקובץ ב-IPFS אינה מכילה את הקובץ עצמו — הבלוקים חיים בדיוק כל עוד לפחות צומת אחד מחזיק אותם ומכריז עליהם בטבלה המבוזרת. הצמדה אינה "שמירת עותק", אלא התחייבות קבועה: אוסף האשפה אינו נוגע בבלוקים מסומנים כל עוד הכלל בתוקף. מכאן שלוש דרכים שונות מהותית לקיים את ההתחייבות הזו.

התכונה המרכזית: המזהה של הקובץ עצמו אינו תלוי היכן הוא מוצמד. לכן האפשרויות אינן שוללות זו את זו, אלא משולבות — המתאר העובדי בדרך כלל כזה: הצמדה על צומת עצמאי, עותק שני בשירות חיצוני, ושער לפניהם כנקודת כניסה אחודה לאפליקציות. מעבר בין אפשרויות אינו שובר את הקישורים.

הבחירה מצטמצמת לשאלה איזה סוג של כשל אתם מוכנים לקבל: אי-זמינות של הצומת שלכם, שינוי תנאים אצל הספק או צוואר בקבוק בשער בעומס שיא. בהמשך מסתכלים על הנפח, תקופת האחסון ודרישות הגישה — מהם נגזרת הקונפיגורציה.

שלבי היישום: מהביקורת ועד מסירת הנהלים

נוהל ההצמדה (pinning) אינו "העלינו קובץ ושכחנו": לכל אובייקט יש כתובת לפי תוכן, ולצומת יש רשימה של מה שהוא מחויב לשמור. אם מנהלים את הרשימה ידנית וללא בקרה, חלק מהקבצים מתנתקים מההצמדה בזמן הניקוי, והקישורים בממשק או בטוקן מתחילים להחזיר ריק. לכן העבודה מתבצעת בסדר קבוע — מהמלאי ועד מסירת התיעוד.

1. ביקורת אחסון. אוספים רשימה של אובייקטים שכבר הונחו, הנפחים שלהם, כפילויות ובעלים. סופרים כמה מערכים ייחודיים באמת יש ואילו מהם קריטיים למוצר.
2. תכנון סכמת ההצמדה. מסמנים את המערכים לפי קבוצות, קובעים מה נשמר באופן קבוע ומה לפי דרישה, וכיצד מתחלקים העותקים בין הצמתים. הסכמה נקבעת לפני הכתיבה הראשונה, ולא משורטטת תוך כדי.
3. הגדרת כללי גישה. מפתחות נפרדים לכתיבה, קריאה וניהול, שיוך לקבוצות, הגבלה לפי תחומים ורוטציה סדירה. דליפת מפתח פרסום מפסיקה לאיים באובדן כל האחסון.
4. הרכבת צינור ההעלאה. סכום הביקורת מחושב בצד השירות לפני השליחה, ניסיון חוזר בעת תקלת רשת הולך לאותה כתובת, ולכן כפילויות אינן מתרבות, והעלאה שהופסקה ממשיכה מאותה נקודה.
5. בדיקת שלמות הקבצים. השוואה תקופתית בין האינדקס לתוכן הצמתים בפועל: הפער נראה לפני שהמשתמש מדווח עליו. אובייקטים שאבדו משוחזרים מגיבוי או מצומת שני.
6. ניטור והתראות. שולטים בזמינות הצמתים, בגידול הנפח ובמוני ההצמדה. התראה מגיעה בעת ניתוק מהצמדה או אזילת מקום, ולא אחרי תלונה.
7. מסירת נהלים. מעבירים את סכמת הכתובות, תיאור ההרשאות, הוראות שחזור ורשימת בדיקה למהנדס תורן. מכאן ואילך צוות הלקוח מנהל את האחסון בעצמו.

כל שלב מסתיים בארטיפקט: רשימת אובייקטים, סכמה, מערך מפתחות, לוגים של השוואה. לפיהם רואים באיזה שלב משהו סטה — וזה זול יותר מאשר לפרק את ההשלכות של ניתוק קבצים קריטיים מההצמדה.

מה מוסרים לידיים: קונפיגורציות, סכמות, מדיניויות

מוסרים לא "שירות עובד", אלא ערכת ארטיפקטים שלפיה צוות הלקוח עצמו משנה כללי הצמדה, מחליף ספק ומטפל באירועים. את האינטגרציה עם Pinata בונים כך שכל הלוגיקה תהיה מתועדת, ולא "חרוטה בראש של המהנדס" — להלן מה שנשאר פיזית במאגר הקוד ובויקי לאחר ההפעלה.

• סכמת האינטגרציה — נתיב הקובץ מההעלאה ועד ההצמדה: היכן מחושבת כתובת התוכן, באיזה רגע מוצב ה-pin, מה קורה בכל שלב בעת תקלה וכיצד לחזור על הפעולה באופן אידמפוטנטי.
• קונפיגורציות של הצומת והשערים — פרמטרי הצמדה, פסקי זמן, מגבלות, מפתחות גישה במאגר סודות מאובטח בתוספת הוראות לרוטציה שלהם.
• נוהל ההצמדה — אילו אובייקטים מחזיקים באופן קבוע, אילו מסירים לפי מועד, מי מאשר שינוי בכלל וכיצד זה מתועד בהיסטוריה.
• מדיניויות גישה — תפקידים, תחומי מפתחות, הגבלות על העלאה וקריאה, סדר הנפקה ושלילה של גישה לעובדים ולשירותים.
• תיעוד האחסון — היכן נמצאים המטא-נתונים, כיצד בנוי השכפול, כיצד להעריך את נפח האחסון והגידול שלו בלי לפנות אלינו.
• ניטור והתראות — בדיקות זמינות של השערים, מהירות ההצמדה ושיעור הפעולות הכושלות עם שיוך לאחריותיים וספי הפעלה.
• תוכנית שחזור — סדר הפעולות בעת אי-זמינות של ספק ההצמדה, מעבר לצומת גיבוי ובדיקת שלמות האובייקטים לפי כתובות התוכן.
• הוראות למהנדסים — הפעלת סביבה, מיגרציות, פעולות אופייניות ורשימת בדיקה לקבלת שחרור.

בנפרד מוסרים יומן החלטות: מדוע נבחרו תקופות הצמדה כאלה, רמות שכפול ונקודות כשל. זה מה שבדרך כלל הולך לאיבוד בעת החלפת ספק.

מקרה בוחן: מרשם קבצים בלי אובדנים ובלי השוואות ידניות

לפני: הצמדה בלי שכפול

מרשם המסמכים חי על צומת אחד של אחסון מבוזר: קבצים נוספו בסקריפט, ה-pinning ב-IPFS נעשה בלי גיבוי, וחלק מההצמדות אבדו בעת אתחול צומת העבודה. הקישור לפי CID המשיך להיפתח, אבל התוכן שמאחוריו כבר לא הוגש — כשל שקט, שהבחינו בו רק לפניית משתמש. השוואת המרשם לקבצים שזמינים בפועל נעשתה ידנית אחת לשבוע, וארכה כארבע שעות.

מה שינו

את ההצמדה העבירו ל-Pinata: כל קובץ מקבל פינים על כמה צמתים של הספק, ומצב המרשם מושווה לספק דרך ממשק תוכנה. את הזמינות בודק מעבר אוטומטי — הוא מבקש את התוכן לפי כל CID ומסמן פער לפני שהמשתמש יראה אותו.

ניסיונות חוזרים והצמדה מחדש בעת תקלה הועברו למדיניות נפרדת, והיסטוריית שינויי המרשם נשמרת בנפרד מהקבצים עצמם.

מה נהיה

זמינות הקבצים עלתה ל-99,9% ונשארת ברמה הזו בלי התערבות ידנית. השחזור לאחר תקלת צומת אורך דקות: המרשם עצמו מראה אילו פינים צריך להרים מחדש.

את ההשוואות הידניות הסירו לחלוטין — במקום משימה של חצי יום נותר דוח שקוראים בשתי דקות, וסוג הכשל "הקישור קיים, הקובץ לא" כבר אינו מופיע במרשם.

עבור הלקוח משמעות הדבר היא שהמרשם מתאר את מצב האחסון בפועל, ולא את מה שהיה ברגע ההעלאה. בהמשך נפרק כיצד מתאר כזה נשמר במצב עובדי.

במה הצמדה שונה מגיבוי

ברשת IPFS הצמדה אינה עותק, אלא התחייבות של צומת מסוים שלא למחוק את בלוק הנתונים בעת איסוף אשפה. כל עוד הצומת חי ומחזיק את הקובץ באחסונו, התוכן זמין לפי כתובת המחושבת מהנתונים עצמם. הגיבוי בנוי אחרת: זהו מופע בלתי-תלוי במקום אחר, עם גרסאות ומדיניות אחסון.

מכאן גם תרחישי כשל שונים. הצומת שהצמיד יכול להיות כבוי, לאבד דיסק או להיעלם יחד עם הספק — הכתובת נשארת תקפה, אבל אף אחד לא עונה לפי. העותק שורד אובדן כזה: הוא מונח בנפרד ואינו תלוי בחיי צומת אחד. לכן הצמדה וגיבוי מכסים סיכונים שונים ואינם מחליפים זה את זה.

גם תקופת האחסון בנויה אחרת. הצמדה תקפה כל עוד מישהו מחזיק בה — מבחינה פורמלית ללא הגבלת זמן, אבל בלי התחייבויות: ההבטחה חיה בדיוק כל עוד חי הצומת. אצל העותק התקופה נקבעת במדיניות — כמה גרסאות קודמות לשמור, באיזו תדירות מתבצעת רוטציה, מה נמחק ראשון. זהו פרמטר מנוהל, ולא תוצר לוואי, והוא בדיוק מה שקובע מה יישאר מהנתונים כעבור שנה.

שחזור קבצים נשען על עותקים, ולא על הצמדה. המתאר העובדי: הצמדה אצל שני ספקים בלתי-תלויים, השוואה סדירה של סכומי ביקורת וייצוא עותק ארכיוני לאחסון קר עם ניהול גרסאות. אז כשל של כל צומת אחד או החלפת ספק אינו הופך את הנתונים לבלתי-זמינים, ושיעור האובייקטים שאבדו נשאר אפס.

ספקות טכניים: מועדים, שלמות, גישה

לפני ההתחלה צוות ההנדסה בודק בדרך כלל ארבעה דברים: תוך כמה זמן הקובץ באמת מוצמד, כיצד להשתכנע שהתוכן לא הוחלף, מי מהגורמים החיצוניים מקבל גישה ומה יהיה עם מרשם שכבר נצבר. להלן תשובות ענייניות, בלי הבטחה של "עובד מהקופסה", כולל לגבי שירותי הצמדה כגון Pinata.

הצמדה אינה קריאה בודדת, אלא מצב: כל עוד לקובץ יש פינים פעילים אצל כמה מחזיקים בלתי-תלויים, הוא זמין גם בעת כשל של אחד מהם. את השלמות מספקת הכתובות לפי תוכן עצמה: ההאש של הקובץ הוא כתובתו, כל עריכה משנה את הכתובת, וההחלפה נעשית גלויה בקריאה הראשונה.

הגישה מוגבלת ברמת השער ובקישורים חתומים עם תפוגה, ולא ב"סודיות" של האחסון. המיגרציה של מרשם קיים מתבצעת בשלב נפרד: סופרים נפח, מסירים כפילויות, מעבירים, משווים סכומי ביקורת — ורק אחר כך מנתקים את המתאר הישן.

כיצד לבדוק שהקובץ לא הוחלף?

ההשוואה נעשית לפי כתובת התוכן בכל קריאה, ולא באופן חד-פעמי בעת ההעלאה. אם סכום הביקורת אינו תואם, הקריאה מחזירה שגיאה והקובץ מסומן כפגום — ההחלפה אינה עוברת בשקט.

מה יהיה עם מרשם שכבר נצבר?

מעבירים בלי לעצור את העבודה: המתאר הישן ממשיך לענות עד שהחדש הושווה בכל הרשומות. החזרה לאחור היא החזרת המתג למקור הקודם, ואין צורך בהעלאה מחדש.

למי זמינים הקבצים בזמן ההעברה?

קישורים מונפקים חתומים ועם תקופה מוגבלת, ההרשאות נבדקות בשער, והכתובות הפנימיות של המחזיקים אינן נחשפות החוצה. בעת ההעברה הקישורים הישנים אינם מבוטלים עד שתפוג תקופתם.

נדון במשימה: הצמדת קבצים למתאר שלכם

כדי שההערכה תישען על מספרים, ולא על הערכות גסות, אנו צריכים פרוסה של האחסון: מה מצמידים ב-IPFS, מי קורא זאת וכמה זמן האובייקטים חיים. להלן מערך מינימלי של נתוני פתיחה שמספיק כדי לחשב נפחים, להרכיב תוכנית יישום ולא לעצב מחדש את סכמת הגישה באמצע. אפשר לשלוח בצורה חופשית: ברשימה, בטבלה או בייצוא מהמרשם הקיים.

• הרכב מרשם הקבצים — סוגי אובייקטים (מדיה, מסמכים, ייצוא משתמשים), גודל ממוצע ושיא, גידול יומי, נפח נוכחי. מכאן מחשבים את תפוקת ההעלאה ואת אסטרטגיית ההצמדה.
• תרחישי גישה — מי ומאיפה קורא: קישורים ציבוריים, שירותים פנימיים, אפליקציות מובייל. בנפרד מתעדים אם דרוש שער או כתובות ישירות לפי תוכן.
• תקופות אחסון — מה חי ללא הגבלת זמן, מה עובר לארכיון, מה נמחק לפי נוהל. מכאן מרכיבים את מדיניויות הניקוי ואת כללי המעבר בין רמות האחסון.
• דרישות גישה — מי מנפיק מפתחות, כיצד מופרדות הרשאות קריאה וכתיבה, האם נדרשת הפרדה לפי מתארים ותיעוד הפניות לאובייקטים.
• נקודות אינטגרציה — הבקנד הקיים, תורים, שירותי עיבוד ולאן חוזר המזהה של האובייקט המוצמד.
• מגבלות המתאר שלכם — מתאר סגור, דרישות למיקום הנתונים, סכמת גיבוי ותרחיש שחזור מאומת.
• מצב נוכחי — איזה ספק הצמדה אתם משתמשים בו, כיצד בנויה הכתובות, ובאילו פעולות כבר נתקלתם בתקרה.

עם מערך כזה אנו חוזרים עם הערכה לפי נפח האחסון, תוכנית יישום לפי שלבים ותיאור של מרשם שישרוד גידול בעומס. תארו את המשימה — נרכיב הצעה ונראה בדיוק מה יוצא לעבודה.