itzg/mc-monitor 镜像文档

]([] ![CircleCI]([***]

镜像概述和主要用途

itzg/mc-monitor 是一款用于监控 Minecraft 服务器状态的 Docker 镜像，提供命令行工具和代理功能。该镜像可实现对 Minecraft 服务器的状态检查、性能指标收集，并支持将监控数据集成到第三方监控系统（如 Telegraf），适用于服务器管理员实时掌握服务器运行状态。

核心功能和特性

• 状态检查：通过 status 子命令快速检查指定 Minecraft 服务器的在线状态，返回明确的退出码（0 表示成功，1 表示失败）。
• 指标收集：通过 gather-for-telegraf 子命令周期性采集服务器指标（如在线人数、响应时间等），并通过 Influx 线协议发送至 Telegraf。
• 多服务器支持：支持同时监控多个 Minecraft 服务器，通过环境变量配置服务器列表。
• 轻量集成：可通过 Docker 快速部署，支持与 Telegraf、InfluxDB、Grafana 等监控工具链无缝集成。

使用场景和适用范围

• Minecraft 服务器管理员：实时监控单台或多台服务器的在线状态及性能指标。
• 监控系统集成：作为数据采集代理，将 Minecraft 服务器指标接入现有监控系统（如 Telegraf + InfluxDB + Grafana），实现可视化与告警。
• 自动化运维：结合脚本或 CI/CD 工具，基于 status 子命令的退出码触发自动化告警或故障恢复流程。

使用方法和配置说明

子命令说明

status：检查服务器状态

用于查询指定 Minecraft 服务器的实时状态，返回服务器是否可达及基本信息。

参数：

• --host：Minecraft 服务器地址（必填）。
• --port：服务器端口（可选，默认 25565）。

退出码：

• 0：服务器状态正常（可达）。
• 1：服务器状态异常（不可达或无响应）。

示例：

docker run -ti --rm itzg/mc-monitor status --host mc.hypixel.net --port 25565

gather-for-telegraf：周期性指标收集

用于周期性采集一个或多个 Minecraft 服务器的性能指标，并通过 TCP 协议以 Influx 线协议格式发送至 Telegraf。

Docker 部署示例

1. 单服务器状态检查（status 子命令）

通过 docker run 直接执行状态检查：

# 检查 mc.hypixel.net:25565 的状态
docker run -ti --rm itzg/mc-monitor status --host mc.hypixel.net

2. 集成 Telegraf 监控（gather-for-telegraf 子命令）

通过 Docker Compose 部署 Telegraf 与 mc-monitor，实现指标采集与存储。

步骤 1：准备 Telegraf 配置文件

创建 telegraf.conf，配置 Telegraf 监听 TCP 端口接收指标：

[[inputs.socket_listener]]
  service_address = "tcp://:8094"  # 监听 8094 端口接收 Influx 协议数据

[[outputs.file]]
  files = ["stdout"]  # 将接收到的指标输出到标准输出（可替换为 InfluxDB 等存储）

步骤 2：编写 Docker Compose 配置

创建 docker-compose.yml，定义 Telegraf 和 mc-monitor 服务：

version: '3'

services:
  telegraf:
    image: telegraf:1.13
    volumes:
      - ./telegraf.conf:/etc/telegraf/telegraf.conf:ro  # 挂载配置文件
    ports:
      - "8094:8094"  # 暴露 TCP 端口供 mc-monitor 发送数据

  monitor:
    image: itzg/mc-monitor
    command: gather-for-telegraf  # 启动指标收集模式
    environment:
      GATHER_INTERVAL: 10s        # 采集间隔（如 10s、1m）
      GATHER_TELEGRAF_ADDRESS: telegraf:8094  # Telegraf 的 TCP 地址
      GATHER_SERVERS: mc.hypixel.net,localhost:25565  # 监控的服务器列表（逗号分隔）

步骤 3：启动服务并查看指标

启动服务：

docker-compose up

Telegraf 服务输出的指标示例（Influx 线协议格式）：

minecraft_status,host=mc.hypixel.net,port=25565,status=success response_time=0.172809649,online=51201i,max=90000i 1576971568953660767
minecraft_status,host=localhost,port=25565,status=success response_time=0.05234512,online=10i,max=20i 1576971579020125479

环境变量配置（gather-for-telegraf 子命令）

使用 gather-for-telegraf 时，需通过环境变量配置采集参数：

指标说明（Influx 线协议格式）

gather-for-telegraf 输出的指标格式示例：

minecraft_status,host=mc.hypixel.net,port=25565,status=success response_time=0.172809649,online=51201i,max=90000i 1576971568953660767

• 标签（Tags）：host（服务器地址）、port（端口）、status（采集状态，success/failure）。
• 字段（Fields）：response_time（响应时间，单位秒）、online（当前在线人数）、max（服务器最大容纳人数）。
• 时间戳：指标采集时间（Unix 时间戳，纳秒级）。