Skip to content

USER_GUIDE.md

Latest commit

 

History

History
130 lines (97 loc) · 12.6 KB

USER_GUIDE.md

File metadata and controls

130 lines (97 loc) · 12.6 KB
Raw

Minecraft 伺服器管理器使用手冊

本手冊提供 Minecraft 伺服器管理器的完整操作流程、功能指南與常見問題排除說明。

系統需求

  • 作業系統：Windows 10／11（64 位元）
  • Java 環境：執行 Minecraft 伺服器所需的 Java Runtime（Java 8 至 Java 21+）
    • 軟體內建自動掃描本機已安裝之 Java 功能，亦可手動瀏覽指定 java.exe
  • .NET 執行環境：
    • 獨立自包含版（Self-contained）：內建完整 .NET 10 Runtime 與相依元件，隨點即開，無需額外安裝任何執行環境
    • 框架相依版（Framework-dependent）：需先安裝微軟官方 .NET 10 Desktop Runtime (x64)，體積極小

取得與啟動

可執行檔位於專案發布目錄 output/：

檔案名稱 版本類型 檔案大小 適用情境與說明
MinecraftServerManager-self-contained.exe 獨立自包含版 較大 強烈推薦，適合所有使用者，內建完整 .NET 10 執行環境與官方單檔壓縮，下載即可直接執行
MinecraftServerManager-framework-dependent.exe 框架相依版 極小 適合進階使用者，電腦必須預先安裝 .NET 10 Desktop Runtime (x64)（可在終端機執行 winget install Microsoft.DotNet.DesktopRuntime.10 快速安裝）

Tip

若執行 MinecraftServerManager-framework-dependent.exe 時系統提示需要安裝 .NET 執行環境，代表您的電腦尚未安裝 .NET 10 Desktop Runtime。此時可透過終端機執行 winget install Microsoft.DotNet.DesktopRuntime.10 安裝、至微軟官網下載安裝，或直接改用 MinecraftServerManager-self-contained.exe 即可順暢運作。

按兩下對應的可執行檔即可啟動主程式。

Note

初次啟動目錄引導：首次啟動程式時，系統會提示您選取一個存放所有 Minecraft 伺服器的主資料夾（系統將在該資料夾內自動建立 servers 子目錄集中管理所有伺服器實例與世界檔案）。若未指定或取消選取，程式將安全結束。後續可於設定頁面隨時檢視或變更該路徑。

功能操作指南

1. 建立全新伺服器

  1. 點選左側導覽列的「建立伺服器」。
  2. 基本資訊：輸入自訂的伺服器名稱，系統會自動規劃存放目錄。
  3. 載入器與版本：
    • 預設推薦使用 Paper（高效能外掛伺服器），亦支援 Fabric、Quilt、Forge、NeoForge 等模組伺服器。
    • 選擇目標載入器後，系統動態向官方 API 查詢相容的 Minecraft 版本與對應的建置/發行版本。
  4. Java 與記憶體設定：
    • 系統會依選定的載入器與 Minecraft 版本動態查詢官方最低需求（例如 Paper 現代版本要求 Java 21+）並自動選取合適的 Java。
    • 點選「管理 Java」可開啟專屬管理對話方塊，檢視本機已安裝的 Java 清單、相容狀態，支援「自動偵測」配對最佳版本、「手動瀏覽」指定自訂 Java 執行檔，或透過 Windows 內建「winget」自動安裝指定版本的 OpenJDK（Java 8 至 21+；點選安裝前系統會先自動檢查本機是否已有可用版本並主動提醒，避免重複安裝）。
    • 拖動記憶體拉桿設定最大配置量，系統會依 Java 版本智慧套用 JVM 垃圾回收最佳化參數（G1GC／ZGC）。
    • 若為 Forge 或 NeoForge 伺服器，系統會在建立、更新與啟動時自動將 GC 最佳化參數、記憶體配置與自訂 JVM 參數安全寫入 user_jvm_args.txt，並在執行啟動批次檔時自動注入環境變數（JAVA_HOME 與 PATH），確保批次檔能以指定的 Java 執行版本精確執行。
  5. 使用者授權合約（EULA）：勾選「我同意 Minecraft EULA」。
  6. 點選「建立伺服器」，程式將自動下載核心與腳本，並啟動初次初始化視窗生成設定與世界；就緒完成後倒數 2 秒（或直接按 Enter 鍵）平順自動跳轉至伺服器管理頁面。若為 Paper 伺服器，外掛套件可直接放入伺服器根目錄下的 plugins/ 資料夾。

