HN 系列 Wiki

主题

这一页讲的是 HNEconomy 最核心的价值：

它不是“只有余额”的插件，而是一套 余额 + 不可变流水 + 系统资金池 + 运维查询 + 归档清理 的经济账务系统。

1. 为什么要强调流水 ​

很多经济插件只有一张余额表。

这种方式的问题是：

  • 钱变了，但不知道为什么变
  • 出问题时很难查是谁改的
  • 无法追某一笔业务
  • 运营排查成本极高

HNEconomy 的设计原则是：

  • 所有余额变动都必须经过统一服务层
  • 所有余额变动都必须写一条数据库流水
  • 余额更新与流水写入必须在同一事务里完成

也就是说，系统追求的是：

  • 可追踪
  • 可检索
  • 可审计
  • 可运维
  • 可导出
  • 可归档
  • 可告警

这也是 HNEconomy 和很多“只负责存余额”的传统经济插件之间最明显的分水岭。

2. 一条流水会记录什么 ​

每条账务流水至少包含这些信息：

  • ownerType
  • ownerId
  • currencyId
  • changeAmount
  • beforeBalance
  • afterBalance
  • changeType
  • reasonText
  • sourceType
  • sourceId
  • businessId
  • operatorType
  • operatorId
  • operatorName
  • serverId
  • createdAt

这意味着后续你可以回答很多运维问题，例如：

  • 这笔钱是谁加的？
  • 是玩家行为、管理员命令、Vault 还是业务插件加的？
  • 原因是什么？
  • 是哪台服写进去的？
  • 这笔记录属于哪一次业务？

3. 为什么要区分 reasonText、sourceType、businessId ​

reasonText ​

给人看的明文原因，例如：

  • 管理员发放
  • 活动补偿
  • 玩家转账
  • 拍卖结算

sourceType ​

给系统与运维筛选用的来源类型，例如：

  • COMMAND
  • PAY
  • VAULT
  • SHOP
  • AUCTION

businessId ​

给某一笔业务打追踪标记，例如：

  • 某次转账
  • 某次结算
  • 某次店铺订单
  • 某次拍卖成交

这三者一起用，才能既方便人看，又方便程序查。

4. 系统资金池是什么 ​

当前版本里，系统资金池不是额外新造的一套账户逻辑，而是复用统一账户体系：

  • owner_type = SYSTEM
  • owner_id = TREASURY

这意味着：

  • 系统资金池也有余额
  • 系统资金池也能参与多货币
  • 系统资金池也有流水
  • 系统资金池也能导出、排行、统计

所以你可以把它理解成：

系统自己的资金账户。

5. 手续费为什么要进系统资金池 ​

如果手续费只是“扣掉然后消失”，虽然也能工作，但不利于运营。

现在的设计是：

  • 玩家支付主金额
  • 玩家额外支付手续费
  • 收款方收到主金额
  • 系统资金池收到手续费

这样好处很明显：

  • 手续费去向可追踪
  • 可以统计今日 / 累计手续费收入
  • 可以和商店、拍卖、税收等玩法统一到同一套系统资金池逻辑

6. 主流水、归档流水与清理任务 ​

这部分是当前版本里很容易被忽视、但对长期运维非常重要的一环。

主流水是什么 ​

主流水就是平时命令默认查询到的那张流水表。

常用命令：

text
/hneco log ...
/hneco logsource ...
/hneco logbiz ...
/hneco logsearch ...
/hneco exportlog ...

它适合：

  • 查近期记录
  • 频繁运维排查
  • 日常导出分析

归档流水是什么 ​

当你开启归档并且记录超过保留期后，旧记录会进入归档流水表。

常用命令：

text
/hneco logarchive ...
/hneco logarchivesource ...
/hneco logarchivebiz ...
/hneco logarchivesearch ...
/hneco exportarchive ...

它适合：

  • 查较久以前的历史账务
  • 主表已经查不到但你仍要追溯的旧交易
  • 导出历史审计记录

delete-after-archive 有什么区别 ​

如果 cleanup.ledger.delete-after-archive: true：

  • 旧记录归档后会从主表删除
  • 主表更轻
  • 历史查询主要走 logarchive*

如果是 false：

  • 主表会继续保留原记录
  • 归档表更像一份额外副本
  • 主表体量会更大

手动和自动清理 ​

