HNCore 当前的配置已经明显拆成三层：

• config.yml：核心运行策略
• storage.yml：数据库与共享存储
• auth.yml：统一授权接入

本页聚焦 config.yml 自身的核心运行策略；如果你是专门来配数据库、连接池、Redis 或 Pub/Sub，建议直接跳到 storage.yml 配置说明。如果你是来配统一授权中心、商品授权码或缓存策略，建议直接看 auth.yml 配置说明。

配置文件分工

文件	负责内容	你最常改什么
config.yml	log.level、兼容旧 debug、formula.groovy、feature-scripts	日志等级、脚本总开关、Groovy 策略、示例释放、脚本目录名
storage.yml	database、storage.mysql、storage.redis	共享数据库、共享键值存储、Redis Pub/Sub
auth.yml	auth.center、auth.cache、auth.products	统一授权中心地址、授权码与本地缓存策略
toolbox-search-aliases.yml	工具箱搜索别名组	中文 / 英文 / 近义词搜索词

建议优先看的配置块

配置块	所在文件	优先级	说明
feature-scripts	config.yml	很高	决定脚本系统是否启用
log.level	config.yml	很高	控制 INFO / DEBUG / TRACE 日志等级
formula.groovy	config.yml	中	这是给业务模块复用的公式引擎，不只是摆设配置
database	storage.yml	中	只有你确实要接共享数据库时才需要细看
storage.mysql / storage.redis	storage.yml	中	共享键值存储与消息总线入口

log.level（推荐写法）

log:
  level: INFO

当前可选值：

• OFF
• INFO
• DEBUG
• TRACE

建议这样理解：

• INFO：默认级别，适合日常生产环境
• DEBUG：开发排障级别，输出关键诊断信息
• TRACE：超详细链路日志，适合查 SQL、公式、集群消息、Buff / Mythic 等高噪声明细
• OFF：关闭常规 info/debug/trace 输出，只保留警告与错误这类关键问题日志

推荐用法

• 日常运行：INFO
• 临时排障：DEBUG
• 深度追链路：TRACE

兼容旧写法：debug

debug: false

旧写法仍兼容，但现在更推荐改成 log.level。

兼容映射规则：

• debug: true → 等价于 log.level: DEBUG
• debug: false → 等价于 log.level: INFO

也就是说：

• 下游项目旧配置暂时不需要立刻重写
• 新文档和新配置建议统一使用 log.level

formula.groovy

formula:
  groovy:
    enabled: true
    security-level: UNSAFE
    max-script-length: 2048
    deny-patterns:
      - '(?i)\bSystem\b'
      - '(?i)\bRuntime\b'
      - '(?i)\bProcessBuilder\b'
      - '(?i)\bclassLoader\b'
      - '(?i)\bgetClass\s*\('
      - '(?i)\bmetaClass\b'
      - '(?i)\bBukkit\b'
      - '(?i)\bJavaPlugin\b'

这是数值公式引擎相关的 Groovy 策略，主要给业务模块复用，例如属性、伤害、数值计算类能力。

enabled

是否允许业务模块使用 Groovy 公式。

security-level

当前默认值是 UNSAFE。

配置注释已经明确说明：这里默认按可信本地环境处理，否则很多正常的 Groovy 写法会被拦截。

max-script-length

单条公式脚本长度限制，默认 2048。

deny-patterns

这是公式脚本的文本黑名单，用来阻止明显不该出现在公式中的关键对象或危险入口。

如果你只是正常使用 HNCore，而不是自己写复杂公式，通常保持默认即可。

feature-scripts

这是当前最重要的一组配置，也是大多数服主真正需要关心的部分。

feature-scripts:
  enabled: true
  release-examples: true
  config-directory: GroovyConfig
  script-directory: GroovyScripts
  groovy:
    enabled: true
    security-level: UNSAFE
    max-script-length: 0
    deny-patterns: []

enabled

是否启用整套模块化脚本系统。

如果这里是 false，后面的内置脚本就算存在文件，也不会按预期工作。

release-examples

是否在首次启动时释放默认脚本与配置。

• true：自动释放内置示例脚本和对应 yml
• false：只保证目录存在，不自动释放示例文件

通常建议保持 true，这样第一次安装时可以直接拿到默认脚本。

config-directory / script-directory

分别指定：

• 脚本配置目录名
• 脚本文件目录名

默认就是：

• GroovyConfig
• GroovyScripts

如果你没有特殊需求，建议保持默认，减少后续排错成本。

groovy.enabled

是否允许脚本系统真正注册 Groovy 脚本。

这项如果关闭，脚本目录仍可能存在，但脚本不会按预期运行。

groovy.security-level

模块化脚本默认按可信本地脚本处理，当前推荐保持 UNSAFE。

而且从当前实现来看，即便你把它改成 SANDBOXED，脚本系统也会发出警告并按 UNSAFE 模式加载，以兼容 import、class、监听器注册等完整脚本能力。

groovy.max-script-length

脚本最大长度限制：

• 0：不限制
• 大于 0：限制长度

对默认内置脚本而言，通常保持默认即可。

groovy.deny-patterns

可选的文本黑名单规则入口。对于纯使用内置脚本的场景，通常无需先改这一项。

storage.yml

数据库与共享存储配置位于 storage.yml。

这页只保留你在看 config.yml 时需要知道的结论，详细字段说明、连接池、Redis 参数和场景示例请直接看 storage.yml 配置说明。

你只需要先记住这几点

• database：共享数据库入口，给 HNCore 下游模块或其他插件复用统一数据库连接
• storage.mysql / storage.redis：共享存储入口，用于键值共享、状态同步与跨模块通信
• 共享键值存储优先使用 Redis；Redis 未启用时才回退到 storage.mysql
• 共享消息总线（Pub/Sub）只在 storage.redis 启用时可用
• 只跑默认脚本时，这些配置通常都可以先保持关闭
• 需要数据库 / 存储时，直接改 storage.yml

对服主最重要的结论

如果你只是想稳定使用默认脚本，优先盯住下面这些点：

• feature-scripts.enabled
• feature-scripts.groovy.enabled
• GroovyConfig/*.yml 中每个脚本自己的 enabled
• 需要数据库 / 存储时，直接改 storage.yml

换句话说，HNCore 是否“跑起来”，核心不是只看文件是否存在，而是看这几层开关是否同时处于正确状态。

建议联动阅读

• 想确认首次启动后目录长什么样：看 安装与首次启动
• 想确认改完配置后该执行什么命令：看 命令说明
• 想理解脚本系统开关和目录行为：看 GroovyScripts 总览
• 想配共享数据库 / 共享存储：看 storage.yml 配置说明
• 想配统一授权中心与商品授权码：看 auth.yml 配置说明
• 想看共享数据库 / 共享存储的开发接口：看 HNCore Java API