ข้ามไปยังเนื้อหา

สถาปัตยกรรม

← กลับไปยังดัชนีเอกสาร

Minecraft Server Manager เป็นแอปพลิเคชัน Node.js แบบ single-process ที่เรนเดอร์บนเซิร์ฟเวอร์ จัดการเซิร์ฟเวอร์ Minecraft ที่ทำงานเป็นคอนเทนเนอร์ Docker โดยใช้ image itzg/docker-minecraft-server โดยสื่อสารกับ Docker daemon ผ่าน API (ไม่เคยเรียกใช้ docker CLI ผ่าน shell)

  • 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: หนึ่ง upstream docker logs --follow (หรือ docker stats) ต่อเซิร์ฟเวอร์หนึ่งตัว แยกข้อมูลแล้วกระจายไปยังแท็บที่เชื่อมต่อทั้งหมด แทนที่จะเป็นหนึ่ง upstream ต่อผู้ดูหนึ่งคน ตัวจัดการคอนโซลจะเก็บบัฟเฟอร์ replay ขนาดเล็กสำหรับแท็บที่เข้าร่วมช้า และจะตัดผู้ใช้ที่ socket หลุดไปไกลเกินไป แทนที่จะทำให้สตรีมที่ใช้ร่วมกันหยุดทำงาน
  • dockerode เป็นวิธีเดียวที่แอปใช้สื่อสารกับ Docker Endpoint จะถูกตรวจจับอัตโนมัติตามแพลตฟอร์ม (Windows named pipe เทียบกับ unix 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 สำหรับ 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.js src/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 จะเดินผ่านสแต็กเราเตอร์สดและล้มเหลวหากเส้นทางเขียนที่ขอบเขตเซิร์ฟเวอร์, การรวม, หรือหน้าไม่มีการควบคุม
  • 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 ของพวกมันจะตาม pack packs.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 จะถูกปฏิเสธ (409 PENDING_CHANGES) ในขณะที่การตั้งค่าอื่นกำลังรอการสร้างใหม่ ดังนั้นจึงสร้างคอนเทนเนอร์ที่เคยทำงานแล้วใหม่เท่านั้น และเซิร์ฟเวอร์ที่กำลังทำงานจะถูกเปลี่ยนแปลงก็ต่อเมื่อคำขอระบุ restart: true (มิฉะนั้น 409 NEEDS_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_recreate difficulty จะถูกเขียนลงในไฟล์และส่งผ่าน RCON เพราะเซิร์ฟเวอร์เฉพาะจะนำคุณสมบัติ difficulty กลับมาใช้ใหม่ทุกครั้งที่บูต Minecraft เองจะบันทึก server.properties ใหม่จากค่าขณะบูตเมื่อ whitelist on/off ซึ่งจะยกเลิกการแก้ไขที่ทำขณะที่เซิร์ฟเวอร์กำลังทำงาน ดังนั้นตัวสลับ whitelist ที่กำลังทำงานจะสแนปชอตไฟล์ก่อนแล้วจึงเขียนกลับโดยเปลี่ยนเฉพาะ white-list ตัวแปร env จะยังคงกำหนดค่าได้อย่างสมบูรณ์เมื่อสร้าง (วิซาร์ดจะแสดงผลและนำไปใช้เพียงครั้งเดียว); พวกมันจะยกเลิกการปักหมุดก็ต่อเมื่อแผงควบคุมแก้ไขคุณสมบัติพื้นฐานเป็นครั้งแรก MOTD มีสัญญาเดียวกัน: การแก้ไขไฟล์ motd โดยตรงจะยกเลิกการตั้งค่า env var นั้น ดังนั้นการเขียนครั้งสุดท้ายจึงมีผล
  • 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 สามารถค้นหาได้; แผงควบคุมเป็นเจ้าของวงจรชีวิตทั้งหมด
  1. require('./instrument') (ช่องทาง Sentry) ก่อนสิ่งอื่นใด จากนั้น require('./preflight') เพื่อแจ้งข้อผิดพลาดอย่างชัดเจนเมื่อเวอร์ชัน Node ไม่รองรับ
  2. โหลดการกำหนดค่า; ตรวจสอบ/สร้าง .session-secret และ .secret-key
  3. ensureDataRoot() - สร้างโครงสร้าง ./data, ล้าง tmp/
  4. รันการย้ายฐานข้อมูล จากนั้น PRAGMA integrity_check (จะบันทึกอย่างละเอียด, ชี้ไปที่ data/backups/_panel หากเกิดข้อผิดพลาด)
  5. เข้ารหัส legacy secrets ที่ใช้ SESSION_SECRET ใหม่ภายใต้ .secret-key (secretsMigration)
  6. นำเข้า API keys จากสภาพแวดล้อมเพียงครั้งเดียว (apiKeys.importFromEnvOnce()), ปักหมุดเซิร์ฟเวอร์ใดๆ ที่ยังคงมีตัวเลือก modpack ที่ไม่ได้ปักหมุด (packPins.pinUnpinnedServers()), ทำเครื่องหมายการสแกนความเข้ากันได้ของเวอร์ชันที่ยังคงทำงานโดยกระบวนการก่อนหน้านี้ว่าถูกขัดจังหวะ (compat.reconcileScans()), จากนั้นจึงใส่ blueprint เริ่มต้น (มีการป้องกัน)
  7. เริ่มเซิร์ฟเวอร์ HTTP + WS เมื่อผูกที่เปิดเผย จะแสดง PIN /setup สำหรับการรันครั้งแรก
  8. ติดตั้งตัวป้องกันรันไทม์หลังการบูต (จับข้อผิดพลาดที่ไม่ได้จัดการ; MSM_EXIT_ON_FATAL=1 จะทำให้เกิดการออกอย่างถาวรสำหรับการปรับใช้ที่มีการดูแล)
  9. เริ่มบริการพื้นหลัง: ตัวจัดการ WS, ตัวจัดทำดัชนีพื้นที่จัดเก็บ, ตัวเฝ้าดูข้อขัดข้อง + สินค้าคงคลัง, ตัวกำหนดเวลา, สะพานเชื่อมเหตุการณ์ Discord, ตัวเฝ้าดูการติดต่อแชทบอท, และ ตัวจับเวลาการบำรุงรักษารายวัน (ลบแถววิเคราะห์เก่า, การถอดความแชทบอท, ประวัติเหตุการณ์ (365 วัน) และแถวแคช API, จากนั้นสแนปชอต panel.db)
  10. เริ่มต้น Docker ในพื้นหลัง UI สามารถใช้งานได้อย่างเต็มที่ในขณะที่ daemon ทำงานอยู่; ฟีเจอร์ Docker จะเปิดใช้งานเมื่อสามารถเข้าถึงได้ เมื่อเชื่อมต่อแล้ว refreshStatuses({ boot }) จะปรับสถานะที่แคชให้สอดคล้องกัน, ส่งเหตุการณ์ offline-after-restart เพียงครั้งเดียวสำหรับเซิร์ฟเวอร์ที่เคยทำงานอยู่ก่อนที่แผงควบคุมจะรีสตาร์ทและจะไม่ถูกนำกลับมา, และลูปบูตจะเริ่มเซิร์ฟเวอร์ auto_start บวกกับกู้คืนเซิร์ฟเวอร์ auto_restart ที่พบว่าขัดข้องระหว่างการหยุดทำงาน (เคารพการหน่วงเวลาเมื่อเกิดข้อขัดข้อง)

ลำดับการ instrument ก่อน preflight เป็นการแลกเปลี่ยนที่ตั้งใจไว้: ช่วยให้การเดินสาย Sentry ในอนาคตสามารถแก้ไขรันไทม์ได้ก่อน โดยมีค่าใช้จ่ายเป็นข้อความที่ไม่เป็นมิตรเล็กน้อยบน Node ที่เก่ามากจริงๆ

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