资源加密 ​

ChaUI 页面使用的图片、动图、字体和音效都保存在玩家客户端。直接把这些文件放进资源目录最方便，但任何拿到客户端文件的人也能直接浏览和复制。ChaAssets 可以把这批素材打包成经过平台认证的 .chaassets 文件，让 ChaUI 在路径不变的情况下读取受保护资源。

这篇教程会从创建项目开始，完整走完上传构建、版本下载、服务器身份和服务器授权四个步骤，并说明离线主菜单素材该选择哪种保护方式。

ChaAssets 能解决什么问题 ​

ChaAssets 适合保护必须发到客户端、又不希望以原图形式公开的素材，例如：

• ChaUI 页面背景、按钮、图标和字体；
• 替换标题主菜单、多人游戏列表等原版页面所需的本地素材；
• ChaEngine 现有模型、贴图等客户端资源；
• 后续接入 ChaAssets 的其他客户端插件资源。

页面和模型中原有的相对路径不需要因为加密而修改。比如页面仍然填写 gui/logo.png，ChaAssets 会在对应插件资源根中寻找这个相对路径。

使用前准备 ​

开始前请确认：

1. 你已经可以登录猹件用户中心。
2. 需要读取加密资源的客户端安装了 ChaAssets。
3. 对于服务器会话资源，服务端也已经安装并正常启用 ChaAssets。
4. 需要打包的普通资源已经整理好，并且能在未加密状态下被 ChaUI 或对应插件正常读取。

建议先复制一份资源目录作为备份。平台接收的是 ZIP，构建成功后会生成新的 .chaassets 文件，不需要覆盖你的原始工程文件。

创建资源项目 ​

进入用户中心的 ChaAssets 页面后创建项目。普通用户只能看到和操作自己创建的项目、版本、服务器身份和授权，其他用户不能通过项目 ID 打开你的内容。

创建时主要填写：

需要替换标题主菜单、多人游戏列表、选项页面等进服前页面时，选择可供客户端本地启动使用的 BOOTSTRAP。只希望玩家连接并获得服务器授权后读取的资源，选择 SESSION。

项目生成过版本后不要随意修改资源根。资源根决定相对路径属于哪个插件，修改它会让现有页面找不到素材。

准备 ZIP ​

平台接受两种目录结构。你可以直接压缩资源目录，也可以保留最外层的插件资源根；两种方式构建后的资源路径相同。

直接资源结构 ​

这是最省事的方式。以 ChaEngine 模型为例，打开资源目录并选中里面的 model 文件夹进行压缩：

model/...
model/外卖箱背包/外卖箱背包.geo.json
model/外卖箱背包/外卖箱背包.png

ChaUI 资源也可以直接以 gui、sounds 或其他实际资源目录为 ZIP 根：

gui/...
gui/main-menu/background.png
sounds/click.ogg

保留项目根目录 ​

如果你习惯直接压缩整个插件资源文件夹，也可以保留项目创建时填写的资源根：

ChaEngine/model/外卖箱背包/外卖箱背包.geo.json
ChaEngine/model/外卖箱背包/外卖箱背包.png

ChaUI 项目同样支持：

ChaUI/model/...
ChaUI/gui/main-menu/background.png
ChaUI/sounds/click.ogg

平台会在构建时移除这一层项目根。因此 ChaEngine/model/外卖箱背包/外卖箱背包.png 和直接结构中的 model/外卖箱背包/外卖箱背包.png 最终是同一个资源路径。

不能混用的结构 ​

同一个 ZIP 中不要一部分文件带项目根、另一部分文件不带：

ChaEngine/model/a.png
model/b.png

这种结构无法确定你想保留哪套目录关系，平台会拒绝构建并提示：

ZIP 内同时存在直接资源路径和插件根目录路径，请统一目录结构后重新上传。

还要避免绝对路径、反斜杠、..、重复文件名、损坏的 ZIP，以及数量或体积明显异常的文件。平台会在构建记录中显示具体原因。

上传与构建 ​

1. 打开项目详情页的“上传与构建”。
2. 选择刚才准备的 ZIP。
3. 点击“上传并构建”。大文件会分片上传，页面会显示进度。
4. 上传完成后等待构建。平台会检查目录、制作加密资源并完成认证。
5. 最近构建变为 SUCCEEDED 后，前往“版本与下载”。

如果网络中断，页面会保存可恢复的上传编号。重新进入项目并选择同一个 ZIP，可以从尚未完成的分片继续。网页不会把原始文件内容或资源密钥保存在浏览器本地。

构建失败时先看“最近构建”下方的红色原因。目录混用、危险路径、文件过大、压缩率异常和 ZIP 损坏会分别给出提示，不再只显示异常名称或“未知错误”。

版本与下载 ​

每次成功构建都会产生一个不可变版本。进入“版本与下载”，核对版本号、安全域、文件大小和清单摘要，然后点击“下载”。

下载得到的文件扩展名必须保留为 .chaassets。文件名可以自己整理，例如：

ui.chaassets
main-menu-2026-07.chaassets
models.chaassets

