> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障处理与安全迁移

<span id="故障处理与安全迁移" />

处理资金或物品问题时先保留操作 ID、玩家 UUID、节点、时间、订单 ID 与错误代码。先暂停相关写入并核查，避免同一请求被反复提交。

<h2 id="常见状态">
  常见状态
</h2>

| 现象 | 处理 |
| - | - |
| 页面过期、订单数量或价格变化 | 重新打开订单再确认，不绕过版本检查 |
| `INVENTORY_FULL` | 物品仍在领取箱；腾出背包空间后再领取，不要在世界里补发同一物品 |
| `GATEWAY_NODE` | 切换到该货币配置的充提节点 |
| `UNCERTIFIED_PROVIDER_VERSION` | 核对实际插件版本并完成测试；不直接添加未知版本 |
| `PROVIDER_API_INCOMPATIBLE` | 停用充提，确认 provider 与发行版；不要用其他适配器顶替 |
| `UI_BACKEND_RETIRED` | 已保存的后端偏好或主题没有实际提供者；保留偏好并回退原版，可在 `/km ui` 改选原版或 IA |
| `IA_PACK_NOT_REGISTERED` / `IA_PACK_NOT_APPLIED` | 核对实际下发的 UUID、SHA-1与玩家成功加载；可临时启用 `gui.itemsadder.diagnostics`，不把无关包或仅接受状态当作就绪 |
| `DLC_NAMESPACE_CHANGED` / `DLC_INSTALLED_PACKAGE_INVALID` | 旧主题数据校验失败。保留命名空间和备份，不删除目录绕过校验；可改选原版或自己的 IA 主题，主题问题不影响市场资产 |
| `UNKNOWN` | 停止重放，查操作详情和外部证据，由管理员确认结果 |
| `EXECUTION_IN_FLIGHT` | 来源节点仍活跃且调用尚未确认结束，不能退款或补发；先等待真实完成回执或处理来源节点 |
| `SOURCE_QUIESCENCE_REQUIRED` | 来源离线不代表调用已经停止；核实停止来源及外部请求不再在途后，才在单独声明页继续确认 |
| `EXECUTION_WINDOW_EXPIRED` | 该次执行许可启动窗口已过，未开始新的扣物/发物/经济调用；先检查操作结果，再重新确认 |
| 数据库不可用 | 恢复数据库后再开放；禁止让不同节点独立继续成交 |
| `NODE_ALREADY_RUNNING` | 检查是否重复使用节点 ID；正常停服后的短暂租约等待不等于资产丢失 |
| `NODE_FENCED` | 本节点已失去写入租约；核查重复节点和旧进程后重启，不让旧节点自动抢回身份 |
| `UNVERIFIED_SPECIAL_ITEM` / `UNVERIFIED_ITEM_DATA` | 该类型或属性尚未进入新交易支持名单；精确样品不能绕过准入，已有托管资产仍可安全退出 |
| `PROTOCOL_UPGRADE_REQUIRES_EXIT` | 先用旧构件完成授权清退，不能在开放市场直接升级协议 |
| `PROTOCOL_UPGRADE_NOT_QUIESCENT` | 检查有效节点租约、开放订单、冻结资金、待核对操作及托管/交付中的物品；不要删除记录绕过检查 |
| 许可证进入退出模式 | 保留查询、取消和资产退出，核查凭据、到期与网络绑定 |

<h2 id="核对-unknown">
  核对 UNKNOWN
</h2>

1. 用 `/km inspect <操作ID>` 查询参与玩家、金额/物品、来源节点、会话与执行阶段；查看物品摘要和该操作的管理修复前后记录，保留外部日志或交易凭证。
2. 分清操作是在外部执行前失败、已经生效，还是证据不足。`UNKNOWN` 不等于失败，也不等于可以再扣一次。
3. 使用[管理员命令](/kitemarket/commands)明确登记成功或失败及原因。证据不足时继续保留，不通过直接改钱包值掩盖差异。
4. 检查余额冻结、领取区和审计记录，再通知玩家结果。

`PREPARED` 仍是准备／执行中的记录，只能查看和刷新，不能提前登记为成功或失败。执行许可、调用返回和最终账本状态分别展示；有结束回执也不等于外部结果已足够确定。经济调用超时后不会重复提交原调用，迟到回执只补充核对证据、保留 `UNKNOWN`，不会自动入账、退款或补发。

执行未确认结束、且来源节点仍活跃时，`EXECUTION_IN_FLIGHT` 会阻止核对，即使管理员选择失败也不能释放资产。来源离线后若缺少结束回执，系统要求单独声明：已停止来源节点，并核实外部经济请求不再在途。只有明确点击声明并再次确认结果后才能登记，声明与处理原因进入审计；租约失效、玩家当前余额或“等了一会”都不能替代这些核验。

