安装与配置

环境要求

组件	要求
Minecraft	Folia / Paper 1.20+（构建目标 1.21.10），兼容 Spigot 系列
Java	21+（与服务器内核一致）
必备插件	ProtocolLib
硬件	≥8 GB 可用内存、SSD 储存；HeavyMode/AI 建议额外预留 2C4G

若准备启用 HeavyMode、深度学习或大规模假矿，请确保 CPU 有足够线程，避免与主线程争用。

部署步骤

1. 获取授权：在 https://shop.nekosoft.cn 购买 前往https://i.nekosoft.cn/login 绑定卡密并获取 api-key。
2. 下载 Jar：
   • 下载：从官方QQ 群文件下载最新Jar。
3. 上传文件：将 Jar（与可能存在的 libs/ 目录）放入服务器 plugins/。
4. 首次启动：重启服务器生成 plugins/NekoAntiXray/config.yml、logs/、replay/ 等目录。
5. 写入密钥与基础配置：打开 config.yml 填入 api-key，根据服务器定位配置检测模式、世界名单、处罚命令。
6. 重启或冷重载：保存配置后推荐完整重启，防止射线线程与假矿缓存残留；不建议使用热加载！！！！
7. 健康检查：使用 /nax status、/nax secureseed status、/nax announcement stats 等命令确认模块正常。

快速上手流程

1. 准备 API Key：缺失密钥会导致插件不可用。
2. 选择检测模式：
   • 轻量钓鱼：关闭 check.AlgoAntiXray.enable，保留 check.xray。
   • 行为分析：开启 check.AlgoAntiXray 并关闭默认检测避免重复处罚。
3. 配置世界范围：在 check.AlgoAntiXray.worlds、blacklist.worlds、antiBrightness.enabledWorlds 中列出检测/豁免世界。
4. 布置权限：为巡查组授予 nekoantixray.alerts、nekoantixray.oretrack、nekoantixray.replay、nekoantixray.cleanup 等节点；普通玩家保持默认。
5. 监控运行：使用 /nax orestats <player>、/nax replay <player>、/nax announcement、/nax togglemassexcavation status 等命令观察检测效果。
6. 启用 AI（可选）：将 model.onnx 与 feature_stats.json 放入插件目录，设置 deeplearn.enable=true 并按照训练参数填写 sequence_length、prediction_threshold 等字段。

配置文件核心字段

API 密钥

api-key: ""  # 必填，请妥善保管

检测模式切换

check:
	xray:
		enable: true             # 钓鱼假矿检测
	AlgoAntiXray:
		enable: false            # 行为模式检测
	heavy-mode:
		enable: true             # HeavyMode 射线追踪

按照服务器类别选择：

• 轻量巡查：默认配置即可。
• 行为分析：启用check.AlgoAntiXray。
• 大型/生电：HeavyMode或者默认模式+大规模挖掘检测。

算法模式（AlgoAntiXray）

check:
	AlgoAntiXray:
		enable: true
		warning-vl: 50
		kick-vl: 80
		enable-ban: true
		ban-vl: 120
		ban-command: 'ban %player% 使用X-Ray外挂 (VL: %vl%)'
		max_path_length: 600

可结合以下子参数细调：

path-detection:
	smooth-path:
		base-turn-threshold: 8
		path-size-divisor-for-turn: 35
fishbone-detection:
	max-y-changes-strict: 4
decay:
	use_factor: true
	factor: 0.9

传统模式（check.xray）

check:
	xray:
		enable: true
		same-chunk-detection: true
		line-break:
			length: 3
		spawn:
			ore: 30
			time: 100
			distance-limit:
				ore: 12
				player: 12
			amount: { min: 5, max: 7 }
		vl:
			ban:
				enable: true
				threshold: 10.0
				command: 'nax ban %player% &c疑似X-Ray (VL: %vl%)'

HeavyMode 关键配置

world-settings:
	default:
		enabled: true
		anti-xray:
			ray-trace-third-person: true
			ray-trace-distance: 80.0
			rehide-blocks: true
			max-ray-trace-block-count-per-chunk: 100
		ray-trace-threads: 4

Mass Excavation 与深度学习

mass-excavation:
	enabled: true
	detection-time-window: 60
	block-count-threshold: 80
	min-volume-threshold: 500

deeplearn:
	enable: true
	sequence_length: 50
	prediction_threshold: 0.5
	cooldown_ms: 5000
	violations:
		enable-punishment: true
		vl-multiplier: 10.0

种子保护

fake-seed:
	enable-fake-seed: true
	show-real-seed-to-op: false

antiSeedCracker:
	enable: true
	modifyEndStructures:
		enable: true
		worlds:
			- world_the_end

故障排查入口

• 控制台出现 [NekoAntiXray] 插件已启用！ 视为初始化成功；若缺少 ProtocolLib 或 API Key，会在此阶段直接报错。
• /nax reload 报错时优先检查 config.yml 缩进与 api-key；必要时使用 yamllint 验证。
• 启用 fake seed 后玩家仍得到真实种子，请确认其是否拥有 fakeseed.viewreal / nekoantixray.realseed 权限，或是否有其他 /seed 插件抢占指令。
• 若深度学习模块无输出，检查 deeplearn.enable、model.onnx、feature_stats.json 及 cooldown_ms 设置。

在 Velocity/Bungee 拓扑下无需额外转发，只需保证下游 Paper/Folia 服务器部署插件且可连通授权服务器即可。