配置

配置文件位于 plugins/SystemMail/config.yml。第一次安装时，多数单服只需要检查授权和 SQLite 文件路径；群组服则需要重点配置 server-id、MySQL 与 Redis。

服务器标识

配置项	默认值	说明	生效
`server-id`	`server-1`	1–64 位字母、数字、`.`、`_`、`-`；每个子服必须唯一	重启

database.type: mysql 时必须启用 Redis；SQLite 模式不能启用 Redis。

配置项	默认值	说明	生效
`mail.time-zone`	`Asia/Shanghai`	Java `ZoneId`；影响日期和界面时间文本	重载
`mail.max-title-length`	`64`	1–256，限制	重载
`mail.max-content-length`	`8192`	1–32767，限制	重载
`mail.max-item-slots`	`27`	0–54，限制	重载
`mail.max-currencies`	`16`	0–64，限制	重载
`mail.max-currency-per-provider`	`1000000000.0`	单个货币 provider 的最大正数金额	重载
`mail.max-commands`	`16`	0–64，限制	重载
`mail.max-recipients-per-request`	`10000`	1–250000；单次请求的收件人数安全上限	重载
`mail.recipient-materialization-batch-rows`	`5000`	100–50000；每批数据库写入行预算，不限制群发总量	重载
`mail.max-admin-drafts`	`500`	1–5000，限制；全服共享草稿总数	重载
`mail.inbox-page-size`	`20`	1–100，限制	重载
`mail.ui-claim-expiry-grace-minutes`	`20`	0–120，限制；`0` 关闭当前详情的领取宽限	重载
`mail.trash-retention-days`	`30`	1–3650，限制	重载

recipient-materialization-batch-rows 决定每个事务处理多少名收件人。每名收件人占用“附件数 + 2”行预算，其中两行分别用于收件关系和通知事件。

例如一封邮件包含 27 个附件，默认预算为 5000 时，每批处理 floor(5000 / 29) = 172 名收件人；10000 名收件人会分约 59 批完成。批次中断后继续构建，整封邮件完成前不会出现在玩家收件箱、未读数或通知中。

max-recipients-per-request 会阻止单次请求计划过多收件人。大型服务器可以按 MySQL 容量提高，应同时关注连接池、事务日志、max_allowed_packet 和通知积压。

配置项	默认值	说明	生效
`commands.allowed-prefixes`	`[]`	空列表禁止所有命令附件；单项最长 128 个字符且不能换行	重载

推荐只加入实际需要的命令前缀：

commands:
  allowed-prefixes:
    - "lp user "
    - "points give "

匹配时会移除命令开头的 / 和空白，并忽略大小写。前缀末尾建议保留空格，避免 give 意外匹配 givehack。

配置项	默认值	说明	生效
`notifications.unread-variable`	`systemmail_unread_count`	玩家未读数变量	重载
`notifications.page-count-variable`	`systemmail_page_count`	未筛选收件箱的总页数变量	重载
`notifications.inbox-ui-id`	`systemmail_inbox`	收件箱注册 ID	重启
`notifications.hud-ui-id`	`systemmail_hud`	新邮件 HUD 注册 ID	重启

这些 identifier 允许 1–128 位字母、数字、.、_、:、-。修改 UI ID 时还要同步修改对应 AXUI 资源，并完整重启。

通常不需要修改本节。遇到超大物品、异常回包或数据库查询压力时，再按实际情况调整。

配置项	默认值	说明	生效
`security.max-item-payload-bytes`	`1048576`	4096–8388608；单件物品序列化上限	重载
`security.max-mail-item-payload-bytes`	`786432`	65536–4194304；整封邮件物品序列化总量	重载
`security.max-ui-packet-fields`	`16`	1–64；玩家请求的最大字段数	重载
`security.max-ui-field-length`	`131072`	256–1048576；单字段最大字符数	重载
`security.max-ui-response-bytes`	`1048576`	65536–4194304；普通动态回包 UTF-8 预算	重载
`security.max-ui-pages`	`500`	10–5000；可访问的最大页数	重载
`security.min-ui-search-length`	`1`	1–16；非空搜索的最短字符数	重载
`security.max-ui-search-length`	`64`	16–128；非空搜索的最长字符数	重载
`security.max-concurrent-ui-queries`	`32`	1–256；还会受连接池和工作线程容量限制	重载
`security.ui-query-timeout-seconds`	`3`	1–30 秒，限制	重载
`security.slow-ui-query-warn-millis`	`500`	100–10000 毫秒，限制	重载

min-ui-search-length 不能大于 max-ui-search-length。邮件详情需要完整展示物品数据，不受普通 max-ui-response-bytes 裁剪；其体积由前两项限制。

执行：

/sma reload

可以重载配置、lang.yml、ui/inbox.yml 和 ui/hud.yml。

以下项目修改后必须完整重启：

不要使用 Bukkit /reload 或 PlugMan 热卸载 SystemMail。数据库连接、Redis 订阅和共享运行库都应随服务器完整启动与关闭。