ארכיטקטורה
Minecraft Server Manager הוא יישום Node.js המוצג בצד השרת, הפועל בתהליך יחיד. הוא מנהל
שרתי Minecraft הפועלים כקונטיינרים של Docker באמצעות ה-
itzg/docker-minecraft-server image, ומתקשר עם
שרת ה-Docker דרך ה-API שלו (לעולם לא על ידי הפעלת docker CLI).
מבנה זמן ריצה
Section titled “מבנה זמן ריצה”- 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עובר על ערימות הנתבים החיים ונכשל אם לנתיב כתיבה, הרכבה, או דף עם היקף שרת אין שומר.
התנהגויות תחום מפתח
Section titled “התנהגויות תחום מפתח”- 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, גם הזוג הישן וגם החדש, מכובדים על ידי כל בחירה אחרת) תחת נעילת הפורט. הוא נדחה (409PENDING_CHANGES) כל עוד הגדרות אחרות ממתינות לבנייה מחדש, כך שהוא בונה מחדש רק קונטיינר שכבר פעל, בפורט חדש; ושרת פועל משונה רק כאשר הבקשה אומרתrestart: true(אחרת 409NEEDS_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 יוכל למצוא אותם; הפאנל הבעלים של מחזור החיים המלא שלהם.
רצף אתחול
Section titled “רצף אתחול”require('./instrument')(תפר Sentry) לפני כל דבר אחר, ואזrequire('./preflight')כדי להיכשל בבירור בגרסת Node לא נתמכת.- טען תצורה; ודא/צור
.session-secretוגם.secret-key. ensureDataRoot()- צור את פריסת./data, נקה אתtmp/.- הפעל מיגרציות מסד נתונים, ואז
PRAGMA integrity_check(רושם בקול רם, מצביע עלdata/backups/_panelבמקרה של כשל). - הצפן מחדש כל סוד ישן המפתח של
SESSION_SECRETתחת.secret-key(secretsMigration). - ייבא מפתחות API מהסביבה פעם אחת (
apiKeys.importFromEnvOnce()), קבע כל שרת שעדיין נושא בורר modpack לא מקובע (packPins.pinUnpinnedServers()), סמן סריקות תאימות גרסה שהושארו פועלות על ידי תהליך קודם כהופרעו (compat.reconcileScans()), ואז זרע תכניות התחלתיות (מוגן). - הפעל את שרת ה-HTTP + WS. ב-bind חשוף, הדפס את ה-PIN של
/setupבהרצה הראשונה. - התקן את שומר הזמן ריצה לאחר האתחול (לוכד תקלות שלא נתפסו;
MSM_EXIT_ON_FATAL=1גורם לו לצאת קשה עבור פריסות מפוקחות). - הפעל שירותי רקע: מתווך WS, מדד אחסון, צופי קריסות + מלאי, מתזמן, גשר אירועי Discord, צופה פנייה של צ’אטבוט, וטיימר תחזוקה יומי (גזום שורות אנליטיקה ישנות, תמלילי צ’אטבוט, היסטוריית אירועים (365 ימים) ושורות מטמון API, ואז צלם את
panel.db). - אתחל את Docker ברקע. הממשק שימושי לחלוטין בזמן שהדמון למטה;
תכונות Docker נדלקות כאשר הוא הופך לנגיש. לאחר החיבור,
refreshStatuses({ boot })מיישב מחדש סטטוסים שמורים במטמון, פולט אירוע חד-פעמי שלoffline-after-restartעבור שרת שהיה פעיל לפני שהפאנל הופעל מחדש ולא יוחזר, ולולאת האתחול מתחילה שרתיauto_startומשחזרת שרתיauto_restartשנמצאו קרוסים במהלך ההשבתה (תוך כיבוד השהיית לולאת קריסה).
סדר ה-instrument-before-preflight הוא פשרה מכוונת: הוא מאפשר לחוט Sentry עתידי לתקן את זמן הריצה תחילה, במחיר הודעה פחות ידידותית בהודעה על גרסת Node עתיקה באמת.
צינור בנייה
Section titled “צינור בנייה”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.