配置说明

配置文件：plugins/LyMySQLCore/config.yml

LyMySQLCore 在插件启动时读取配置并初始化 MySQL 连接。修改数据库配置或 join-load-delay 后，需要重启服务器使配置生效。项目中没有注册独立的重载命令。

LyMySQLCore 负责为依赖它的插件提供 MySQL 玩家数据存储基础。必须安装 LyMySQLCore，并且数据库连接成功后，依赖插件的数据读写、玩家数据加载事件和保存事件才会生效。

默认配置

# 数据库配置。连接成功后，依赖插件才能执行后续数据操作。
mysql:
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1
  link: 'useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8'

# 玩家加入服务器后，数据加载完成事件的延迟，单位为 tick。
join-load-delay: 20

配置文件中的数据库账号需要能够连接目标数据库，并具备创建表、查询、插入和更新数据的权限。LyMySQLCore 启动时会自动创建所需的数据表。

配置项

mysql

mysql 节点用于配置数据库连接信息。插件会根据这些配置拼接 JDBC 地址：

jdbc:mysql://<ip>:<port>/<databasename>?<link>

配置项	类型	默认值	说明
mysql.databasename	字符串	mc2	要连接的 MySQL 数据库名称。
mysql.username	字符串	mc2	MySQL 登录账号。
mysql.password	字符串	mc1234	MySQL 登录密码。建议修改为实际数据库密码。
mysql.port	整数	3306	MySQL 服务端口。
mysql.ip	字符串	127.0.0.1	MySQL 服务地址。127.0.0.1 表示数据库运行在当前服务器。
mysql.link	字符串	useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8	JDBC 连接参数，会直接拼接到连接地址末尾。

mysql.link 中的参数使用 & 分隔。项目默认配置包含以下参数：

参数	说明
useSSL=false	不使用 SSL 连接。
serverTimezone=UTC	指定数据库连接时区为 UTC。
characterEncoding=UTF-8	指定连接字符编码为 UTF-8。

如果数据库服务器使用其他时区，可以在 mysql.link 中调整 serverTimezone 的值，例如 Asia/Shanghai。该参数必须符合 JDBC 驱动支持的时区名称。

join-load-delay

配置项	类型	默认值	单位	说明
join-load-delay	长整数	20	tick	玩家数据加载完成后，延迟触发 MySQLSafePlayerLoadEvent，并结束数据加载保护状态。

join-load-delay: 20

服务器中 20 tick 通常约为 1 秒。该配置只控制玩家数据加载完成后的事件延迟，不负责数据库连接重试，也不会改变数据库连接超时时间。

数据库连接

LyMySQLCore 在启动时会读取 mysql 节点并建立连接池。连接池的最小空闲连接数为 1，最大连接数为：

min(20, 可用处理器数量 + 1)

启动时会在控制台输出实际使用的 JDBC 地址以及连接成功或失败信息。数据库连接失败时，插件会输出失败提示，并停止自身启用流程。

警告

数据库连接成功是 LyMySQLCore 正常工作的前提。必须安装 LyMySQLCore 且成功连接数据库后，依赖插件的玩家数据加载、保存和循环保存功能才会生效。

自动创建的数据表

LyMySQLCore 启动时会自动创建以下数据表。通常不需要手动执行建表语句。

lymysqlcore_lock

该表用于记录玩家当前由哪个服务器持有数据锁，避免同一玩家在多个服务器之间同时读写数据。

字段	类型	说明
id	int(16) UNSIGNED	自增主键。
player_name	varchar(32)	玩家名称，唯一。
server	varchar(32)	持有锁的服务器标识。
lock_time	timestamp	锁的更新时间，默认使用当前时间。

表使用 InnoDB 引擎和 utf8mb4 字符集，并包含玩家名称、服务器标识和锁时间相关索引。

lymysqlcore_playerlog

该表用于记录玩家名称与 UUID 的对应关系。玩家首次加入服务器时，如果不存在记录，插件会异步写入玩家名称和 UUID。

字段	类型	说明
id	int(16) UNSIGNED	自增主键。
player_name	varchar(128)	玩家名称，唯一。
uuid	varchar(36)	玩家 UUID。

玩家数据加载保护

玩家加入服务器后，LyMySQLCore 会先记录玩家状态并尝试获取数据库锁。数据完成加载前，玩家处于受保护状态：

• 玩家会暂时获得失明效果。
• 玩家移动会被取消，并返回加入服务器时的位置。
• 物品丢弃会被取消。
• 玩家交互会被取消。
• 玩家造成的实体伤害会被取消。
• 背包点击和打开操作会被取消。
• 玩家聊天会被取消。

只有玩家数据加载完成，并且触发 MySQLSafePlayerLoadEvent 后，插件才会解除这类保护。依赖插件不应在该事件触发前执行需要玩家数据的操作。

如果玩家无法获得有效的数据锁，插件会持续尝试获取锁。达到内部尝试次数上限后，玩家会被踢出服务器，并显示“数据加载失败，请稍后再试”。该尝试次数没有对应的配置项。

数据保存机制

LyMySQLCore 支持以下数据保存时机：

时机	说明
玩家离开服务器	保存玩家数据，完成后释放当前服务器持有的玩家锁。
玩家被踢出服务器	执行与离开服务器相同的数据保存和解锁流程。
服务器执行 stop 或 restart	先保存在线玩家数据，再允许服务器继续关闭或重启。
定时循环保存	定期为在线且已完成加载的玩家调用供应商的循环保存方法。

服务器关闭时，插件会等待当前服务器持有的玩家锁释放，再继续关闭流程。等待次数和等待间隔由插件内部固定，配置文件没有对应配置项。

配置修改注意事项

• mysql.password 中包含特殊字符时，建议使用单引号或双引号包裹密码。
• mysql.port 应填写 MySQL 服务实际监听的端口。
• mysql.databasename 对应的数据库需要提前存在；插件负责创建自身的数据表，不负责创建数据库本身。
• 数据库账号需要具备创建 lymysqlcore_lock 和 lymysqlcore_playerlog 表的权限。
• 修改配置后必须重启服务器，不能依赖插件重载来重新建立数据库连接。
• 不要删除或重命名配置节点，插件会按固定键名读取配置。

连接失败排查

先检查控制台输出的 MySQLLink -> jdbc:mysql://...，确认实际拼接出的地址与配置一致。

现象	检查项
连接超时或无法连接	检查 mysql.ip、mysql.port、数据库服务状态、防火墙和网络访问权限。
Access denied	检查 mysql.username、mysql.password，并确认账号已被授权访问目标数据库。
Unknown database	检查 mysql.databasename，并确认目标数据库已经创建。
创建数据表失败	确认数据库账号具备建表、查询、插入和更新权限。
时区相关错误	检查 mysql.link 中的 serverTimezone，并填写 JDBC 驱动支持的时区名称。
依赖插件没有加载或保存数据	确认 LyMySQLCore 已安装、插件已成功启用，并且控制台显示数据库连接成功。

配置示例

本机数据库

mysql:
  databasename: minecraft
  username: root
  password: '请填写数据库密码'
  port: 3306
  ip: 127.0.0.1
  link: 'useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8'

join-load-delay: 20

局域网数据库

mysql:
  databasename: server_data
  username: mc_user
  password: '请填写数据库密码'
  port: 3306
  ip: 192.168.1.100
  link: 'useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=UTF-8'

join-load-delay: 20