HN 系列 Wiki

主题

这页按模块说明 config.yml。

顶层示例 ​

yml
debug: false

database:
  use-shared-database: true
  fail-if-shared-db-unavailable: true

table-prefix: "hn_eco_"
server-id: "default-server"
main-currency: "gold"

debug ​

yml
debug: false

控制插件调试输出。

建议 ​

  • 日常运行：false
  • 排查问题：临时开 true

database ​

yml
database:
  use-shared-database: true
  fail-if-shared-db-unavailable: true

use-shared-database ​

当前版本建议保持：

yml
true

因为 HNEconomy 的设计前提就是复用 HNCore 共享数据库。

fail-if-shared-db-unavailable ​

当前版本建议保持：

yml
true

含义是：

  • 共享数据库不可用时直接失败
  • 不做静默降级

这是为了保证账务一致性。

table-prefix ​

yml
table-prefix: "hn_eco_"

控制数据库表前缀。

用途 ​

  • 区分不同插件的数据表
  • 方便同库维护
  • 避免和其他系统撞表名

建议 ​

除非你明确知道为什么要改，否则保持默认即可。

server-id ​

yml
server-id: "default-server"

这个值会进入流水记录，用来标识：

  • 这笔账是在哪个服产生的

如果你是多服架构，建议按服区显式配置，例如：

yml
server-id: "survival-1"

main-currency ​

yml
main-currency: "gold"

主货币会影响：

  • /pay 默认使用的货币
  • Vault 默认映射货币
  • 一批 Placeholder 默认返回的货币
  • 某些不传货币参数的命令展示逻辑

注意 ​

主货币必须：

  • 存在于 currencies.yml
  • 并且是启用状态

treasury ​

yml
treasury:
  enabled: true
  owner-id: "TREASURY"
  display-name: "系统国库"
  alert:
    enabled: false
    check-interval-seconds: 300
    low-balance-thresholds:
      gold: 1000

enabled ​

是否启用系统资金池。

如果你要启用：

  • 手续费归集
  • 系统资金池统计
  • 系统资金池命令
  • 系统资金池告警

那就保持 true。

owner-id ​

系统资金池账户在底层就是一个 SYSTEM owner。

默认使用：

text
owner_type = SYSTEM
owner_id = TREASURY

display-name ​

展示给运维和命令输出看的名字。

文档里统一把这套能力称为“系统资金池”，但这里的显示名你可以自由定义； 默认资源文件当前示例是：

text
系统国库

alert ​

用于系统资金池余额告警。

enabled ​

是否启用系统资金池阈值监控。

check-interval-seconds ​

轮询周期，单位秒。

low-balance-thresholds ​

按货币定义低余额阈值，例如：

yml
low-balance-thresholds:
  gold: 1000
  point: 500

当系统资金池余额低于阈值时会打告警日志；恢复后会输出恢复日志。

vault ​

yml
vault:
  enabled: true

控制是否启用 Vault 接入。

说明 ​

即使你安装了 Vault，如果这里关掉，插件也不会去注册 Vault 的经济服务实现。

placeholderapi ​

yml
placeholderapi:
  enabled: true

控制是否启用 PlaceholderAPI 扩展注册。

pay ​

yml
pay:
  enabled: true
  require-permission: false
  allow-self: false
  min-amount: 1
  max-amount: 0
  daily-max-amount: 0
  cooldown-seconds: 0
  default-receive-enabled: true
  allowed-currencies: []

这是玩家转账系统的核心配置。

enabled ​

是否允许玩家使用 /pay。

require-permission ​

是否要求玩家具有：

text
hneconomy.command.pay

allow-self ​

是否允许玩家给自己转账。

通常建议保持：

yml
false

min-amount ​

玩家单次最小转账额。

max-amount ​

玩家单次最大转账额。

  • 0 表示不限制
  • > 0 表示设置上限

daily-max-amount ​

玩家每日累计转出上限。

  • 0 表示不限制

cooldown-seconds ​

玩家两次 /pay 之间的冷却时间。

  • 0 表示无冷却

default-receive-enabled ​

新玩家默认是否允许接收转账。

allowed-currencies ​

限制哪些货币允许玩家转账。

  • 空列表 [] = 所有启用货币都可转
  • 非空列表 = 只有列出的货币可转

pay.fee ​

yml
pay:
  fee:
    enabled: false
    rate: 0.0
    fixed: 0.0
    min-fee: 0.0
    max-fee: 0.0

玩家转账手续费配置。

当前模型 ​

