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+ |
? 安装步骤
- 从 Releases 标签页下载最新的
.jar 文件
- 将其放入服务器的
/plugins/ 文件夹中
- 启动(或重启)服务器
- 根据需要编辑
plugins/statfyr/config.yml
- 使用
/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
对于生产服务器,强烈建议采取以下措施:
- 启用 API 密钥认证 — 设置
enable-api-key: true 并生成一个强随机密钥
- 限制 CORS 来源 — 将
"*" 替换为你的仪表板的实际域名
- 启用 IP 白名单 — 如果只有已知服务需要访问,将其锁定为这些 IP
- 启用 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 许可证 发布。
Statfyr
A blazing-fast REST API for Minecraft player statistics
Statfyr is a lightweight Paper plugin that exposes your server's player statistics through a clean, documented REST
API. Dashboards, bots, leaderboard websites, Discord integrations — build anything, in any language, against a single
HTTP endpoint.
✨ Features
- ? Full stat access — playtime, kills, deaths, blocks mined, items crafted, movement, and more
- ? Leaderboards — ranked endpoints for playtime, kills, deaths, mined, and crafted
- ⚡ Async loading — stats are fetched off the main thread, zero TPS impact
- ?️ gzip compression — optional response compression for bandwidth efficiency
- ? Bearer authentication — lock your API behind a secret key
- ?️ Rate limiting — per-IP request throttling out of the box
- ? CORS support — configurable allowed origins for browser-based clients
- ? IP whitelist — restrict access to specific trusted addresses
- ? HTTPS / SSL — optional TLS via Java keystore
- ? Built-in API docs — browsable documentation at
/api/docs
- ? Pagination & sorting — standard
limit, page, and order params across all list endpoints
- ⚙️ Response caching — configurable TTL to reduce repeated stat lookups
? Requirements
| Requirement |
Version |
| Java |
16+ |
| Paper/Spigot |
1.16.5+ |
? Installation
- Download the latest
.jar from the Releases tab
- Drop it into your server's
/plugins/ folder
- Start (or restart) your server
- Edit
plugins/statfyr/config.yml to your liking
- Use
/statfyr reload to apply changes without a full restart
The API will be live at http://your-server-ip:8080/api by default.
? API Overview
All responses are JSON. The base URL for all endpoints is:
http://your-server:8080/api
Endpoints at a Glance
| Method |
Endpoint |
Description |
GET |
/api/health |
Server health and version info |
GET |
/api/players |
List all known players |
GET |
/api/player/{player} |
Full stats for a player (UUID or name) |
GET |
/api/player/{player}/summary |
Lightweight summarized stats |
GET |
/api/leaderboard/{type} |
Ranked leaderboard |
Leaderboard Types
playtime · kills · deaths · mined · crafted
? Usage Examples
Get all online players:
GET /api/players?online_only=true&limit=25
Get a player's full stats, filtered to mined and crafted categories:
GET /api/player/Steve?summary=true&categories=mined,crafted
Get the top 10 playtime leaderboard:
GET /api/leaderboard/playtime?limit=10&order=desc
Authenticated request:
GET /api/players
Authorization: Bearer your-secret-key
Example Response — Player Summary
{
"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
}
}
Example Response — Leaderboard
{
"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
}
}
⚙️ Configuration
The full config file is generated at plugins/statfyr/config.yml on first run.
http:
port: 8080
bind-address: "0.0.0.0" # Use 127.0.0.1 to restrict to localhost
security:
enable-api-key: false # Enable Bearer token auth
api-key: "" # Set your key here, or via STATFYR_API_KEY env var
enable-rate-limit: true
rate-limit-requests: 120 # Requests per window
rate-limit-window-seconds: 60
enable-cors: true
allowed-origins:
- "*" # Lock this down in production
cache:
ttl-seconds: 60
refresh-seconds: 10
Environment variable overrides:
| Variable |
Config Key |
STATFYR_API_KEY |
security.api-key |
STATFYR_KEYSTORE_PASSWORD |
https.keystore-password |
? Securing Your API
For production servers, it is strongly recommended to:
- Enable API key authentication — set
enable-api-key: true and generate a strong random key
- Restrict CORS origins — replace
"*" with your dashboard's actual domain
- Enable IP whitelisting — if only known services need access, lock it to those IPs
- Enable HTTPS — generate a keystore and set
https.enabled: true
Generate a keystore for HTTPS:
keytool -genkeypair -alias statfyr \
-keyalg RSA -keysize 2048 \
-storetype JKS \
-keystore plugins/statfyr/keystore.jks \
-validity 3650
? API Documentation
Interactive API documentation is available at:
http://your-server:8080/api/docs
Disable it in production with docs.enabled: false.
?️ HTTP Status Codes
| Code |
Meaning |
200 |
Success |
400 |
Bad request (invalid parameters) |
401 |
Unauthorized (missing or invalid API key) |
403 |
Forbidden (IP not whitelisted) |
404 |
Player or resource not found |
429 |
Too many requests (rate limit exceeded) |
500 |
Internal server error |
?️ Commands & Permissions
| Command |
Permission |
Description |
/statfyr reload |
statfyr.reload |
Reload the configuration |
/statfyr status |
statfyr.status |
Show API status and port |
? Support & Community
? License
Statfyr is released under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