Hypixel Mirror API

核心特性

智能缓存

数据缓存 3 小时，访问过期缓存时自动从官方 API 刷新，用户完全无感知。

多密钥管理

支持多个 Hypixel API 密钥，自动轮换使用，失效密钥自动删除。

完整统计

详细的请求日志、缓存命中率、密钥使用情况等统计数据。

管理工具

Web 界面管理缓存和密钥，支持手动清理和维护操作。

系统要求

组件	版本要求	说明
PHP	7.4+	推荐使用 PHP 8.0+
MySQL	5.7+	或 MariaDB 10.2+
Web 服务器	Nginx 1.25+ 或 Apache 2.4+	推荐使用 Nginx
PHP 扩展	PDO, PDO_MySQL, cURL, JSON	必需扩展

搭建教程

1 下载项目

                            git clone https://github.com/weige0831/HypixelAPImirror.git

cd HypixelAPImirror

2 配置数据库

登录 MySQL 并创建数据库（如果使用现有数据库可跳过）：

                            # 登录 MySQL

mysql -u root -p

# 创建数据库

CREATE DATABASE IF NOT EXISTS api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 退出 MySQL

exit;

导入数据库结构：

mysql -u root -p api < database.sql

3 配置文件

复制配置模板并编辑：

                            cp config.example.php config.php

nano config.php

需要修改的配置项：

database.host - 数据库主机地址
database.dbname - 数据库名称（默认：api）
database.username - 数据库用户名
database.password - 数据库密码
admin.username - 管理员用户名
admin.password - 管理员密码（请使用强密码）

4 配置 Web 服务器

Nginx 配置示例：

                            server {

    listen 80;

    server_name api.example.com;

    root /path/to/hypixelmirro/public;

    index index.php;

    location / {

        try_files $uri $uri/ /index.php?$query_string;

    }

    location ~ \.php$ {

        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;

        fastcgi_index index.php;

        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

        include fastcgi_params;

    }

}

重启 Nginx：

systemctl restart nginx

5 运行初始化

访问初始化页面（需要管理员认证）：

http://api.example.com/setup.php

或使用命令行：

curl -u admin:password "http://api.example.com/setup.php"

提示： 初始化脚本会自动检查系统要求、创建数据库表、验证配置等。

6 添加 API 密钥

首先，在 Hypixel 开发者面板获取您的 API 密钥。

然后，使用以下任一方式添加密钥：

方式一：使用 GET 请求（推荐）

                            curl -u admin:password "http://api.example.com/hypixel-keys.php?add_key=YOUR_HYPIXEL_API_KEY"
                        

方式二：使用 POST 请求

                            curl -u admin:password -X POST \

  -H "Content-Type: application/json" \

  -d '{"hypixel_key":"YOUR_HYPIXEL_API_KEY"}' \

  "http://api.example.com/hypixel-keys.php"

验证密钥已添加

                            # 查看所有密钥

curl -u admin:password "http://api.example.com/hypixel-keys.php"

提示：

系统会自动验证密钥有效性，无效的密钥无法添加
可以添加多个密钥，系统会自动轮换使用
建议添加 2-3 个密钥以提高服务稳定性

重要： 至少需要添加一个有效的 Hypixel API 密钥才能使用服务。

API 文档

GET 获取玩家数据

获取指定玩家的所有 Hypixel 数据。支持通过 UUID 或玩家名称查询。

请求 URL

                            GET /index.php?uuid={player_uuid}

GET /index.php?name={player_name}

请求参数

参数	类型	必需	说明
`uuid`	string	二选一	玩家的 UUID（32位，无连字符）
`name`	string	二选一	玩家的游戏名称

响应示例

{
  "success": true,
  "data": {
    "player": {
      "uuid": "f7c77d999f154a66a87dc4a51ef30d19",
      "displayname": "jeb_",
      "firstLogin": 1413309026000,
      "lastLogin": 1731662015000,
      "playername": "jeb_",
      "networkExp": 1234567,
      "stats": {
        "Bedwars": {
          "wins_bedwars": 1250,
          "kills_bedwars": 8500,
          ...
        },
        "SkyWars": {
          ...
        }
      },
      ...
    },
    "fetch_time": "2025-11-25 10:30:00"
  }
}

错误响应

{
  "success": false,
  "error": "Either player UUID or name is required"
}

使用示例

                            # 通过 UUID 查询

curl "https://api.example.com/index.php?uuid=f7c77d999f154a66a87dc4a51ef30d19"

# 通过玩家名查询

curl "https://api.example.com/index.php?name=Notch"

GET 获取统计信息

获取 API 服务的运行统计信息，包括请求数、缓存命中率、密钥使用情况等。

请求 URL