可用 `/km admin <玩家UUID或在线名>` 交叉检查同一玩家的钱包、资产全部状态、订单和历史。离线玩家使用完整 UUID；名字仅解析本服在线玩家。这里是只读审计入口，不提供代领、改余额或通用发币操作。证据页只展示可解释字段，缺失的历史资料会明确标注，不以原始序列化内容代替结论。

<h2 id="备份与迁移">
  备份与迁移
</h2>

迁移前停止所有旧节点的市场写入，妥善处理或登记未完成操作。备份完整数据库和 `plugins/KiteMarket/` 配置；网络身份、币种定义、钱包、订单、托管物品及操作记录必须一起保留。
GUI 偏好位于独立 InnoDB 表 `km_ui_preferences` 和 `km_ui_theme_selections`，均按网络＋玩家 UUID 保存模式或主题 ID 与数据库更新时间。没有偏好记录为 `AUTO`，没有主题记录使用所选后端的服务器默认主题。启动通过迁移入口创建，不改变金融表结构版本或快照格式 2。使用固定表清单的备份／恢复工具要纳入两表；不要只迁移金融表而遗漏玩家选择。旧主题 ID 保留读取，缺少对应主题时回退，不改写原偏好。

恢复时先在隔离环境验证数据库和插件，再逐个接入节点。服务器 Minecraft 版本、市场协议、物品配置与币种定义要一致；每个节点 ID 保持唯一。确认旧节点不会继续写入后再开放新网络。

当前数据库模式版本为 1，启动会校验该值和 InnoDB 引擎。升级前先清查未结束订单、领取资产和 `PREPARED`/`UNKNOWN` 操作，再备份并在隔离库验证。没有已定义的跨模式自动降级流程，不能用旧 JAR 或部分恢复绕过版本检查。
更换插件 JAR 时仍需全网正常停服、完整备份并统一构件；只有界面改动时，不需要协议升级或清空现有资产。默认采用暖色布局，旧自定义槽位自动使用兼容布局，无效候选保持当前设置。自动顺序为 IA→原版，默认不指定 IA 主题；旧偏好和配置不自动重写。第三方主题无需额外的 KiteMC 主题授权，已有实测范围见[兼容说明](/kitemarket/compatibility)。

如果数据库中已有 `km_dlc_proofs` 等扩展表，仍纳入完整 `km_*` 备份／恢复。已安装的主题资源、证明或密文缓存应随对应构件备份，不自动删除或混用旧加载器。密钥缓存属于私有运维数据，不能放入公开下载。

第三方主题从 `plugins/KiteMarket/themes/` 加载，迁移需保留主题声明和各自资源。用 `/km ui` 查看实际界面与回退原因；资源包内容改变后，登记新的实际下发 UUID 和对应 SHA-1，再 `/km reload`。同一已登记 UUID 换摘要会被拒绝。主题不可用只影响呈现，不撤单或释放市场冻结资金；具体步骤见[ItemsAdder 接入](/kitemarket/dlc)和[界面 SDK](/kitemarket/ui-development)。

不要只恢复订单表，不要只回滚某一节点配置，不要把生产库同时接到克隆测试服。货币精度或外部后端变化需专门对账迁移。跨 Minecraft 版本转换不属于首版能力。

<h2 id="升级已有市场到协议-4">
  升级已有市场到协议 4
</h2>

协议4构件保存出售订单的最低购买量，出售仍使用每件单价、部分购买，拍卖按整标总价。协议由构件确定，不能混用节点或通过热重载切换。数据库模式版本为 `1`，物品快照格式为 `2`，网络授权使用 HTTP v2；这些编号分别检查。新市场无需迁移字段。具体实测范围以[兼容说明](/kitemarket/compatibility)为准，升级规则不等于所有组合已经通过验收。

已有协议1、2或3市场均采用以下严格升级步骤，不保留开放订单或托管交易：

