? 概述
IPViewer 是一个插件,提供了一种查看玩家 IP 地址的简单方法,有助于服务器管理以及检测封禁规避或多开行为。
注意: 此处描述的所有技术设置和功能均针对该插件的最新版本,可能无法与旧版本完全兼容。
? 功能
- 查看自安装插件以来加入服务器的所有玩家,包括其 IP 地址和最后在线时间
- 轻松筛选和搜索玩家 IP
- 检测多个账号共享同一 IP 的情况
- 帮助追踪封禁规避和可疑活动
? 命令
以下是该插件中可用的所有命令:
/ipv help - 此命令允许你显示所有可能的插件命令
/ipv reload - 此命令允许你重载插件配置
/ipv script generate - 恢复内置的默认脚本,覆盖 plugins/IPViewer/scripts/default.js。这不会更改已选定的脚本
/ipv script set <file> - 选择一个现有的脚本,例如 /ipv script set custom.js,并将其文件名保存到 script_geo_location 中。文件名必须以 .js 结尾;不接受路径
/ipv list [filters] - 此命令允许你浏览玩家列表,并可选择应用过滤器
? /ipv list 的过滤器
/ipv list 命令支持灵活的过滤器,帮助你搜索和组织玩家 IP 数据。所有过滤器都可以在单个命令中组合使用。
| 过滤器 |
描述 |
page:<number> 或仅 <number> |
显示特定结果页(例如,/ipv list 2 或 /ipv list page:2) |
player:<text> |
按玩家名称过滤结果(支持部分匹配和通配符) |
ip:<text> |
按 IP 地址过滤(支持部分匹配和通配符) |
country:<text> |
按国家名称或代码过滤(例如,country:"United States") |
state:<text> |
按地区或州过滤(用于更细粒度的 IP 地理位置信息,例如,state:"New York") |
time:<duration> |
仅显示在指定时间范围内出现的玩家(例如,time:24h, time:30m) |
? 通配符
使用文本的过滤器(player、ip、country、state)支持 SQL 风格的通配符:
你也可以在过滤器值中使用空格:
- 将空格替换为
+ - country:United+States
- 用引号包裹值 -
state:"New York"
当使用引号时,+ 字符将按原样保留。
? 示例
/ipv list player:stev% ip:192.168.% time:7d page:3
此命令显示名字以 stev 开头、IP 以 192.168. 开头且在最近 7 天 内出现过的玩家的第 3 页结果。
? 配置
配置文件会在首次启动时生成,你可以修改它以调整输出格式或其他插件设置。查看默认配置文件在此处。
配置文件中的所有消息均使用 MiniMessage 格式,支持丰富的文本格式化(颜色、渐变、粗体等)。你可以使用 MiniMessage Viewer 预览和创建格式化消息。
script_geo_location 用于选择用于解析玩家地理位置的 JavaScript 文件:
script_geo_location: 'default.js'
文件名将在 plugins/IPViewer/scripts/ 目录内解析。请使用诸如 custom.js 这样的名称,以拉丁字母、数字、下划线或连字符开头;其余字符也可包含点号。不接受目录路径和其他扩展名。执行 /ipv script set custom.js 会立即保存选择。如果你手动编辑配置文件,请使用 /ipv reload 来应用更改。
? 自定义地理位置脚本
脚本系统允许管理员选择如何获取玩家地理位置:使用其他提供商、通过请求头提供 API 密钥,或在无需重建插件的情况下转换提供商的响应。
在启动时,IPViewer 会检查 plugins/IPViewer/scripts/default.js 是否存在,如果缺失则复制内置的默认脚本。现有文件保持不变,包括空文件。执行 /ipv script generate 会将此默认文件显式替换为内置版本;它不会重置 script_geo_location。
每次玩家加入时,插件会读取所选脚本,并在异步调度器上通过 GraalJS 运行 getGeoLocation(ip)。对脚本的更改将在下次玩家加入时生效,无需重载。该函数必须同步返回一个包含字符串字段 country 和 state 的对象;接受包含这些字段的 JSON 字符串。IPViewer 使用 Gson 解析结果,并据此创建或更新玩家的档案。若出现脚本、HTTP 或结果格式错误,则会记录日志,且此次查询不会更新档案。
返回的 JSON 必须具备以下结构(两个字段均为必填项,且必须为字符串类型):
{
"country": "United States",
"state": "California"
}
返回等效的 JavaScript 对象,或使用 JSON.stringify({country: "United States", state: "California"}) 返回 JSON 字符串。
嵌入式 GraalJS 提供了诸如 JSON.parse 和 JSON.stringify 等 JavaScript 语言特性,但不包含浏览器或 Node.js 的网络 API。IPViewer 提供了 httpGet(url, headers?),因此脚本无需使用 Java 类:
function getGeoLocation(ip) {
const url = `https://ipwho.is/${encodeURIComponent(ip)}?fields=success,message,country,region`
const data = JSON.parse(httpGet(url, {Accept: "application/json"}))
if (data.success !== true)
throw new Error("GeoIP service error: " + (data.message || "Unknown error"))
if (typeof data.country !== "string" || typeof data.region !== "string")
throw new Error("GeoIP service returned invalid country or region")
return {
country: data.country,
state: data.region
}
}
httpGet 执行同步 HTTP/HTTPS GET 请求,并将响应体作为 UTF-8 文本返回。可选的对象参数用于提供字符串类型的请求头,例如 {Authorization: "Bearer YOUR_API_KEY"}。连接和请求超时时间为五秒;网络故障和非 2xx 响应将抛出错误。请使用普通函数;不支持 async 函数和 Promise 结果。禁止直接访问 Java 类。
要添加提供商,请创建类似 plugins/IPViewer/scripts/custom.js 的文件,实现针对该提供商的响应映射 getGeoLocation(ip),并通过 /ipv script set custom.js 进行选择。Tab 补全功能会列出可用的 .js 文件。默认提供商使用 HTTPS;有关其当前免费层限制,请参阅 提供商文档。
⚙️ 开发者或管理员设置
插件拥有以下权限:
| 权限 |
含义 |
默认访问 |
ipviewer.update_listener |
接收更新 notifications 的权限 |
op |
ipviewer.use |
使用命令的权限 |
op |
ipviewer.help |
使用命令 help 的权限 |
op |
ipviewer.reload |
使用命令 reload 的权限 |
op |
ipviewer.script |
使用命令 script 的权限 |
op |
ipviewer.list |
使用命令 list 的权限 |
op |
❗ 问题报告
如果您发现任何错误,请在此处 提交消息 或在 Discord 上留言。
? 社交媒体
? 指标
? Overview
IPViewer is a plugin that provides a simple way to view players' IP addresses, helping with server management and detecting ban evasion or multi-accounts.
Note: All technical settings and features described here are intended for the latest version of the plugin and may not be fully compatible with older versions.
? Features
- View all players who have joined the server since the plugin was installed, along with their IP addresses and last seen time
- Filter and search player IPs easily
- Detect shared IPs across multiple accounts
- Helps track down ban evasion and suspicious activity
? Commands
Here are all the commands that can be used in the plugin:
/ipv help - This command allows you to display all possible plugin commands
/ipv reload - This command allows you to reload the plugin config
/ipv script generate - Restore the bundled default script, overwriting plugins/IPViewer/scripts/default.js. This does not change the selected script
/ipv script set <file> - Select an existing script, such as /ipv script set custom.js, and save its filename to script_geo_location. The filename must end in .js; paths are not accepted
/ipv list [filters] - This command allows you to browse the list of players with optional filters
? Filters for /ipv list
The /ipv list command supports flexible filters to help you search and organize player IP data. All filters can be used together in a single command.
| Filter |
Description |
page:<number> or just <number> |
Displays a specific results page (e.g., /ipv list 2 or /ipv list page:2) |
player:<text> |
Filters results by player name (supports partial matches and wildcards) |
ip:<text> |
Filters by IP address (supports partial matches and wildcards) |
country:<text> |
Filters by country name or code (e.g., country:"United States") |
state:<text> |
Filters by region or state (useful for more granular IP geolocation, e.g., state:"New York") |
time:<duration> |
Shows only players seen within a time range (e.g., time:24h, time:30m) |
? Wildcards
Filters that use text (player, ip, country, state) support SQL-style wildcards:
% - Matches any sequence of characters
_ - Matches a single character
You can also use spaces in filter values:
- Replace spaces with
+ - country:United+States
- Wrap the value in quotes -
state:"New York"
When quotes are used, + characters are preserved as written.
? Example
/ipv list player:stev% ip:192.168.% time:7d page:3
This command shows page 3 of players whose names start with stev, IP starts with 192.168., and who have been seen in the last 7 days.
? Configuration
The config file is generated on first launch and modify it to adjust output formats or other plugin settings. View default config here.
All messages in the config use the MiniMessage format, which allows rich text formatting (colors, gradients, bold, etc.). You can preview and create formatted messages using the MiniMessage Viewer.
script_geo_location selects the JavaScript file used to resolve player geolocation:
script_geo_location: 'default.js'
The filename is resolved inside plugins/IPViewer/scripts/. Use a name such as custom.js, starting with a Latin letter, digit, underscore or hyphen; the remaining characters may also include dots. Directory paths and other extensions are not accepted. /ipv script set custom.js saves the selection immediately. If you edit the config manually, use /ipv reload to apply it.
? Custom geolocation scripts
The scripting system lets administrators choose how player geolocation is obtained: use another provider, supply an API key through request headers, or transform the provider's response without rebuilding the plugin.
On startup, IPViewer checks whether plugins/IPViewer/scripts/default.js exists and copies the bundled default if it is missing. Existing files are left untouched, including empty files. /ipv script generate explicitly replaces this default file with the bundled version; it does not reset script_geo_location.
For each player join, the plugin reads the selected script and runs getGeoLocation(ip) through GraalJS on its asynchronous scheduler. Changes to a script apply on the next join, without a reload. The function must synchronously return an object with string fields country and state; a JSON string containing those fields is also accepted. IPViewer parses the result with Gson and uses it to create or update the player's profile. Script, HTTP or result-format errors are logged, and that lookup does not update the profile.
The returned JSON must have this structure (both fields are required and must contain strings):
{
"country": "United States",
"state": "California"
}
Return the equivalent JavaScript object, or use JSON.stringify({country: "United States", state: "California"}) to return a JSON string.
Embedded GraalJS provides JavaScript language features such as JSON.parse and JSON.stringify, but does not include browser or Node.js networking APIs. IPViewer supplies httpGet(url, headers?), so scripts do not need Java classes:
function getGeoLocation(ip) {
const url = `https://ipwho.is/${encodeURIComponent(ip)}?fields=success,message,country,region`
const data = JSON.parse(httpGet(url, {Accept: "application/json"}))
if (data.success !== true)
throw new Error("GeoIP service error: " + (data.message || "Unknown error"))
if (typeof data.country !== "string" || typeof data.region !== "string")
throw new Error("GeoIP service returned invalid country or region")
return {
country: data.country,
state: data.region
}
}
httpGet performs a synchronous HTTP/HTTPS GET and returns the response body as UTF-8 text. An optional object supplies string-valued headers, for example {Authorization: "Bearer YOUR_API_KEY"}. The connection and request timeouts are five seconds; network failures and non-2xx responses throw an error. Use ordinary functions; async functions and Promise results are not supported. Direct Java class access is disabled.
To add a provider, create a file such as plugins/IPViewer/scripts/custom.js, implement getGeoLocation(ip) with the response mapping for that provider, and select it with /ipv script set custom.js. Tab completion lists available .js files. The default provider uses HTTPS; consult the provider documentation for its current free-tier limits.
⚙️ Settings for developers or administrators
The plugin has permissions:
| Permissions |
Meaning |
Default access |
ipviewer.update_listener |
Permission to receive update notifications |
op |
ipviewer.use |
Permission to use commands |
op |
ipviewer.help |
Permission to use command help |
op |
ipviewer.reload |
Permission to use command reload |
op |
ipviewer.script |
Permission to use command script |
op |
ipviewer.list |
Permission to use command list |
op |
❗ Issues
Please leave messages about any errors you find here or on the Discord
? Social Media
? Metrics
评论 0
登录后参与评分
还没有评论,来抢沙发吧