2. 伺服器日常管理

在左側「管理伺服器」頁面，可檢視所有已建立的伺服器卡片與目前運作狀態：

  • 伺服器狀態與容量：卡片顯示伺服器資料容量；缺少核心必要啟動檔案時，狀態欄會以警示色標示缺漏項目。
  • 啟動伺服器：點選卡片上的「啟動」按鈕，系統會先檢查伺服器核心必要檔案（如核心 JAR、啟動腳本或參數檔）；檔案缺漏時會停用啟動操作，補齊檔案後即可重新檢查。
  • 開啟資料夾：點選「開啟資料夾」，直接在檔案總管中開啟該伺服器的根目錄。
  • 名單管理：點選「名單管理」開啟伺服器玩家名單與權限設定對話方塊，集中控管四大關鍵設定：
    • 管理員名冊 (ops.json)：設定玩家 OP 權限層級（Level 1～4）與是否略過人數限制；核取方塊支援按一下即時切換。
    • 白名單 (whitelist.json)：維護准入名冊，搭配屬性中的白名單功能限制進場。
    • 玩家封鎖名冊 (banned-players.json) 與 IP 封鎖名冊 (banned-ips.json)：檢視與維護禁止進入名單。
    • 支援離線快取索引（usercache.json），自動關聯玩家 UUID 與名稱。
  • 記憶體配置：點選「記憶體設定」，快速調整該伺服器的最大與最小 JVM 記憶體分配量。
  • 相對路徑顯示：伺服器清單之「路徑」欄位採用相對於存放目錄之精簡相對路徑顯示，滑鼠懸停即可顯示完整絕對路徑。
  • 屬性設定：點選「屬性設定」開啟 server.properties 編輯視窗，修改遊戲難度、PVP、最大玩家數等參數；系統具備屬性數值合法性驗證（如連接埠 1～65534、IP 位址格式與列舉值驗證）及版本樂觀鎖保護，防止並行儲存衝突與無效設定。
  • 立即備份：點選「備份」，系統將自動封裝為 ZIP 備份檔，並自動保留最新 10 份備份。
  • 還原備份：點選「還原」，選擇歷史備份點執行交易式安全還原。
  • 刪除伺服器：點選「刪除」並確認後安全移除伺服器目錄；若該伺服器存在受管理的歷史備份，系統將主動詢問是否一併刪除備份檔案，避免佔用磁碟空間。

3. 獨立主控台即時監控

伺服器啟動後，將開啟專屬的即時監控視窗：

  • 即時狀態與系統通知：頂部顯示即時伺服器運作狀態（包含「啟動中」、「已就緒」與線上玩家數量，由系統自動即時解析加入／退出事件與完成開機訊號）。當伺服器開機就緒時，系統將主動發出 Windows 桌面就緒通知提醒管理員。
  • 高效能記錄：採用 50ms 微批次聚合技術，杜絕大量輸出時的介面凍結，並自動過濾終端機 ANSI 色碼。
  • 指令傳送與歷史紀錄：在底部輸入框鍵入 Minecraft 指令（例如 op <玩家名稱> 或 say <公告>），按 Enter 即可傳送至伺服器 stdin；支援鍵盤方向鍵上下瀏覽歷史指令並自動保留編輯草稿。
  • 停止伺服器：
    • 停止：優先傳送平順停止指令（stop），等待伺服器安全儲存世界地圖後關閉。
    • 強制終止：若伺服器未於時限內關閉，可執行強制終止以清理殘餘行程。

4. 模組管理與 Modrinth 線上安裝

