WebMonitor v1.0.0 · 首个公开版本

WebMonitor v1.0.0 —— 首个公开版本。

把 Minecraft 挂机整合包里的方块、机器和方块实体 NBT，变成可查询的 API、可订阅的事件，和一张能点开看的 3D 地图；机器停了、该维护了、流体见底了，主动推到手机上。

下载

文件	用途
web_monitor_interface-1.0.0-all.jar	Forge 1.20.1 模组（含 netty-codec-http），丢进 mods/
webmonitor-console-0.1.0.zip	监控台：守护进程 + Web 控制台，前端已预构建

⚠️ mod 只装这一个 jar。源码构建会同时产出普通 jar（不含 netty HTTP codec，MC 1.20.1 也不自带），
两个都放进 mods/ 时 Forge 不会报错，只会安静地挑一个 —— 挑错了就是启动即崩。
所以这里只提供 -all 版。

模组

# 解压到整合包的 mods/ 目录，重启游戏
# 专用服务器需要 API Key（单人 / 局域网集成服务器免 key）：
/webmonitor key generate 手机监控

Mod 默认在 127.0.0.1:18080 起一个只读的 REST + WebSocket 服务。

监控台

unzip webmonitor-console-0.1.0.zip
cd webmonitor-console-0.1.0

npm --prefix server install     # 只装运行依赖：tsx、ws
npm start                       # → http://localhost:18081

Windows 直接双击 start-windows.bat；Docker 用 docker compose up -d。

前端已经构建好了，所以不需要装 vite / vue-tsc 那一套（约 100 MB 开发依赖）；
只有要改前端源码时才需要 npm --prefix web install && npm --prefix web run build。
包内 INSTALL.md 有完整说明，仓库里的 console 手册 是完整文档。

没开游戏也能先看效果：npm run mock 起一个假 mod，npm start 起守护进程。

环境

	版本
Minecraft	1.20.1
Forge	47.4.20（任意 [47,)）
监控台	Node.js 20+

这个版本包含

模组 web_monitor_interface 1.0.0

• 只读 REST API：服务器状态 / TPS / 维度 / 方块 / 方块实体 / 实体 / 玩家 / Forge 能力（energy、items、fluid）
• WebSocket 实时事件：chat.public、player.join、player.quit
• API Key 鉴权 + 每 key 限流；集成服务器免 key
• 3D 地图用的按列扫描接口（/surface），方块状态去重键已修正（旧版会把所有「无属性方块」共用一个下标）
• 所有世界访问都经 MinecraftThread.call() 回到服务端线程，Netty 线程绝不直接碰 Minecraft API

监控台 web_monitor_console 0.1.0

• 规则引擎：BlockState / BlockEntity NBT 点分路径条件，边沿 / 持续触发、冷却、恢复通知、试运行
• 3D 地图：真实材质渲染（mod 数据 > 原版资源 > 上传材质包 > 色块），面剔除、镂空列三态堆叠、可疑列全列核实；键盘 WASD/QE 选块，可以选中被遮挡的地下格
• GT 机器状态：按 blockId 分派到 10 个 kind 解码存档字段，字段中文标签来自 mod 界面原文的四层证据链，113 个 GT 方块的渲染兜底
• 通知渠道：Windows Toast / ntfy（Android，走 FCM）/ Webhook（Discord、飞书、企微）/ 日志
• 免游戏联调：内置 mock mod，npm run mock + npm run contract + npm run smoke 全套验证不用开游戏

已知限制

• 客户端（连远程服）模式下只加载玩家周围区块，地图请用「定位玩家」把中心对准玩家
• 客户端模式下 status.running 恒为 false（它只表示本地有没有 MinecraftServer），人数请看 /players
• GT 字段标签只覆盖已核定的方块家族；未覆盖的字段会在面板上显式标注「暂无中文映射」，不会瞎猜
• 监控台包内不含 node_modules：需要联网执行一次 npm --prefix server install

文档

• 根 README —— 快速开始与架构
• console 手册 —— 配置、规则、通知、地图材质、Admin API、故障排查
• mod 线程模型与鉴权
• GT 字段解析

完整变更：首次发布，见 提交历史。