HN 系列 Wiki

主题

这页专门回答一个问题：

HNEconomy 出问题时，到底该先查什么、后查什么，才能最快定位？

如果你已经开始正式上线使用， 这页会比“把所有命令都背下来”更有用。

一、先记住一个总原则 ​

排障时不要一上来就：

  • 乱改配置
  • 乱重载
  • 先怀疑数据库坏了
  • 直接手改余额表

HNEconomy 最稳的排障顺序应该是：

text
启动与依赖
→ 货币定义
→ 余额与流水
→ 玩家交互
→ 系统资金池
→ 归档清理
→ 外部集成

也就是说：

  • 先排底层
  • 再排业务层
  • 最后排集成层

这样最不容易误判。

二、10 秒快速判断：问题大概在哪一层 ​

现象 1：插件直接起不来 ​

优先看：

  • HNCore 是否正常启用
  • HNCore 共享数据库是否可用
  • main-currency 是否有效

这通常是：

  • 基础设施层
  • 启动配置层

现象 2：插件能启动，但命令说货币不存在 ​

优先看：

  • currencies.yml
  • main-currency
  • 货币是否启用

这通常是：

  • 货币定义层

现象 3：余额不对 / 玩家说钱不见了 ​

优先看：

  • /hneco balance
  • /hneco log
  • /hneco logsearch
  • /hneco logarchive

这通常是：

  • 账务层
  • 运维查询层

现象 4：/money 正常，但 /pay 失败 ​

优先看：

  • pay.enabled
  • pay.require-permission
  • 金额限制
  • 拒收状态
  • 手续费与总支出

这通常是：

  • 玩家交互层
  • 风控规则层

现象 5：系统资金池数字不对 ​

优先看：

  • /hneco treasury stats
  • /hneco treasury log
  • 手续费是否开启
  • 系统资金池是否启用

这通常是：

  • 系统资金池层
  • 手续费归集层

现象 6：老记录查不到 ​

优先看：

  • /hneco status
  • cleanup.ledger.*
  • /hneco logarchive
  • /hneco exportarchive

这通常是：

  • 归档清理层

现象 7：Placeholder / Vault / 商店接入不对 ​

优先看：

  • 对应插件是否安装
  • 对应开关是否开启
  • 是否已经回到底层验证过余额 / 流水本身没问题

这通常是：

  • 外部集成层

三、最推荐的标准排障顺序 ​

第 1 步：先确认插件是否正常启动 ​

先确认：

  • HNCore 已启用
  • HNEconomy 已启用
  • 没有共享数据库不可用错误
  • 没有主货币无效错误

如果这一步就不通过，后面很多问题都不用继续查。

第 2 步：确认主货币和货币定义 ​

检查：

  • config.yml 的 main-currency
  • currencies.yml 里是否存在该货币
  • 货币是否 enabled: true

再用：

text
/hneco currency list

确认运行时真的注册成功。

第 3 步：先查余额，再查流水 ​

排账务时永远不要只看余额。

推荐顺序：

text
/hneco balance <玩家>
/hneco log <玩家>
/hneco logsearch player=<玩家>

原因是：

  • balance 告诉你现在余额是多少
  • log 告诉你最近发生了什么
  • logsearch 告诉你能否按条件进一步缩小范围

如果主表里查不到，再继续查：

text
/hneco logarchive <玩家>
/hneco logarchivesearch player=<玩家>

第 4 步：定位是不是 /pay 规则问题 ​

如果玩家说“我有钱但转不了”，优先排这些：

  • pay.enabled
  • pay.require-permission
  • pay.allow-self
  • pay.min-amount
  • pay.max-amount
  • pay.daily-max-amount
  • pay.cooldown-seconds
  • pay.allowed-currencies
  • 收款方是否拒收
  • 手续费后余额是否仍足够

推荐命令：

text
/hneco paystat <玩家>

必要时再配合：

text
/hneco suspicious ...

第 5 步：确认系统资金池与手续费归集 ​

如果你怀疑手续费、税费、系统资金池入账不对，建议这样查：

text
/hneco treasury stats [货币]
/hneco treasury log [货币]
/hneco treasury trend [货币] [天数]

同时回看：

  • treasury.enabled
  • pay.fee.enabled
  • 低余额阈值配置

第 6 步：确认归档与清理是否影响了查询结果 ​

如果你发现：

  • 主流水查不到
  • 导出记录变少了
  • 很久以前的记录突然“像消失了一样”