在「模組管理」頁面選擇欲管理的模組伺服器：

  • 本地模組管理：
    • 自動列出 mods 資料夾中的所有模組與狀態，支援 Windows 原生自然排序與多選（Ctrl 多選、Shift 連選）。
    • 點兩下模組項目或點選操作按鈕即可智慧切換「啟用」與「停用」（透過標準 .jar 與 .jar.disabled 切換，並自動處理衝突備份）。
    • 支援右鍵快捷選單：切換啟用狀態、複製模組資訊、在檔案總管中顯示與刪除模組。
    • 選取 2 個以上模組時自動啟用「批次切換」功能；「檢查更新」採用現代化彈性語意版本比對引擎（FlexVersion），自動比對並精準篩選相容之最新發行版。若有可更新項目將直接跳出清單確認視窗，若皆為最新則顯示 3 秒自動關閉提示，兼顧操作效率與直覺體驗。
    • 提供多格式匯出功能，可將模組清單匯出為純文字檔（.txt）、JSON（.json）、HTML（.html）或標準 Excel（.xlsx）試算表，匯出完成後可快速開啟檢視。
  • Modrinth 線上搜尋與安裝：
    • 頂部明確提示目前伺服器的相容條件（Minecraft 版本與載入器類型），輸入關鍵字即時搜尋相容模組。
    • 相依性自動規劃：選擇模組版本時，系統自動遞迴解析必要相依模組，並提示一併排入安裝清單，省去手動尋找前置模組的困擾。
    • 待安裝清單視窗：點選「檢視安裝清單」可開啟專屬視窗，集中檢視待安裝與更新的項目，支援快速清空或直接點選「開始安裝」。
    • 點選「開始安裝」，系統將非同步下載並自動比對 SHA-512／SHA-1 雜湊值，驗證通過後直接部署至 mods 目錄。
    • 下載來源安全防護：系統會自動驗證模組下載來源是否屬於官方 Modrinth CDN（cdn.modrinth.com）；若偵測到非官方下載網址，將主動彈出警示視窗向使用者確認，防範未驗證來源的安全風險。

5. 交易式備份與安全還原

  • 自動輪替原則：每次建立備份均會記錄時間戳記，系統維持最多 10 份最新備份，逾期檔案自動安全清理。
  • 交易式還原保證：還原過程先於隔離暫存區解壓縮並校驗路徑安全性；在覆蓋前自動建立還原快照（Rollback Snapshot），若還原中途遭遇異常，系統會自動回復至原本狀態，防止世界資料損壞。
  • 現場記錄檔安全留存：執行備份還原時，系統會自動留存伺服器目前現場的 logs/ 與 crash-reports/ 目錄並於還原完成後移回合併，避免還原操作覆蓋掉重要當機調查線索。

6. 外部伺服器匯入

點選導覽列的「匯入伺服器」，可選取本機現有的伺服器資料夾或 ZIP 壓縮檔，安全匯入至管理器統一維護。匯入過程由背景非同步執行，並自動校驗伺服器核心、載入器類型與設定完整性。

7. 軟體偏好設定與更新

點選導覽列底部的「關於與設定」：

  • 版本與開發資訊：檢視目前應用程式版本號碼、技術堆疊與開源授權條款（GPLv3），並可快速點選前往 GitHub 專案頁面。
  • 軟體更新檢查：
    • 勾選「自動檢查更新」可在啟動時自動比對遠端版本。
    • 點選「檢查更新」立即連線至 GitHub Releases 檢查有無新版本，下載時強制透過官方提供的 SHA-256 digest 雜湊驗證，確保檔案完整與安全。
  • 主題外觀切換：提供「淺色模式」、「深色模式」或「依照系統設定」，隨選即時套用高對比色彩。
  • 全域介面縮放：支援 50% 至 300% 全域介面比例縮放，並提供自訂百分比輸入，適配各類高 DPI 與超高解析度螢幕。
  • 視窗尺寸管理：即時顯示目前螢幕解析度與視窗尺寸，並提供「重設為預設大小」與「還原預設」按鈕，快速復原初始介面配置。

常見問題與故障排除

1. 啟動框架相依版時提示缺少 .NET 執行環境

若執行 output/MinecraftServerManager-framework-dependent.exe 出現提示視窗，請前往微軟官方網站下載並安裝 .NET 10 Desktop Runtime (x64)，或直接改用內建完整環境的 output/MinecraftServerManager-self-contained.exe。

2. 伺服器啟動失敗或瞬間當機

  • 請檢查伺服器設定的 Java 版本是否與 Minecraft 版本相符（例如 Minecraft 1.20.5+ 需要 Java 21 以上）。
  • 請至主控台視窗檢視當機報告（Crash Report），確認是否因模組相依性缺失或記憶體配置超出實體限制所致。

3. 初次啟動出現 Windows SmartScreen 提示

本軟體為免費開源專案，未購買商業數位憑證。若於 Windows 首次啟動時出現「Windows 已保護您的電腦」提示，請點選「其他資訊（More info）」→「仍要執行（Run anyway）」即可正常啟動；主程式日常更新均內建全自動 SHA-256 完整性檢查，請安心使用。

4. 如何回報問題或建議

如遇程式異常，請至 GitHub Issues 提出，並附上 Windows 版本、使用的版本類型、操作步驟與記錄檔（位於 %LOCALAPPDATA%\Programs\MinecraftServerManager\Logs\）。