GET /stats.php

响应示例

{
  "success": true,
  "data": {
    "timestamp": "2025-11-25 10:30:00",
    "date": "2025-11-25",
    "api_keys": {
      "total": 3,
      "valid": 3
    },
    "today_stats": {
      "api_requests": 125,
      "cache_hits": 450,
      "successful_requests": 570,
      "failed_requests": 5,
      "unique_players": 89,
      "total_requests": 575
    },
    "cache_stats": {
      "total_entries": 500,
      "valid_entries": 480,
      "expired_entries": 20
    },
    "keys_detail": [
      {
        "key": "12345678...abcd",
        "owner": "admin",
        "requests_today": 42,
        "total_requests": 1250,
        "is_valid": true
      }
    ]
  }
}

使用示例

curl "https://api.example.com/stats.php"

错误代码

HTTP 状态码	说明	可能原因
200	成功	请求成功处理
400	请求错误	缺少必需参数或参数格式错误
401	未授权	访问管理功能需要认证
404	未找到	玩家不存在或端点不存在
429	请求过多	触发速率限制
500	服务器错误	内部错误，请联系管理员

管理功能

认证要求： 所有管理接口都需要 HTTP Basic 认证，使用 config.php 中配置的管理员账户。

GET 初始化脚本需要认证

用于首次部署或重新初始化系统。检查系统要求、创建数据库表、验证配置。

请求 URL

GET /setup.php

功能说明

✅ 检查 PHP 版本和必需扩展
✅ 检查数据库表是否存在
✅ 自动创建缺失的表
✅ 检查 API 密钥数量
✅ 验证配置文件

响应示例

{
  "success": true,
  "setup_time": "2025-11-25 10:30:00",
  "steps": [
    {
      "step": "system_check",
      "status": "success",
      "message": "System requirements checked"
    },
    {
      "step": "table_check",
      "status": "success",
      "message": "All tables exist"
    },
    {
      "step": "api_keys_check",
      "status": "success",
      "message": "Found 3 valid API keys"
    }
  ],
  "message": "✅ Setup completed successfully!",
  "next_steps": [
    "1. Add Hypixel API keys via /hypixel-keys.php",
    "2. Test the API via /index.php?uuid=player_uuid",
    "3. Monitor statistics via /stats.php"
  ]
}

使用示例

curl -u admin:password "https://api.example.com/setup.php"

GET POST 密钥管理需要认证

管理 Hypixel API 密钥。查看、添加密钥及其使用统计。

1️⃣ 查看所有密钥

GET /hypixel-keys.php

返回所有 API 密钥的列表及其统计信息。

响应示例：

{
  "success": true,
  "data": [
    {
      "key": "12345678-1234-1234-1234-123456789abc",
      "created_at": "2025-11-25 10:00:00",
      "last_checked": "2025-11-25 12:30:00",
      "last_used": "2025-11-25 12:35:00",
      "daily_requests": 125,
      "total_requests": 5430,
      "is_valid": true,
      "status_code": 200,
      "owner": "admin",
      "notes": "主密钥"
    }
  ]
}

使用示例：

curl -u admin:password "https://api.example.com/hypixel-keys.php"

2️⃣ 添加新密钥（方式一：GET）

GET /hypixel-keys.php?add_key={your_hypixel_api_key}

使用示例：

                            curl -u admin:password "https://api.example.com/hypixel-keys.php?add_key=12345678-1234-1234-1234-123456789abc"
                        

成功响应：

{
  "success": true,
  "message": "Hypixel API key added successfully"
}

3️⃣ 添加新密钥（方式二：POST）

                            POST /hypixel-keys.php

Content-Type: application/json

{

  "hypixel_key": "your_hypixel_api_key"

}

使用示例：

                            curl -u admin:password -X POST \

  -H "Content-Type: application/json" \

  -d '{"hypixel_key":"12345678-1234-1234-1234-123456789abc"}' \

  "https://api.example.com/hypixel-keys.php"

📋 密钥信息字段说明

字段	类型	说明
`key`	string	API 密钥（完整显示）
`owner`	string	密钥所有者/备注（可选）
`notes`	string	备注信息（可选）
`is_valid`	boolean	密钥是否有效
`daily_requests`	integer	今日请求数
`total_requests`	integer	总请求数
`last_used`	datetime	最后使用时间
`status_code`	integer	最后请求的 HTTP 状态码

❌ 错误响应

{
  "success": false,
  "error": "Invalid Hypixel API key"
}

重要提示：

添加密钥时系统会自动验证其有效性
只有通过验证的密钥才会被添加到数据库
无效的密钥在使用时会被自动删除
可以在 Hypixel 开发者面板获取 API 密钥