已经投入使用的版本不要用内容不同的同名文件直接替换。需要更新素材时重新上传并生成新版本，再将新文件分发给客户端。

.chaassets 放在哪里 ​

.chaassets 放在当前游戏版本目录的 resourcepacks/<资源根>/ 中，与原来的普通资源目录位于同一个插件资源根下。例如：

.minecraft/
└─ resourcepacks/
   ├─ ChaUI/
   │  ├─ ui.chaassets
   │  └─ gui/
   │     └─ temporary-preview.png
   └─ ChaEngine/
      ├─ models.chaassets
      └─ model/
         └─ local-test/

常用完整路径包括：

.minecraft/resourcepacks/ChaUI/ui.chaassets
.minecraft/resourcepacks/ChaEngine/models.chaassets

不要把 .chaassets 放进 Minecraft 原版资源包的 assets/<namespace>/，也不要在页面路径前加容器文件名。页面中的 gui/logo.png 仍然只写 gui/logo.png。

服务器身份 ​

SESSION 资源需要先确认玩家连接的是已获许可的服务器。新版流程不要求你准备身份字段或上传任何密钥，只需用网页生成的一次性命令完成配对。

下面继续使用同一个模拟案例：

项目名称：修仙主题模型资源
资源根：ChaEngine
安全域：SESSION
资源版本：版本 1
服务器身份：修仙主题服务器

用一次性命令配对 ​

1. 确认服务端已经安装新版 ChaAssets，并至少正常启动过一次。
2. 在用户中心进入“服务器身份”，点击“添加服务器”。
3. 服务器名称填写 修仙主题服务器，点击“生成配对命令”。
4. 复制网页显示的完整命令，在目标服务器的控制台执行一次。
5. 保持弹窗打开。网页显示“配对成功”，服务器列表出现“修仙主题服务器”且状态为“可用”后，本步骤完成。

下面的命令只是排版示例，示例码不能实际使用：

/chaassets pair J7K9-P2MX

实际配对码有较短的有效期，并且只能成功使用一次。过期或输错时关闭旧弹窗，再生成一条新命令即可。配对期间只会发生一次明确的服务器到平台请求，不会因此开启后台常驻连接。

多台子服共用同一身份 ​

如果 A、B 两台子服都属于你完全信任的同一集群，并且希望它们解码同一份资源，可以让它们共享完整的 plugins/ChaAssets/keys/ 文件夹：

1. 先在子服 A 完成配对。
2. 完全停止 A、B 两台服务器。
3. 把 A 的整个 plugins/ChaAssets/keys/ 文件夹复制到 B，不要只挑其中某一个文件。
4. 分别启动 A、B；以后每个节点仍要独立完成自己的启动检查。

共享同一套 keys 的节点在平台上代表同一个服务器身份，也会共享同一组资源授权和同一个撤销结果。平台不会统计或监控这个身份背后有多少节点。

如果所有 keys 副本都丢失，不需要尝试恢复或轮换。把它视为一台新服务器，重新执行“添加服务器”流程；确认新身份工作后，在用户中心删除旧服务器记录。

服务器授权 ​

配对成功后，在网页直接保存资源版本与服务器之间的启用关系：

1. 打开“修仙主题模型资源”的“服务器授权”。
2. 点击“启用资源”。
3. 资源版本选择 版本 1 · SESSION。
4. 目标服务器选择 修仙主题服务器。
5. 点击“保存并启用”。
6. 页面显示下面的结果后，网页操作已经完成：

配置已保存，将在服务器下次启动检查时生效。

不需要重新构建或重新下载 models.chaassets。正常重启对应服务器后，ChaAssets 只在启动阶段取得当前启用配置；共享 keys 的集群需要分别重启每个节点，尚未重启的节点会继续沿用自己本次运行已经加载的配置。

停止使用时点击“停止授权”。删除或撤销服务器身份也遵循同一原则：平台先保存目标状态，对应节点在下次成功启动检查时应用。平台不会为了立即生效而中断正在运行的服务器或玩家会话。

服务器什么时候会连接平台 ​

ChaAssets 与平台的通信刻意保持得很少：

运行期间没有心跳、定时授权轮询、WebSocket、SSE 或长轮询。玩家登录不会请求平台，玩家每次读取资源也不会请求平台；会话授权通过现有 Minecraft 网络通道在玩家和当前服务器之间完成。

如果服务器启动时暂时无法访问平台，会尝试读取上一次经过平台验证并保存在本地的授权快照。只要该快照仍然完整可信，服务器可以继续使用它，本次运行也不会因为平台之后的网络波动而改变。

全新的服务器身份如果从未成功取得过启动快照，而首次启动检查又失败，服务器仍会正常启动，但本次运行不开放加密资源。网络恢复后再次正常重启即可，不需要修改资源包或重新配对。

普通文件与 .chaassets 如何共存 ​

ChaAssets 不要求你一次性把所有资源都改成加密文件：

