storage.yml 配置说明 | HN 系列 Wiki

storage.yml 是 HNCore 当前专门负责 共享数据库 与 共享存储 的配置文件。

如果你要配这些内容：

SQLite / MySQL 共享数据库
共享键值存储
Redis Pub/Sub
MySQL 连接池
Redis 连接参数
给 HNAttribute 这类下游模块提供跨服同步能力

那应该优先看这一页。

文件定位

默认路径：

text

plugins/HNCore/storage.yml

当前版本里，HNCore 会在启动时读取这个文件，并在执行：

text

/hncore reload

时重新加载它。

如果你只是想先确认“当前配置有没有真的跑起来”，推荐先执行：

text

/hncore status

这个命令不会重建状态，但会直接告诉你共享数据库、共享存储、Redis、Pub/Sub 当前是否可用。

这份文件管什么

storage.yml 现在主要分成三块：

database
storage
cluster

可以简单理解为：

配置块	作用	更像什么
`database`	共享数据库入口	一套给下游插件复用的统一数据库连接
`storage`	共享存储入口	键值存储、Redis Pub/Sub、底层共享消息能力
`cluster`	ClusterBus 入口	面向业务模块的统一集群控制面

完整默认结构

yml

database:
  enabled: false
  type: sqlite

  sqlite:
    file: data/hncore.db

  mysql:
    host: localhost
    port: 3306
    database: hncore
    username: root
    password: ""
    pool-size: 10

storage:
  mysql:
    enabled: false
    host: localhost
    port: 3306
    database: hncore
    username: root
    password: ""
    pool-size: 10
    table-prefix: hnc_
    connection-timeout-ms: 10000

  redis:
    enabled: false
    host: localhost
    port: 6379
    password: ""
    database: 0
    ssl: false
    timeout-ms: 3000
    pool-max-total: 8
    pool-max-idle: 8
    pool-min-idle: 0
    key-prefix: hnc:
    channel-prefix: hnc:

cluster:
  node-id: ""
  transport: auto
  channel: "cluster.bus"
  ping-timeout-ms: 1500

database

enabled

yml

database:
  enabled: false

是否启用 共享数据库。

如果你只是用 HNCore 自带脚本、工具箱，或者当前根本没有下游插件要复用数据库，通常可以先保持关闭。

type

yml

database:
  type: sqlite

当前共享数据库支持：

sqlite
mysql

如果你要做单服、轻量、本地存储，通常 sqlite 更省事。

如果你要接远程数据库、统一管理或更稳定地给多插件复用，才考虑 mysql。

database.sqlite

file

yml

sqlite:
  file: data/hncore.db

这是 SQLite 数据文件的相对路径。

默认会落在：

text

plugins/HNCore/data/hncore.db

database.mysql

基础连接参数

yml

mysql:
  host: localhost
  port: 3306
  database: hncore
  username: root
  password: ""

这部分就是最常见的 MySQL 连接信息。

pool-size

yml

mysql:
  pool-size: 10

这是 共享数据库这一路 的 MySQL 连接池大小。

可以把它理解成：

连接池最多保留多少活跃数据库连接
数值过小：并发高时更容易等待
数值过大：数据库侧资源占用更高

如果你只是普通单服、轻中等负载，默认 10 往往够用。

`storage` 与 `cluster` 的区别

这两个概念容易混：

storage.redis.*：底层 Redis 连接、连接池、键值前缀、频道前缀
cluster.*：业务层 ClusterBus 的节点 ID、transport、逻辑 channel、ping 窗口

可以简单理解成：

storage 负责“怎么连 Redis”
cluster 负责“连上之后业务层集群怎么组织”

storage

storage 和 database 不是一回事。

当前实现中：

共享键值存储优先使用 Redis
Redis 不可用时，回退到 storage.mysql
共享消息总线（Pub/Sub）只在 Redis 可用时启用

也就是说，storage 更偏向：

键值读写
通道广播
跨服同步
下游模块共享状态

storage.mysql

enabled

yml

storage:
  mysql:
    enabled: false

是否启用 共享存储的 MySQL 后端。

它通常作为：

Redis 不可用时的键值存储回退后端
某些下游模块共享状态时的 MySQL 承载层

基础连接参数

yml

host: localhost
port: 3306
database: hncore
username: root
password: ""

这部分和普通 MySQL 连接配置一致。

pool-size

yml

pool-size: 10

这是 共享存储这一路 的 MySQL 连接池大小。

要特别注意：

