ClientPolicy
ClientPolicy 用于识别主动宣告自身存在的客户端模组,将其与你定义的策略配置文件进行比对,并执行 LOG(记录日志)→ WARN(警告)→ KICK(踢出玩家) 的阶梯式处理。玩家可以通过 /clientpolicy rules 查看规则,确保没有人会在不知情的情况下被踢出服务器。
无需安装任何客户端模组。Vanilla(原版)、Fabric、Forge 和 NeoForge 客户端均可正常工作。
⚠️ 首先阅读:ClientPolicy 不是什么
ClientPolicy 不是反作弊系统。
其检测机制基于客户端主动提供的三项信息:
- 它注册的插件消息通道(plugin messaging channels),
- 它的
minecraft:brand 字符串,
- 是否存在模组加载器握手信号。
一个从不与服务器通信的模组对此方法是不可见的。X-ray(透视)、killaura(杀戮光环)、reach(超距攻击)、freecam(自由视角)、auto-clickers(自动点击器)等作弊行为不会注册任何通道,因此无法在此处被检测到。
ClientPolicy 确实 能可靠地看到以下模组:Litematica、Xaero's Minimap/World Map、JourneyMap、VoxelMap、WorldEditCUI、Baritone、ReplayMod、Distant Horizons、Simple Voice Chat、Vivecraft、LabyMod、Lunar Client,以及你教会它的任何其他模组。
出于故意,这一限制在 config.yml、/clientpolicy check 和 /clientpolicy rules 中均有重复说明。一种让管理员误以为具备反作弊能力的策略工具,比完全没有工具更糟糕。
✨ 功能特性
- ? 指纹引擎 — 从登录时刻开始缓冲通道注册信息,因此即使在
PlayerJoinEvent(玩家加入事件)之前到达的记录也不会丢失。品牌标识和模组加载器握手信号会与之同步读取。
- ? 签名数据库 —
signatures.yml 将模组 ID 映射到通道模式(支持通配符,例如 litematica:*)、品牌正则表达式以及类别(MINIMAP 小地图、SCHEMATIC 蓝图、AUTOMATION 自动化、PERFORMANCE 性能优化、UTILITY 实用工具)。
- ?️ 策略配置文件 —
BLOCKLIST(黑名单,仅 deny 列表中的 ID 视为违规)或 ALLOWLIST(白名单,不在 allow 列表中的内容均视为违规)。玩家通过 clientpolicy.profile.<name> 解析到相应的配置文件,若未指定则回退至 default-profile(默认配置)。
- ? 分级执行 — 每个配置文件拥有独立的阶梯策略:首次命中触发
WARN,后续命中触发 KICK,并配有可配置的升级阈值和计数器重置窗口。clientpolicy.bypass 权限可在仍记录检测信息的同时豁免玩家。
- ⏱️ 延迟与重复扫描 — 首次评估在加入后
scan-delay-ticks 个刻钟运行,此后每新注册一个通道都会为 rescan-window-seconds 秒内的该玩家触发另一次评估。迟注册并不能规避执行。
- ? 玩家透明度 —
/clientpolicy rules 会向玩家展示其所属配置文件中允许和禁止的模组列表,并按类别分组。踢出消息会指明违规模组并指引玩家查阅规则。
- ? 发现模式 —
/clientpolicy inspect <player> 会打印原始通道、品牌、已匹配的签名以及未匹配任何签名的通道,以便你编写自己的签名规则。
- ?️ 审计追踪 — 每次检测和采取的行动都会写入 SQLite 数据库,并通过
/clientpolicy history <player> 读取,包括服务器本地缓存中的离线玩家记录。
- ? 未知通道策略 — 未匹配任何签名的通道会有独立的操作(默认为仅记录日志),这可以防止
ALLOWLIST(白名单)配置文件因无害的基础通信管道而踢出玩家。
明确超出范围的功能: 行为型作弊检测、客户端配套模组、资源包强制实施、模组文件哈希验证、Web 面板、MySQL 支持。
✅ 第一步:验证你的签名
通道名称会随 Minecraft 版本和模组更新而变化。随附的 signatures.yml 只是一个起始集合,并非绝对真理。请确认你所关心的每一项条目:
- 在自己的客户端上安装模组并加入服务器。
- 运行
/clientpolicy inspect <yourname> 并阅读 Unrecognised channels(未识别通道)部分。
- 将这些通道复制到
signatures.yml 的相应条目中。
- 运行
/clientpolicy reload。
在将任何配置文件切换为 ALLOWLIST(白名单)模式之前,请务必完成此操作。在白名单模式下,未经核实的签名列表意味着你会因为从未教过插件的通道而踢出玩家。
/clientpolicy check 提供的是仅限当前玩家自身的视图,且对所有人开放是安全的——正是这一点使得政策能够由其适用对象进行审计。
? 命令
根命令 /clientpolicy,别名 /cp。
| 命令 |
描述 |
权限节点 |
/clientpolicy rules |
显示你自己配置文件中允许/禁止的模组列表,按类别分组 |
clientpolicy.rules (所有人) |
/clientpolicy check |
显示服务器当前在你客户端上看到的内容 |
clientpolicy.check (所有人) |
/clientpolicy inspect <player> |
原始通道、品牌、已匹配签名、扫描状态 |
clientpolicy.admin (OP) |
/clientpolicy history <player> [limit] |
过去的检测记录和采取行动(默认 10,最大 100) |
clientpolicy.admin |
/clientpolicy profile <player> |
玩家解析到了哪个配置文件及其原因 |
clientpolicy.admin |
/clientpolicy rescan <player> |
立即重新应用策略,包括阶梯升级 |
clientpolicy.admin |
/clientpolicy reload |
重载 config.yml 和 signatures.yml |
clientpolicy.admin |
权限节点
| 节点 |
默认值 |
含义 |
clientpolicy.rules |
everyone |
使用 /clientpolicy rules |
clientpolicy.check |
everyone |
使用 /clientpolicy check |
clientpolicy.admin |
op |
检查、历史记录、配置文件、重扫、重载 |
clientpolicy.bypass |
nobody |
豁免所有行动。检测信息仍会被记录,工作人员仍会收到通知。 |
clientpolicy.notify |
op |
在每次违规时接收聊天通知 |
clientpolicy.profile.<name> |
nobody |
将玩家绑定到 <name> 配置文件 |
通过权限插件分配 clientpolicy.profile.<name>,并为每位玩家或组分配恰好一个权限——如果一名玩家持有多个配置文件权限,则取最先找到的那个生效。
⚙️ 配置
detection:
scan-delay-ticks: 60 # 首次评估,加入服务器后 60 tick = 3s
rescan-window-seconds: 120 # 新通道在此时长内重新触发评估
track-brand: true
brand-unknown-action: LOG # ALLOW | LOG | WARN | KICK,在窗口结束时应用
policy:
default-profile: default
unknown-channel-action: LOG # 保持宽松;这是白名单的安全阀
ignore-channels: # 从不进行评估,支持 * 和 ?
- "minecraft:*"
- "bungeecord:*"
- "fabric:registry_sync"
enforcement:
kick-message: |
<red>检测到本服务器不允许的模组:<white><mod>
<gray>允许的模组:查看 <aqua>/clientpolicy rules
warn-message: "<gold>[!] <yellow><mod> <gray>在此不被允许。下次你将被踢出。"
notify-staff: true
notify-format: "<gray>[CP] <white><player> <gray>-> <red><mod> <dark_gray>(<action>)"
profiles:
default:
mode: BLOCKLIST # ALLOWLIST | BLOCKLIST
allow: [litematica, sodium, iris, worldeditcui, replaymod]
deny: [xaeros-minimap, journeymap, voxelmap, baritone]
ladder:
first: WARN
after: KICK
escalate-after: 2 # 第 1-2 次警告,第 3 次起踢出
counter-reset-hours: 24
builder: # clientpolicy.profile.builder
mode: BLOCKLIST
allow: [litematica, worldeditcui, sodium, iris, xaeros-minimap]
deny: [baritone]
ladder:
first: LOG
after: WARN
escalate-after: 3
counter-reset-hours: 24
storage:
retention-days: 30 # 旧记录将在启动时被清理
messages:
prefix: "<dark_gray>[<aqua>ClientPolicy<dark_gray>] "
所有消息均使用 MiniMessage 格式。kick-message、warn-message 和 notify-format 中的占位符包括:<player>、<mod>、<mod_id>、<channels>、<category>、<profile>、<reason>、<action>、<count> —— 其中 <reason> 为以下值之一:DENIED、NOT_ALLOWED、UNKNOWN_CHANNEL、UNKNOWN_BRAND。
仅 WARN 和 KICK 会广播至 clientpolicy.notify。LOG 类型的检测仅记录到控制台并可通过 /clientpolicy history 查看 —— 一个单一的模组客户端很容易暴露十几个未编入目录的通道,若全部广播将使该权限功能不可用。
通道一旦注册便不会被遗忘:即使客户端注册后立即注销,也已暴露了模组信息。
? 安装
- 将
ClientPolicy-<version>.jar 放入 plugins/ 目录。
- 启动服务器。
config.yml、signatures.yml 和 data.db 将在 plugins/ClientPolicy/ 中创建。
- 在你信任它们之前验证签名 —— 见上文章节。
- 编辑
config.yml 中的配置档案,然后运行 /clientpolicy reload。
|
|
| 服务器 |
Paper 1.21 – 1.21.11(整个版本线共用一个 jar;无 NMS,无反射) |
| Java |
21 |
| 依赖项 |
org.xerial:sqlite-jdbc,由 Paper 的库加载器在运行时下载 |
如果你的服务器无法访问 Maven Central,SQLite 驱动程序将无法加载。检测和强制执行功能仍可正常工作;仅 /clientpolicy history 和跨会话违规计数器被禁用,并在启动时打印警告。
? 源码
源代码与问题追踪器:CyberSoldier112/clientpolicy
ClientPolicy
ClientPolicy identifies the client mods that announce themselves to your server, compares them against a policy profile you define, and applies a LOG → WARN → KICK ladder. Players can read the rules with /clientpolicy rules, so nobody gets kicked by a rule they were never shown.
No client-side mod is required. Vanilla, Fabric, Forge and NeoForge clients all work.
⚠️ Read this first: what ClientPolicy is not
ClientPolicy is not an anti-cheat.
Detection works by looking at three things the client volunteers:
- the plugin messaging channels it registers,
- its
minecraft:brand string,
- the presence of a mod loader handshake.
A mod that never talks to the server is invisible to this method. X-ray, killaura, reach, freecam, auto-clickers and similar cheats register no channels and cannot be detected here.
What ClientPolicy does see reliably: Litematica, Xaero's Minimap/World Map, JourneyMap, VoxelMap, WorldEditCUI, Baritone, ReplayMod, Distant Horizons, Simple Voice Chat, Vivecraft, LabyMod, Lunar Client, and anything else you teach it.
This limit is repeated in config.yml, in /clientpolicy check and in /clientpolicy rules, on purpose. A policy tool that lets admins believe they have cheat detection is worse than no tool at all.
✨ Features
- ? Fingerprint engine — channel registrations are buffered from the login moment, so records arriving before
PlayerJoinEvent are never lost. Brand and mod loader handshake are read alongside them.
- ? Signature database —
signatures.yml maps a mod id to channel patterns (wildcards supported, e.g. litematica:*), a brand regex and a category (MINIMAP, SCHEMATIC, AUTOMATION, PERFORMANCE, UTILITY).
- ?️ Policy profiles —
BLOCKLIST (only ids in deny are violations) or ALLOWLIST (anything not in allow is a violation). Players resolve to a profile through clientpolicy.profile.<name>, falling back to default-profile.
- ? Tiered enforcement — a per-profile ladder: first hits
WARN, later hits KICK, with a configurable escalation threshold and counter reset window. clientpolicy.bypass exempts a player while still recording the detection.
- ⏱️ Delayed and repeated scanning — the first evaluation runs
scan-delay-ticks after join, then every newly registered channel triggers another evaluation for rescan-window-seconds. Registering late does not dodge enforcement.
- ? Player transparency —
/clientpolicy rules shows a player the allowed and denied list of their own profile, grouped by category. Kick messages name the offending mod and point back at the rules.
- ? Discovery mode —
/clientpolicy inspect <player> prints raw channels, brand, matched signatures and the channels that matched nothing, so you can write your own signatures.
- ?️ Audit trail — every detection and action is written to SQLite and read back with
/clientpolicy history <player>, including offline players in the server's local cache.
- ? Unknown-channel policy — channels matching no signature get their own action (default: log only), which keeps
ALLOWLIST profiles from kicking people over harmless plumbing.
Deliberately out of scope: behavioural cheat detection, a client companion mod, resource pack enforcement, mod file hash verification, a web panel, MySQL.
✅ Step one: verify your signatures
Channel names change between Minecraft versions and mod releases. The shipped signatures.yml is a starting set, not ground truth. Confirm every entry you care about:
- Join with the mod installed on your own client.
- Run
/clientpolicy inspect <yourname> and read the Unrecognised channels section.
- Copy those channels into a
signatures.yml entry.
/clientpolicy reload.
Do this before switching any profile to ALLOWLIST. In allowlist mode, an unverified signature list means kicking players for channels you simply never taught the plugin about.
/clientpolicy check is the same view limited to a player's own client, and is safe to leave available to everyone — it is what makes the policy auditable by the people it applies to.
? Commands
Root command /clientpolicy, alias /cp.
| Command |
Description |
Permission |
/clientpolicy rules |
The allowed/denied mod list of your profile, grouped by category |
clientpolicy.rules (everyone) |
/clientpolicy check |
What the server currently sees on your own client |
clientpolicy.check (everyone) |
/clientpolicy inspect <player> |
Raw channels, brand, matched signatures, scan state |
clientpolicy.admin (op) |
/clientpolicy history <player> [limit] |
Past detections and actions (default 10, max 100) |
clientpolicy.admin |
/clientpolicy profile <player> |
Which profile a player resolved to, and why |
clientpolicy.admin |
/clientpolicy rescan <player> |
Re-apply the policy immediately, ladder included |
clientpolicy.admin |
/clientpolicy reload |
Reload config.yml and signatures.yml |
clientpolicy.admin |
Permissions
| Node |
Default |
Meaning |
clientpolicy.rules |
everyone |
Use /clientpolicy rules |
clientpolicy.check |
everyone |
Use /clientpolicy check |
clientpolicy.admin |
op |
inspect, history, profile, rescan, reload |
clientpolicy.bypass |
nobody |
Exempt from every action. Detections are still recorded and staff are still notified. |
clientpolicy.notify |
op |
Receive a chat notification on every violation |
clientpolicy.profile.<name> |
nobody |
Bind a player to the profile <name> |
Assign clientpolicy.profile.<name> through a permissions plugin, and give exactly one per player or group — a player holding two profile permissions gets whichever is found first.
⚙️ Configuration
detection:
scan-delay-ticks: 60 # first evaluation, 60 ticks = 3s after join
rescan-window-seconds: 120 # new channels re-trigger evaluation for this long
track-brand: true
brand-unknown-action: LOG # ALLOW | LOG | WARN | KICK, applied at window end
policy:
default-profile: default
unknown-channel-action: LOG # keep this soft; it is the allowlist safety valve
ignore-channels: # never evaluated, supports * and ?
- "minecraft:*"
- "bungeecord:*"
- "fabric:registry_sync"
enforcement:
kick-message: |
<red>A mod not permitted on this server was detected: <white><mod>
<gray>Allowed mods: <aqua>/clientpolicy rules
warn-message: "<gold>[!] <yellow><mod> <gray>is not permitted here. Next time you will be kicked."
notify-staff: true
notify-format: "<gray>[CP] <white><player> <gray>-> <red><mod> <dark_gray>(<action>)"
profiles:
default:
mode: BLOCKLIST # ALLOWLIST | BLOCKLIST
allow: [litematica, sodium, iris, worldeditcui, replaymod]
deny: [xaeros-minimap, journeymap, voxelmap, baritone]
ladder:
first: WARN
after: KICK
escalate-after: 2 # hits 1-2 WARN, hit 3 onwards KICK
counter-reset-hours: 24
builder: # clientpolicy.profile.builder
mode: BLOCKLIST
allow: [litematica, worldeditcui, sodium, iris, xaeros-minimap]
deny: [baritone]
ladder:
first: LOG
after: WARN
escalate-after: 3
counter-reset-hours: 24
storage:
retention-days: 30 # older records are pruned at startup
messages:
prefix: "<dark_gray>[<aqua>ClientPolicy<dark_gray>] "
All messages use MiniMessage. Placeholders in kick-message, warn-message and notify-format: <player>, <mod>, <mod_id>, <channels>, <category>, <profile>, <reason>, <action>, <count> — where <reason> is one of DENIED, NOT_ALLOWED, UNKNOWN_CHANNEL, UNKNOWN_BRAND.
Only WARN and KICK are broadcast to clientpolicy.notify. LOG detections go to the console and to /clientpolicy history only — a single modded client easily brings a dozen uncatalogued channels, and broadcasting those would make the permission unusable.
Channels are never forgotten once registered: a client that registers and immediately unregisters has still revealed the mod.
? Installation
- Drop
ClientPolicy-<version>.jar into plugins/.
- Start the server.
config.yml, signatures.yml and data.db are created in plugins/ClientPolicy/.
- Verify the signatures before you trust them — see the section above.
- Edit your profiles in
config.yml, then run /clientpolicy reload.
|
|
| Server |
Paper 1.21 – 1.21.11 (one jar for the whole line; no NMS, no reflection) |
| Java |
21 |
| Dependencies |
org.xerial:sqlite-jdbc, downloaded at runtime by Paper's library loader |
If your server cannot reach Maven Central, the SQLite driver will not load. Detection and enforcement still work normally; only /clientpolicy history and the cross-session violation counter are disabled, and a warning is printed at startup.
? Source
Source code and issue tracker: CyberSoldier112/clientpolicy
评论 0
登录后参与评分
还没有评论,来抢沙发吧