AdventureResourceSync
AdventureResourceSync 将群组服各子服的 CraftEngine 资源合并为统一资源包，由 Hub 分发配置、重建、托管并通知玩家下载；Velocity 端可阻止未加载最新版资源包的玩家进入业务服。
结构化合并
汇总多子服 resources 与 YAML，二进制冲突可按最新文件处理。
反向分发
将统一资源和 commands.yml 等文件同步回全部节点。
内置托管
Hub 通过 HTTP 提供 latest.zip，并向在线玩家重新发送。
代理门禁
未完成最新版资源包加载时，只允许停留或返回 Lobby。
| 版本 | 1.1.0 |
|---|---|
| 模块 | Bukkit + Velocity |
| 服务端 | Paper 1.21，Java 21 |
| 主要目标 | CraftEngine 群组服资源统一 |
双端安装
- 在登录服/Lobby 安装 Bukkit 模块，并配置
role: hub。 - 在其他子服安装同一 Bukkit 模块，配置
role: node与唯一server-id。 - 在 Velocity 安装代理模块。
- 确保 Hub 能通过文件系统访问每个子服 CraftEngine 目录。
- 配置共享目录、HTTP 公网地址、端口和 Velocity 的 Lobby 名称。
Bukkit 的 server-id 必须与 Velocity 服务器名相同，否则定向下发和加载状态同步会失效。
Hub / Node 架构
| 角色 | 职责 |
|---|---|
| Hub | 合并、分发、重建、发布、HTTP 托管、通常负责玩家首次下发 |
| Node | 提供本服资源源文件、接收统一资源和配置、执行 CraftEngine 重载 |
| Velocity | 读取共享加载状态，拦截未加载玩家向业务服转移 |
| 共享目录 | 保存统一版本、信号与跨端状态 |
一键 deploy
指定节点资源 → Hub 合并 → 分发所有节点 → 重建 → 发布 latest.zip → 更新版本Hub 通常是 master，分发时自动排除自己的资源源目录，避免反复自合并。
合并资源
merge:
structured-yaml:
enabled: true
binary-files:
strategy: newest-file- 结构化 YAML 合并按键组合配置，降低简单覆盖造成的丢项。
- 资源目录从指定服务器或全部服务器读取。
- 二进制重名时默认选择修改时间最新的文件。
/ars merge <server|all>只执行合并，不分发与重建。
不同子服不应定义同名但含义不同的模型、贴图或命名空间；自动策略无法判断业务语义。
分发配置
hub:
distribute:
enabled: true
sync-resources: true
sync-files:
- "commands.yml"
node:
sync-resources: true
sync-files:
- "commands.yml"分发把 Hub 生成的统一 resources 以及白名单配置文件复制到每个节点的 CraftEngine 目录。节点收到信号后可执行配置的重载命令。
不要把包含本服端口、数据库或世界差异的配置加入 sync-files；统一文件必须在所有子服语义一致。
重建与发布
rebuild:
watch-signal: true
signal-check-seconds: 5
commands:
- "ce reload"
- "ce upload"
publish-delay-ticks: 120
generated-pack: "./plugins/CraftEngine/generated/resource_pack.zip"- Hub 或节点执行 CraftEngine reload。
- Hub 运行 upload/生成资源包。
- 等待生成完成后读取 configured generated-pack。
- 复制为 HTTP 服务使用的最新包并更新版本。
- 共享信号通知其他节点刷新。
资源包下发
resource-pack:
public-url: "https://资源包域名/latest.zip"
bind-host: "0.0.0.0"
bind-port: 8225
required: true
send-delay-ticks: 40
node:
send-on-join: false- Hub 内置 HTTP 服务监听 bind-host/bind-port。
- public-url 必须是玩家客户端可访问的完整地址。
required: true会把拒绝资源包视为无法继续游戏。/ars send <server|all>让指定服在线玩家立即下载最新版。- 节点默认不在入服时重复发送，通常由 Hub 统一下发。
Velocity 门禁
lobby-server: "lobby"
shared-dir: ".../cache/AdventureResourceSync"
block-transfer-if-not-loaded: true
message: "§c你还没有加载最新服务器资源包，请先回到登录服完成加载。"Bukkit 在所有服务器监听资源包状态，并把玩家已加载的版本写入共享状态。Velocity 在玩家尝试切换服务器时比对最新版：
- 已加载最新版：允许前往业务服。
- 未加载或版本过期：阻止转移并提示返回/停留 Lobby。
- 重新下发成功后，节点也会更新状态以解除门禁。
配置参考
| 字段 | 说明 |
|---|---|
role | hub 或 node |
server-id | 与 Velocity 服务器名一致 |
hub.craftengine-dir | 统一资源包 master 目录 |
hub.shared-dir | 版本与信号共享目录 |
hub.servers | 服务器 ID 到 CraftEngine 目录映射 |
node.reload.commands | 同步后执行的命令 |
resource-pack.public-url | 玩家访问的 URL |
resource-pack.bind-port | 内置 HTTP 监听端口 |
默认配置包含示例服务器绝对路径和地址，不能直接复制到其他机器。
命令与权限
根命令 /ars，别名 /advsync、/arsync；全部需要 adventureresourcesync.admin（OP）。
| 命令 | 作用 |
|---|---|
/ars status | 角色、server-id、版本、共享目录和托管信息 |
/ars deploy <server|all> | 合并→分发→重建→发布 |
/ars merge <server|all> | 仅合并 |
/ars distribute | 仅分发到节点 |
/ars rebuild | 执行重建命令 |
/ars publish | 发布已生成资源包 |
/ars send <server|all> | 向在线玩家下发 |
/ars push | 节点推送本服资源 |
/ars reload | 重载设置 |
deploy、merge、distribute、rebuild、publish 只能在 Hub 执行。
推荐运维流程
- 在目标节点完成 CraftEngine 内容修改并本地验证。
- 备份 Hub 统一资源目录和上一个 latest.zip。
- 执行
/ars deploy <节点>。 - 检查 Hub 日志中的合并冲突、生成命令和发布版本。
- 先对测试玩家执行
/ars send lobby。 - 确认资源包加载成功及 Velocity 门禁解除。
- 再执行
/ars send all。
长期保留至少一个上一版本资源包及其统一资源源目录；发生贴图/模型异常时能快速恢复。
故障排查
HTTP 资源包无法下载
- 检查 8225 端口、防火墙、反向代理和 public-url。
- 在玩家网络侧访问 latest.zip，而不是只在服务器本机测试。
- 确认 generated-pack 已生成并被 publish 复制。
节点未更新
- 检查 Hub 对节点目录的文件权限和路径。
- 确认 sync-resources、sync-files 与 reload.enabled。
- 检查共享目录和 signal watcher。
玩家一直被门禁拦截
- Bukkit server-id 与 Velocity 名称是否一致。
- 两端 shared-dir 是否指向同一位置。
- 玩家加载状态对应的版本是否为最新发布版本。