Skip to content

README.zh-CN.md

Latest commit

 

History

History
311 lines (200 loc) · 13.9 KB

README.zh-CN.md

File metadata and controls

311 lines (200 loc) · 13.9 KB
Raw
BlockPilotMC 标志

BlockPilotMC

适用于 Windows 与 Linux 的自托管 Minecraft Java 服务器管理面板

版本 平台 Node.js 许可 语言

GitHub · 安装 · 设置 · 安全政策

English · 繁體中文 · 简体中文

BlockPilotMC 是什么？

BlockPilotMC 是一套自托管的 Minecraft Java 服务器管理面板。你可以在浏览器中创建或导入服务器、启动和停止服务器、查看实时控制台、编辑文件、管理插件与模组、安装整合包、创建备份、管理账号并查看主机资源。面板运行在自己的 Windows 或 Linux 主机上，世界文件、配置、账号数据与备份都由自己保存。

它适合想管理一台或多台 Minecraft 服务器，又不想在终端、文件管理器和备份工具之间来回切换的用户。

界面截图

服务器总览

查看主机负载、Minecraft 进程、面板状态与服务器入口。

BlockPilotMC 服务器总览

我的服务器

直接查看服务器是否运行，并使用常用的启动与停止操作。

BlockPilotMC 我的服务器

备份中心

查看备份内容、大小、保存位置，以及下载与恢复操作。

BlockPilotMC 备份中心

安装服务器

按照页面创建 Paper、Purpur、Vanilla、Fabric、Folia、Forge、NeoForge 或 Velocity 服务器。

BlockPilotMC 安装服务器

Modrinth 浏览

在面板中搜索 Modrinth，并选择可用于服务器的整合包版本。

BlockPilotMC Modrinth 浏览

压缩包与网址导入

上传 .mrpack、Server Pack ZIP，或粘贴直接下载地址。

BlockPilotMC 压缩包与网址导入

导入现有服务器

选择已有服务器目录，并由 BlockPilotMC 帮助识别启动命令。

BlockPilotMC 导入现有服务器

主要功能

  1. 创建或导入 Paper、Purpur、Vanilla、Fabric、Folia、Forge、NeoForge、Velocity 与自定义启动方式的 Minecraft Java 服务器。
  2. 使用实时 WebSocket 控制台输入命令、查看彩色输出、重新连接、搜索并保存完整会话日志。
  3. 浏览和编辑服务器文件，管理 server.properties、插件、模组与手动放入的 JAR。
  4. 搜索 Modrinth、安装支持的 .mrpack，并导入作者提供的 Server Pack 压缩包。
  5. 手动或定时创建完整备份与世界备份，可在“设置”指定备份存储文件夹，再从面板下载或恢复。
  6. 查看主机 CPU、内存，以及 Java PID、Minecraft CPU、RSS 内存、JVM 上限与运行时间。
  7. 管理管理员和操作员账号、登录期限、空闲退出、登录保护与审计记录。
  8. 切换深色或浅色界面、上传背景图、修改登录页文字，并设置面板端口或可选绑定 IP。
  9. 支持 Windows、Linux 源码启动，并提供 systemd 与 Docker 示例。

Discord 集成与 Minecraft 通知

BlockPilotMC v1.0.5 为每台 Minecraft 服务器提供独立的 Discord 集成，可同时使用 Webhook 通知 与 Discord Bot 双向桥接。

Minecraft → Discord Webhook 通知

每台服务器可单独设置 Webhook URL 与显示名称，并选择：

  • 服务器状态：启动、完成启动、停止及异常结果。
  • 玩家加入／离开。
  • 玩家聊天转发。
  • 可选的警告与错误摘要。
  • Webhook URL 仅在 API 后端加密保存，一般设置读取不会返回明文。

Discord Bot → Minecraft 双向聊天与管理

Bot Token 仅在 API 后端加密保存。使用前需在 Discord Developer Portal 启用 Message Content Intent。目标频道需要 View Channel、Send Messages、Read Message History；自动更新频道主题时还需要 Manage Channels。

