管理员文档 · 跨服务器功能
配置 Dominion 的共享数据库、跨服领地管理、缓存同步与跨服传送。
跨服功能
Dominion 的跨服务器功能把多个代理后的后端服连接到同一个外部数据库。玩家可以查看和管理其他服务器上的领地，也可以在有传送点且权限允许时跨服传送。请先在维护窗口和测试服验证，再用于生产环境。
跨服功能不是“复制一份 SQLite 文件”。它依赖共享数据库、代理路由、稳定的服务器身份和目标世界，任何一项不一致都可能造成数据不可见或传送失败。
需要满足的前置条件
- 多个 Minecraft 后端已经接入 BungeeCord 或 Velocity 等代理，并且代理中的服务器名称可被后端使用；
- 所有后端安装相同的 Dominion JAR，并统一 flag、语言和限制文件；
- 准备 MySQL、MariaDB 或 PostgreSQL 等外部数据库；SQLite 不支持跨服务器模式；
- 所有后端可以连接同一个数据库，账号至少具备 Dominion 所需的建表、读写和索引权限；
- 每个后端有唯一、稳定、为正整数的
server-id； server-name与代理配置中的后端名称完全一致；- 需要跨服传送的目标后端存在对应世界，并能加载领地记录中的目标坐标。
核心配置
所有后端的数据库信息必须指向同一个数据库；server-name 和 server-id 则必须按后端分别设置：
database:
type: mysql
host: db.example.internal
port: '3306'
database: dominion
username: dominion
password: change-this
connection-pool-size: 10
multi-server:
enable: true
server-name: survival
server-id: 1第二台后端可以是：
multi-server:
enable: true
server-name: resource
server-id: 2三个键的含义
| 键 | 要求 |
|---|---|
multi-server.enable | 设为 true 才启用共享服务器缓存和跨服能力 |
multi-server.server-name | 与 BungeeCord/Velocity 中的后端名称一致，用于跨服连接 |
multi-server.server-id | 正整数，并且在共享数据库的所有后端中唯一；已有数据后不要修改 |
如果 database.type 是 sqlite，或 server-id 小于等于 0，插件会记录错误并自动关闭多服务器模式。这个自动关闭是保护措施，不代表配置已经正确。
推荐部署顺序
新的群组服
- 先在测试环境创建外部数据库和专用账号，限制数据库账号只访问 Dominion 使用的库；
- 在每台后端填写相同的数据库连接信息，确认库名、账号、密码和端口一致；
- 为每台后端分配唯一的
server-id，并把server-name写成代理中的实际名称； - 先不要让玩家进入，检查代理路由、后端端口和每台服的服务端核心；
- 确认所有后端文件已经保存后，再依次启动并查看 Dominion 的数据库连接、多服初始化和插件启用日志；
- 从每台后端分别登录测试账号，验证领地列表、成员关系、权限、传送点和跨服传送；
- 确认稳定后再开放玩家，并设置定期数据库备份。
已经使用 SQLite 的单服
已有数据时，先保留原服务器的 server-id（默认通常为 1），不要为了迁移而随意更换：
- 停服并完整备份
plugins/Dominion/； - 使用
/dominion export db导出当前数据库数据； - 准备干净的 MySQL/MariaDB/PostgreSQL 数据库；
- 在维护窗口配置外部数据库，先确保目标数据库为空且连接成功；
- 按管理员命令的确认流程使用
/dominion import db confirm恢复/迁移数据； - 核对领地数量、所有者、父子关系、成员、权限组、传送点和服务器 ID；
- 确认单服数据正常后，再加入其他后端并为它们分配新的 ID。
导入命令用于迁移或恢复，不用于把两个已经各自产生数据的数据库直接合并。项目当前没有为多个独立旧数据库提供安全的自动合并方案；这种情况应保留备份并先制定人工迁移方案。
跨服数据同步
数据归属
每个领地、成员和权限组记录都会关联创建/管理它的 server-id。Dominion 启动多服模式后，会从共享数据库加载其他服务器的缓存，并通过数据库中的更新日志通知其他实例刷新数据。
更新延迟
当前实现的跨服缓存轮询间隔为约 5 秒，更新日志在完成消费或超过保留时间后清理。因此，A 服刚修改成员或领地，B 服 UI 仍可能短暂显示旧数据；这不是数据库写入失败的直接证据。等待同步周期后再复查，并同时查看两台服务端日志。
需要保持一致的内容
数据库中的领地、成员、组和传送点是共享数据；config.yml、flags.yml、limitations/、world-wide/ 和语言文件仍是每台后端本地配置。要让玩家在不同服获得一致体验，应自行保持这些文件的策略一致，尤其是传送开关、可用 flag、尺寸限制和 UI 默认值。
跨服传送流程
玩家传送到同一后端时，插件直接在本服安全位置传送；目标领地属于其他后端时，流程大致是：
- 先检查玩家的传送限制、冷却、延迟和目标领地
teleportflag； - 将待传送玩家与目标领地记录写入共享数据；
- 通过
BungeeCord插件消息请求代理把玩家连接到server-name对应的后端； - 玩家在目标后端加入后，目标服读取待传送记录并把玩家安全传送到领地传送点。
所以“能在列表中看到远程领地”不等于“跨服传送一定成功”。需要同时检查代理路由、后端名称、目标世界、传送点、权限和数据库待传送记录。
上线后的验证矩阵
| 测试 | 预期结果 |
|---|---|
| A 服创建领地，B 服打开我的领地 | 等待同步后可以看到 A 服领地 |
| A 服添加/移除成员，B 服读取权限 | 约一个同步周期后显示新成员状态 |
| 普通玩家传送到另一服领地 | 受目标领地 teleport、玩家限制、冷却和延迟共同控制 |
| 管理员跨服查看/管理 | 只在 dominion.admin 或领地权限实际允许时放行 |
| 目标服不存在对应世界 | 传送应失败并保留可诊断的日志，而不是当作正常传送 |
| 一台服暂时停止 | 其他服不应共享到它的实时缓存；恢复后再观察同步和数据库连接 |
建议用一个普通账号和一个管理员账号分别测试，避免 admin-bypass: true 让管理员误以为普通玩家也能跨服操作。
常见问题
启动后多服自动关闭
检查 database.type 的值为外部数据库类型，server-id 为正整数。修正后完整重启。不要只修改 UI 默认值或执行缓存重载。
看不到其他服务器的领地
确认所有后端连接同一个数据库，数据库账号没有连接到其他环境，multi-server.enable 已开启，所有后端使用相同的 Dominion JAR，服务器 ID 没有冲突。等待同步周期后再重新打开 UI。仍然异常时，查看数据库连接和 Dominion 日志。
跨服传送停在原服或连接失败
按顺序检查：server-name 与代理完全一致，代理允许后端连接，BungeeCord/Velocity 配置已经重载，目标服在线，目标世界存在，玩家拥有传送权限。目标服名称拼写错误时，数据库数据可能正常，但代理无法完成跳转。
修改后另一台服仍显示旧权限
先等待同步周期，再用普通账号重新打开页面。若数据仍未更新，确认两台服都能读写共享数据库，更新日志表没有异常，并确认本地配置没有关闭目标 flag。
更换 server-id
不要直接更换。已有领地记录与旧 ID 关联，修改后可能无法找到原有数据。确需调整时，应停服、备份数据库、先设计数据迁移，再在测试环境验证；不能把改 ID 当成常规重命名操作。
维护和回滚
跨服上线后至少同时备份数据库与每台后端的 plugins/Dominion/。修改数据库连接、服务器 ID、代理名称或跨服开关时安排维护窗口。发生数据异常时先停服保留日志和数据库现场，不要删除服务器记录或反复启动覆盖问题，再按迁移与备份策略执行恢复。