Statfyr

插件

· 作者 Ded3ec

Statfyr 是一款轻量级的 Paper 插件,通过清晰且文档完善的 REST API 暴露服务器玩家统计数据。仪表盘、机器人、排行榜网站、Discord 集成——使用单一 HTTP 端点,用任意语言构建任何功能。

0 本站下载 0 关注 更新于 5 个月前

最新 1.0.0-BETA · 1.21.10 · Bukkit / Paper

一键开服(送7天)

Statfyr

为 Minecraft 玩家统计数据打造的极速 REST API


Statfyr 是一款轻量级的 Paper 插件,通过清晰且文档完善的 REST API 暴露你服务器的玩家统计数据。无论是仪表盘、机器人、排行榜网站还是 Discord 集成——只需针对单一 HTTP 端点,即可用任何语言构建任何应用。


✨ 功能特性

  • ? 完整的统计数据访问 —— 游戏时长、击杀数、死亡数、挖掘的方块数、制作的物品数、移动距离等
  • ? 排行榜 —— 提供按游戏时长、击杀数、死亡数、挖掘数和制作数排名的端点
  • ⚡ 异步加载 —— 统计数据在后台线程获取,零 TPS 影响
  • ?️ gzip 压缩 —— 可选的响应压缩,节省带宽
  • ? Bearer 认证 —— 使用密钥保护你的 API
  • ?️ 速率限制 —— 开箱即用的基于 IP 的请求节流
  • ? CORS 支持 —— 可配置的允许来源,支持浏览器端客户端
  • ? IP 白名单 —— 限制仅特定可信地址可访问
  • ? HTTPS / SSL —— 通过 Java keystore 可选启用 TLS
  • ? 内置 API 文档 —— 可通过 /api/docs 浏览的文档
  • ? 分页与排序 —— 所有列表端点均支持标准的 limit、page 和 order 参数
  • ⚙️ 响应缓存 —— 可配置的 TTL,减少重复的统计数据查询

? 依赖要求

依赖项 版本
Java 16+
Paper/Spigot 1.16.5+

? 安装步骤

  1. 从 Releases 标签页下载最新的 .jar 文件
  2. 将其放入服务器的 /plugins/ 文件夹中
  3. 启动(或重启)服务器
  4. 根据需要编辑 plugins/statfyr/config.yml
  5. 使用 /statfyr reload 应用更改,无需完全重启服务器

API 默认将在 http://your-server-ip:8080/api 上线。


? API 概览

所有响应均为 JSON 格式。所有端点的基础 URL 为:

http://your-server:8080/api

端点一览

方法 端点 描述
GET /api/health 服务器健康状态及版本信息
GET /api/players 列出所有已知玩家
GET /api/player/{player} 获取玩家的完整统计数据(UUID 或名称)
GET /api/player/{player}/summary 获取轻量级的汇总统计数据
GET /api/leaderboard/{type} 获取排名排行榜

排行榜类型

playtime · kills · deaths · mined · crafted


? 使用示例

获取所有在线玩家:

GET /api/players?online_only=true&limit=25

获取玩家的完整统计数据,并筛选出挖掘和制作类别:

GET /api/player/Steve?summary=true&categories=mined,crafted

获取前 10 名游戏时长排行榜:

GET /api/leaderboard/playtime?limit=10&order=desc

带认证的请求:

GET /api/players
Authorization: Bearer your-secret-key

示例响应 — 玩家摘要

{
  "uuid": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Alex",
  "online": false,
  "playtime_ticks": 125,
  "playtime_seconds": 6,
  "playtime_formatted": "6s",
  "combat": {
    "deaths": 0,
    "player_kills": 0,
    "mob_kills": 0,
    "damage_dealt": 0,
    "damage_taken": 0
  },
  "movement": {
    "distance_walked_cm": 0,
    "distance_walked_m": 0,
    "distance_sprinted_cm": 0,
    "distance_sprinted_m": 0,
    "distance_flown_cm": 0,
    "distance_flown_m": 0,
    "distance_swum_cm": 0,
    "distance_swum_m": 0,
    "total_distance_cm": 0,
    "total_distance_m": 0,
    "total_distance_km": 0,
    "jumps": 0
  },
  "activity": {
    "chests_opened": 0,
    "items_crafted": 0,
    "items_broken": 0,
    "items_used": 0,
    "items_picked_up": 0,
    "items_dropped": 0,
    "blocks_mined": 0
  },
  "metadata": {
    "generated_at": "2026-05-20T11:17:16.252462500Z",
    "execution_time_ms": 34,
    "movement_enabled": true,
    "combat_enabled": true,
    "activity_enabled": true
  }
}

示例响应 — 排行榜

{
  "stat": "playtime",
  "total": 1,
  "limit": 25,
  "offset": 0,
  "page": 1,
  "entries": [
    {
      "rank": 1,
      "uuid": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Steve",
      "online": false,
      "value": 125,
      "formatted": "6s"
    }
  ],
  "metadata": {
    "generated_at": "2026-05-20T11:18:07.625703400Z",
    "execution_time_ms": 3,
    "ascending": false,
    "online_only": false
  }
}

⚙️ 配置

首次运行时会在 plugins/statfyr/config.yml 生成完整的配置文件。

http:
  port: 8080
  bind-address: "0.0.0.0"   # 使用 127.0.0.1 以限制仅本地访问

security:
  enable-api-key: false      # 启用 Bearer token 认证
  api-key: ""                # 在此设置你的密钥,或通过 STATFYR_API_KEY 环境变量设置

  enable-rate-limit: true
  rate-limit-requests: 120   # 每个窗口内的请求数
  rate-limit-window-seconds: 60

  enable-cors: true
  allowed-origins:
    - "*"                    # 在生产环境中请收紧此设置

cache:
  ttl-seconds: 60
  refresh-seconds: 10

环境变量覆盖:

变量 配置键
STATFYR_API_KEY security.api-key
STATFYR_KEYSTORE_PASSWORD https.keystore-password

? 保护你的 API

对于生产服务器,强烈建议采取以下措施:

  1. 启用 API 密钥认证 — 设置 enable-api-key: true 并生成一个强随机密钥
  2. 限制 CORS 来源 — 将 "*" 替换为你的仪表板的实际域名
  3. 启用 IP 白名单 — 如果只有已知服务需要访问,将其锁定为这些 IP
  4. 启用 HTTPS — 生成密钥库并设置 https.enabled: true

为 HTTPS 生成密钥库:

keytool -genkeypair -alias statfyr \
  -keyalg RSA -keysize 2048 \
  -storetype JKS \
  -keystore plugins/statfyr/keystore.jks \
  -validity 3650

? API 文档

交互式 API 文档可在以下地址查看:

http://your-server:8080/api/docs

在生产环境中通过 docs.enabled: false 禁用它。


?️ HTTP 状态码

代码 含义
200 成功
400 错误请求(参数无效)
401 未授权(缺少或无效的 API 密钥)
403 禁止访问(IP 未在白名单中)
404 未找到玩家或资源
429 请求过多(超出速率限制)
500 内部服务器错误

?️ 命令与权限

命令 权限 描述
/statfyr reload statfyr.reload 重新加载配置
/statfyr status statfyr.status 显示 API 状态和端口

? 支持与社区

  • 即将推出!!

? 许可证

Statfyr 根据 MIT 许可证 发布。


你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源