跳到主要内容

运维排障

本页按“先确认插件是否正常启动，再确认具体功能”的顺序排查。

启动失败或红字报错​

先看控制台启动日志：

  1. 是否缺少硬依赖 NBTAPI。
  2. 是否有运行库下载失败，例如 Kotlin、Exposed、HikariCP 或数据库驱动。
  3. 是否有 database.yml 连接失败。
  4. 是否有 YAML 解析错误，通常是缩进、Tab、冒号或引号问题。

首次启动不要热加载。离线服务器请先在网络正常的同版本环境启动一次，复制服务端根目录下的 libraries 到正式服。

配置修改不生效​

确认修改的是实际运行目录：

服务端根目录/plugins/SakuraBind

保存后可执行：

/sakurabind reload
/sakurabind reload settings.yml

以下内容通常需要重启：

  • block-listener
  • block-cache-backup.enable 与 block-cache-backup.interval-minutes
  • entity-listener
  • send-back-database
  • modules/*.yml 中写明重启生效的模块总开关
  • 日志文件路径
  • 缓存大小

匹配器不生效​

先确认测试玩家是不是 OP。OP 默认拥有 sakurabind.bypass.all，会跳过点击、捡起、丢弃、使用、装备、扫描器等自动绑定监听。测试自动绑定时请用非 OP 账号，或在权限插件中把测试玩家的 sakurabind.bypass.all 设为 false。

手持目标物品执行：

/sakurabind test tryMatch <匹配器ID>

再按输出检查：

  • name 只匹配自定义名，不匹配原版翻译名。
  • name-without-color、lore-without-color 会去除颜色代码后匹配。
  • material 是正则；materials 是 Bukkit 材质名列表。
  • 正确键名是 materialIds，不是 materialId。
  • 多个 match 条件是同时满足。
  • 多个匹配器都能命中时，靠前的匹配器先生效。

查看手持物 NBT：

/sakurabind nbt

输出在控制台。

遗失物品找不回​

检查顺序：

  1. database.yml 是否连接成功。
  2. config.yml 是否 send-back-database: true。
  3. send-back-queue 是否至少保留 database。
  4. 玩家背包或末影箱是否已满。
  5. 是否安装了背包同步插件，玩家是否还在同步保护阶段。
  6. 控制台是否有数据库写入异常。

玩家领取：

/sakurabind getLost

管理员查看或编辑暂存箱：

/sakurabind openLost <玩家名或UUID> 1

方块或实体绑定无效​

方块绑定需要：

config.yml
block-listener: true

实体绑定需要：

config.yml
entity-listener: true

修改后重启服务端。实体绑定命令只在 Minecraft 1.13+ 可用。

不要删除 plugins/SakuraBind/data。启用方块或实体绑定后，该目录会保存持久化绑定缓存。

方块缓存异常恢复​

方块缓存备份位于 plugins/SakuraBind/backup/block-cache。检测到上一次 JVM 异常退出时：

  • 主方块缓存仍有数据：插件跳过恢复，以主缓存为准。
  • 主方块缓存为空：插件依次验证最新的 a/b 完整快照，恢复第一份有效数据。
  • 快照条目数不匹配或读取失败：插件尝试上一份快照，并在控制台输出警告。
  • 没有可用快照：插件保持空缓存并输出警告，不会盲目使用未完成备份。

恢复后插件会清理已加载世界中位置为空气的方块条目；未加载或不存在的世界不会在这一步清理。排障时请保留 data 和 backup/block-cache 两个目录，并检查控制台中的“方块绑定备份/恢复”日志。若看到 interval-minutes 必须大于 0，请改为正整数并重启。

性能异常​

优先检查这些配置：

  • scanner-period 是否过低。
  • settings.yml 是否有大量复杂正则匹配器。
  • 是否全局开启了 auto-bind.enable 或 auto-unbind.enable。
  • modules/migration.yml 是否迁移完成后仍保持开启。
  • modules/unique-item.yml 是否在生产环境扫描过多物品。
  • 是否频繁执行 /sakurabind superCallback。

大型服建议先用测试服验证自动绑定、数据迁移和唯一物品功能，再放到正式服。

需要审计日志​

默认日志系统关闭。按需开启：

logger.yml
enable: true
console: true
file: true
database: false

送回日志：

send-back-logger.yml
enable: true
console: true
file: true
database: false

修改日志文件路径后重启服务端。