为 Minecraft 服务器搭建 Prometheus/InfluxDB 采集 + Grafana 仪表板的实时监控栈

方案简介

UnifiedMetrics 是一个面向 Minecraft 服务器的完全开源指标采集插件（License: GNU LGPLv3）。它通过在服务端侧以低开销方式采集运行时指标，把数据导出到 Prometheus 或 InfluxDB 这类时序/监控系统，并提供配套的 Grafana 仪表板，使服主可以像监控普通服务一样实时观测 MC 服务器的健康度。该项目适合需要为自己的 MC 服务器接入现代化监控栈的个人服主、运维工程师以及提供 MC 宿主服务的厂商（项目特别鸣谢了 Bloom Host 提供开发服）。

适用对象

• 运行 Spigot、Fabric、Minestom、Velocity、BungeeCord 等任意支持平台的 MC 服务器运维者
• 希望统一多平台（基岩除外）下指标语义与可视化效果的团队
• 想为 MC 服务端做性能基线与异常告警的开发者

解决的问题

• MC 原生 / 第三方插件缺少对运行时（JVM、Tick、玩家、实体）指标的标准化采集
• 多平台下各自一套指标体系，难以横向比较
• 缺一个现成的可视化模板，需要自己写 PromQL / Grafana Panel

亮点与能力

根据 README 列出的能力，本方案可提供：

• 跨平台一致的指标体系：在所有支持的服务端平台上获得同一套指标与功能，运维不必针对每个平台单独适配。
• 实时监控：基于 Prometheus / InfluxDB 与官方提供的 Grafana 仪表板实现实时可视化，并提供在线 Demo 预览。
• 高性能采集：采集逻辑对服务器性能影响极低（low to none performance impact）。
• 开箱即用仪表板：项目自带 Grafana Dashboard 接入文档，部署即用。
• 默认采集项覆盖 JVM 运行时：包括 GC 耗时与回收字节、内存使用与提交值、CPU 负载与进程启动时间、线程数等系统级指标。
• MC 业务指标：包括登录、加入、退出、聊天、Ping 等事件计数，插件数量与在线玩家数。
• 服务端 Tick 与世界指标（Bukkit/Minestom 平台）：Tick 时长直方图、世界实体/玩家/区块计数。
• 公开 API 供二次开发：通过 dev.cubxity.plugins.metrics.api.UnifiedMetricsProvider 获取实例，便于其他插件读取或扩展指标。

组成与分工

本方案由以下成员协同完成：

• UnifiedMetrics 插件：核心采集器，部署在 MC 服务端进程内，负责按 collector 收集系统与游戏指标，并按平台适配。
• Minecraft Server（多平台后端）：被监控的目标，提供运行载体；支持 Spigot 1.8+（含其衍生分支）、Fabric 1.16+、Minestom、Velocity、BungeeCord。
• Prometheus：拉取型时序数据库，作为指标后端之一负责存储与查询。
• InfluxDB：另一种被支持的指标后端，适配偏好 Push 模式或已在使用 Influx 技术栈的用户。
• Grafana：可视化层；项目提供官方 Dashboard，可直接 import 后在浏览器中查看 JVM 内存、GC、Tick、玩家数等关键指标。
• JDK 8+（Fabric 需 16+，Minestom 需 17+）：编译/运行插件及被监控 JVM 进程所需的运行时。
• Sonatype OSS Snapshots（仅 API 用户）：开发者通过 Gradle 引入 unifiedmetrics-api 时使用的快照仓库。

前置要求

在动手前需准备以下环境：

• JDK：构建需 JDK 8+；若面向 Fabric 则需 16+，面向 Minestom 则需 17+。
• Git（可选）：用于克隆源代码。
• 被监控的 MC 服务端：从 Compatibility 节列出的 Spigot / Fabric / Minestom / Velocity / BungeeCord 中任选其一。
• 指标后端：至少部署 Prometheus 或 InfluxDB 其中一个。
• Grafana：用于导入官方仪表板展示指标。

获取源代码（构建步骤前置）：

$ git clone https://github.com/Cubxity/UnifiedMetrics && cd UnifiedMetrics

实施步骤

1. 构建插件产物

进入源码目录后执行 Gradle 构建：

$ ./gradlew assemble -x signArchives

-x signArchives is required to skip signing, unless you have signing set up

若只针对某个平台构建，可在子项目路径前加冒号限定，例如：

$ ./gradlew :unifiedmetrics-platform-bukkit:assemble -x signArchives

构建产物位于 subproject/build/libs。

2. 部署到 MC 服务端

将对应平台（Spigot / Fabric / Minestom / Velocity / BungeeCord）的 jar 放入服务端的 plugins 或等价目录，按常规插件方式启动一次以生成配置。

3. 配置指标后端

在生成的配置中选择启用 Prometheus 或 InfluxDB，填写后端地址与端口。该插件作为采集端，将数据按所选后端协议暴露/上报。

4. 部署 Prometheus / InfluxDB

• 若使用 Prometheus：把 UnifiedMetrics 暴露的端点加入 scrape_configs。
• 若使用 InfluxDB：在 InfluxDB 端开启对应数据库与写入权限，插件按配置上报。

5. 部署 Grafana 并导入官方 Dashboard

按照项目提供的 Grafana 集成指南 导入官方 Dashboard，配置好 Prometheus 或 InfluxDB 作为数据源即可开箱可视化。

6.（可选）作为 API 依赖集成

若你也是插件开发者，可在 examples 目录下找到用法示例。Gradle Kotlin DSL：

repositories {
    mavenCentral()

    // Snapshots repository (only required for -SNAPSHOT versions)
    maven("https://s01.oss.sonatype.org/content/repositories/snapshots/")

dependencies {
    // Replace this with the desired version
    compileOnly("dev.cubxity.plugins", "unifiedmetrics-api", "0.3.6")

运行时通过服务管理器获取实例：

import dev.cubxity.plugins.metrics.api.UnifiedMetricsProvider

/* ... */

val api = UnifiedMetricsProvider.get()

注意事项与常见问题

构建与签名

• 不配置签名时必须加 -x signArchives，否则 Gradle 会因缺失签名配置而失败。
• 构建 JDK 版本要求随目标平台变化：Fabric 需 16+，Minestom 需 17+，其他平台 8+ 即可。

平台支持范围

• 服务端：Spigot 1.8+（含其衍生分支）、Fabric 1.16+、Minestom、Velocity、BungeeCord。
• 指标后端：仅 Prometheus 与 InfluxDB 两种，未列出其他（如 OpenTSDB、Mimir 等）兼容情况。

API 集成要点

• 引入 unifiedmetrics-api 时建议使用 compileOnly / provided 范围，由 UnifiedMetrics 在运行时提供实现。
• 优先使用平台自带的服务管理器获取 API 实例，而不是直接 new。

致谢与商业说明

• Bloom Host 为本项目提供开发服务器，并在 Special Thanks 中放置了联盟链接，属商业合作而非技术约束，使用本项目不强制依赖 Bloom。
• YourKit 为本项目提供 Java/.NET 监控与剖析工具支持。

优缺点

• ✓ 官方附带开箱即用 Grafana 仪表板
• ✓ 跨主流 MC 服务端平台统一指标
• ✕ 仅支持 Prometheus 和 Inf

出处

本方案挖掘自开源项目 Cubxity/UnifiedMetrics，方案内容与实施命令均来自其 README 原文。