database.mysql.pool-size
storage.mysql.pool-size

这两个不是同一个池。

简单区分：

database.mysql.pool-size：共享数据库连接池
storage.mysql.pool-size：共享存储 MySQL 后端连接池

如果你在调 HNAttribute 的跨模块共享能力、存储回退或键值访问性能，通常更相关的是这里。

table-prefix

yml

table-prefix: hnc_

共享存储 MySQL 表前缀。

如果你希望多个项目共用同一个数据库库名，但不想表名冲突，可以改这里。

connection-timeout-ms

yml

connection-timeout-ms: 10000

共享存储 MySQL 的连接超时时间，单位毫秒。

太短：网络稍慢时更容易连接失败
太长：故障时等待更久

默认 10000 也就是 10 秒，通常已经比较稳妥。

storage.redis

enabled

yml

storage:
  redis:
    enabled: false

是否启用 Redis。

如果你要：

让共享键值优先走 Redis
启用共享消息总线
让 HNAttribute 这类下游模块做跨服同步

那通常需要把这里打开。

基础连接参数

yml

host: localhost
port: 6379
password: ""
database: 0
ssl: false
timeout-ms: 3000

含义分别是：

host / port：Redis 地址
password：密码
database：逻辑库编号
ssl：是否启用 SSL
timeout-ms：连接超时

Redis 连接池参数

yml

pool-max-total: 8
pool-max-idle: 8
pool-min-idle: 0

这三项控制的是 HNCore 维护的 Redis 连接池，不是业务模块自己再单独开池。

可以这样理解：

pool-max-total：连接池最多允许多少连接
pool-max-idle：最多保留多少空闲连接
pool-min-idle：至少保留多少空闲连接

一般建议：

普通单服 / 轻中等负载：保持默认即可
多下游模块共用 Redis、消息较频繁：可以适当提高 pool-max-total
不要把 pool-min-idle 调得明显高于实际需要，否则空闲连接会长期占着资源

key-prefix

yml

key-prefix: hnc:

共享键值存储的 key 前缀。

如果多个系统共用同一个 Redis，建议保留或自定义前缀，避免 key 冲突。

channel-prefix

yml

channel-prefix: hnc:

共享消息频道前缀。

如果你要做多服广播，这个前缀应该在要互通的服务器之间保持一致。

cluster

cluster 这一段不是底层 Redis 连接参数，而是 HNCore ClusterBus / 集群控制面 的业务层配置。

node-id

yml

cluster:
  node-id: "lobby-1"

当前服务器在集群里的唯一标识。

如果留空，HNCore 会自动回退为：

text

服务器名@端口

例如：

text

paper@25565

这适合单服测试，但多服正式环境建议显式配置唯一值。

transport

yml

cluster:
  transport: auto

可选值：

auto
redis
loopback

语义是：

auto：优先 Redis，Redis 不可用时回退 loopback
redis：强制要求 Redis；Redis 不可用时 ClusterBus 会保持不可用
loopback：只在本服本进程内回环，不跨服

如果你看到启动日志是：

text

transport=loopback

说明 ClusterBus 已建立，但当前只是本地自测状态。

channel

yml

cluster:
  channel: "cluster.bus"

ClusterBus 的逻辑频道名。

当 transport 真正走 Redis 时，最终发出的频道会叠加：

storage.redis.channel-prefix
cluster.channel

所以多服互通时，这两项都应保持兼容。

ping-timeout-ms

yml

cluster:
  ping-timeout-ms: 1500

/hncore cluster ping 的默认等待窗口，单位毫秒。

这一段和 `/hncore cluster status` 的关系

如果你改了 cluster.* 配置，通常建议用：

text

/hncore reload
/hncore cluster status

来确认：

当前节点 ID 是什么
transport 最终是 redis 还是 loopback
ClusterBus 是否真的可用

HNAttribute 和连接池的关系

很多人会在 HNAttribute 文档里找连接池，但当前版本里：

HNAttribute 不单独维护自己的 MySQL 连接池参数
它现在做跨服同步时，优先依赖的是 HNCore 的 ClusterBus
ClusterBus 的跨服 transport 底层仍然复用 HNCore 的共享 Redis Pub/Sub
它如果以后复用共享数据库 / 共享存储，也还是走 HNCore 提供的能力

也就是说：

想调连接池：看 HNCore 的 storage.yml
想看广播为什么没生效：先看 HNCore 的 Redis 是否真的启用了
想快速判断是不是 HNCore 这层没起来：先执行 /hncore status 和 /hncore cluster status

