דלגו לתוכן

ארכיטקטורה

← חזרה לאינדקס התיעוד

Minecraft Server Manager הוא יישום Node.js המוצג בצד השרת, הפועל בתהליך יחיד. הוא מנהל שרתי Minecraft הפועלים כקונטיינרים של Docker באמצעות ה- itzg/docker-minecraft-server image, ומתקשר עם שרת ה-Docker דרך ה-API שלו (לעולם לא על ידי הפעלת docker CLI).

  • Express + Handlebars מרנדרים דפים בצד השרת. אין SPA; ה-JavaScript בדפדפן ב-public/js/ הוא שיפור הדרגתי שנכתב ידנית. שלב esbuild (pnpm run build:js) מאגד ומכווץ אותו ל-public/dist/js/; היישום מגיש את החבילה הזו כאשר היא קיימת ואת המקור הגולמי אחרת, כך שגם הרצה בפיתוח ללא בנייה עדיין עובדת.
  • node:sqlite (מובנה ב-Node; הפאנל דורש Node ≥ 24) הוא מסד הנתונים - סינכרוני, ללא מודולים מקוריים, במצב WAL. מריץ מיגרציות גרסאות קטן מיישם את src/db/migrations/* בעת האתחול. הצהרות מוכנות נשמרות במטמון ב-src/db/index.js עם מפתח לפי טקסט ה-SQL.
  • ws נושא את זרמי הקונסולה והסטטיסטיקות החיים. שניהם מתווכים: אחד למעלה docker logs --follow (או docker stats) לכל שרת, מפורק פעם אחת ומפוזר לכל טאב מחובר, במקום אחד למעלה לכל צופה. מתווך הקונסולה שומר על מאגר השמעה קטן לטאבים מצטרפים מאוחרים וזורק מנוי שחיבור ה-socket שלו נופל רחוק מדי במקום להאט את הזרם המשותף.
  • dockerode היא הדרך היחידה שבה היישום מתקשר עם Docker. נקודת הקצה מזוהה אוטומטית לפי פלטפורמה (שם צינור Windows לעומת socket יוניקס).
  • כל המצב המתמשך חי תחת ספרייה אחת ($DATA_DIR, ברירת מחדל ./data). העתקת ספרייה זו מעבירה את כל הפאנל.

תלויות זורמות בכיוון אחד:

┌─────────────────────────────┐
HTTP ───────▶│ web/routes/* (+ middleware)│ נתח ואמת קלט, עצב תגובות
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ services/* │ לוגיקת תחום (התכונות בפועל)
└───┬─────────┬─────────┬─────┘
│ │ │
┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐
│ docker/* │ │ db/* │ │ storage/* │ תשתית
└───────────────┘ └─────────┘ └─────────────┘
  • web/routes/ - נתב אחד לכל תחום (players, worlds, crashes, blueprints, files, …). web/app.js מרכיב את אלו ברמה העליונה (api.js, ה-JSON API של הסשן שמחזיק גם את נתיבי השרת הליבה ומרכיב את נתבי התחום לכל שרת; index.js, הדפים; auth, account, tasks, …). הנתבים מאמתים עם zod, קוראים לשירות, ומחזירים JSON או מרנדרים תצוגה. לוגיקת עסקים אינה שייכת לכאן. שני נתבים מורכבים ב-אזור הציבורי, לפני requireAuth: routes/status.js (דפי סטטוס לכל שרת אופציונליים) ו-routes/apiV1.js (/api/v1, API JSON לקריאה בלבד המאומת באמצעות אסימון Bearer שהונפק על ידי מנהל מערכת מ-services/apiTokens.js, כבוי אלא אם מופעל בהגדרות; ראה docs/public-api.md).
  • services/ - לב היישום. כל שירות שייך לתחום אחד ועשוי להיות תלוי בתשתית ובשירותים אחרים.
  • docker/ - עטיפות dockerode: connect (זיהוי נקודת קצה + בריאות שרת), containers (יצירה/הפעלה/עצירה/יצירה מחדש עם mount-ים, מגבלות זיכרון/CPU, ותוויות), logs, stats, images, networks (גילוי רשת מארח), hostPath (שורשים מחדש של bind paths תחת DATA_DIR_HOST), ו-watcher שהופך אירועי Docker להיסטוריה + זיהוי קריסות.
  • db/ - עטיפת SQLite ומריץ המיגרציות.
  • storage/ - האתחול של ./data, שומר הנתיבים (safeJoin, עמוד השדרה של בטיחות קבצים), ומדד הגודל ברקע + אכיפת מכסות.

חפיפה:

  • config/ - תצורת סביבה בתוספת קטלוג השדות: מקור האמת היחיד להגדרות שרת. כל משתנה סביבה של itzg מקוטלג (תווית, עזרה, סוג, יחידה, ברירת מחדל, אימות, סעיף, דגלי סכנה). האשף, טפסי ההגדרות, ואימות zod כולם נגזרים ממנו, כך שחשיפת הגדרה חדשה היא שינוי נתונים, לא אינסטלציה חדשה של ממשק משתמש.
  • events/ - recordEvent() הוא נקודת הכניסה היחידה ליומן ההיסטוריה; אירועי מחזור חיים לוכדים גם קטעי יומן שרת ל-data/logs/<id>/events/.
  • ws/ - WebSockets מאומתים לקונסולה + סטטיסטיקות (עוגיית סשן מאומתת בעת שדרוג, Origin נבדק כדי לחסום גניבת אתרים צולבת), מתווכים לכל שרת (ראה “מבנה זמן ריצה”).
  • logger.js + instrument.js - require('./logger')(label) מחזיר יומן Pino לכל מודול; רמה מ-LOG_LEVEL, makeFailureThrottle() שומר על לולאת רקע שנכשלת באופן קבוע בשורה אחת של יומן בתוספת שורה “התאושש”. src/utils/logSanitize.js מסיר מפתחות בצורת פרטי התחברות ואסימוני webhook מהמטא-דאטה המובנה; src/config/logLevel.js הוא רשימת ההיתרים המשותפת לרמה (נשמרת בנפרד כדי למנוע מחזור דרישות עם config). src/instrument.js הוא תפר Sentry רדום, נטען ראשון ב-src/server.js. src/web/middleware/requestLog.js כותב שורת גישה אחת לכל בקשה (מדלג על /healthz ונכסים סטטיים). ESLint אוכף no-console תחת src/**, עם preflight.js, instrument.js, ו-config/index.js פטורים (הם פועלים לפני שהיומן קיים).
  • הגבלת קצב - src/web/middleware/rateLimit.js מציב express-rate-limit לפני /api (RATE_LIMIT_API_PER_MIN, ברירת מחדל 1200) והכניסות / 2FA / הגדרות POST (RATE_LIMIT_AUTH_PER_15MIN, ברירת מחדל 100); 0 משבית מגביל. הוא מקודד לפי req.ip, כך ש-TRUST_PROXY חשוב מאחורי פרוקסי. ל-/api/v1 יש מגבלות משלו: מכסה לכל IP לקוח (פי חמישה מתקציב האסימון לכל לקוח) שפועל לפני אימות האסימון, ואז תקציב לכל אסימון (RATE_LIMIT_PUBLIC_API_PER_MIN, ברירת מחדל 120) מקודד לפי מזהה האסימון המאומת. מונה רך נפרד לכל חשבון ב- src/web/middleware/auth.js מטפל בנעילת כניסה (לכל IP ולכל חשבון גלובלי, דועך).
  • הרשאה: שתי שכבות. התפקיד הגלובלי (requireAuth → requireRole / requireWrite ב-src/web/middleware/auth.js) שומר על פעולות בכל הפאנל והוא ברירת המחדל בכל שרת. הרשאות לכל שרת (src/services/permissions.js, תשע יכולות המאוחסנות כרשימת JSON לכל (user, server) ב-user_server_permissions) מרככות את ברירת המחדל הזו עבור שרת אחד; כל נתיב /api/servers/:id, הרכבת נתב משנה, דף, WebSocket, ורשימה בכל הפריסה עוברים דרך src/web/middleware/serverAccess.js (serverScope, מורכב על קידומת /servers/:id של ה-API ושל נתב הדפים, מסתיר שרת ללא view כ-404; requireCap(cap) מציין את היכולת שנדרשת לנתיב). כתיבות ששמן שרת בגוף (לוחות זמנים, חילוץ והתקנת עולם, ייצוא תכניות) פתוחות לצופים רק על ידי requireWrite עבור אותו שרת, וכל נתיב כזה בודק את היכולת בעצמו. test/permissions-routes.test.js עובר על ערימות הנתבים החיים ונכשל אם לנתיב כתיבה, הרכבה, או דף עם היקף שרת אין שומר.
  • Modpacks תמיד מקובעים. ה-image משדרג אוטומטית חבילות לא מקובעות בכל הפעלה מחדש, כך שהפאנל פותר “latest” למזהה גרסה קונקרטי בזמן ההתקנה ומקבע אותו. שדרוגים הם זרימה מורכבת מפורשת (updates/): תצוגה מקדימה → גיבוי לפני עדכון → עצירה חלקה → הצמדה מחדש → יצירה מחדש → ניטור בריאות → גלגול לאחור בלחיצה אחת.
  • שכבת ה-mod המותאמת אישית מנוהלת על ידי הפאנל: mods שנוספו על ידי משתמש נוחתים בספרייה המנוטרלת כפילויות ומקושרים קשיחים לשרת כך שהם שורדים עדכוני חבילה. השבתה מודעת לסוג. מכיוון שהספרייה שומרת כל בנייה שהורידה, עדכון רושם את הבנייה שהוחלפה (server_content.previous_*) ויכולה להיות מוחזרת מקבצים מקומיים בלבד. השבתת mod של חבילה כותבת את משתנה הסביבה של החבילה במקום זאת; packs.applyPack נושא את זה ואת שאר כוונון החבילה (PACK_TUNING_KEYS) מעבר לשינוי גרסה של אותה חבילה, וזורק אותו כאשר החבילה משתנה.
  • שדרוג גרסת Minecraft חייב להירוויח. services/compat.js סורק את ה-mods של השרת - נפתרים משורות שהותקנו על ידי הפאנל, ואז מניפסט חבילת CurseForge, ואז לפי hash תוכן מול Modrinth/CurseForge - ובונים מטריצת תמיכה (loader, גרסת Minecraft) לכל פרויקט מתוך latestFilesIndexes של CurseForge (200 פרויקטים לבקשה) ורשימת הגרסאות לכל פרויקט של Modrinth (בקשה אחת לכל פרויקט, שזה מה ששומר על loader וגרסה יחד). בודק העדכונים מציע רק את הגרסה החדשה ביותר שכל mod תומך בה, ולא מציע דבר כלל כאשר התשובה לא ניתנת לקביעה: אין סריקה, סריקה עבור גרסה או loader שונה, כזו שמעולם לא הסתיימה, או קובץ jar ששום רישום לא מזהה. סריקות הן ידניות בלבד, וההתקדמות והתוצאות החלקיות שלהן נמצאות ב-version_compat (לא ב-services/tasks.js בזיכרון), כך שרענון או הפעלה מחדש של הפאנל ממשיכים במקום להיתקע על ספינר; reconcileScans() מסמן סריקות יתומות על ידי כיבוי בעת האתחול הבא.
  • גרסת ה-mod loader היא פין, כמו כל דבר אחר. services/loaderPin.js קורא את הבנייה המותקנת מתוך מניפסט ההתקנה של ה-image עצמו (.forge-manifest.json וחבריו) וכותב את הפין: משתנה ה-loader של itzg בשרת רגיל (FORGE_VERSION, …), או CF_MOD_LOADER_VERSION בחבילת CurseForge של Forge או Fabric, אשר דורס את הגרסה שהחבילה מצהירה עליה. מתקין ה-CurseForge של ה-image מתעלם מדריסה זו עבור NeoForge, ולחבילות Modrinth ו-FTB אין כאלה, כך שה-loader שלהן עוקב אחר החבילה. packs.applyPack מסיר את כל משתני CF_ בעת עדכון או גלגול לאחור של חבילה, אשר זורק דריסה עם השאר. בנייה מטיפוס נבדקת מול הרשימה המלאה של הרישום תחילה (services/loaderVersions.js; של Forge מגיע ממטא-דאטה של maven, שמשמיט מספרים; פספוס נבדק שוב פעם מול הרישום עצמו), ואז השינוי הוא גיבוי → פין (מעל הסביבה כפי שהיא לאחר הגיבוי) → בנייה מחדש.
  • פורטים מוקצים מסכמה בסיסית (משחק מ-PORT_GAME_START ומעלה, RCON = משחק + PORT_RCON_OFFSET, Bedrock מ-PORT_BEDROCK_START), נבדקים זמינותם, ונשמרים במסד הנתונים. “תפוס” הוא האיחוד של כל תביעות השרתים (פורטים חיים, בתוספת זוג ממתין למטה), כל פורט מארח שכל קונטיינר Docker מפרסם (containers.publishedHostPorts: קשירות חיות של קונטיינרים פועלים בתוספת אלו שהוגדרו של כל קונטיינר עצור, מכיוון שבדיקת bind של מערכת ההפעלה מתוך הקונטיינר של הפאנל עצמו רואה רק את מרחב הרשת של אותו קונטיינר), ובדיקת מערכת ההפעלה. חלק ה-Docker נשמר במטמון למשך 3 שניות ומוגבל: רשימה שלא עונה תוך 2.5 שניות זורקת רק את חלק ה-Docker, ובדיקת inspect איטית עולה רק את הפורטים של אותו קונטיינר. יצירת שרת ו-servers.changeGamePort בוחרים פורטים דרך שרשרת סריאליזציה אחת שמכסה רק את הבחירה ואת טענתה (כתיבת השורה ליצירה, השמירה בזיכרון לשינוי פורט); בוחר הפורטים של BlueMap והדריסות הנוספות של פורטים אינם בתוכו ואינם מתייעצים עם Docker. שינוי פורט בשרת קיים (servers.changeGamePort, תחת נעילת ה-op של השרת) מיושם בבת אחת, מכיוון ש-Docker מתקן קשירות פורטים בעת יצירת קונטיינר: הזוג החדש (RCON תמיד משחק + PORT_RCON_OFFSET) נבדק ונשמר בזיכרון (ports.reserve, גם הזוג הישן וגם החדש, מכובדים על ידי כל בחירה אחרת) תחת נעילת הפורט. הוא נדחה (409 PENDING_CHANGES) כל עוד הגדרות אחרות ממתינות לבנייה מחדש, כך שהוא בונה מחדש רק קונטיינר שכבר פעל, בפורט חדש; ושרת פועל משונה רק כאשר הבקשה אומרת restart: true (אחרת 409 NEEDS_CONFIRM). ה-image נמשך ושם קונטיינר מותאם אישית נבדק לפני שנוגעים במשהו. שרת פועל נעצר; ואז הזוג החדש נכתב עם pending_recreate = 1 (כך שקריסת פאנל משם משאירה “בנייה מחדש ממתינה” כנה), הקונטיינר מוסר, נבנה מחדש על הזוג החדש ומופעל. אם שלב כלשהו לאחר העצירה נכשל, putBackOnOldPort כותב את הזוג הישן בחזרה, בונה מחדש (ומפעיל מחדש, אם הוא פעל) עליו ורושם איזה שלב נכשל; היסטוריה והתראות אומרות אם גם זה נכשל, מה שמשאיר את השרת עצור עד שמישהו יפעיל אותו. היכולת settings מספיקה, כולל שרת פועל. לא-מנהלי מערכת יכולים לבחור רק מ-PORT_GAME_START ומעלה. (עמודות port_*_pending ממיגרציה 029 שייכות לעיצוב מוקדם יותר, שלא שוחרר ואינן בשימוש; 031 מנקה אותן.) התנגשות נענה 409 עם code: 'BUSY', אשר הקוראים המנסים שוב למטה בודקים במקום את הניסוח. הפעלה מחדש אוטומטית לאחר קריסה (watcher.restartAfterCrash) וגיבוי מתוזמן או התחלה (scheduler.runTaskWithRetry) שמוצאים את השרת עסוק בפעולה אחרת מנסים שוב כל 20 שניות / 60 שניות למשך עד 30 דקות, ועדכון או גלגול לאחור של חבילה מנסים שוב את השלבים הנעולים שלה באותה דרך (opLock.retryWhileBusy); הפעלה מחדש של קריסה או התחלה מתוזמנת ממתינה מוותרת ברגע שמישהו עצר, הרג או התחיל את השרת מאז (events.lifecycleActionSince), והפעלה מחדש של קריסה גם כאשר הפעלה מחדש אוטומטית כבויה או שהשרת אינו קיים. הפעלות מחדש מתוזמנות, עצירות ופקודות אינן מנסות שוב, ולוח זמנים שהרצתו האחרונה עדיין ממתינה מדלג על ההפעלה הבאה שלו.
  • מכסות דיסק נאכפות על ידי הפאנל מכיוון ש-Docker אינו יכול להגביל את השימוש ב-bind-mount: המדד שומר במטמון גדלים לכל ספרייה ופעולות גידול דיסק מוגבלות על פיהן.
  • סודות (סיסמאות RCON, מפתחות API, סודות TOTP, כתובת ה-Discord webhook) מוצפנים במנוחה עם AES-256-GCM באמצעות מפתח אקראי ייעודי ב-$DATA_DIR/.secret-key (מצב 0600, נוצר אוטומטית). הוא בלתי תלוי ב-SESSION_SECRET; מפתח הנגזר מ-SESSION_SECRET נשמר כגיבוי לצורך פענוח בלבד עבור ערכים שנכתבו לפני שהמפתח הייעודי היה קיים, ו-src/services/secretsMigration.js מצפין מחדש אותם תחת המפתח הייעודי פעם אחת בעת האתחול. קובץ .secret-key קיים אך אינו ניתן לפענוח הוא שגיאת אתחול קשה (הוא לעולם לא נוצר מחדש בשקט מעל). תכניות מוחקות את כל הסודות בעת ייצוא.
  • server.properties הוא בבעלות הפאנל אך מוצל על ידי הסביבה. ה-image של itzg מאשר מחדש כל מאפיין מגובה סביבה בכל הפעלה (OVERRIDE_SERVER_PROPERTIES ברירת מחדל true), כך שערך שהפאנל עורך ישירות - בקרות עולם PvP/קושי, מתג ה-whitelist, עורך הקבצים - יוחזר בשקט בהפעלה הבאה אלא אם כן משתנה הסביבה התואם יוסר והקונטיינר ייווצר מחדש. כל כתיבת מאפיין ישירה עוברת דרך writeServerProperties() (קובץ שלם) או setServerProperty() (מפתח אחד) ב-src/services/servers.js, אשר כותבים מחדש את הקובץ באופן אטומי, מבטלים את משתנה הסביבה מאחורי כל מפתח ששונה (דרך התכונה prop: בשדות הקטלוג, נבדק במבחנים מול הגדרות המאפיינים של ה-image עצמו), ומסמנים pending_recreate. הקושי נכתב לקובץ וגם נשלח דרך RCON, מכיוון ששרת ייעודי מיישם מחדש את מאפיין difficulty בכל אתחול. Minecraft עצמו שומר מחדש את server.properties מערכי האתחול שלו בעת הפעלה/כיבוי של whitelist, אשר יבטל עריכות שבוצעו בזמן שהשרת פועל, כך שמתג ה-whitelist הפועל מצלם את הקובץ תחילה וכותב אותו בחזרה עם שינוי רק של white-list. משתני הסביבה נשארים ניתנים להגדרה מלאה בעת יצירה (האשף מציג אותם והם חלים פעם אחת); הם רק מבטלים את הפין בפעם הראשונה שהפאנל עורך את המאפיין הבסיסי. MOTD הוא אותו חוזה: עריכת קובץ motd ישירה מבטלת אותו, כך שהכתיבה האחרונה מנצחת.

פורמטים של נתונים וחוטים

Section titled “פורמטים של נתונים וחוטים”
  • data/panel.db - מסד הנתונים SQLite. מצולם יומי באמצעות VACUUM INTO ל- data/backups/_panel/ (האחרונים 14 נשמרים); PRAGMA integrity_check פועל בעת האתחול.
  • data/.session-secret - הסוד החתום אוטומטית של עוגיית הסשן, נוצר בהרצה הראשונה אם SESSION_SECRET לא מוגדר. מחיקתו מסובבת את הסוד (מה שפוסל סשנים).
  • data/.secret-key - מפתח ההצפנה הייעודי במנוחה בגודל 32 בתים (מצב 0600), נוצר אוטומטית בהרצה הראשונה. בלתי תלוי ב-SESSION_SECRET; מחיקתו הופכת כל פרטי התחברות מאוחסנים לבלתי ניתנים לפענוח, כך שהוא שייך לגיבויים שלך.
  • תכניות (.mcserver.zip) - קובץ zip עם manifest.json המתאר תצורה, משאבים, הפניה לחבילה מקובעת, מניפסט שכבת-על (מקורות URL + sha256), קבצי תצורה נבחרים, ואופציונלית עולם. ייבוא מוריד מחדש ומאמת hash כל mod ומקצה פורטים חדשים.
  • קונטיינרים של Docker שנוצרו על ידי הפאנל נקראים ומסומנים כך שה-watcher יוכל למצוא אותם; הפאנל הבעלים של מחזור החיים המלא שלהם.
  1. require('./instrument') (תפר Sentry) לפני כל דבר אחר, ואז require('./preflight') כדי להיכשל בבירור בגרסת Node לא נתמכת.
  2. טען תצורה; ודא/צור .session-secret וגם .secret-key.
  3. ensureDataRoot() - צור את פריסת ./data, נקה את tmp/.
  4. הפעל מיגרציות מסד נתונים, ואז PRAGMA integrity_check (רושם בקול רם, מצביע על data/backups/_panel במקרה של כשל).
  5. הצפן מחדש כל סוד ישן המפתח של SESSION_SECRET תחת .secret-key (secretsMigration).
  6. ייבא מפתחות API מהסביבה פעם אחת (apiKeys.importFromEnvOnce()), קבע כל שרת שעדיין נושא בורר modpack לא מקובע (packPins.pinUnpinnedServers()), סמן סריקות תאימות גרסה שהושארו פועלות על ידי תהליך קודם כהופרעו (compat.reconcileScans()), ואז זרע תכניות התחלתיות (מוגן).
  7. הפעל את שרת ה-HTTP + WS. ב-bind חשוף, הדפס את ה-PIN של /setup בהרצה הראשונה.
  8. התקן את שומר הזמן ריצה לאחר האתחול (לוכד תקלות שלא נתפסו; MSM_EXIT_ON_FATAL=1 גורם לו לצאת קשה עבור פריסות מפוקחות).
  9. הפעל שירותי רקע: מתווך WS, מדד אחסון, צופי קריסות + מלאי, מתזמן, גשר אירועי Discord, צופה פנייה של צ’אטבוט, וטיימר תחזוקה יומי (גזום שורות אנליטיקה ישנות, תמלילי צ’אטבוט, היסטוריית אירועים (365 ימים) ושורות מטמון API, ואז צלם את panel.db).
  10. אתחל את Docker ברקע. הממשק שימושי לחלוטין בזמן שהדמון למטה; תכונות Docker נדלקות כאשר הוא הופך לנגיש. לאחר החיבור, refreshStatuses({ boot }) מיישב מחדש סטטוסים שמורים במטמון, פולט אירוע חד-פעמי של offline-after-restart עבור שרת שהיה פעיל לפני שהפאנל הופעל מחדש ולא יוחזר, ולולאת האתחול מתחילה שרתי auto_start ומשחזרת שרתי auto_restart שנמצאו קרוסים במהלך ההשבתה (תוך כיבוד השהיית לולאת קריסה).

סדר ה-instrument-before-preflight הוא פשרה מכוונת: הוא מאפשר לחוט Sentry עתידי לתקן את זמן הריצה תחילה, במחיר הודעה פחות ידידותית בהודעה על גרסת Node עתיקה באמת.

pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild → public/dist/js/, ESM עם חלוקת קוד). postinstall מריץ CSS בלבד. public/css/app.css ו-public/dist/ הם ארטיפקטים של בנייה המוזנחים ב-git; שלב בניית ה-Dockerfile מריץ את ה-pnpm run build המלא ומעתיק את public/ לתמונת זמן הריצה. נכסים סטטיים מוגשים immutable/long-cache עבור קבצים עם טביעת אצבע, short-cache עבור CSS/JS, ו-no-cache עבור HTML ו-/api.