小白 · 插件文档

外观

⚙️ 配置参考与默认文件 ​

基线：InvSync 2.5.31。下载件取自该版本仓库快照，更新插件时再核对，不能把示例密码用于生产。

同步字段 ​

下表 key 位于 sync 分组，保持原大小写；不要把现有 key 擅自改名。

key数据模板默认
inventory背包、装备、副手true
ender末影箱true
exp等级、经验条与累计总经验true
health当前生命true
food饥饿值true
statistics统计数据true
advancement进度true
buff药水效果true
maxHealth最大血量及相关属性修饰器false
persistentDataContainer玩家 PDC，受服务端版本约束false
gameMode游戏模式false
opOP 状态false
location世界名、坐标、朝向false
vaultVault 余额false
cmiFlyChargeCMI 飞行能量true，需 CMI
initVault / initFlyCharge尚无对应记录时从本服初始化true
disableAll关闭主同步应用，备份用途false；不是不读取/不保存数据的总停机开关

粒度边界

配置并非任意状态的完全隔离层。例如当前应用末尾仍写入选中槽位和饱和度，没有独立同步开关；启用扩展后还受扩展逻辑影响。大厅与生存隔离优先采用独立数据集而非猜测单项开关效果。

数据服务 ​

  • storage：mysql（默认）或 mongodb。
  • redis.database：默认 0，模板注释范围 0–15，实际受 Redis 部署限制。
  • redis.prefix：默认空，只隔离 Redis 键，不隔离持久化库。
  • redis.lockRefreshIntervalTicks：默认 300，按 50ms/tick 转为墙上时间续锁，建议 100–400；锁 TTL 60 秒。
  • MySQL 使用 user / passwd，不是示例常见的 username / password。

Redis 和持久化连接配置要全网一致，失败处理见故障排查。

保存与性能 ​

key默认含义
data-serializerkryo玩家整体缓存序列化；也可 gson，切换需维护流程
auto-save.enablefalse独立定时保存
auto-save.time6000 tick20 TPS 时 5 分钟；低 TPS 会延长
world-save-player-datatrue主世界保存时触发玩家保存
sync.disconnectSaveDelay1 tick退出时已捕获快照，延迟提交写入；不是延迟后重新采集背包的保证
sync.quitSavePriorityMONITOR退出监听优先级：LOWEST/LOW/NORMAL/HIGH/HIGHEST/MONITOR
sync.skipWriteWhenFieldMatchtrue未变化字段优化；异常时可维护停服后关闭排查
options.advancement-main-threadfalse进度应用线程选项，按实际服务端兼容测试
freezedef默认事件拦截；pe/plib 需要 PacketEvents/ProtocolLib，未启用依赖会回退默认实现

安全与兼容 ​

  • invalid-item-policy：deny 默认拒绝异常；remove 清除不认识的附魔后重试；skip 跳过物品并可能在后续保存永久丢失，慎用。
  • skip-items / skip-items-lore：保存时过滤，见物品过滤。
  • player-invulnerability-cleanup.enabled 默认 false；delay-ticks 默认 100，范围 0–72000，0 表示立即检查。会清理原生无敌状态，确认不与其他插件保护冲突再开。
  • migrator-pds 默认 false，PDS 迁移专用。
  • dragon-armourers-delay 默认 80 tick，刷新兼容延迟。
  • hook-plan 默认 false；debug 默认 false，排查时开启后及时关闭。

完整默认配置 ​

查看主配置
yaml
# 调试模式（开启此选项后台日志会变多）
debug: false
# 是否 hook plan插件
hook-plan: false
redis:
  host: localhost
  port: 6379
  # redis 数据库编号，可选 0-15
  database: 0
  # 在线玩家续锁周期，单位 tick，默认 15 秒
  # 60 秒锁过期时间下，建议保持在 100-400 tick 之间
  lockRefreshIntervalTicks: 300
  #  password: ""
  #  prefix: "server"
# 玩家冻结系统
# def 使用Bukkit拦截事件(默认)
# pe 使用PacketEvents拦截数据包
# plib 使用ProtocolLib拦截数据包
freeze: 'def'
# 登录后自动关闭玩家原生无敌状态
# enabled: 是否启用，默认 false；关闭时不执行任何检查
# delay-ticks: 登录后等待的时间，单位 tick，默认 100（5 秒），有效范围 0-72000；0 表示加入后立即检查
player-invulnerability-cleanup:
  enabled: false
  delay-ticks: 100
# 自动保存
auto-save:
  # 是否启用
  enable: false
  # 保存的时间 这里单位是tick   1秒=20tick
  time: 6000
# 玩家数据序列化方式 可选 gson 和 kryo
# 默认最开始是GSON，自2.3.77起增加了Kryo
# 如果之前用的是Gson 要改用kryo的话 需要全服都改成kryo并清空redis的invsync数据才能使用
data-serializer: 'kryo'
# 是否在世界保存的时候保存玩家数据
world-save-player-data: true
# 存储类型: mysql 或 mongodb
storage: 'mysql'
mysql:
  host: 'localhost'
  port: 3306
  database: 'database'
  user: 'user'
  passwd: 'passwd'
  ssl: false