换句话说，连接池 / Redis 连接 / PubSub 订阅线程都由 HNCore 统一维护，不是让 HNAttribute 或其他业务模块各自再开一套。

最常见的三种场景

1. 只跑 HNCore 默认脚本

通常保持：

yml

database:
  enabled: false

storage:
  mysql:
    enabled: false
  redis:
    enabled: false

2. 需要共享数据库，但不需要 Redis 广播

通常重点看：

yml

database:
  enabled: true
  type: mysql

并补完整 database.mysql.* 参数。

3. 需要 HNAttribute 跨服同步

通常重点看：

yml

storage:
  redis:
    enabled: true

然后确保：

多台服 Redis 地址一致
channel-prefix 兼容你的部署方式
先用 /hncore status 看共享消息总线是否可用
如刚改完配置，再执行 /hncore reload

改完后怎么验证

最直接的验证顺序通常是：

text

/hncore status
/hncore reload
/hncore status

可以这样理解：

第一次 status：看当前运行态是什么
reload：把磁盘配置重新读进来
第二次 status：确认新状态是否真的已经生效

重点观察：

共享数据库是否启用 / 是否初始化成功
共享存储 MySQL 是否启用 / 是否初始化成功
共享存储 Redis 是否启用 / 是否初始化成功
共享键值存储是否可用，以及当前后端是什么
共享消息总线（Pub/Sub）是否可用

所以这页配置改完后，不要只保存文件，至少看一次 status，需要重建状态时再执行 reload。

常见误区

以为 `database.mysql.pool-size` 和 `storage.mysql.pool-size` 是一个东西

不是。

它们属于两条不同的能力链路，调优时要分开看。

以为开了 MySQL 就等于 Pub/Sub 可用

不是。

Pub/Sub 只和 Redis 有关。

以为 HNAttribute 自己也要单独配一套 Redis / MySQL 连接池

不需要。

HNAttribute 的相关共享能力是接在 HNCore 这层上的。

建议联动阅读

想理解 HNCore 主配置：看 config.yml 配置说明
想看重载后状态如何判断：看命令说明
想看下游怎么用这些共享能力：看 HNCore Java API
想看 HNAttribute 为什么会依赖这里：看 HNAttribute 集成与 API

文件定位 ​

这份文件管什么 ​

完整默认结构 ​

database ​

enabled ​

type ​

database.sqlite ​

file ​

database.mysql ​

基础连接参数 ​

pool-size ​

storage 与 cluster 的区别 ​

storage ​

storage.mysql ​

enabled ​

基础连接参数 ​

pool-size ​

table-prefix ​

connection-timeout-ms ​

storage.redis ​

enabled ​

基础连接参数 ​

Redis 连接池参数 ​

key-prefix ​

channel-prefix ​

cluster ​

node-id ​

transport ​

channel ​

ping-timeout-ms ​

这一段和 /hncore cluster status 的关系 ​

HNAttribute 和连接池的关系 ​

最常见的三种场景 ​

1. 只跑 HNCore 默认脚本 ​

2. 需要共享数据库，但不需要 Redis 广播 ​

3. 需要 HNAttribute 跨服同步 ​

改完后怎么验证 ​

常见误区 ​

以为 database.mysql.pool-size 和 storage.mysql.pool-size 是一个东西 ​

以为开了 MySQL 就等于 Pub/Sub 可用 ​

以为 HNAttribute 自己也要单独配一套 Redis / MySQL 连接池 ​

建议联动阅读 ​

文件定位

这份文件管什么

完整默认结构

database

enabled

type

database.sqlite

file

database.mysql

基础连接参数

pool-size

`storage` 与 `cluster` 的区别

storage

storage.mysql

enabled

基础连接参数

pool-size

table-prefix

connection-timeout-ms

storage.redis

enabled

基础连接参数

Redis 连接池参数

key-prefix

channel-prefix

cluster

node-id

transport

channel

ping-timeout-ms

这一段和 `/hncore cluster status` 的关系

HNAttribute 和连接池的关系

最常见的三种场景

1. 只跑 HNCore 默认脚本

2. 需要共享数据库，但不需要 Redis 广播

3. 需要 HNAttribute 跨服同步

改完后怎么验证

常见误区

以为 `database.mysql.pool-size` 和 `storage.mysql.pool-size` 是一个东西

以为开了 MySQL 就等于 Pub/Sub 可用

以为 HNAttribute 自己也要单独配一套 Redis / MySQL 连接池

建议联动阅读