สถาปัตยกรรม
Minecraft Server Manager เป็นแอปพลิเคชัน Node.js แบบ single-process ที่เรนเดอร์บนเซิร์ฟเวอร์ จัดการเซิร์ฟเวอร์ Minecraft ที่ทำงานเป็นคอนเทนเนอร์ Docker โดยใช้ image itzg/docker-minecraft-server โดยสื่อสารกับ Docker daemon ผ่าน API (ไม่เคยเรียกใช้ docker CLI ผ่าน shell)
รูปแบบการทำงาน (Runtime shape)
หัวข้อที่มีชื่อว่า “รูปแบบการทำงาน (Runtime shape)”- Express + Handlebars ใช้เรนเดอร์หน้าเว็บฝั่งเซิร์ฟเวอร์ ไม่มี SPA; JavaScript ใน
public/js/เป็นการปรับปรุงแบบ progressive enhancement ที่เขียนขึ้นเอง ขั้นตอน esbuild (pnpm run build:js) จะรวมและย่อขนาดให้เป็นpublic/dist/js/; แอปจะเสิร์ฟ bundle นั้นเมื่อมีอยู่ และ source ดั้งเดิมหากไม่มี เพื่อให้การรันในโหมดพัฒนาโดยไม่ต้อง build ยังคงทำงานได้ node:sqlite(ฝังมากับ Node; แผงควบคุมต้องการ Node ≥ 24) คือฐานข้อมูล แบบ synchronous, ไม่มี native modules, โหมด WAL ตัวจัดการการอัปเกรดเวอร์ชันขนาดเล็กจะใช้src/db/migrations/*เมื่อเริ่มทำงาน Prepared statements จะถูกแคชไว้ในsrc/db/index.jsโดยใช้ข้อความ SQL เป็นคีย์wsใช้สำหรับการสตรีมคอนโซลและสถิติแบบสด ทั้งสองอย่างเป็นแบบ brokered: หนึ่ง upstreamdocker logs --follow(หรือdocker stats) ต่อเซิร์ฟเวอร์หนึ่งตัว แยกข้อมูลแล้วกระจายไปยังแท็บที่เชื่อมต่อทั้งหมด แทนที่จะเป็นหนึ่ง upstream ต่อผู้ดูหนึ่งคน ตัวจัดการคอนโซลจะเก็บบัฟเฟอร์ replay ขนาดเล็กสำหรับแท็บที่เข้าร่วมช้า และจะตัดผู้ใช้ที่ socket หลุดไปไกลเกินไป แทนที่จะทำให้สตรีมที่ใช้ร่วมกันหยุดทำงาน- dockerode เป็นวิธีเดียวที่แอปใช้สื่อสารกับ Docker Endpoint จะถูกตรวจจับอัตโนมัติตามแพลตฟอร์ม (Windows named pipe เทียบกับ unix socket)
- สถานะถาวรทั้งหมดจะอยู่ในไดเรกทอรีเดียว (
$DATA_DIR, ค่าเริ่มต้นคือ./data) การคัดลอกไดเรกทอรีนั้นจะย้ายแผงควบคุมทั้งหมด
การจัดชั้น (Layering)
หัวข้อที่มีชื่อว่า “การจัดชั้น (Layering)”การพึ่งพาไหลไปในทิศทางเดียว:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ แยกวิเคราะห์และตรวจสอบความถูกต้องของอินพุต, จัดรูปแบบการตอบสนอง └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ ตรรกะของโดเมน (ฟีเจอร์จริง) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ โครงสร้างพื้นฐาน └───────────────┘ └─────────┘ └─────────────┘web/routes/- เราเตอร์หนึ่งอันต่อโดเมน (players,worlds,crashes,blueprints,files, …)web/app.jsจะรวมเราเตอร์ระดับบนสุด (api.js, JSON API สำหรับ session ที่มีเราเตอร์เซิร์ฟเวอร์หลักและรวมเราเตอร์โดเมนต่อเซิร์ฟเวอร์;index.js, หน้าต่างๆ;auth,account,tasks, …) เราเตอร์จะตรวจสอบความถูกต้องด้วย zod, เรียกใช้ service, และคืนค่า JSON หรือเรนเดอร์มุมมอง ตรรกะทางธุรกิจไม่ควรอยู่ที่นี่ มีสองเราเตอร์ที่รวมอยู่ใน โซนสาธารณะ ก่อนrequireAuth:routes/status.js(หน้าสถานะ HTML ต่อเซิร์ฟเวอร์ที่เลือกเปิดใช้งาน) และroutes/apiV1.js(/api/v1, JSON API แบบอ่านอย่างเดียวที่รับรองความถูกต้องด้วย Bearer token ที่ออกโดยผู้ดูแลระบบจากservices/apiTokens.js, ปิดใช้งานเว้นแต่จะเปิดใช้งานในการตั้งค่า; ดูdocs/public-api.md)services/- หัวใจของแอป แต่ละ service จะเป็นเจ้าของโดเมนหนึ่งโดเมนและอาจพึ่งพาโครงสร้างพื้นฐานและ service อื่นๆdocker/- ส่วนห่อหุ้ม dockerode:connect(การตรวจจับ endpoint + สุขภาพของ daemon),containers(สร้าง/เริ่ม/หยุด/สร้างใหม่พร้อม bind mounts, การจำกัดหน่วยความจำ/CPU, และ labels),logs,stats,images,networks(การค้นหาเครือข่ายโฮสต์),hostPath(เปลี่ยนเส้นทาง bind paths ภายใต้DATA_DIR_HOST), และwatcherที่แปลงเหตุการณ์ Docker เป็นประวัติ + การตรวจจับข้อขัดข้องdb/- ส่วนห่อหุ้ม SQLite และตัวจัดการการอัปเกรดstorage/- การเริ่มต้น./data, ตัวป้องกันเส้นทาง (safeJoin, แกนหลักด้านความปลอดภัยของไฟล์), และตัวจัดทำดัชนีขนาดพื้นหลัง + การบังคับใช้โควต้า
การทำงานข้ามส่วน:
config/- การกำหนดค่าสภาพแวดล้อมพร้อมกับ แคตตาล็อกฟิลด์: แหล่งความจริงแหล่งเดียวสำหรับการตั้งค่าเซิร์ฟเวอร์ ตัวแปรสภาพแวดล้อม itzg ทุกตัวจะถูกจัดทำแคตตาล็อก (ป้ายกำกับ, ความช่วยเหลือ, ประเภท, หน่วย, ค่าเริ่มต้น, การตรวจสอบความถูกต้อง, ส่วน, ธงอันตราย) วิซาร์ด, ฟอร์มการตั้งค่า, และการตรวจสอบความถูกต้องด้วย zod ทั้งหมดได้มาจากสิ่งนี้ ดังนั้นการเปิดเผยการตั้งค่าใหม่จึงเป็นการเปลี่ยนแปลงข้อมูล ไม่ใช่การเดินสาย UI ใหม่events/-recordEvent()เป็นจุดเข้าใช้งานเดียวสำหรับบันทึกประวัติ; เหตุการณ์วงจรชีวิตยังบันทึกส่วนของคอนโซลคอนเทนเนอร์ไปยังdata/logs/<id>/events/ด้วยws/- WebSockets คอนโซล + สถิติที่รับรองความถูกต้อง (การตรวจสอบ cookie session เมื่ออัปเกรด, การตรวจสอบOriginเพื่อบล็อกการโจมตีแบบ cross-site hijacking), จัดการต่อเซิร์ฟเวอร์ (ดู “รูปแบบการทำงาน”)logger.js +instrument.js** -require(‘./logger’)(label)จะคืนค่า logger [Pino](https://getpino.io) ต่อโมดูล; ระดับจากLOG_LEVEL,makeFailureThrottle()จะรักษาลูปพื้นหลังที่ล้มเหลวอย่างต่อเนื่องให้เป็นบรรทัดบันทึกเดียวพร้อมกับบรรทัด "recovered"src/utils/logSanitize.jsจะลบข้อมูลคีย์ที่มีรูปแบบข้อมูลประจำตัวและโทเค็น webhook ออกจากข้อมูลเมตาที่มีโครงสร้าง;src/config/logLevel.jsเป็นรายการที่อนุญาตระดับที่ใช้ร่วมกัน (แยกไว้เพื่อหลีกเลี่ยงวงจรการ require กับconfig)src/instrument.jsเป็นช่องทาง Sentry ที่ไม่ได้ใช้งาน โหลดเป็นอันดับแรกในsrc/server.jssrc/web/middleware/requestLog.jsจะเขียนบันทึกการเข้าถึงหนึ่งบรรทัดต่อคำขอ (ข้าม/healthzและไฟล์สแตติก) ESLint บังคับใช้no-consoleภายใต้src/, โดยมีpreflight.js,instrument.js, และconfig/index.js` ได้รับการยกเว้น (ทำงานก่อนที่ logger จะมีอยู่)- การจำกัดอัตรา (Rate limiting) -
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) โดยใช้คีย์จาก ID โทเค็นที่ตรวจสอบแล้ว ตัวนับแบบ soft ต่อบัญชีแยกต่างหากในsrc/web/middleware/auth.jsจะจัดการการล็อกบัญชี (ต่อ IP และทั่วทั้งบัญชี, ลดลงตามเวลา) - การอนุญาต (Authorization): สองชั้น ระดับสิทธิ์ทั่วโลก (
requireAuth→requireRole/requireWriteในsrc/web/middleware/auth.js) จะควบคุมการดำเนินการทั่วทั้งแผงควบคุมและเป็นค่าเริ่มต้นบนเซิร์ฟเวอร์ทุกเครื่อง สิทธิ์ต่อเซิร์ฟเวอร์ (src/services/permissions.js, เก้าความสามารถที่เก็บเป็นรายการ JSON ต่อ(user, server)ในuser_server_permissions) จะปรับแต่งค่าเริ่มต้นนั้นสำหรับเซิร์ฟเวอร์หนึ่งเครื่อง; ทุกเส้นทาง/api/servers/:id, การรวม sub-router, หน้า, WebSocket, และรายการทั่วทั้ง fleet จะผ่านsrc/web/middleware/serverAccess.js(serverScope, รวมอยู่บน prefix/servers/:idของทั้ง API และเราเตอร์หน้า, จะซ่อนเซิร์ฟเวอร์โดยไม่มีviewเป็น 404;requireCap(cap)จะระบุความสามารถที่เส้นทางต้องการ) การเขียนที่ระบุเซิร์ฟเวอร์ในส่วน body (ตารางเวลา, การแยกและติดตั้ง world, การส่งออก blueprint) จะเปิดให้ผู้ดูโดยrequireWriteเท่านั้นสำหรับเซิร์ฟเวอร์นั้น และแต่ละเส้นทางดังกล่าวจะตรวจสอบความสามารถด้วยตัวเองtest/permissions-routes.test.jsจะเดินผ่านสแต็กเราเตอร์สดและล้มเหลวหากเส้นทางเขียนที่ขอบเขตเซิร์ฟเวอร์, การรวม, หรือหน้าไม่มีการควบคุม
พฤติกรรมหลักของโดเมน (Key domain behaviors)
หัวข้อที่มีชื่อว่า “พฤติกรรมหลักของโดเมน (Key domain behaviors)”- Modpacks จะถูกปักหมุดเสมอ Image จะอัปเกรด modpack ที่ไม่ได้ปักหมุดโดยอัตโนมัติทุกครั้งที่รีสตาร์ท ดังนั้นแผงควบคุมจะแก้ไข “latest” ให้เป็นเวอร์ชันที่แน่นอนเมื่อติดตั้งและปักหมุด การอัปเกรดเป็นกระบวนการที่ชัดเจน (
updates/): แสดงตัวอย่าง → สำรองข้อมูลก่อนอัปเดต → หยุดอย่างนุ่มนวล → ปักหมุดใหม่ → สร้างใหม่ → ตรวจสอบสุขภาพ → กู้คืนด้วยคลิกเดียว - การซ้อนทับ mod ที่กำหนดเอง ถูกจัดการโดยแผงควบคุม: mod ที่ผู้ใช้เพิ่มจะอยู่ในไลบรารีที่ deduplicated และจะถูก hard-link เข้าไปในเซิร์ฟเวอร์เพื่อให้รอดจากการอัปเดต pack การปิดใช้งานจะขึ้นอยู่กับคลาส เนื่องจากไลบรารีจะเก็บทุก build ที่ดาวน์โหลดไว้ การอัปเดตจะบันทึก build ที่ถูกแทนที่ (
server_content.previous_*) และสามารถกู้คืนได้จากไฟล์ภายในเท่านั้น การปิดใช้งาน mod ของ pack จะเขียนตัวแปรสภาพแวดล้อมการยกเว้นของ pack แทน;packs.applyPackจะส่งผ่านสิ่งนั้นและส่วนที่เหลือของการปรับแต่ง pack (PACK_TUNING_KEYS) ข้ามการเปลี่ยนแปลงเวอร์ชันของ pack เดียวกัน และจะลบทิ้งเมื่อเปลี่ยน pack - การอัปเกรดเวอร์ชัน Minecraft จะต้องได้รับการพิสูจน์
services/compat.jsจะสแกน mod ของเซิร์ฟเวอร์ - แก้ไขจากแถวที่ติดตั้งโดยแผงควบคุม, จากนั้นจาก manifest ของ CurseForge pack, จากนั้นโดยการแฮชเนื้อหากับ Modrinth/CurseForge - และสร้างเมทริกซ์การรองรับ (loader, เวอร์ชัน Minecraft) ต่อโปรเจกต์ จากlatestFilesIndexesของ CurseForge (200 โปรเจกต์ต่อคำขอ) และรายการเวอร์ชันต่อโปรเจกต์ของ Modrinth (หนึ่งคำขอต่อโปรเจกต์ ซึ่งทำให้ loader และเวอร์ชันจับคู่กัน) ตัวตรวจสอบการอัปเดตจะเสนอเฉพาะเวอร์ชันล่าสุดที่ mod ทุกตัว รองรับ และจะไม่เสนออะไรเลยเมื่อไม่สามารถระบุคำตอบได้: ไม่มีการสแกน, การสแกนสำหรับเวอร์ชันหรือ loader ที่แตกต่างกัน, การสแกนที่ไม่เคยเสร็จสิ้น, หรือ jar ที่ทั้งสองรีจิสทรีไม่รู้จัก การสแกนทำด้วยตนเองเท่านั้น และความคืบหน้าและผลลัพธ์บางส่วนจะอยู่ในversion_compat(ไม่ใช่ในservices/tasks.jsที่อยู่ในหน่วยความจำ) ดังนั้นการรีเฟรชหรือการรีสตาร์ทแผงควบคุมจะดำเนินการต่อแทนที่จะค้างอยู่ที่สปินเนอร์;reconcileScans()จะทำเครื่องหมายการสแกนที่ถูกทิ้งร้างจากการปิดระบบเมื่อบูตครั้งถัดไป - เวอร์ชันของ mod loader เป็นการปักหมุด เช่นเดียวกับทุกสิ่ง
services/loaderPin.jsจะอ่าน build ที่ติดตั้งจาก manifest การติดตั้งของ image เอง (.forge-manifest.jsonและไฟล์ที่คล้ายกัน) และเขียนการปักหมุด: ตัวแปร itzg ของ loader บนเซิร์ฟเวอร์ธรรมดา (FORGE_VERSION, …) หรือCF_MOD_LOADER_VERSIONบน CurseForge pack ของ Forge หรือ Fabric ซึ่งจะแทนที่เวอร์ชันที่ pack ประกาศ ตัวติดตั้ง CurseForge ของ image จะไม่สนใจการแทนที่นั้นสำหรับ NeoForge และ modrinth และ FTB pack จะไม่มี ดังนั้น loader ของพวกมันจะตาม packpacks.applyPackจะลบตัวแปรCF_ทั้งหมดเมื่ออัปเดตหรือย้อนกลับ pack ซึ่งจะลบการแทนที่พร้อมกับส่วนที่เหลือ การตรวจสอบ build ที่พิมพ์จะถูกตรวจสอบกับรายการเต็มของรีจิสทรีก่อน (services/loaderVersions.js; ของ Forge มาจากข้อมูลเมตา maven ซึ่งข้ามตัวเลข; การพลาดจะถูกตรวจสอบอีกครั้งหนึ่งครั้งกับรีจิสทรีเอง) จากนั้นการเปลี่ยนแปลงจะเป็นการสำรองข้อมูล → ปักหมุด (เหนือ env ตามที่เป็นอยู่หลังจากการสำรองข้อมูล) → สร้างใหม่ - พอร์ต จะถูกจัดสรรจากสคีมพื้นฐาน (เกมจาก
PORT_GAME_STARTขึ้นไป, RCON = เกม +PORT_RCON_OFFSET, Bedrock จากPORT_BEDROCK_START) ตรวจสอบความพร้อมใช้งาน และจองไว้ในฐานข้อมูล “ถูกใช้งาน” คือการรวมกันของการอ้างสิทธิ์ของเซิร์ฟเวอร์ทุกตัว (พอร์ตสด, บวกกับคู่ที่รอดำเนินการด้านล่าง), พอร์ตโฮสต์ทุกพอร์ตที่คอนเทนเนอร์ Docker ใดๆ เผยแพร่ (containers.publishedHostPorts: การผูกแบบสดของคอนเทนเนอร์ที่กำลังทำงาน บวกกับคอนฟิกที่กำหนดค่าไว้ของคอนเทนเนอร์ที่หยุดทำงานแต่ละตัว เพราะการตรวจสอบ bind ของ OS จากภายในคอนเทนเนอร์ของแผงควบคุมเองจะเห็นเฉพาะเน็ตเวิร์กเนมสเปซของคอนเทนเนอร์นั้น) และการตรวจสอบ OS ส่วนของ Docker จะถูกแคชไว้ 3 วินาทีและจำกัด: รายการที่ไม่ตอบสนองภายใน 2.5 วินาทีจะลบเฉพาะส่วนของ Docker และการตรวจสอบที่ช้าจะมีค่าใช้จ่ายเฉพาะพอร์ตของคอนเทนเนอร์นั้น การสร้างเซิร์ฟเวอร์และการservers.changeGamePortจะเลือกพอร์ตผ่านสายการทำให้เป็นอนุกรมเดียวที่ครอบคลุมเฉพาะการเลือกและการจอง (การเขียนแถวสำหรับการสร้าง, การจองในหน่วยความจำสำหรับการเปลี่ยนแปลงพอร์ต) ตัวเลือกพอร์ตของ BlueMap และการแทนที่พอร์ตเพิ่มเติมไม่ได้อยู่ในนั้นและไม่ได้ปรึกษา Docker การเปลี่ยนแปลงพอร์ตบนเซิร์ฟเวอร์ที่มีอยู่ (servers.changeGamePort, ภายใต้ op lock ของเซิร์ฟเวอร์) จะถูกนำไปใช้ทันที เพราะ Docker จะแก้ไขการผูกพอร์ตเมื่อสร้างคอนเทนเนอร์: คู่ใหม่ (RCON มักจะเป็นเกม +PORT_RCON_OFFSET) จะถูกตรวจสอบและจองในหน่วยความจำ (ports.reserve, ทั้งคู่เก่าและใหม่, ได้รับการยอมรับจากทุกการเลือกอื่น) ภายใต้ port lock จะถูกปฏิเสธ (409PENDING_CHANGES) ในขณะที่การตั้งค่าอื่นกำลังรอการสร้างใหม่ ดังนั้นจึงสร้างคอนเทนเนอร์ที่เคยทำงานแล้วใหม่เท่านั้น และเซิร์ฟเวอร์ที่กำลังทำงานจะถูกเปลี่ยนแปลงก็ต่อเมื่อคำขอระบุrestart: true(มิฉะนั้น 409NEEDS_CONFIRM) Image จะถูกดึงและตรวจสอบชื่อคอนเทนเนอร์ที่กำหนดเองก่อนที่จะแตะต้องสิ่งใด เซิร์ฟเวอร์ที่กำลังทำงานจะถูกหยุด จากนั้นคู่ใหม่จะถูกเขียนพร้อมpending_recreate = 1(ดังนั้นหากแผงควบคุมขัดข้องหลังจากนั้น จะเหลือ “rebuild pending” ที่ซื่อสัตย์) คอนเทนเนอร์จะถูกลบ สร้างใหม่ด้วยคู่ใหม่และเริ่มทำงาน หากขั้นตอนใดๆ หลังจากหยุดทำงานล้มเหลวputBackOnOldPortจะเขียนคู่เก่ากลับ สร้างใหม่ (และรีสตาร์ท หากกำลังทำงาน) และบันทึกว่าขั้นตอนใดล้มเหลว ประวัติและการแจ้งเตือนจะระบุหากแม้กระทั่งสิ่งนั้นก็ล้มเหลว ซึ่งจะทำให้เซิร์ฟเวอร์หยุดทำงานจนกว่าจะมีคนเริ่มใช้งาน สิทธิ์settingsเพียงพอ รวมถึงเซิร์ฟเวอร์ที่กำลังทำงาน ผู้ที่ไม่ใช่ผู้ดูแลระบบสามารถเลือกได้เฉพาะจากPORT_GAME_STARTขึ้นไป (คอลัมน์port_*_pendingจากการย้าย 029 เป็นของดีไซน์ก่อนหน้านี้ที่ยังไม่ได้เผยแพร่และไม่ได้ใช้งาน; 031 จะล้างออก) การชนกันของ lock จะตอบกลับ 409 ด้วยcode: 'BUSY'ซึ่งผู้เรียกที่ลองใหม่ด้านล่างจะตรวจสอบแทนข้อความ การรีสตาร์ทอัตโนมัติเมื่อเกิดข้อขัดข้อง (watcher.restartAfterCrash) และการสำรองข้อมูลตามกำหนดเวลาหรือการเริ่มทำงาน (scheduler.runTaskWithRetry) ที่พบว่าเซิร์ฟเวอร์กำลังยุ่งอยู่กับการดำเนินการอื่นจะลองอีกครั้งทุกๆ 20 วินาที / 60 วินาที เป็นเวลาสูงสุด 30 นาที และการอัปเดต pack หรือการย้อนกลับจะลองขั้นตอนที่ถูก lock ด้วยวิธีเดียวกัน (opLock.retryWhileBusy); การรีสตาร์ทเมื่อเกิดข้อขัดข้องหรือการเริ่มทำงานตามกำหนดเวลาที่รอดำเนินการจะยอมแพ้เมื่อมีคนหยุด, ฆ่า, หรือเริ่มเซิร์ฟเวอร์ตั้งแต่ (events.lifecycleActionSince); และการรีสตาร์ทเมื่อเกิดข้อขัดข้องจะยอมแพ้เมื่อปิดการรีสตาร์ทอัตโนมัติหรือเซิร์ฟเวอร์หายไป การรีสตาร์ทตามกำหนดเวลา, การหยุด, และคำสั่งจะไม่ถูกลองใหม่ และตารางเวลาที่การรันครั้งสุดท้ายยังคงรอดำเนินการอยู่จะข้ามการเรียกครั้งต่อไป - โควต้าดิสก์ ถูกบังคับโดยแผงควบคุมเพราะ Docker ไม่สามารถจำกัดการใช้งาน bind-mount ได้: ตัวจัดทำดัชนีจะแคชขนาดต่อไดเรกทอรี และการดำเนินการขยายดิสก์จะถูกควบคุมโดยสิ่งเหล่านี้
- ข้อมูลลับ (รหัสผ่าน RCON, คีย์ API, ข้อมูลลับ TOTP, URL webhook ของ Discord) จะถูกเข้ารหัสขณะจัดเก็บด้วย AES-256-GCM โดยใช้คีย์สุ่มเฉพาะที่
$DATA_DIR/.secret-key(โหมด0600, สร้างขึ้นอัตโนมัติ) แยกต่างหากจากSESSION_SECRET; คีย์ที่ได้จากSESSION_SECRETจะถูกเก็บไว้เป็น fallback สำหรับการถอดรหัสเท่านั้นสำหรับค่าที่เขียนก่อนที่คีย์เฉพาะจะมีอยู่ และsrc/services/secretsMigration.jsจะเข้ารหัสค่าเหล่านั้นใหม่ภายใต้คีย์เฉพาะเมื่อเริ่มทำงาน.secret-keyที่มีอยู่แต่ไม่สามารถแยกวิเคราะห์ได้จะเป็นข้อผิดพลาดร้ายแรงเมื่อเริ่มทำงาน (จะไม่สร้างใหม่โดยอัตโนมัติทับของเดิม) Blueprints จะลบข้อมูลลับทั้งหมดเมื่อส่งออก server.propertiesเป็นของแผงควบคุมแต่ถูกซ่อนโดย env Image itzg จะยืนยันคุณสมบัติที่รองรับโดย env อีกครั้งทุกครั้งที่เริ่มทำงาน (OVERRIDE_SERVER_PROPERTIESค่าเริ่มต้นคือ true) ดังนั้นค่าที่แผงควบคุมแก้ไขโดยตรง - PvP/difficulty ของ World Controls, สลับ whitelist, ตัวแก้ไขไฟล์ - จะถูกย้อนกลับอย่างเงียบๆ ในการเริ่มทำงานครั้งถัดไป เว้นแต่ตัวแปร env ที่ตรงกันจะถูกลบออกและคอนเทนเนอร์ถูกสร้างใหม่ การเขียนคุณสมบัติโดยตรงทุกครั้งจะผ่านwriteServerProperties()(ทั้งไฟล์) หรือsetServerProperty()(หนึ่งคีย์) ในsrc/services/servers.jsซึ่งจะเขียนไฟล์ใหม่แบบ atomic, ยกเลิกการตั้งค่า env var หลังคีย์ที่เปลี่ยนแปลงแต่ละคีย์ (ผ่านแอตทริบิวต์prop:ในฟิลด์แคตตาล็อก, ตรวจสอบในการทดสอบกับคำจำกัดความคุณสมบัติของ image เอง) และตั้งค่าสถานะpending_recreatedifficulty จะถูกเขียนลงในไฟล์และส่งผ่าน RCON เพราะเซิร์ฟเวอร์เฉพาะจะนำคุณสมบัติdifficultyกลับมาใช้ใหม่ทุกครั้งที่บูต Minecraft เองจะบันทึก server.properties ใหม่จากค่าขณะบูตเมื่อwhitelist on/offซึ่งจะยกเลิกการแก้ไขที่ทำขณะที่เซิร์ฟเวอร์กำลังทำงาน ดังนั้นตัวสลับ whitelist ที่กำลังทำงานจะสแนปชอตไฟล์ก่อนแล้วจึงเขียนกลับโดยเปลี่ยนเฉพาะwhite-listตัวแปร env จะยังคงกำหนดค่าได้อย่างสมบูรณ์เมื่อสร้าง (วิซาร์ดจะแสดงผลและนำไปใช้เพียงครั้งเดียว); พวกมันจะยกเลิกการปักหมุดก็ต่อเมื่อแผงควบคุมแก้ไขคุณสมบัติพื้นฐานเป็นครั้งแรก MOTD มีสัญญาเดียวกัน: การแก้ไขไฟล์motdโดยตรงจะยกเลิกการตั้งค่า env var นั้น ดังนั้นการเขียนครั้งสุดท้ายจึงมีผล
ข้อมูลและรูปแบบการสื่อสาร (Data & wire formats)
หัวข้อที่มีชื่อว่า “ข้อมูลและรูปแบบการสื่อสาร (Data & wire formats)”data/panel.db- ฐานข้อมูล SQLite จะถูกสแนปชอตรายวันผ่านVACUUM INTOไปยังdata/backups/_panel/(เก็บไว้ 14 รายการล่าสุด);PRAGMA integrity_checkจะทำงานเมื่อเริ่มทำงานdata/.session-secret- secret สำหรับลงนาม cookie ที่สร้างขึ้นอัตโนมัติ สร้างขึ้นเมื่อรันครั้งแรกหากSESSION_SECRETไม่ได้ตั้งค่า การลบจะหมุนเวียน secret (ซึ่งจะทำให้ session ไม่ถูกต้อง)data/.secret-key- คีย์เข้ารหัส 32 ไบต์เฉพาะสำหรับการจัดเก็บ (โหมด0600), สร้างขึ้นอัตโนมัติเมื่อรันครั้งแรก แยกต่างหากจากSESSION_SECRET; การลบจะทำให้ข้อมูลลับที่จัดเก็บทั้งหมดไม่สามารถถอดรหัสได้ ดังนั้นจึงควรเก็บไว้พร้อมกับการสำรองข้อมูลของคุณ- Blueprints (
.mcserver.zip) - ไฟล์ zip ที่มีmanifest.jsonอธิบายการกำหนดค่า, ทรัพยากร, การอ้างอิง pack ที่ปักหมุด, manifest การซ้อนทับ (URL ต้นทาง + sha256), ไฟล์กำหนดค่าที่เลือก, และอาจมี world ด้วย การนำเข้าจะดาวน์โหลดใหม่และตรวจสอบแฮชของ mod แต่ละตัว และกำหนดพอร์ตใหม่ - คอนเทนเนอร์ Docker ที่สร้างโดยแผงควบคุมจะมีชื่อและป้ายกำกับเพื่อให้ watcher สามารถค้นหาได้; แผงควบคุมเป็นเจ้าของวงจรชีวิตทั้งหมด
ลำดับการบูต (Boot sequence)
หัวข้อที่มีชื่อว่า “ลำดับการบูต (Boot sequence)”require('./instrument')(ช่องทาง Sentry) ก่อนสิ่งอื่นใด จากนั้นrequire('./preflight')เพื่อแจ้งข้อผิดพลาดอย่างชัดเจนเมื่อเวอร์ชัน Node ไม่รองรับ- โหลดการกำหนดค่า; ตรวจสอบ/สร้าง
.session-secretและ.secret-key ensureDataRoot()- สร้างโครงสร้าง./data, ล้างtmp/- รันการย้ายฐานข้อมูล จากนั้น
PRAGMA integrity_check(จะบันทึกอย่างละเอียด, ชี้ไปที่data/backups/_panelหากเกิดข้อผิดพลาด) - เข้ารหัส legacy secrets ที่ใช้
SESSION_SECRETใหม่ภายใต้.secret-key(secretsMigration) - นำเข้า API keys จากสภาพแวดล้อมเพียงครั้งเดียว (
apiKeys.importFromEnvOnce()), ปักหมุดเซิร์ฟเวอร์ใดๆ ที่ยังคงมีตัวเลือก modpack ที่ไม่ได้ปักหมุด (packPins.pinUnpinnedServers()), ทำเครื่องหมายการสแกนความเข้ากันได้ของเวอร์ชันที่ยังคงทำงานโดยกระบวนการก่อนหน้านี้ว่าถูกขัดจังหวะ (compat.reconcileScans()), จากนั้นจึงใส่ blueprint เริ่มต้น (มีการป้องกัน) - เริ่มเซิร์ฟเวอร์ HTTP + WS เมื่อผูกที่เปิดเผย จะแสดง PIN
/setupสำหรับการรันครั้งแรก - ติดตั้งตัวป้องกันรันไทม์หลังการบูต (จับข้อผิดพลาดที่ไม่ได้จัดการ;
MSM_EXIT_ON_FATAL=1จะทำให้เกิดการออกอย่างถาวรสำหรับการปรับใช้ที่มีการดูแล) - เริ่มบริการพื้นหลัง: ตัวจัดการ WS, ตัวจัดทำดัชนีพื้นที่จัดเก็บ, ตัวเฝ้าดูข้อขัดข้อง + สินค้าคงคลัง, ตัวกำหนดเวลา, สะพานเชื่อมเหตุการณ์ Discord, ตัวเฝ้าดูการติดต่อแชทบอท, และ ตัวจับเวลาการบำรุงรักษารายวัน (ลบแถววิเคราะห์เก่า, การถอดความแชทบอท, ประวัติเหตุการณ์ (365 วัน) และแถวแคช API, จากนั้นสแนปชอต
panel.db) - เริ่มต้น Docker ในพื้นหลัง UI สามารถใช้งานได้อย่างเต็มที่ในขณะที่ daemon ทำงานอยู่; ฟีเจอร์ Docker จะเปิดใช้งานเมื่อสามารถเข้าถึงได้ เมื่อเชื่อมต่อแล้ว
refreshStatuses({ boot })จะปรับสถานะที่แคชให้สอดคล้องกัน, ส่งเหตุการณ์offline-after-restartเพียงครั้งเดียวสำหรับเซิร์ฟเวอร์ที่เคยทำงานอยู่ก่อนที่แผงควบคุมจะรีสตาร์ทและจะไม่ถูกนำกลับมา, และลูปบูตจะเริ่มเซิร์ฟเวอร์auto_startบวกกับกู้คืนเซิร์ฟเวอร์auto_restartที่พบว่าขัดข้องระหว่างการหยุดทำงาน (เคารพการหน่วงเวลาเมื่อเกิดข้อขัดข้อง)
ลำดับการ instrument ก่อน preflight เป็นการแลกเปลี่ยนที่ตั้งใจไว้: ช่วยให้การเดินสาย Sentry ในอนาคตสามารถแก้ไขรันไทม์ได้ก่อน โดยมีค่าใช้จ่ายเป็นข้อความที่ไม่เป็นมิตรเล็กน้อยบน Node ที่เก่ามากจริงๆ
ไปป์ไลน์การสร้าง (Build pipeline)
หัวข้อที่มีชื่อว่า “ไปป์ไลน์การสร้าง (Build pipeline)”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild → public/dist/js/, ESM พร้อม code-splitting) postinstall จะรันเฉพาะ CSS เท่านั้น public/css/app.css และ public/dist/ เป็น artifact ที่ถูก gitignore; ขั้นตอนการสร้าง Dockerfile จะรัน pnpm run build เต็มรูปแบบและคัดลอก public/ เข้าไปใน runtime image ไฟล์สแตติกจะถูกเสิร์ฟแบบ immutable/long-cache สำหรับไฟล์ที่มี fingerprint, short-cache สำหรับ CSS/JS, และ no-cache สำหรับ HTML และ /api