1. 用旧构件清查钱包、领取箱、开放订单和 `PREPARED` / `UNKNOWN` 操作。先核对未知副作用，不能盲目补发或退款。
2. 通过已验证的授权清退流程进入 `EXIT_ONLY`，等待未成交订单、拍卖、冻结资金和托管状态全部清退。可用钱包余额与待领物品可以保留。
3. 正常停止所有节点，备份完整 `km_*` 数据、各节点 `plugins/KiteMarket/` 和原 JAR，验证可还原，并等待所有节点租约失效。
4. 首个节点显式配置实际来源 `network.upgrade-from-protocol: '3'`；实际来源为1或2时分别填写 `'1'` 或 `'2'`。将所有节点替换为协议4构件，保持 Minecraft 版本、币种、`network.name`、`network.item-profile` 一致。来源协议必须准确，不能同时修改币种或物品环境。
5. 先启动一个节点。升级只在旧身份完全匹配、市场为 `EXIT_ONLY`、无有效节点租约、开放订单、冻结资金、`PREPARED` / `UNKNOWN` 操作，以及 `ESCROW` / `DELIVERING` 物品时进行。身份更新、全部旧节点代次和会话失效、`PROTOCOL_UPGRADE` 审计在同一数据库事务提交，保留网络 UUID、授权绑定、可用钱包、待领快照及历史。租约过期但仍存活的旧节点不能重新心跳或取得会话。
6. 验证 UUID、余额、待领资产和授权后，移除临时升级字段，再启动其他新节点。授权恢复后可重新开放市场；已清退订单不会复活。

检查失败时保留记录并排查，不篡改身份摘要或数据库租约。旧构件接入已升级网络会被拒绝。协议4没有自动降级路径；回滚须全网停服，核对升级后资产变化，再恢复同一时间点的完整数据库及匹配配置/JAR。不能把旧 JAR 接到已经发生新交易的数据库。

<h3 id="原始快照与属性比较">
  原始快照与属性比较
</h3>

新物品快照格式为 `2`。`data` 保存服务器产生的原始字节，`rawDigest` 单独校验完整性；属性比较的 `fingerprint` 忽略数量。原有格式 `1` 快照不自动重写，仍保留原摘要校验和资产退出。

属性比较只忽略 typed-NBT compound 的字段键序，以及旧版根 `tag.Enchantments` / `tag.StoredEnchantments` 中具有唯一字符串 `id` 的原版附魔条目顺序。名称、Lore、其他列表（包括 PDC 列表）、数据类型、数值、字符串和数组内容仍参与比较。损坏、歧义或超出解析预算的数据会拒绝，不退回宽松匹配。

比较不会改写实际托管物品；领取仍还原原始快照。原始字节完整性与属性等价是独立检查，也不开放玩家自定义 NBT 表达式。[验证记录](/kitemarket/compatibility)列出准确构件和场景。

<h3 id="支持名单收紧与已有资产">
  支持名单收紧与已有资产
</h3>

新交易目前只接受经过样本验证的基础 `UNSPECIFIC`、附魔书 `ENCHANTED` 类型和已验证属性键。药水、书、头颅、地图、特殊盔甲及其他未验证类型会明确拒绝；精确样品不能绕过这道准入。PDC 等已经验证、但高级条件无法解释的数据仍需精确样品。

准入只限制新增样品、发布、供货与托管。已有物品的还原、撤单返还、清退和领取保留，继续检查快照格式、摘要与来源游戏版本；不能因支持名单收紧销毁或永久锁住旧资产。类型准入也不等于整个版本、跨服或经济组合已认证，实际范围见[认证状态](/kitemarket/compatibility)。

<h2 id="最小验证清单">
  最小验证清单
</h2>

使用隔离测试玩家和少量测试资产覆盖收购、一口价、竞拍、双节点同时操作、充提、满背包领取和重启恢复。测试完回收测试资产与记录，保留有用的验收结果。详细平台范围见[认证状态](/kitemarket/compatibility)。

上述清单适用于新环境启用或相关功能改动。界面更新还应检查导航、草稿、金额输入、资源包拒绝／失败和第三方主题回退。使用隔离角色与订单，不重置现有玩家资产。

<h2 id="开发者只读接口">
  开发者只读接口
</h2>

`com.kitemc.market.api.KiteMarketApi` 在数据库初始化成功后通过 Bukkit `ServicesManager` 注册。独立 Java 11／MIT SDK 提供网络 ID、币种精度、订单、钱包、领取资产和历史的不可变白名单摘要；没有公开规则匹配、发币、远程充提或通用交易写接口。安装与签名见[市场 API 入门](/kitemarket/api)。

查询返回 `CompletableFuture`；不要在游戏主线程或 Folia 玩家线程上调用 `join()`/`get()`。原始审计 JSON、物品字节、执行令牌、许可证和恢复证据不外发，返回列表与嵌套对象不可变。读取玩家/背包或更新界面需调度到正确的玩家上下文。

`MarketCommittedEvent` 仅通知已提交的购买、供货和竞拍胜出，是不可取消的异步事件，返回 `TradeSummary` 而非原始 JSON。监听者按网络 ID 和事件 ID 去重，并将玩家操作调度到对应 Entity Scheduler。通知可能延迟，启动前历史不补发，也不是恰好一次或可靠补发接口；消费者应查询权威状态。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.