注意： 目前不支持通过 API 删除密钥。无效的密钥会在使用时自动从数据库中删除。如需手动删除，请直接操作数据库。

GET 缓存管理需要认证

查看缓存统计信息和手动清理缓存。

缓存统计

GET /cache-stats.php

显示详细的缓存统计信息，包括总条目数、有效条目、过期条目、重复条目等。

快速清理

                            # 标准清理

GET /cleanup.php

# 强制清理（更激进）

GET /cleanup.php?force=1

响应示例

{
  "success": true,
  "cleanup_type": "force",
  "cleanup_time": "2025-11-25 10:30:00",
  "before_cleanup": {
    "total_entries": 500,
    "valid_entries": 450,
    "expired_entries": 50
  },
  "cleanup_result": {
    "expired_removed": 50,
    "duplicates_removed": 5,
    "total_cleaned": 55
  },
  "after_cleanup": {
    "total_entries": 445,
    "valid_entries": 445,
    "expired_entries": 0
  },
  "summary": {
    "space_saved": 55
  }
}

使用示例

                            # 标准清理

curl -u admin:password "https://api.example.com/cleanup.php"

# 强制清理

curl -u admin:password "https://api.example.com/cleanup.php?force=1"

GET 维护工具需要认证

全功能缓存维护工具，支持多种维护操作。

请求 URL

GET /maintenance.php?action={action}

支持的操作

操作	说明
`status`	查看缓存状态和重复项统计
`cleanup`	标准清理（删除过期和重复）
`force_cleanup`	强制清理（更激进）
`remove_duplicates`	仅删除重复条目
`full_maintenance`	完整维护（删除重复 + 强制清理）

使用示例

                            # 查看状态

curl -u admin:password "https://api.example.com/maintenance.php?action=status"

# 标准清理

curl -u admin:password "https://api.example.com/maintenance.php?action=cleanup"

# 完整维护

curl -u admin:password "https://api.example.com/maintenance.php?action=full_maintenance"

状态响应示例

{
  "success": true,
  "action": "status",
  "timestamp": "2025-11-25 10:30:00",
  "data": {
    "cache_stats": {
      "total_entries": 500,
      "valid_entries": 480,
      "expired_entries": 20,
      "duplicate_entries": 3
    },
    "duplicates": {
      "uuid_duplicates": 2,
      "name_duplicates": 1
    },
    "total_issues": 23
  }
}

缓存策略

工作原理

本系统采用智能的即时缓存过期检测机制：

🔄 缓存流程

用户请求 → 系统首先查询缓存
检查有效性 → 如果缓存存在，检查是否过期
- ✅ 有效：直接返回缓存数据
- ❌ 过期：立即删除该条记录，从官方 API 获取新数据
缓存新数据 → 将新获取的数据缓存 3 小时
返回数据 → 用户获得最新数据（完全透明）

⏱️ 时间设置

参数	值	说明
缓存时长	3 小时 (10800 秒)	可在 config.php 中修改
过期检测	每次请求	访问时即时检测
批量清理	1/100 概率	>50 条过期时触发

🛡️ 防止重复

插入新缓存前自动删除旧缓存
定期检查并清理重复条目
维护工具提供手动清理重复功能

📊 性能优化

即时清理：单条过期记录立即删除，无需批量扫描
批量备份：后台定期清理大量过期数据
索引优化：UUID、名称、过期时间都有索引
命中率统计：完整的缓存命中率跟踪

最佳实践：

优先使用 UUID 查询（更稳定，玩家可能改名）
缓存命中时响应极快（< 10ms）
缓存未命中时从官方 API 获取（200-500ms）
过期刷新对用户完全透明

使用示例

JavaScript / Fetch API

                            // 获取玩家数据

async function getPlayerData(uuid) {

  try {

    const response = await fetch(`https://api.example.com/index.php?uuid=${uuid}`);

    const data = await response.json();

    if (data.success) {

      console.log('Player:', data.data.player.displayname);

      console.log('Stats:', data.data.player.stats);

      return data.data;

    } else {

      console.error('Error:', data.error);

    }

  } catch (error) {

    console.error('Request failed:', error);

  }

}

// 使用

getPlayerData('f7c77d999f154a66a87dc4a51ef30d19');

Python / requests

                            import requests

def get_player_data(uuid):

    url = f"https://api.example.com/index.php?uuid={uuid}"

    try:

        response = requests.get(url)

        data = response.json()

        if data['success']:

            player = data['data']['player']

            print(f"Player: {player['displayname']}")

            print(f"Network Level: {player.get('networkExp', 0)}")

            return data['data']

        else:

            print(f"Error: {data['error']}")

    except Exception as e:

        print(f"Request failed: {e}")

# 使用