支持 Discord 服务器 ID、频道 ID、Discord → Minecraft tellraw 聊天、受限远程管理命令、默认 !bp 命令前缀，以及服务器状态与运行信息的频道主题自动更新。

命令侦测与权限

BlockPilotMC 会分析启动文件、JAR、Forge／NeoForge libraries、模组与运行中的 help 输出，建立 Discord 可用命令列表；侦测到 spark 时也可提供 TPS / MSPT 查询。

每个命令可分别设置管理员可用与玩家可用。管理员身份组与单独允许用户可使用管理员命令；玩家身份组只能使用明确开启“玩家可用”的命令。两种权限同时存在时，以管理员权限优先。

更多说明请参阅 docs/DISCORD.md。

运行要求

  • Node.js 22 至 26
  • npm 10 或更高版本
  • 与 Minecraft 版本兼容的 Java
  • Chrome、Edge、Firefox、Safari 等现代浏览器
  • SQLite 已内置，不需要另外安装数据库服务

安装方式

Windows

根据需要选择启动语言：

Start-BlockPilot-ZH.bat   中文（简体）
Start-BlockPilot-TW.bat   中文（繁体）
Start-BlockPilot-EN.bat   English
Start-BlockPilot.bat      启动时选择语言

三个语言版本都会检查 npm；如果未安装且电脑可以使用 winget，会安装 Node.js LTS。启动器会根据 package-lock.json 安装固定版本的依赖并构建项目。完成后，Windows 会打开两个控制台：WEB 启动窗口显示面板地址，API 窗口显示服务信息。成功的 Dashboard 轮询不再逐条输出，避免 API 窗口快速刷屏。

BlockPilotMC v1.0.5 改用包含 Windows x64 预编译文件的 better-sqlite3 13.0.2，因此一般受支持的 Windows x64 环境不需要预先安装 Python 或 Visual Studio Build Tools。如果 npm 仍回退到原生编译，启动器会把完整内容保存到 runtime/install/npm-install.log，并用简短信息提示安装 Python 3，以及包含“使用 C++ 的桌面开发”工作负载的 Visual Studio 2022 Build Tools。生产依赖审计保存于 runtime/install/npm-audit.log，只报告结果，不会自动执行可能造成不兼容的强制修复。

第一次启动会创建 .env，并在控制台显示随机管理员密码。请先保存，再在登录后修改密码。

Linux

Ubuntu 与 Debian 可以使用一行命令安装为 systemd 服务：

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

安装完成后打开 http://<主机IP>:8787。安装程序会显示一次初始管理员密码，并配置开机自动启动。

如果只想在下载或 Git clone 的项目目录中直接运行：

npm ci
chmod +x start-linux.sh
./start-linux.sh

start-linux.sh 会在缺少 .env 时创建初始设置、按需安装 Linux 依赖、完成构建并启动面板。防火墙、systemd 与其他发行版说明请查看 安装说明。

手动启动源码

请先进入包含 package.json 的 BlockPilotMC 项目根目录，再执行：

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

默认本机地址：

http://127.0.0.1:8787

同一网络中的设备需要访问时，请将 HOST 设置为 0.0.0.0、在主机防火墙开放端口，再使用主机 LAN IP 打开面板。

Docker

项目中提供 Dockerfile 与 docker-compose.yml。使用前请先阅读 Docker 部署，并确认 runtime/ 与 Server/ 的挂载位置。

基本设置

常用设置保存在 .env：

PORT=8787
HOST=0.0.0.0
WEB_ORIGINS=http://localhost:8787,http://127.0.0.1:8787

“设置”页面可以修改面板端口和可选绑定 IP。网络设置保存后，需要重新启动 BlockPilotMC。

请勿提交 .env、运行数据、服务器文件、凭证或 API Key。公开源码检查请参阅 设置说明。

文档

开发与检查

npm install
npm run lint
npm run check:i18n
npm run check:ui
npm run check:network
npm run check:source
npm run build

一次运行全部检查：

npm run verify

主要目录：

