通过第三方 API 查询玩家 IP 归属地，并在玩家加入服务器时发送欢迎消息的 Spigot 1.8.8 插件。
包名：
org.lengmc.bettergeoip
仓库：https://github.com/LengMC/BetterGeoIP
- 🔍 查询玩家 / IP 的归属地（国家 / 省 / 市 / 区 / 运营商 / ASN / 经纬度）
- 👋 加入欢迎：可隐藏原版加入消息，广播自定义欢迎消息
- 🔄 多数据源：内置 4 个 API（IP.CN / 百度 / Ping00 / IP-API.com），可热切换
- 💾 缓存：IP 维度缓存，可配置过期时间（默认 60 分钟），重启后保留
- 🔁 重试：API 查询失败自动重试（默认 3 次）
- 🌐 异步：所有 HTTP 请求都在异步线程执行，不卡主线程
- 🎨 占位符：欢迎消息支持十余种变量（
{player}、{ip}、{location}等）
- 把
BetterGeoIP-1.0.jar放到服务器的plugins/目录 - 启动一次服务器，会自动生成
plugins/BetterGeoIP/config.yml - 根据需要修改
config.yml - 重启服务器或使用
/geoip reload重载
兼容 Spigot 1.8.8（理论上 1.8.x 都可以跑）。
api:
selected: "ip_api" # 当前使用的 API（可从 available_apis 中选）
retry_count: 3 # 查询失败重试次数
timeout_seconds: 10 # HTTP 超时
available_apis:
ip_cn: { name: "IP.CN", url: "...", enabled: true }
baidu: { name: "百度IP查询", url: "...", enabled: true }
ping00: { name: "Ping00", url: "...", enabled: true }
ip_api: { name: "IP-API.com", url: "...", enabled: true }
welcome:
enabled: true
hide_original_join_message: true
# 默认只显示玩家名 + 归属地，不暴露 IP 和运营商（隐私考虑）
message: "&a欢迎 &e{player} &a来自 &b{location}"
cache:
enabled: true
expire_minutes: 60| 占位符 | 含义 | 示例 |
|---|---|---|
{player} |
玩家名 | Steve |
{ip} |
IP 地址 | 1.2.3.4 |
{country} |
国家 | 中国 |
{region} |
省/地区 | 北京 |
{city} |
城市 | 北京 |
{district} |
区/县 | 海淀 |
{isp} |
运营商 | 电信 |
{asn} |
ASN | AS4134 |
{lat} |
纬度 | 39.9042 |
{lon} |
经度 | 116.4074 |
{location} |
国家·省·市·区 拼接 | 中国 · 北京 · 北京 |
{source} |
数据来源 | IP-API.com |
主命令 /geoip（简写 /bgi）
| 命令 | 权限 | 说明 |
|---|---|---|
/geoip me |
geoip.use |
查询自己的 IP 归属地 |
/geoip <player> |
geoip.admin |
查询其他玩家 |
/geoip ip <ip|player> |
geoip.admin |
查询任意 IP 或玩家 |
/geoip reload |
geoip.admin |
重载配置 |
/geoip api list |
geoip.use |
列出可用 API |
/geoip api info |
geoip.use |
查看当前 API 详情 |
/geoip api switch <name> |
geoip.admin |
切换 API |
/geoip cache clear |
geoip.admin |
清空 IP 缓存 |
/geoip cache status |
geoip.use |
查看缓存状态 |
/geoip status |
geoip.use |
插件状态总览 |
geoip.use— 基础命令（默认所有玩家）geoip.admin— 管理员命令（默认 OP）
| Key | 名称 | 速度 | 国内精度 | 国外精度 | 经纬度 | 备注 |
|---|---|---|---|---|---|---|
ip_api |
IP-API.com | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ✅ | 免费版限 45 req/min |
ip_cn |
IP.CN | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ❌ | 国内比较准 |
baidu |
百度 IP 查询 | ⭐⭐ | ⭐⭐ | ⭐ | ❌ | 无 Key 也能用 |
ping00 |
Ping00 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ✅ | 部分地区需付费 |
⚠️ 国内 API（IP.CN、百度、Ping00）在境外服务器访问可能不稳定，建议国外服务器用ip_api。
git clone https://github.com/LengMC/BetterGeoIP.git
cd BetterGeoIP
mvn clean package产物：target/BetterGeoIP-1.0.jar
依赖：JDK 8+、Maven 3.6+
src/main/java/org/lengmc/bettergeoip/
├─ BetterGeoIP.java # 插件主类
├─ ConfigManager.java # 配置加载 / API 选择
├─ CacheManager.java # IP 缓存（持久化）
├─ GeoInfo.java # 数据模型 + 占位符替换 + JSON 提取
├─ GeoIPManager.java # HTTP 调用 + 4 个 API 解析
├─ GeoIPCommand.java # /geoip 命令（含 Tab 补全）
└─ PlayerJoinListener.java # 加入事件 → 异步查询 → 欢迎广播
Q: 启动后控制台报 "API 测试失败"？
A: 服务器无法访问外部网络，或当前 API 被防火墙拦截。换一个 API 试试，或检查 api.timeout_seconds。
Q: 欢迎消息里的变量没有被替换？
A: 检查 config.yml 里是否用错了占位符（例如 {player} 写成了 {Player}），占位符区分大小写。
Q: 切换 API 后还需要重启服务器吗？
A: 不需要，/geoip api switch <name> 热切换，立刻生效。
Q: hide_original_join_message 不生效？
A: 确认 welcome.enabled 也是 true。原版加入消息在优先级最高的 handler 里被设为 null。
MIT License