mongodb:
  host: 'localhost'
  port: 27017
  database: 'database'
  #  authenticationDatabase: 'admin'
  #  user: 'user'
  #  passwd: 'passwd'
mobs:
  # 是否同步宝可梦数据
  pixelmon: false
  # 是否同步时装工坊数据
  armourersWorkshop: false
  # 是否同步 ftbQuests
  ftbQuests: false
  # 是否同步神秘时代
  thaumcraft: false
options:
  # 是否使用主线程同步成就
  advancement-main-thread: false
sync:
  # 关闭所有同步项，仅用于玩家数据备份
  disableAll: false
  # 是否同步统计数据
  statistics: true
  # 是否同步经验等级、经验条进度和累计总经验；默认 true，可选 true/false，无单位
  exp: true
  # 是否同步末影箱
  ender: true
  # 是否同步血量
  health: true
  # 是否同步饥饿值
  food: true
  # 是否同步背包
  inventory: true
  # 是否同步成就数据
  advancement: true
  # 是否同步药水效果
  buff: true
  # 是否同步游戏模式
  gameMode: false
  # 是否同步最大血量
  maxHealth: false
  # 是否同步PersistentDataContainer数据
  persistentDataContainer: false
  # 是否同步OP
  op: false
  # 是否同步CMI飞行能量
  cmiFlyCharge: true
  # 如果数据库没有飞行能量数据是否从这个服务器读取
  initFlyCharge: true
  # 是否同步vault经济
  vault: false
  # 如果数据库没有vault数据是否从这个服务器读取
  initVault: true
  # 是否同步服务器中的位置
  location: false
  # 玩家退出时延迟多少tick再保存数据
  # 用于兼容在退出前最后一刻才回写物品状态的插件（如部分收纳袋/背包插件）
  disconnectSaveDelay: 1
  # 玩家退出保存监听优先级
  # 可选: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR
  # 建议默认 MONITOR，让其他插件先完成同tick的物品状态刷新
  quitSavePriority: 'MONITOR'
  # 玩家进服时按字段比对 PDC 指纹与数据库指纹，命中的字段跳过对应的 write 分支
  # 同服重连场景下绝大多数字段都能命中，跨服切换时未变的字段也能命中
  # 遇到玩家进服后状态不正确等问题可关闭回退到全量写入
  skipWriteWhenFieldMatch: true
# 同步时跳过的物品名称 名称会忽略颜色符号完全匹配
skip-items:
  - '不同步物品名1'
  - '不同步物品名2'
# 同步时跳过的物品lore 有这个lore就会跳过 会检测颜色符号
skip-items-lore:
  - '不同步的lore'
# 物品反序列化失败时的处理策略（例如物品包含服务器不存在的附魔）
# remove - 移除无效附魔，保留物品其余数据
# skip - 跳过整个物品，该槽位变为空
# deny - 直接报错，阻止玩家进入服务器（默认行为）
invalid-item-policy: 'deny'
# PlayerDataSQL 迁移程序 执行迁移命令后还需一直开着这个选项 增加这个开关是因为并不是所有人都有pds
migrator-pds: false
# DragonArmourers 刷新延迟时间
dragon-armourers-delay: 80
# 玩家数据备份
backup:
  # 是否启用备份功能
  enabled: false
  # 玩家退出时自动备份
  on-disconnect: true
  # 自动保存时自动备份
  on-auto-save: false
  # 世界保存时自动备份
  on-world-save: false
  # 跳过空数据备份（背包和末影箱都为空时不备份，防止空数据覆盖有效备份）
  skip-empty: true
  # 备份保留策略（多层保留，防止数据丢失后空备份覆盖所有有效备份）
  retention:
    # 最近保留的备份数量
    latest: 10
    # 每天保留一个备份，保留最近多少天
    daily: 7
    # 每周保留一个备份，保留最近多少周
    weekly: 4
    # 每月保留一个备份，保留最近多少个月
    monthly: 3
查看语言文件
yaml
inventory:
  lock: '&7[&e&l!&7] &c你的背包已被锁定'
  error: '&7[&e&l!&7] &c数据同步出错,请联系管理处理'
  timeout-new: '&7[&e&l!&7] §c加载数据超时,请等待15秒后进入服务器'
  sync-busy: '&7[&e&l!&7] &c数据同步中,请稍后再进入服务器'
  not-exist: '&7[&e&l!&7] §c玩家数据不存在'
  # 填空不会触发
  load-start: '&7[&e&l!&7] &c正在加载数据'
  load-done: '&7[&e&l!&7] &c同步已完成 主线程耗时 {0} 异步耗时 {1}'
  edit:
    success: '&7[&e&l!&7] &a编辑已生效'
    invalid-data: '&7[&e&l!&7] &c检测到并过滤了 {0} 个越界物品，关闭界面后将修复数据'
    invalid-slot: '&c无效槽位'
    title:
      inventory: '&7编辑玩家 &a{0} &7背包数据'
      ender: '&7编辑玩家 &a{0} &7末影箱数据'
