📡 Redis 预加载部署（推荐）

1. 安装代理组件

按代理类型安装 InvSyncVelocity 或 InvSyncBungee，所有参与切服的代理均安装。代理使用 Java 17+，主插件与代理组件保持同版本。

首次启动生成配置后停止代理。Velocity 配置目录为 plugins/invsyncvelocity，Bungee 为 plugins/InvSyncBungee。

2. 代理配置

在代理组件的 config.toml 中配置：

# 通信方式；新配置默认 redis，旧配置缺字段时兼容 ws。
transport = "redis"
# 每个 ACK 阶段最长等待，默认 1500 毫秒，允许 100–10000。
handoff-timeout-ms = 1500

[redis]
# 与子服共享 Redis 的实际地址、端口、密码、编号和前缀。
host = "10.0.0.2"
port = 6379
password = ""
database = 0
# 子服未配置 prefix 时留空。
prefix = ""

代理要能访问该地址；容器里的 localhost 指容器自身。Redis 认证、库编号和 prefix 必须与子服一致。

3. 子服配置

每台子服停服编辑 plugins/InvSync/preload.yml：

# 默认 false；开启整个预加载子系统。
enabled: true
# 代理和子服必须同一种通信方式。
transport: redis
# 每台不同，匹配代理注册的子服名，不区分大小写。
server-name: 'survival'
# 默认空；自动检测玩家目录，非标准布局才指定。
player-data-folder: ''

子服 Redis 连接复用主配置，不需要在预加载文件重复填写。

server-name 留空或 auto 可取服务器目录名；支持 PAPI 变量，但变量最多等待 30 秒，失败回退目录名。生产部署优先直接指定稳定、唯一的名字。

4. 启动与成功标志

代理与子服启动顺序不限，等待订阅接入。检查：

• 子服打印 [RedisPreload] 已订阅 和实际子服名。
• 代理识别对应子服已通过 Redis 接入，协议版本相容。
• 没有子服重名、prefix 不匹配或订阅失败。
• 测试账号 A → B 切服后数据正确，日志显示预加载准备/认领/剩余应用。

只看到主插件“Redis 连接成功”不代表预加载通道已经接入。不要把调试 prequit 当生产上线必需步骤，它会冻结并交接测试玩家；优先真实正常切服验证。

升级注意

旧配置没有 transport 时保留 WS 行为，不自动改成 Redis。要切换时所有参与组件一起修改，勿混用。升级前备份配置、数据库与玩家数据，按升级指南验证。