当前有两条维护路径：

  • 自动维护：由 cleanup.enabled 和 interval-seconds 控制
  • 手动维护：/hneco cleanup

怎么看清理到底有没有在跑 ​

用：

text
/hneco status

你可以看到：

  • 主流水表条数
  • 归档流水表条数
  • 幂等表条数
  • 转账日统计条数
  • 导出文件数
  • 自动清理开关、批大小、保留策略
  • 最近一次维护开始/完成时间与结果

7. 常用运维命令 ​

查玩家主流水 ​

text
/hneco log <玩家> [货币] [页码]

查玩家归档流水 ​

text
/hneco logarchive <玩家> [货币] [页码]

按来源查主流水 ​

text
/hneco logsource <sourceType> <sourceId> [页码]

按来源查归档流水 ​

text
/hneco logarchivesource <sourceType> <sourceId> [页码]

按业务查主流水 ​

text
/hneco logbiz <businessId> [页码]

按业务查归档流水 ​

text
/hneco logarchivebiz <businessId> [页码]

高级组合筛选 ​

text
/hneco logsearch player=Steve currency=gold type=ADMIN_GIVE
/hneco logsearch sourceType=PAY from=2026-03-01 to=2026-03-31
/hneco logarchivesearch player=Steve from=2026-01-01 to=2026-02-01

导出 CSV ​

text
/hneco exportlog ...
/hneco exportarchive ...

系统资金池流水与统计 ​

text
/hneco treasury log [货币] [页码]
/hneco treasury stats [货币]
/hneco treasury trend [货币] [天数]
/hneco treasury export [货币] [limit]

查看维护状态与手动清理 ​

text
/hneco status
/hneco cleanup

8. 玩家转账风控做了哪些事 ​

当前 /pay 不只是简单扣减，而是带了比较完整的基础风控：

  • 开关控制
  • 权限控制
  • 是否允许给自己转账
  • 最小金额
  • 最大金额
  • 每日累计上限
  • 冷却时间
  • 收款方拒收状态
  • 手续费
  • 权限组手续费覆盖

这意味着：

  • 玩家经济是可运营的
  • 不只是“理论上可以转账”

9. 可疑交易与排行榜 ​

可疑交易 ​

text
/hneco suspicious <最小金额> [货币] [天数] [条数] [player=玩家] [reason=关键词]

适合快速筛：

  • 大额玩家转账
  • 某玩家近期异常交易
  • 某类原因关键词的异常转账

转账排行榜 ​

text
/hneco top <货币> [天数] [人数]

余额排行榜 ​

text
/hneco topbalance <货币> [人数]

这两类榜单对运维也有帮助，因为你能快速看到：

  • 最近谁在频繁转出
  • 哪些账户持有过多余额
  • 哪些资金流和余额分布已经开始偏离正常运营预期

10. 系统资金池告警 ​

如果你在 config.yml 里开启：

yml
treasury:
  alert:
    enabled: true

系统就会定时检查系统资金池余额是否低于阈值。

典型用途 ​

  • 主货币系统资金池快见底了
  • 某类活动积分系统资金池不足
  • 及时提醒运营补库

当前行为是：

  • 低于阈值时输出告警日志
  • 恢复后输出恢复日志
  • 状态不变时不重复刷屏

11. 推荐的运维排查顺序 ​

如果你怀疑某个玩家的钱不对 ​

建议按这个顺序查：

  1. /hneco balance <玩家>
  2. /hneco log <玩家>
  3. /hneco logsearch player=<玩家> from=... to=...
  4. 如果主表查不到，再试 /hneco logarchive <玩家>
  5. 如果怀疑某次业务：/hneco logbiz <businessId> / /hneco logarchivebiz <businessId>
  6. 如果怀疑玩家转账：/hneco paystat <玩家> + /hneco suspicious ...

如果你怀疑系统整体资金流有问题 ​

建议按这个顺序查：

  1. /hneco treasury stats
  2. /hneco treasury trend
  3. /hneco treasury log
  4. /hneco treasury export

如果你怀疑归档清理不正常 ​

建议按这个顺序查：

  1. /hneco status
  2. 看 cleanup 配置是否启用
  3. 看归档保留天数是否合理
  4. 必要时手动执行 /hneco cleanup
  5. 再用 logarchive* 或 exportarchive 验证旧记录是否可见

推荐阅读 ​

HN 系列插件文档

Copyright © 2024