HN 系列 Wiki

主题

这页聚焦 HNMail 的主配置文件。当前版本的配置结构比较清晰：

  • config.yml：功能开关、同步、清理、群发、PlaceholderAPI
  • messages.yml：提示与日志文案
  • mail-templates.yml：模板邮件与模板附件

如果你想先把邮箱跑起来，最常改的其实就是 config.yml。

当前版本的完整示例 ​

yml
debug: false

database:
  use-shared-database: true
  table-prefix: hnmail_

mail:
  expire-days: 30
  max-title-length: 32
  max-content-length: 500
  allow-player-send: true
  allow-money-attachment: false
  allow-command-attachment: false

gui:
  inbox-title: "&8你的邮箱"
  page-size: 28

sync:
  enabled: true
  channel: "hnmail.sync"
  resubscribe-interval-ticks: 300

broadcast:
  batch-size: 200
  async-delay-ticks: 1
  log-page-size: 10

cleanup:
  enabled: true
  interval-ticks: 72000
  batch-size: 200
  deleted-retention-days: 7
  audit-retention-days: 90
  player-registry-retention-days: 180
  broadcast-log-retention-days: 30

placeholder-api:
  enabled: true

建议优先看的配置块 ​

配置块优先级主要影响
database很高是否强制依赖 HNCore 共享数据库、表前缀
mail很高玩家发信、附件能力、文本长度限制
sync中跨服提醒与订阅频道
broadcast中群发批量大小、日志分页大小
cleanup中自动清理与数据保留
placeholder-api中是否注册 %hnmail_*% 占位符
gui低到中邮箱界面标题与页大小

database ​

yml
database:
  use-shared-database: true
  table-prefix: hnmail_

use-shared-database ​

当前版本默认且实际要求使用 HNCore 共享数据库。

建议保持：

yml
true

因为 HNMail 的核心能力都建立在共库前提上：

  • 跨服共用邮箱
  • 离线收信
  • 模板群发
  • 广播任务日志

table-prefix ​

邮件系统的表前缀。

默认：

yml
hnmail_

如果你同一个库里跑多个环境，可以改成更有辨识度的前缀，但建议一次定好，后续少改。

mail ​

yml
mail:
  expire-days: 30
  max-title-length: 32
  max-content-length: 500
  allow-player-send: true
  allow-money-attachment: false
  allow-command-attachment: false

expire-days ​

邮件默认过期天数。

用途：

  • 控制收件箱长期体量
  • 降低旧数据积累
  • 配合清理任务工作

max-title-length / max-content-length ​

限制邮件标题和正文长度，避免：

  • 过长文本污染邮箱界面
  • 玩家把邮箱当长文本存档
  • 后台系统误塞超长正文

allow-player-send ​

是否允许玩家互发邮件。

如果你只想把 HNMail 当成“系统奖励邮箱”，可以直接关掉。

allow-money-attachment ​

是否启用金币附件能力。

前提：

  • 已安装 HNEconomy
  • 你确认货币、最大余额、账变逻辑已经可用

allow-command-attachment ​

是否启用命令附件能力。

默认建议保持关闭，只有在你非常明确命令附件会做什么时再打开。

gui ​

yml
gui:
  inbox-title: "&8你的邮箱"
  page-size: 28

inbox-title ​

收件箱 GUI 标题。

page-size ​

每页邮件显示数量。

当前默认值 28 用于配合当前邮箱 GUI 布局。一般不建议随意改太大。

sync ​

yml
sync:
  enabled: true
  channel: "hnmail.sync"
  resubscribe-interval-ticks: 300

enabled ​

是否启用跨服同步提醒层。

主要影响：

  • 新邮件实时提醒
  • 多服之间的提醒消息传播

channel ​

共享消息总线频道名。

建议固定，不要随意改，除非你明确知道自己在做环境隔离。

resubscribe-interval-ticks ​

定时检查订阅状态并自动补订阅的周期。

在消息连接偶尔波动的环境里，这能提高稳定性。

broadcast ​

yml
broadcast:
  batch-size: 200
  async-delay-ticks: 1
  log-page-size: 10

batch-size ​

模板群发时每批处理多少个目标。

值越大：

  • 发送更快
  • 但业务压力更集中

值越小：

  • 更稳
  • 但全量群发耗时更长

async-delay-ticks ​

批次之间的调度间隔。

如果你的玩家目录很大，可以适当调高，避免任务太紧凑。

log-page-size ​

/hnmail broadcastlog 列表与详情的默认分页大小。

如果你希望后台一次看更多记录，可以适当调大，但不建议太夸张。

cleanup ​

yml
cleanup:
  enabled: true
  interval-ticks: 72000
  batch-size: 200
  deleted-retention-days: 7
  audit-retention-days: 90
  player-registry-retention-days: 180
  broadcast-log-retention-days: 30

enabled ​

是否启用自动清理任务。

建议生产环境保持开启。

interval-ticks ​

清理任务运行间隔，单位是 tick。

72000 tick 约等于 1 小时。

batch-size ​

每批清理多少条目标数据。

主要影响：

  • 一次清理压力
  • 清理任务完成速度

deleted-retention-days ​

已删除邮件的保留天数。

超过这个时间后，清理任务会彻底删除旧邮件及其相关附件 / 审计数据。

audit-retention-days ​

附件 / 邮件审计数据的保留天数。

如果你需要较长时间追查玩家领取、删除、发信行为，这个值不建议设得太短。

player-registry-retention-days ​

玩家目录中“长期未活跃玩家”的保留天数。

它主要影响离线全玩家群发的目标池规模，以及清理任务是否会裁剪过旧的玩家目录记录。

broadcast-log-retention-days ​

广播任务日志与明细的保留天数。

如果你的服务器经常做补偿、节日邮件或活动群发，这个值不建议太短。

placeholder-api ​

yml
placeholder-api:
  enabled: true

enabled ​

是否在检测到 PlaceholderAPI 时注册 HNMail 占位符。

当前版本支持的占位符包括：

  • %hnmail_unread%
  • %hnmail_total%
  • %hnmail_allow_player_mail%
  • %hnmail_allow_player_mail_text%
  • %hnmail_template_count%
  • %hnmail_broadcast_job_count%
  • %hnmail_latest_broadcast_status_text%
  • %hnmail_latest_broadcast_success_rate_text%

更完整的占位符列表，建议直接看 PlaceholderAPI 占位符。

推荐的首版配置策略 ​

想先稳稳跑通基础邮箱 ​

建议：

  • allow-player-send: true
  • allow-money-attachment: false
  • allow-command-attachment: false
  • sync.enabled: false 或等共享消息就绪后再开
  • cleanup.enabled: true
  • placeholder-api.enabled: false 或后续再开

想把它作为运营奖励中心 ​

建议：

  • allow-player-send: false 或低权限开放
  • allow-money-attachment: true
  • allow-command-attachment: 按需开启
  • sync.enabled: true
  • cleanup.enabled: true
  • broadcast.batch-size 使用较保守的值
  • placeholder-api.enabled: true

建议联动阅读 ​

HN 系列插件文档

Copyright © 2024