get_player_data('f7c77d999f154a66a87dc4a51ef30d19')

PHP / cURL

                            <?php

function getPlayerData($uuid) {

    $url = "https://api.example.com/index.php?uuid=" . urlencode($uuid);

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    curl_close($ch);

    if ($httpCode === 200) {

        $data = json_decode($response, true);

        if ($data['success']) {

            return $data['data'];

        }

    }

    return null;

}

// 使用

$playerData = getPlayerData('f7c77d999f154a66a87dc4a51ef30d19');

if ($playerData) {

    echo $playerData['player']['displayname'];

}

?>

Bash / curl

                            #!/bin/bash

# 获取玩家数据

UUID="f7c77d999f154a66a87dc4a51ef30d19"

curl "https://api.example.com/index.php?uuid=$UUID" | jq .

# 管理员清理缓存

curl -u admin:password "https://api.example.com/cleanup.php?force=1" | jq .

# 查看统计

curl "https://api.example.com/stats.php" | jq '.data.today_stats'

故障排除

❌ 常见问题

1. "No valid Hypixel API keys available"

原因：没有可用的有效 API 密钥

解决方案：

访问 /hypixel-keys.php 添加新的 API 密钥
检查现有密钥是否有效
确保密钥来自 Hypixel 开发者面板

2. "Connection failed: ..."

原因：数据库连接失败

解决方案：

检查 config.php 中的数据库配置
确认 MySQL 服务正在运行
验证数据库用户权限
测试数据库连接：mysql -u username -p database

3. "Class 'XXX' not found"

原因：PHP 类加载错误

解决方案：

检查文件权限：chmod -R 755 /path/to/hypixelmirro
确认所有源文件都存在于 src/ 目录
检查 PHP include_path 配置

4. 缓存未清理

原因：过期数据未被删除

解决方案：

手动强制清理：/cleanup.php?force=1
使用维护工具：/maintenance.php?action=full_maintenance
检查服务器时区设置是否正确

5. 401 Unauthorized

原因：访问管理功能需要认证

解决方案：

确认使用了正确的管理员账户
检查 config.php 中的 admin 配置
使用 curl -u username:password 格式

🔍 调试技巧

查看 PHP 错误日志

                            # Ubuntu/Debian

tail -f /var/log/php7.4-fpm.log

# 或 Nginx 错误日志

tail -f /var/log/nginx/error.log

测试数据库连接

mysql -u your_username -p api -e "SELECT COUNT(*) FROM player_cache;"

检查 PHP 扩展

php -m | grep -E "pdo|curl|json"

测试类加载

curl "https://api.example.com/test.php"

📧 获取帮助

如果以上方法无法解决您的问题：

📝 在 GitHub 提交 Issue（包含错误日志）
💬 加入社区讨论
📧 联系技术支持

提示： 提交问题时，请包含：PHP 版本、MySQL 版本、错误日志、复现步骤。

项目概述

核心特性

智能缓存

多密钥管理

完整统计

管理工具

系统要求

搭建教程

1 下载项目

2 配置数据库

3 配置文件

4 配置 Web 服务器

5 运行初始化

6 添加 API 密钥

方式一：使用 GET 请求（推荐）

方式二：使用 POST 请求

验证密钥已添加

API 文档

GET 获取玩家数据

请求 URL

请求参数

响应示例

错误响应

使用示例

GET 获取统计信息

请求 URL

响应示例

使用示例

错误代码

管理功能

GET 初始化脚本 需要认证

请求 URL

功能说明

响应示例

使用示例

GET POST 密钥管理 需要认证

1️⃣ 查看所有密钥

响应示例：

使用示例：

2️⃣ 添加新密钥（方式一：GET）

使用示例：

成功响应：

3️⃣ 添加新密钥（方式二：POST）

使用示例：

📋 密钥信息字段说明

❌ 错误响应

GET 缓存管理 需要认证

缓存统计

快速清理

响应示例

使用示例

GET 维护工具 需要认证

请求 URL

支持的操作

使用示例

状态响应示例

缓存策略

工作原理

🔄 缓存流程

⏱️ 时间设置

🛡️ 防止重复

📊 性能优化

使用示例

JavaScript / Fetch API

Python / requests

PHP / cURL

Bash / curl

故障排除

❌ 常见问题

1. "No valid Hypixel API keys available"

2. "Connection failed: ..."

3. "Class 'XXX' not found"

4. 缓存未清理

5. 401 Unauthorized

🔍 调试技巧

查看 PHP 错误日志

测试数据库连接

检查 PHP 扩展

测试类加载

GET 初始化脚本需要认证

GET POST 密钥管理需要认证

GET 缓存管理需要认证

GET 维护工具需要认证