跨服传送

文档版本: v1.2.1页面更新: 2026-09-14

KaTpa 可以配合 KaProxy，让玩家向其他子服务器的玩家发送请求。请求被接受后，需要传送的玩家先完成倒计时，然后自动切换服务器并到达目标玩家身边。

准备工作#

Velocity 3.4 或兼容版本，或 BungeeCord 1.21
每个子服安装相同版本的 KaTpa
代理端安装 KaProxy
所有子服使用同一个 MySQL 或 MariaDB 数据库保存 KaTpa 设置

代理端设置#

将 KaProxy-1.0.0.jar 放入代理服务器的 plugins 文件夹。
启动代理服务器，让 KaProxy 生成配置。
确认 KaProxy 配置中 Tpa 和 Back 模块已开启：

modules:
  tpa:
    enabled: true
  back:
    enabled: true

重启代理服务器，或执行 /kaproxy reload。

子服设置#

每个子服的 plugins/KaTpa/config.yml 都需要启用代理功能：

proxy:
  enabled: true

storage:
  type: mysql
  mysql:
    host: 127.0.0.1
    port: 3306
    database: katpa
    username: katpa
    password: change-me
    use-ssl: false

请将示例中的数据库地址、账号和密码替换为自己的信息，并确保所有子服填写相同的数据库配置。完成后重启所有子服。

跨服模式下，子服的真实服务器 ID 由 KaProxy 从代理端自动获取，无需手动配置 server-id。config.yml 中的 server-id 仅用于单服模式或 UI 显示名称。

玩家体验#

启用后，/tpa 和 /tpahere 的玩家列表会显示整个群组服的在线玩家。/back 和 /dback 也可跨服返回，/warp 和 /home 同样支持跨服传送，代理端会切换玩家到目标服并传送到精确坐标。白名单、黑名单、接收方式、冷却和传送中断规则在跨服请求中同样有效。跨服传送与本服一致，都会先完成吟唱倒计时（modules.<模块>.warmup-seconds，默认 3 秒）再切换子服；吟唱期间移动、受伤或离线都会中断传送。

默认情况下，如果目标玩家在倒计时期间切换到另一个子服，KaProxy 会继续前往目标玩家当前所在的服务器。

目标可用性校验#

每次传送在开始倒计时前都会先校验目标是否可用，校验失败会直接取消本次传送并给出提示，不会进入倒计时：

目标位于本服时，要求目标世界已加载；否则提示“目标世界 … 未加载，传送已取消”。
目标位于其他子服时，要求该子服当前在线（由 KaProxy 探测，并在在线快照中下发）；否则提示“目标服务器 … 当前不可用，传送已取消”。
代理通道不可用时，提示“跨服服务当前不可用”。

因此目标世界被卸载或目标子服已停机时，玩家不会白白等待倒计时结束再失败。

地标与玩家地标同步#

多个子服共享同一数据库时，/warp（公共地标）与 /pwarp（玩家地标）的列表需要在各子服保持一致。KaTpa 会在每个子服内存中缓存这两份列表，并自动同步：

本地新增、编辑或删除地标并成功写入数据库后，会通过 KaProxy 向其他子服广播一次变更（主题 warp / player_warp），其他子服收到后自动重载对应缓存。
玩家进入子服时会主动重载一次缓存（2 秒去抖），兜底补上该子服无人在线期间错过的变更。

因此在一个子服新建的地标，无需重启，玩家在其他子服打开 /warp / /pwarp 即可看到。/home 按玩家存储，玩家每次进服都会从数据库重载，不涉及跨服同步。

排查#

如果提示“跨服服务当前不可用”，请依次检查：

KaProxy 是否已在代理端正常启用。
KaProxy 的 Tpa 模块是否开启（跨服返回还需 Back 模块开启）。
当前子服的 proxy.enabled 是否为 true。
玩家是否已经正常通过代理进入子服。
代理端和子服控制台是否出现报错。