优先看：

text
/hneco status

重点看：

  • 主流水表条数
  • 归档流水表条数
  • 最近一次清理结果
  • 归档保留天数

然后再确认：

yml
cleanup:
  ledger:
    archive-enabled: true
    retention-days: ...
    delete-after-archive: ...

最后用：

text
/hneco logarchive ...
/hneco exportarchive ...

验证旧记录是不是其实已经进归档表了。

第 7 步：最后再查外部集成 ​

这一步包括：

  • PlaceholderAPI
  • Vault
  • 商店接入
  • 拍卖接入

注意：

只有在余额、流水、系统资金池本身都已经正常时，外部集成排查才有意义。

否则你很容易把底层账务问题误判成集成问题。

四、按场景给出最短排障路径 ​

场景 A：插件启动失败 ​

最短路径：

  1. 看 HNCore 是否先启用
  2. 看共享数据库是否可用
  3. 看 main-currency 是否存在且启用
  4. 再看 currencies.yml 是否写错

场景 B：玩家说自己余额不对 ​

最短路径：

  1. /hneco balance <玩家>
  2. /hneco log <玩家>
  3. /hneco logsearch player=<玩家>
  4. 如果主表无记录，再查 /hneco logarchive <玩家>
  5. 如果怀疑具体业务，再查 logbiz / logarchivebiz

场景 C：玩家说转账失败 ​

最短路径：

  1. 看失败提示
  2. 查 pay 配置
  3. /hneco paystat <玩家>
  4. 查目标玩家是否拒收
  5. 查手续费后总支出是否超余额

场景 D：系统资金池余额异常 ​

最短路径：

  1. /hneco treasury stats
  2. /hneco treasury log
  3. 看 pay.fee.enabled
  4. 看 treasury.enabled
  5. 必要时导出系统资金池流水

场景 E：老记录查不到 ​

最短路径：

  1. /hneco status
  2. 看 cleanup.ledger.retention-days
  3. 看 delete-after-archive
  4. 查 /hneco logarchive
  5. 查 /hneco exportarchive

场景 F：Placeholder 显示异常 ​

最短路径：

  1. 确认安装了 PlaceholderAPI
  2. 确认 placeholderapi.enabled: true
  3. 确认你写的是 %hncore_economy_xxx%
  4. 确认货币 ID 正确
  5. 再回到底层检查余额 / 系统资金池统计本身是否正常

场景 G：Vault 接入不正常 ​

最短路径：

  1. 确认安装了 Vault
  2. 确认 vault.enabled: true
  3. 确认主货币正常
  4. 先用 HNEconomy 原生命令验证余额与流水
  5. 再回头看 Vault 插件侧行为

五、最有用的几条排障命令 ​

如果你是运维，最值得熟悉的是这几条：

text
/hneco balance <玩家>
/hneco log <玩家>
/hneco logsearch ...
/hneco logarchive <玩家>
/hneco paystat <玩家>
/hneco suspicious ...
/hneco treasury stats
/hneco treasury log
/hneco status
/hneco cleanup

这几条基本已经覆盖：

  • 账务确认
  • 交易追踪
  • 风控排查
  • 系统资金池运维
  • 归档清理

六、最容易误判的地方 ​

误判 1：只看余额，不看流水 ​

余额只是结果，流水才是过程。

误判 2：主表查不到就以为记录丢了 ​

当前版本有归档逻辑，老记录可能已经不在主表。

误判 3：/money 能看余额，就以为 /pay 一定能转 ​

查看余额和允许转账不是一回事。

误判 4：Placeholder 出错就直接怪 PlaceholderAPI ​

很多时候其实是：

  • 货币 ID 写错
  • 主货币没配好
  • 底层余额本身就不对

误判 5：看到系统资金池没变就怀疑手续费没收 ​

先确认：

  • 手续费是否开启
  • 当前货币是否允许转账
  • 这笔转账是否真正执行成功

七、推荐的运维查看顺序 ​

如果你是值班运维，比较推荐把 HNEconomy 的排障动作固定成下面这个节奏：

  1. 先确认插件和依赖正常
  2. 再确认货币定义正常
  3. 再确认余额和流水一致
  4. 再确认玩家规则是否限制业务
  5. 再确认系统资金池与手续费归集
  6. 最后确认归档和外部集成

长期来看，这样最省时间，也最不容易误操作。

推荐阅读 ​

HN 系列插件文档

Copyright © 2024