command:
  reload-lang: '&7[&e&l!&7] &7语言文件已重载'
  save: '&7[&e&l!&7] &7玩家 &a{0} &7的数据已保存'
  save-busy: '&7[&e&l!&7] &c玩家 &e{0} &c正在同步数据, 已跳过保存'
  freeze: '&7[&e&l!&7] &7玩家 &a{0} &7被冻结的状态为{1}'
  unlockAll: '&7[&e&l!&7] &a成功解锁所有玩家数据'
  lock: '&7[&e&l!&7] §a锁定状态: {0}'
  edit-online: '&7[&e&l!&7] §c玩家在线,请使用CMI编辑或其他插件'
  edit-lock: '&7[&e&l!&7] §c数据已被锁定(玩家可能在线),请使用CMI编辑或其他插件'
  restoresMaxHealth:
    start: '&7[&e&l!&7] §a开始恢复所有玩家最大血量,此过程可能有点漫长,请不要关服'
    end: '&7[&e&l!&7] §a成功恢复玩家最大血量'
  backup:
    created: '&7[&e&l!&7] &a已为玩家 &e{0} &a创建备份'
    empty: '&7[&e&l!&7] &c该玩家没有备份数据'
    restore-success: '&7[&e&l!&7] &a已成功恢复玩家 &e{0} &a的备份数据'
    restore-fail: '&7[&e&l!&7] &c恢复备份失败'
    not-found: '&7[&e&l!&7] &c未找到指定的备份'
    disabled: '&7[&e&l!&7] &c备份功能未启用'
查看预加载文件
yaml
# InvSync 跨服预加载子系统配置
#
# 该子系统让 Velocity / Bungee 在玩家切服前通知本服提前抢锁 + 预读 + 离线写入 vanilla 字段到
# playerdata/<uuid>.dat。玩家进服 trySync 直接跳过抢锁循环 + skip 已写入字段的 write 分支。
#
# 任何环节失败都会自动回退到原 trySync 流程，无功能损失。

# 是否启用整个预加载子系统（关闭后所有相关组件不会启动 / 不会触发）
enabled: false

# 与代理端（Velocity / BungeeCord）的通信方式，默认 redis
#   redis  推荐。直接复用 config.yml 里已配置的 Redis 通信，子服无需开放端口，
#          支持多个代理同时连接同一台子服。代理端 config.toml 需填写同一个 Redis（含 prefix）
#   ws     旧版 WebSocket 方式。子服主动连接下面 ws.url 指向的单个代理，多代理时其余代理无法预加载
# 从旧版本升级且文件里没有这一项时，会自动补为 ws，保持升级前的行为不变
transport: redis

# 本服的子服名，必须和代理端配置里的子服名一致（不区分大小写）
# 三种写法：
#   ''  或  auto        启动时自动用服务端根目录名（仅内存，文件不动）
#   survival            直接写死，最稳
#   '%server_name%'     PAPI 变量，需要装 PlaceholderAPI；子服名已经在某个变量里时用这个
# 写 PAPI 变量时，InvSync 会等变量能解析出来再连接代理（最多等 30 秒，避免用 %xxx% 原文
# 当子服名导致预加载静默失效）；30 秒还解析不出来就回退目录名并打 warn
# 注意：多台子服不能使用相同的子服名
server-name: ''

# 以下仅 transport: ws 时使用
ws:
  # 旧版本的子服名配置位置，已迁移到上面的 server-name；仅当上面的 server-name 留空时才会读取这里
  server-name: ''
  # 代理端 WS 服务地址，一般是内网地址 + 代理端 config.toml 配置的端口
  url: 'ws://localhost:8765/invsync'
  # 注册鉴权密钥，必须和代理端 config.toml 的 secret 一致
  secret: 'change-me'

# 玩家数据目录（含 <uuid>.dat 的目录）
#
# 留空即可，插件会自动检测。检测方式是"按版本排优先级 + 实地探测"：
#   MC 26.1.2 及以上：<主世界>/players/data
#   MC 26.1.2 以下：  <主世界>/playerdata
# 两个路径都会试，谁真的装着 <uuid>.dat 就用谁；已知布局全都没命中时，还会在主世界目录里
# 浅层扫一遍找玩家数据目录。主世界取自 Bukkit 世界列表 / server.properties 的 level-name。
#
# 只有用了非标目录布局、或自动检测日志报找不到时才需要显式配置。这里可以填：
#   玩家数据目录：world/players/data  或  world/playerdata
#   世界目录：    world              （自动补上面的子目录）
#   服务端根目录：/home/mc/server     （读 server.properties 的 level-name 再补）
# 绝对路径和相对路径都支持，相对路径以服务器根目录（plugins/ 的上一级）为基准。
player-data-folder: ''

reloadLang 只重载语言。数据服务及多数运行选项修改后正常重启，避免热重载带来不一致。

技术说明以对应版本为准 · 购买与售后 QQ：3104026189

© xbaimiao