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

# 故障处理与安全迁移

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

## 常见状态

| 现象 | 处理 |
| - | - |
| 页面过期、订单数量或价格变化 | 重新打开订单再确认，不绕过版本检查 |
| `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` | 检查有效节点租约、开放订单、冻结资金、待核对操作及托管/交付中的物品；不要删除记录绕过检查 |
| 许可证进入退出模式 | 保留查询、取消和资产退出，核查凭据、到期与网络绑定 |

## 核对 UNKNOWN

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

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

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

可用 `/km admin <玩家UUID或在线名>` 交叉检查同一玩家的钱包、资产全部状态、订单和历史。离线玩家使用完整 UUID；名字仅解析本服在线玩家。`kitemarket.audit.all` 提供只读审计，`kitemarket.manage` 另行允许管理操作；管理写入必须选择明确目标、填写原因并确认，结果保留审计。

资金补偿消耗管理员实际已有资金，物品操作使用真实持有物或已有资产，不提供任意造币或改写余额的入口。核对未知操作仍需真实执行证据，不能用一笔补偿掩盖原操作。证据页只展示可解释字段，缺失的历史资料会明确标注，不以原始序列化内容代替结论。

## 备份与迁移

迁移前停止所有旧节点的市场写入，妥善处理或登记未完成操作。备份完整数据库、`plugins/KiteMarket/`、匹配 JAR，以及玩家、世界和外部经济插件数据。网络身份、币种定义、钱包、订单、托管物品及操作记录必须作为同一环境检查点保留。

v1.1 新建单服默认使用独立 SQLite；多服共享使用 MySQL／MariaDB 的 InnoDB 数据库。SQLite 要通过一致性备份或正常停服、完成 checkpoint 后取得副本。运行中的 `-wal`／`-shm` 可能包含未合入主文件的状态，不要只复制主文件或删除这些文件来绕过检查。离线导入和迁移工具要求来源已经停服、完成 checkpoint 且无 sidecar。

GUI 偏好位于 `km_ui_preferences` 和 `km_ui_theme_selections`，按网络＋玩家 UUID 保存后端或主题 ID 与数据库更新时间。两种存储模式都要纳入备份；共享模式使用 InnoDB。没有偏好记录为 `AUTO`，没有主题记录使用所选后端的服务器默认主题。旧主题 ID 保留读取，缺少对应主题时回退，不改写原偏好。

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

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

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

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

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

### 离线导入与存储迁移

从 zAuctionHouse 导入时只读取停服副本，先审核预检、币种映射与真实物品，再确认报告摘要。已有 v1.1 SQLite 市场也可通过离线工具迁到空的共享数据库，保留原网络身份，不与另一市场合并。

> **[离线导入与存储迁移](https://www.kitemc.asia/kitemarket/operations/importing.md)**
>
> 分开了解来源副本、维护暂停、逐项导入，以及 SQLite 转共享数据库的步骤。

## v1.1 安装与已有数据准备

v1.1 以全新安装交付，不承诺 v1.0.0 直接换包或无缝升级。新市场使用独立目录和新数据库，运行包见[下载页](https://www.kitemc.asia/kitemarket/download.md)，日常流程见[使用指南](https://www.kitemc.asia/kitemarket/guide.md)。

已有数据先按以下步骤准备独立副本：

1. 正常停止全部旧节点，备份完整数据库、各节点的 `plugins/KiteMarket/`、旧 JAR，以及玩家、世界和经济插件数据，验证同一时间点的完整环境检查点可还原。
2. 副本使用独立数据库、目录和端口；不连接生产经济数据或修改生产授权绑定。保留原网络、币种、物品配置、游戏版本及授权文件，先检查副本中的配置、钱包／冻结、订单、领取资产和未决操作。
3. 在副本核对迁移前后数据、实际领取和恢复流程，再制定原环境的切换与回滚步骤。仅有启动成功不足以证明可用。

v1.1 保留协议 `4`／结构 `1` 到协议 `5`／结构 `2` 的迁移机制：检查旧结构、节点租约和身份，在写入前备份完整 `km_*` 数据至 `plugins/KiteMarket/backups/database-upgrade/`，并保留资产及旧节点围栏。已有 MySQL/MariaDB 连接不会被切换成空 SQLite 库；配置、语言和主题需要按实际文件核对。这些保护不是完整旧环境已通过迁移的保证。

备份失败、旧资产表或字段缺失、旧节点仍活动时停止迁移，保留原数据，不用空表或另一数据库继续。未决操作保留核对路径，不自动退款或补发。回滚必须全网停服，核对变更后的资产，再恢复同一完整备份及匹配配置与旧包；不能只换回旧 JAR。

下方协议1–3到4的步骤属于历史迁移流程，不是 v1.1 新安装步骤。

## 升级已有市场到协议 4

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

已有协议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 接到已经发生新交易的数据库。

### 原始快照与属性比较

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

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

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

### 支持名单收紧与已有资产

新交易以当前构件的物品准入和序列化往返检查为准。v1.1 可以保存已通过检查的特殊物品与容器，并提供只读容器预览；不能沿用早期只有基础类型和附魔书的支持名单，也不能据此认定所有特殊物品均可交易。

ItemsAdder、Oraxen、Nexo、MMOItems 的公共 API 身份桥接用于识别真实来源与业务 ID，不代替完整属性比较或保真检查。精确样品也不能绕过准入。看到 `UNVERIFIED_SPECIAL_ITEM`、`UNVERIFIED_ITEM_DATA` 或 `ITEM_ROUNDTRIP_UNSAFE` 时保留原因并停止发布，详见[物品准入与保真](https://www.kitemc.asia/kitemarket/trading/items.md)。

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

## 最小验证清单

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

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

## 开发者只读接口

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

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

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

### 扩展服务与玩家确认请求

v1.1 另外提供 `KiteMarketExtensions` 和 `KiteMarketRequests` 服务，原 `KiteMarketApi` 的只读语义保持不变。

| 服务 | 用途与边界 |
| - | - |
| `KiteMarketExtensions` | 注册经济、真实物品身份、只读容器预览、交易规则／复核和通知提供者；所属插件停用后自动卸载 |
| `KiteMarketRequests` | 请求报价、打开宿主确认页或丢弃未提交报价；没有远程确认或提交入口 |

交易规则和复核扩展只能拒绝请求，不能改价、换收款人或替换真实物品。经济调用沿用核心执行许可、操作编号与精度；扩展不能绕过资产保护。提供者状态变化后应调用 `changed(owner)`，让原报价失效。

报价绑定所属插件、玩家会话、订单与规则版本及有效期。发布、购买、供货、竞拍和撤单仍由玩家在 KiteMarket 保护的确认页手动确认，并再次检查真实背包和当前状态。`PENDING_REVIEW` 不可当作失败自动重试。签名、线程约束和最小示例见[市场 API](https://www.kitemc.asia/kitemarket/api.md)。


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