FAQ、术语速查与升级检查表

FAQ

可以只装 API JAR 吗？

不可以。服主只装 SealAttributes-<version>.jar 主运行 JAR。API JAR只给开发者 compileOnly。

支持 Folia 或 1.12.2 吗？

不支持。当前要求 Java 21 和 1.21.x 范围，plugin.yml 没有 Folia 声明。

为什么 /sa reload 成功但数据库地址没换？

后端、端点、连接池、worker 和队列容量要求完整重启。热重载只接受可安全切换的运行参数。

可以同时用内置装备读取和 SealItems 吗？

不应。会双算六槽属性。关闭内置 reader 后完整重启，并用 sources 证明只有 sealitems:*。

Lore 和 PDC 哪个好？

新服用 STRUCTURED PDC。Lore 是不可信迁移兼容层，一次只能启用其中一种读取模式。

ADD 15 和 TOTAL_PERCENT 0.15 有什么区别？

API 中前者固定加 15，后者把 AMOUNT 总体乘以 1.15。物品 JSON/Lore 的百分比写 15，解析后才变 0.15。

为什么上限提高，当前资源没自动充满？

设计如此：提高上限不赠送余额，降低上限会夹取。使用公开 fill/restore 由玩法显式决定。

能跨服共用 MySQL 吗？

可以把库放外部，但 V1 没有跨服在线会话权威和消息总线；不能让同一在线玩家在多个服同时写。

扩展能热更新吗？

不能。正常停服后替换 extensions/*.jar。错误扩展会让主插件拒绝启动。

环境伤害也走 RPG 防御吗？

不走。摔落、溺水、虚空、饥饿等保持服务端原版规则。

combat trace 是审计日志吗？

不是。它只保留参与者最近一次有界内存记录，重启清空，也不公开第三方扩展未上报的内部步骤。

术语速查

术语	一句话
provider	一个调用方绑定并独占的命名空间。
owner epoch	插件实例租约，禁用后旧句柄失效。
source	一个业务事实的稳定键。
snapshot	来源或主体在某修订的完整不可变状态。
revision	防止旧写覆盖新写的单调版本。
runtime	只在当前会话存在。
permanent	持久到数据库。
expires_at	带绝对到期时间的持久来源。
READY	持久数据与初始来源已装配。
fail closed	不确定时拒绝，不猜测通过。
effective	经过安全夹取/平台证明后真正用于消费的值。

升级检查表

升级前

• [ ] 阅读目标版本 changelog、known limitations、API baseline；
• [ ] 记录旧主 JAR SHA、八份配置、扩展、服务端、Java、依赖版本；
• [ ] /sa database flush 后正常停服并确认 drained；
• [ ] SQLite 停服复制，或 MySQL 外部一致性备份；
• [ ] 在隔离环境完成一次真实恢复；
• [ ] 第三方 consumer/扩展对目标 API重新编译；
• [ ] 确认只替换主运行 JAR，不误装 probes/API/adapters。

隔离验收

• [ ] 启动迁移，无 future schema/backup confirm 错误；
• [ ] /sa version、doctor、database status 正常；
• [ ] 玩家登录 READY，永久来源、健康、资源恢复；
• [ ] 六槽或 SealItems 七来源不双算；
• [ ] 近战、投射物、技能、治疗、恢复、死亡/重生；
• [ ] PAPI、全息、MythicMobs 用实际版本验证；
• [ ] /sa reload 成功/失败回滚各测试一次；
• [ ] 正常停服 drained，端口与文件释放。

上线与回滚

• [ ] 维护窗口内再次备份；
• [ ] 部署与隔离环境同 SHA 的 JAR/配置；
• [ ] 冒烟完成再开放流量；
• [ ] 监控 DB queue、rejection、TPS/MSPT、全息 drop；
• [ ] 若 schema 已迁移，回滚同时恢复旧数据库和配置，不能只换 JAR。

本文档的版本纪律

每次发布应把“自动化测试”“MySQL 条件验证”“真实 Minecraft 服务器验证”“正式交付/部署”分开记录。某个旧版本在 Leaf 上跑过，不证明后来工作树的 JAR也跑过；某次 check 全绿，也不证明 MySQL 或线上依赖已参与。

下一步可回到 SealAttributes 首页 或使用顶部搜索按错误码、配置键、属性 ID 检索。