性能与运维建议
大量物品 / 高人数服务器下，QI 的加载、刷新、缓存如何调优与运维。
一、加载与重载
- 物品 / 段 / 套装 / 动作表在启动和
/qi reload时加载。重载会重新编译全部内容并热刷新在线玩家。 - 大量物品时，
/qi reload有一次性开销（编译 + 校验 + 刷新）。建议：- 高峰期避免频繁
reload；改完批量一次重载。 - 用
/qi reload而非重启，热刷新更快。
- 高峰期避免频繁
- 编译结果有 LRU 缓存（
CompileSessionStore，最多 4096 条，按物品指纹），重复装配命中缓存。
二、装备属性同步开销
属性同步由 EquipmentWatcher 驱动，已做去抖：
- 比对「装备签名」，变了才刷新，避免每 tick 重算。
- 轮询周期约 1 tick 调度，但实际刷新只在装备变化时发生。
优化点：
- 避免做「每 tick 强制
refreshEquipmentAttributes」的外部逻辑，让 watcher 自己按需刷新。 - 套装件数变化有额外的延迟刷新（约 1 秒），属正常去抖。
三、动作触发开销
- 触发有 120ms 去重窗口（
ActionTriggerDedup），防一次操作多次触发。 - 冷却存内存（
ConcurrentHashMap），重启丢失——这是设计，不持久化。 tick周期触发由TickHandTicker每 20 tick 调度，作用于手持 / 装备物品。别配过密的 tick（如每 1 tick），按需用tick: 40（2 秒）等。
四、常驻效果与套装
PermEffectSync每约 6 秒（120 tick）续期常驻药水效果；这是低频任务。- 套装属性掉到阈值下会自动移除
qi:set:<id>源。
五、刷新命令的范围控制
需要让玩家身上旧物品按新配置重渲染时，按需选范围，别动辄全服全刷：
| 命令 | 范围 | 何时用 |
|---|---|---|
/qi refresh hand | 仅主手 | 自测最快 |
/qi refresh equipment | 装备槽 | 改了装备相关 |
/qi refresh inventory | 背包 | 改了背包物品 |
/qi refresh all | 全部在线玩家 | 大改后统一刷，人多时谨慎 |
刷新 = 每件 rebuild() + variables().refresh()，物品越多越重。见 诊断排错 §6。
六、写域 / 路由严格模式
config.yml：
write-domains.strict: true、action-routing.strict: true是默认且推荐：把潜在错误在保存 / 加载时变成硬错误，避免运行时隐患。- 仅在迁移 / 调试期临时设
false（降级为警告），稳定后改回true。
七、内容包与备份
- 用
/qi packs export定期导出内容包，作为内容快照备份 / 跨服分发。 - 物品 / 套装 / 段都是纯 YAML，直接纳入你的配置版本管理 / 定时备份即可。
见 导入导出实操。
八、监控清单
定期 / 上线后检查：
- [ ]
/qi diagnose—— 子系统全可用（N/M 中 N=M） - [ ]
/qi problems—— 无未处理问题 - [ ] 启动日志 —— 属性后端 / 宝石后端按预期接入
- [ ] 高峰期
/qi reload频率受控
九、容量规划经验
| 规模 | 建议 |
|---|---|
| 物品数百 | 默认配置足够 |
| 物品上千 | 避免高峰 reload；用内容包分包管理；关注 reload 耗时 |
| 高人数（数百在线） | 让 watcher 自管属性刷新，避免外部每 tick 强刷；tick 触发间隔放宽 |