MC 基岩版多服务器状态检测 — 文档

说明：本文件为 server.js 项目的使用与部署说明（针对基岩版 Minecraft 服务器状态检测）。

简介
先决条件与依赖
安装与部署
配置说明（servers 数组）
API 使用
定时检测与日志
常见问题与排查
可选改进

简介

本项目用于周期性检查多台 Minecraft 基岩版（Bedrock）服务器的在线状态，并通过简单的 HTTP API 提供最新状态查询。项目不再使用数据库，所有状态保存在内存中（服务重启后会丢失）。

核心文件：server.js

功能概览：

支持同时检测多台服务器
按需实时检测：每次 API 请求都会即时向目标服务器发起检查并返回结果（默认不做持久化或定时检测）
提供 GET /api/status 与 GET /api/status/:id 两个接口返回最新状态

先决条件与依赖

Node.js：建议使用 Node 18+（Express 5 使用了较新 Node 特性）。如果无法升级，请使用 Express 4.x（见常见问题）。
npm

项目依赖：

express
minecraft-server-util（注意：该包已不再维护，npm 安装时会有警告）
node-cron（可选）：当前默认实现为按需实时检测，不依赖定时任务；如需定时检测可安装并在代码中启用。

在项目目录（e:\ 或 /www/js，取决于你的部署目录）运行：

PowerShell 示例：

cd e:\
npm install express minecraft-server-util
# 可选：若需要定时任务 support
# npm install node-cron

Linux/Bash 示例（若在 /www/js）：

cd /www/js
npm install express minecraft-server-util
# 可选：若需要定时任务 support
# npm install node-cron

注意：如果你的系统 Node 版本较旧（如 v14），安装最新 Express（5.x）会产生兼容性问题，建议升级 Node 到 v18+ 或改装依赖为 express@4（见下文）。

安装与部署

把 server.js 放到目标服务器目录，例如 e:\server.js（Windows）或 /www/js/server.js（Linux）。
在该目录运行 npm install 安装依赖。
启动：

PowerShell / Windows：

node e:\下载\server.js

Linux：

node /www/js/server.js

后台运行（推荐使用 pm2）：

npm install -g pm2
pm2 start /www/js/server.js --name mc-status
pm2 save
pm2 logs mc-status

配置说明（`servers` 数组）

在 server.js 文件中有一个 servers 数组，用于定义要检测的服务器。示例：

const servers = [
  { id: 'server1', name: 'Primary', host: '103.40.14.14', port: 41657 },
  { id: 'server2', name: 'Example', host: 'play.example.com', port: 19132 }
];

字段说明：

id：唯一标识符，用于 API 路径（如 /api/status/server1）。
name：可读名称，仅用于返回和日志。
host：IP 或域名。
port：基岩版端口，默认 19132，若非默认请修改。

你可以直接编辑 server.js 中的数组，或按需改造为读取 servers.json、环境变量或配置文件。

API 使用

GET /api/status
- 返回所有已配置服务器的实时检测结果（每次调用都会即时请求目标服务器并返回当前状态）。
GET /api/status/:id
- 返回指定 id 的服务器的实时检测结果（只检测该服务器并返回）。

示例（curl）：

curl http://localhost:3000/api/status
curl http://localhost:3000/api/status/server1

返回字段示例（单个服务器）

{
  "id": "server1",
  "name": "Primary",
  "host": "103.40.14.14",
  "port": 41657,
  "checkedAt": "2025-11-28T20:00:00.000Z",
  "online": true,
  "players": { "online": 2, "max": 20 },
  "motd": "欢迎来到服务器",
  "version": "1.20",
  "error": null
}

字段说明：

checkedAt：最近一次检测时间（ISO 字符串）。
online：布尔，服务器是否在线。
players：对象，包含 online（当前在线人数）和 max（最大人数）。
motd：服务器 MOTD（如可用）。
version：服务器版本信息（如可用）。
error：检测失败时的错误信息。

检测与日志

按需实时检测：当前实现为按需实时检测（API 调用即时检测），默认不启用定时任务或持久化。
日志通过 console.log/console.error 输出；生产环境建议把输出交给进程管理器（如 pm2）或重定向到文件。

提示：如需降低对目标服务器的查询压力，可在代码中加入短期缓存（TTL），或启用 node-cron 做定时采样并在 API 返回缓存结果。

常见问题与排查

问：启动时报 Cannot find module 'node:events' 或类似错误。
- 因为安装了需要 Node 18+ 的依赖（例如 Express 5）。解决方法：升级 Node 到 v18+（推荐），或改用 express@4.x 以兼容旧版本 Node（例如 v14）。
问：npm install 在错误目录执行（例如在 /root 而非 /www/js），导致运行时找不到模块。
- 请务必在应用目录执行 npm install，确保 node_modules 位于与 server.js 同一目录或上层可被解析的位置。

菜单

分享