兼容性、安装与首次启动

环境矩阵

项目	支持范围	说明
Java	21	其他主版本会被 `/sa doctor` 判为不支持。
Paper / Purpur	1.21～1.21.11	编译基线是 Paper API 1.21.4。范围内仍要按实际构建验收。
Leaf	1.21.4～1.21.11	1.21.4 是完整功能/性能基线，但该分支已停止维护。
Folia	不支持	`plugin.yml` 没有 `folia-supported: true`。
MythicMobs	可选，5.x	编译 API 为 5.12.1；其他主版本不承诺。
PlaceholderAPI	可选	缺失时只关闭占位符。
DecentHolograms	可选	`required: false` 时缺失只关闭全息。
数据库	SQLite 或 MySQL	不支持其他数据库和自动跨后端迁移。

获取或构建 JAR

生产服优先使用项目维护者明确交付的主运行 JAR，并记录 SHA-256。当前源码没有可据以承诺的公开下载地址，不要从不明网盘获取。

从源码构建需要 JDK 21：

powershell

cd D:\path\to\SealAttributes
.\gradlew.bat clean check --rerun-tasks
Get-FileHash .\sealattributes-paper\build\libs\SealAttributes-1.0.9.jar -Algorithm SHA256

预期：Gradle 输出 BUILD SUCCESSFUL；主运行 JAR 位于 sealattributes-paper/build/libs/。以下文件不能放入生产服 plugins/：API JAR、adapters 子模块、文档 JAR、performance probe、compatibility probe、Douluo verification probe。

安装步骤

正常停止服务器，确认 Java 21：java -version。
把且只把 SealAttributes-1.0.9.jar 放入 plugins/。
若有可信扩展 JAR，先不要安装；先让核心插件单独完成首次启动。
启动服务器，等待控制台出现插件启用和 storage ready 信息。
登录后执行 /sa doctor、/sa stats、/sa health <玩家>。
正常停止一次，确认日志含 storage stopped: drained=true。

不要使用 Bukkit /reload、PlugMan 或同类热替换工具。它们不会遵守 owner epoch、数据库队列和扩展类加载器生命周期。

首次生成的目录

text

plugins/SealAttributes/
├─ config.yml
├─ attributes.yml
├─ combat.yml
├─ sources.yml
├─ display.yml
├─ gui.yml
├─ messages.yml
├─ database.yml
├─ datasource.yml          # TabooLib 内部桥接，不要编辑
├─ storage/
│  └─ sealattributes.db    # 默认 SQLite，启动后创建
└─ extensions/             # 可信启动扩展 JAR

八份业务 YAML 都是严格配置。未知键、错误类型、越界值、固定字段被改动或缺少必需消息都会拒绝候选配置。datasource.yml 不是第九份业务配置。

默认最小可用状态

首次启动无需修改 YAML：默认 SQLite、权威战斗、结构化 PDC 装备读取、GUI、全息（非必需）和诊断均启用。没有 PlaceholderAPI/DecentHolograms/MythicMobs 时，核心仍应启用。

验收清单：

/sa version 显示插件、API baseline 与平台信息；
/sa doctor 的 Java、服务器版本、数据库为正常；
/sa stats 打开七类属性 GUI；若 GUI 被关闭，会提示改用 inspect；
/sa inspect <自己> sealattributes:max_health 能返回属性；
/sa health <自己> 能显示当前生命和 Paper 最终有效最大生命；RPG max_health 用 inspect 查看；
plugins/SealAttributes/storage/sealattributes.db 存在；
停服时存储队列成功排空。

首次启动失败怎么判断

现象	最常见原因	处理
插件直接停用	Java/服务端不兼容、配置校验、数据库启动、扩展失败	从第一条 `SealAttributes` 错误开始读；不要只看最后的 disable。
MySQL 启动失败	网络、账户权限、TLS、公钥或备份确认	先用数据库客户端从同一主机验证，再查数据库配置。
`stats` 显示未就绪	玩家数据仍在预载或预载失败	`/sa doctor <玩家>`；检查数据库和队列，而不是反复重登。
没有全息	未装 DecentHolograms 或插件不可用	默认 `required: false`，这是降级而非核心故障。
装备没属性	物品不是有效 JSON PDC、槽不支持或模式错误	用 `/sa item inspect`，再读装备与物品数据。

安装扩展或切换 SealItems 前

这两类变更都必须完整停服：

扩展只在启动时扫描 extensions/*.jar，不支持热加载；
SealItems 接管装备 provider 后，built-in-equipment-reader.enabled 不能靠热重载切换。

下一步：从零服主实战。

兼容性、安装与首次启动 ​

环境矩阵 ​

获取或构建 JAR ​

安装步骤 ​

首次生成的目录 ​

默认最小可用状态 ​

首次启动失败怎么判断 ​

安装扩展或切换 SealItems 前 ​