apps/api/       Fastify API、SQLite、进程控制、备份与文件服务
apps/web/       React 界面与三语言翻译
scripts/        构建、检查、诊断与维护工具
docs/           安装、部署、安全与项目文档
runtime/        面板运行数据；Git 只保留 .keep
Server/         Minecraft 服务器根目录；Git 只保留 .keep

安全提醒

BlockPilotMC 可以启动 Java 进程、修改服务器文件并接收管理命令。请勿直接暴露在不受信任的公网。远程管理建议配合 HTTPS、可信反向代理、VPN 或其他访问控制。

安全问题请按照 SECURITY.md 私下报告。

参与项目

欢迎报告问题或提交范围明确的修改。提交前请先阅读 CONTRIBUTING.md。新增界面文字时，必须同时提供英文、繁体中文与简体中文。

许可与商标

BlockPilotMC 采用 Apache License 2.0 许可。项目同时提供 NOTICE 与 第三方声明。

Minecraft 名称及相关商标属于其权利人。BlockPilotMC 不是 Mojang Studios、Microsoft、CurseForge、Overwolf 或 Modrinth 的官方产品，也未获得其背书。

CurseForge API Key 与衍生项目规范

重要：Fork／衍生项目不得沿用 BlockPilotMC 原作者或任何第三方的 CurseForge API Key。

CurseForge 官方规定每位 Developer 应申请并使用核发给自己的唯一 API Key；API Key 不可转让，也不得分享给第三方。任何 Fork、修改版、再发行版、商业部署或其他衍生项目，在启用 CurseForge 集成前都必须申请并更换为自己／所属组织获核准的 Key。

公开版 BlockPilotMC 不会把维护者 API Key 放入源代码、.env、GitHub 或 Release。管理员输入的 Key 会储存在本机 SQLite，并使用 AES-256-GCM 进行静态加密保护。AES 加密并不代表共享 Key 符合 CurseForge 条款；衍生项目仍必须取得自己的 Key。

若未更换自己的 Key，除了可能造成 Key 泄露与配额被多人共用，依 CurseForge 条款，超额时 API 访问可能被拒绝，违反条款时相关授权可能被终止；终止后必须停止使用 API 并删除 Key。

启用前请阅读：

CurseForge API — 官方公开版规范

原始 BlockPilot Minecraft Panel 已获 CurseForge 团队批准使用 3rd Party CurseForge API。

官方 BlockPilotMC 公开版保留原项目的 CurseForge API Key，并使用 AES-256-GCM 加密保存；Key 不写入 .env、前端或一般 API 响应。

Fork、衍生项目、Mirror、Docker 衍生镜像及重新分发版本不得继续使用原 BlockPilotMC 的 CurseForge API Key。 衍生项目必须移除原 Key，并自行向 CurseForge 申请和使用自己的 API Key。

Apache-2.0 仅授权 BlockPilotMC 源代码，不包括 CurseForge API Key 的再授权或继续使用权。

详见：

  • PUBLIC_RELEASE_CURSEFORGE_NOTICE.md
  • docs/CURSEFORGE_API_POLICY.md
  • docs/CURSEFORGE_DERIVATIVE_PROJECT_REQUIREMENTS.md

SQLite 损坏自动保护

若启动时检测到 database disk image is malformed，BlockPilot 不会直接删除原数据库，而会先将 blockpilot.sqlite、-wal 与 -shm 保存到 runtime/recovery/database-corrupt-<时间>/，再建立新的 SQLite 数据库继续启动。确认新面板正常前请不要删除 recovery 文件夹。

源代码验证

GitHub Actions 与本地 CI 可执行：

npm run verify

该命令会依次执行 TypeScript / lint 验证与正式 build。

总览 RSS 动态刻度

总览中的“Minecraft 资源趋势”会根据当前运行中服务器的 JVM 最大内存总和自动调整 RSS 图表上限。例如两台服务器各设置 4 GB，图表上限会以 8 GB 为基准；启动或停止服务器时会自动更新。如果实际 RSS 超过设置上限，图表仍会自动扩展至实际最高值。