Skip to content

INSTALLATION.md

Latest commit

 

History

History
213 lines (145 loc) · 5.85 KB

INSTALLATION.md

File metadata and controls

213 lines (145 loc) · 5.85 KB
Raw

安裝與部署

系統需求

  • Node.js 22–26
  • npm 10 以上
  • Java 17 或 21；實際版本依 Minecraft 與核心需求而定
  • Windows 10/11、Windows Server，或常見 x86_64 Linux 發行版

SQLite 已內建，不需要另外安裝資料庫。含原生模組的 node_modules 不能直接跨 Windows 與 Linux 共用；更換平台後請重新執行相依套件安裝。

Windows

根目錄提供四個啟動檔：

Start-BlockPilot-TW.bat   中文（繁體）
Start-BlockPilot-ZH.bat   中文（簡體）
Start-BlockPilot-EN.bat   English
Start-BlockPilot.bat      啟動時選擇語言

語言啟動檔會檢查 npm。若電腦尚未安裝 npm，且系統可以使用 winget，啟動檔會安裝 Node.js LTS；接著依 package-lock.json 執行 npm ci 並建置 API 與 Web。啟動完成後會保留兩個視窗：WEB 視窗顯示面板網址與啟動狀態，API 視窗顯示後端服務訊息。瀏覽器開啟後可關閉 WEB 視窗；若要停止面板，請在 API 視窗按 Ctrl+C。

Windows 原生模組備援工具

BlockPilotMC v1.0.4 使用 better-sqlite3 13.0.2。在支援的 Windows x64 與 Node.js 22–26 環境中，npm 應直接取得套件提供的預編譯檔，正常情況不必另外安裝 Python 或 C++ 編譯器。

如果下載的套件不適用於目前架構、快取損壞，或 npm 仍嘗試執行 node-gyp，啟動器會停止安裝並顯示簡短指引。此時才需要：

  • Python 3；Python 3.12 以上需搭配 node-gyp 10 以上。
  • Visual Studio 2022 Build Tools。
  • 使用 C++ 的桌面開發（Desktop development with C++） 工作負載。

可使用啟動器顯示的 winget 指令安裝。完整 npm 輸出不會洗滿啟動視窗，而是保存到：

runtime/install/npm-install.log

安裝成功後會另外執行正式環境相依套件稽核，結果保存到：

runtime/install/npm-audit.log

稽核結果不會自動執行 npm audit fix --force，避免未經測試的破壞性升級。

手動啟動時，先進入含有 package.json 的專案根目錄：

npm ci
npm run setup-env
npm run build
npm start

Ubuntu / Debian 一行安裝

以下指令會安裝必要套件、Node.js 22、Java 21，下載 v1.0.4，完成建置並註冊為 systemd 服務：

curl -fsSL https://raw.githubusercontent.com/BlockPilotDev/BlockPilotMC/v1.0.4/scripts/install-ubuntu.sh | sudo bash

安裝完成後：

sudo systemctl status blockpilot
hostname -I

假設主機 IP 是 192.168.1.50，同網段瀏覽器開啟：

http://192.168.1.50:8787

安裝程式會在終端機顯示一次初始管理員密碼。請先保存，再於登入後修改密碼。

Linux 直接執行

先下載或 clone 專案，並進入含有 package.json 的根目錄：

git clone --branch v1.0.4 --depth 1 https://github.com/BlockPilotDev/BlockPilotMC.git
cd BlockPilotMC
npm ci
chmod +x start-linux.sh
./start-linux.sh

start-linux.sh 會：

  • 檢查 Node.js 22–26 與 npm 10 以上版本。
  • 正確辨識 linux-x64 等平台識別。
  • 在缺少或平台不一致時重新安裝相依套件。
  • 在 .env 不存在時建立隨機管理員密碼。
  • 建置 API 與 Web，再執行 node app.js。

停止直接執行的面板時，按 Ctrl+C。

Fedora

sudo dnf install -y nodejs npm gcc-c++ make python3 java-21-openjdk-headless git

git clone --branch v1.0.4 --depth 1 https://github.com/BlockPilotDev/BlockPilotMC.git
cd BlockPilotMC
npm ci
chmod +x start-linux.sh
./start-linux.sh

請先確認 node -v 為 22–26、npm -v 為 10 以上。

systemd 安裝與更新

在已下載的專案根目錄執行：

chmod +x scripts/install-systemd.sh
sudo ./scripts/install-systemd.sh

預設安裝位置為 /opt/blockpilot，服務帳號為 blockpilot。安裝程式會在啟用服務前完成 npm ci 與 npm run build，正式服務只啟動已建置的 app.js，不會在 systemd 的唯讀環境重新安裝或編譯。

升級時會保留：

/opt/blockpilot/.env
/opt/blockpilot/runtime
/opt/blockpilot/Server

常用命令：

sudo systemctl start blockpilot
sudo systemctl stop blockpilot
sudo systemctl restart blockpilot
sudo systemctl status blockpilot
sudo journalctl -u blockpilot -f

服務預設允許寫入 runtime、Server 與既有 .env。若要使用安裝目錄外的 Minecraft 路徑，需同步調整 systemd 的 ReadWritePaths。

.env 與首次登入

一行安裝與 scripts/install-systemd.sh 會自動建立 /opt/blockpilot/.env，一般不需要手動執行 npm run setup-env。

直接從原始碼執行時，start-linux.sh 也會在缺少 .env 時自動建立。若要手動執行 npm 指令，必須先進入專案根目錄：

cd /opt/blockpilot
sudo -u blockpilot -H npm run setup-env

若 .env 已存在，setup-env 不會覆蓋。忘記管理員密碼時：

cd /opt/blockpilot
sudo -u blockpilot -H npm run reset-admin -- admin '至少12字元的新密碼'
sudo systemctl restart blockpilot

區域網路連線

預設設定：

PORT=8787
HOST=0.0.0.0

本機網址：

http://127.0.0.1:8787

Ubuntu UFW 範例，僅允許 192.168.1.0/24 網段：

sudo ufw allow from 192.168.1.0/24 to any port 8787 proto tcp

不要把管理面板直接暴露在未受保護的公網。遠端管理建議搭配 HTTPS、可信反向代理、VPN 或其他存取控制層。

啟動失敗時

先查看服務日誌，不要只看 systemctl status：

sudo journalctl -u blockpilot -b -n 120 --no-pager

也可直接測試已安裝程式：

sudo systemctl stop blockpilot
sudo -u blockpilot -H bash -lc 'cd /opt/blockpilot && node app.js'

完成測試後重新啟動：

sudo systemctl restart blockpilot

Docker

Docker 使用方式請參閱 DOCKER.md。