• 安装 ChaAssets 后，普通文件和已经获得许可的 .chaassets 可以分别提供不同的相对路径。
• 同一个相对路径同时存在时，已经通过认证并获得许可的容器资源优先。
• 如果容器已经声明某个路径但验证失败，客户端不会悄悄改读旁边的同名普通文件，避免受保护内容被无提示替换。
• 未安装 ChaAssets 时，客户端会忽略 .chaassets 文件；ChaUI 和其他消费者仍按原有方式读取普通文件。

因此可以先保留普通文件完成页面调试，再逐步把正式素材打包。需要回退时也不必修改页面 yml，只要确保希望读取的资源在当前环境中确实可用。

未连接服务器时如何加载页面素材 ​

标题主菜单、单人游戏、多人游戏列表和选项页面会在尚未连接服务器时出现。这类页面不能等待服务器临时下发许可，应该使用项目创建时选择的 BOOTSTRAP 资源。

客户端下载并保存这类 .chaassets 后，可以在启动游戏和未连接服务器时直接从本地读取。后续使用 ChaUI 全局本地页面包替换主菜单等原版页面时，这类资源不会因为尚未进服而缺失；服务器更新页面包的能力应以对应 ChaUI 版本的功能说明为准。

SESSION 更适合仅在某个服务器中使用的界面与素材。玩家必须连接目标服务器并获得有效授权后才能读取。页面配置无效、素材缺失或授权不可用时，ChaUI 应沿用安全回退行为，不能让玩家失去进入游戏或返回原版页面的能力。

常见错误 ​

构建提示混用了两种目录结构 ​

打开 ZIP，决定使用直接结构还是保留项目根结构，然后把所有资源统一到一种形式。不要同时保留 ChaEngine/model/... 和 model/...。

构建提示路径不安全 ​

检查 ZIP 内文件名是否包含绝对路径、盘符、反斜杠、.. 或控制字符。资源路径统一使用 /，并确保每一级目录都有正常名称。

构建提示文件、总大小或压缩率超过限制 ​

删除无关备份、重复素材和临时文件，确认没有把整个游戏目录或其他大型文件一起压入 ZIP。对本身已经高度压缩的异常文件重新导出后再上传。

ZIP 上传完成但显示文件损坏或无法读取 ​

在本地用常见压缩软件测试解压。若无法完整解压，重新从原始资源目录创建 ZIP，不要上传分卷压缩包或只修改扩展名的其他格式。

页面找不到 .chaassets ​

确认文件位于当前实际启动的游戏版本目录，而不是另一个实例；再检查是否放在 resourcepacks/ChaUI/ 或项目对应资源根中，并保留 .chaassets 扩展名。

安装后仍只读取普通文件 ​

确认 ChaAssets 已在客户端正常加载，并检查容器资源根是否与项目一致。SESSION 资源还需要当前服务器身份已配对、对应版本已启用，并在保存配置后完成过一次服务器重启。

未安装 ChaAssets 时加密素材不显示 ​

这是预期行为。未安装 ChaAssets 的客户端会忽略 .chaassets，但普通文件仍能使用。如果页面必须兼容这类客户端，需要继续分发对应普通素材；如果素材必须受保护，则要求使用者安装 ChaAssets。

配对码不存在或已经过期 ​

关闭当前弹窗，重新点击“添加服务器”并立即执行新命令。示例中的 J7K9-P2MX 只是演示，不能用于真实配对。

首次配对时服务器无法访问平台 ​

检查服务器配置中的平台地址、DNS、HTTPS 出站网络和系统时间。配对本身需要一次短请求；网络修复后可以直接生成新的配对码重试。

启动时提示平台暂时不可用 ​

已经成功启动过的身份会尝试使用上一次验证通过的本地快照。先观察后续日志是否显示快照已载入；如果是，本次运行可以继续，不需要频繁重启或反复保存授权。

新服务器启动后没有加密资源 ​

全新身份还没有本地快照时，首次启动检查必须成功一次。确认平台网络恢复后正常重启服务器；服务器会保持可运行，只是检查成功前不会开放加密资源。

集群中只有部分子服应用了新授权 ​

共享 keys 不代表配置会运行期推送。每个节点都要在网页保存配置后分别重启；没有重启的节点继续使用自己的本次启动快照。

删除服务器后运行中的节点仍能使用资源 ​

这是启动时生效设计的正常结果。运行中的节点不会被平台远程中断；它在下一次能联系平台的启动检查中取得撤销结果。

安全建议 ​

• 默认让不同服务器使用独立身份；只有同一管理边界内完全受信任的子服集群才共享完整 keys。
• 妥善备份服务器的整个 plugins/ChaAssets/keys/ 文件夹，不要只备份其中单个文件。
• 正式资源使用新版本发布，保留旧版本以便客户端平稳回退。
• 服务器停用后及时在网页停止资源授权并撤销或删除身份，记得变更在下次启动检查时生效。
• 不要把数据库密码、服务器令牌、账号凭据等真正机密放进任何客户端资源。
• 全部 keys 丢失时创建新服务器身份，不使用密钥恢复或轮换流程。

完成这些步骤后，ChaUI 仍使用原来的相对资源路径，而正式素材可以从经过平台认证的 .chaassets 中读取。之后新增其他客户端资源消费者时，也可以复用同一套项目、版本、服务器身份和授权流程。