收款方收到主金额，付款方额外支付手续费。

也就是：

  • 付款方扣 主金额 + 手续费
  • 收款方收 主金额
  • 系统资金池收 手续费

字段说明 ​

enabled ​

是否启用手续费。

rate ​

比例手续费，例如：

yml
rate: 0.03

表示 3%。

fixed ​

固定手续费。

min-fee ​

最小手续费。

max-fee ​

最高手续费。

pay.fee.permission-overrides ​

yml
permission-overrides:
  vip:
    permission: "hneconomy.payfee.vip"
    rate: 0.01
    fixed: 0.0
    min-fee: 0.0
    max-fee: 0.0

用于按权限覆盖默认手续费。

常见用法 ​

  • 普通玩家 3%
  • VIP 玩家 1%
  • 特权玩家 0%

这很适合做：

  • VIP 减免
  • 身份组差异费率
  • 活动服特权费率

account ​

yml
account:
  auto-create-on-first-access: true

是否在第一次访问账户时自动开户。

当前建议保持 true，这样：

  • 第一次查余额
  • 第一次加钱
  • 第一次扣钱

都能更自然地工作。

query ​

yml
query:
  default-page-size: 10
  max-page-size: 100

控制命令层分页查询。

用途 ​

  • /hneco log
  • /hneco logsearch
  • /hneco treasury log

等命令会受这里影响。

export ​

yml
export:
  max-rows: 5000
  directory: "exports"

控制 CSV 导出。

max-rows ​

单次导出最大条数。

directory ​

导出目录，默认在插件数据目录下。

cleanup ​

yml
cleanup:
  enabled: true
  interval-seconds: 1800
  batch-size: 1000
  idempotent-retention-days: 7
  pay-daily-stat-retention-days: 180
  ledger:
    archive-enabled: true
    retention-days: 90
    delete-after-archive: true
  export-file-retention-days: 30

这一段控制自动清理、流水归档和导出文件保留策略。

enabled ​

是否启用自动维护任务。

关闭后：

  • 启动时不会定时跑清理任务
  • 但你仍然可以手动执行 /hneco cleanup
  • 并通过 /hneco status 查看最近一次维护结果

interval-seconds ​

自动维护任务的执行周期，单位秒。

batch-size ​

单轮清理 / 归档的批处理大小。

如果你的流水量比较大，可以根据数据库承载能力逐步调大或调小。

idempotent-retention-days ​

idempotent 幂等记录保留天数。

pay-daily-stat-retention-days ​

玩家转账日统计保留天数。

ledger.archive-enabled ​

是否启用主流水归档。

开启后，超过保留期的主流水会转移到归档流水表，便于：

  • 降低主表体积
  • 保留历史审计数据
  • 配合 logarchive / exportarchive 查询旧记录

ledger.retention-days ​

主流水保留天数。

超过该天数的主流水会进入归档候选范围。

ledger.delete-after-archive ​

是否在成功归档后从主流水表删除原记录。

  • true：主表更轻，历史记录主要走归档表查询
  • false：保留主表原记录，相当于额外做一份归档副本

通常建议保持 true。

export-file-retention-days ​

导出目录中历史 CSV 文件的保留天数。

GUI 配置文件 ​

玩家面板配置不在 config.yml 里，而是在插件数据目录下单独管理：

  • plugins/HNEconomy/gui/player-economy.yml
  • plugins/HNEconomy/gui/pay-player-list.yml
  • plugins/HNEconomy/gui/pay-currency.yml
  • plugins/HNEconomy/gui/pay-amount.yml

这些文件控制：

  • /money 主面板标题、按钮、槽位、文案
  • /pay 无参数时的在线玩家选择面板
  • 选择目标后进入的货币选择面板
  • 快捷金额按钮、金额页与确认前展示

如果你要改玩家面板，建议直接看：

如果你要改命令提示、状态输出或玩家可见文案，建议继续看：

reason ​

yml
reason:
  max-length: 255
  default-admin-give: "管理员发放"
  default-admin-take: "管理员扣除"
  default-admin-set: "管理员设置余额"
  default-admin-transfer: "管理员转账"
  default-player-pay: "玩家转账"

这一段很重要，因为它直接影响流水里展示给运维看的原因文本。

max-length ​

会限制明文原因长度，避免数据库里出现过长描述。

其他默认原因 ​

当命令没有显式填写 reason 时，会用这里的默认文案补齐。

这能避免出现一堆“未知原因”的脏流水。

推荐阅读 ​

HN 系列插件文档

Copyright © 2024