Towny 数据存储原理完全指南扁平文件与 MySQL 双引擎读写及数据库迁移机制【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/TownyTowny 是 Minecraft Bukkit/Spigot 服务器上的经典城镇建设插件它的数据存储采用「扁平文件FlatFile」与MySQL 数据库」双引擎设计并内置了自动化的数据库迁移机制。无论你是首次部署 Towny还是想从文件存储切换到 MySQL本文都会帮你快速搞懂 Towny 数据是怎么读、怎么写、怎么升级的。️ 为什么是「双引擎」设计Towny 的数据源由统一入口管理插件启动时读取settings/database.yml配置文件根据database_load与database_save两项设置决定使用哪套引擎存储引擎适用场景特点flatfile默认中小规模服务器无需额外依赖纯文本文件方便手动备份与排查mysql大型服务器、多插件协作结构化存储、连接池加速、适合海量城镇地块数据配置项集中定义在 DatabaseConfig.java 中包括database.database_load、database.database_save以及 MySQL 主机、端口、库名、表前缀、连接池大小等全部参数默认值均为flatfile。旧版本config.yml中的数据库设置还会被自动迁移到独立的database.yml文件入口逻辑见 Towny.java。 扁平文件引擎目录结构与读写流程一键生成的数据目录启用 flatfile 时Towny 会在数据目录下自动创建整齐的分类文件夹每个实体对象对应一个文件见 TownyFlatFileSource.javadata/ ├── residents/ 居民按 UUID 命名的 .txt内含已删除与休眠子目录 ├── towns/ 城镇 ├── nations/ 国家 ├── worlds/ 世界 ├── townblocks/ 城镇地块按 世界名/x_z_尺寸.data 命名 ├── plotgroups/ 地块组 ├── districts/ 城区 ├── jails/ 监狱 └── regen.txt 地块还原队列命名规则很直观居民、城镇、国家均以UUID作为文件名如getResidentFilename而城镇地块采用x_z_尺寸.data的坐标命名如 TownyFlatFileSource.java这样即使重命名城镇也不会影响数据定位。异步写入不卡服务器的关键Towny 的读写都遵循「主线程不碰 IO」的原则。所有写操作不会立即落盘而是先放入一个并发队列由后台任务每 5 个 tick约 0.25 秒批量消费队列定义与异步任务启动TownyDatabaseHandler.java具体的文件写入由轻量任务 FlatFileSaveTask.java 执行服务器关闭时finishTasks()会排空整个队列确保所有未落盘的数据全部保存完毕见 TownyDatabaseHandler.java避免掉数据小贴士居民长时间离线后会被移入residents/hibernated/休眠加载完成时还会自动清理同名重复居民记录保证数据一致性见 TownyDatabaseHandler.java。三种备份格式内置备份功能支持folder目录复制、zip、tar.gz三种格式一键打包data/、logs/、settings/三个目录见 TownyDatabaseHandler.java。️ MySQL 引擎连接池、自动建表与异步 SQLHikariCP 连接池初始化选择 mysql 后Towny 会使用高性能连接池 HikariCP 建立连接并开启语句缓存、批量重写等优化参数连接池大小、最大存活时间、超时时间均可在database.yml中调整见 TownySQLSource.java。10 张核心表自动创建首次连接成功时SQLSchema.java 会自动创建并升级全部 10 张数据表无需手动执行建表语句表名默认前缀towny_存储内容worlds世界设置nations/towns国家 / 城镇信息residents/hibernated_residents居民 / 休眠居民townblocks城镇地块按 世界xz 联合主键plotgroups/districts/jails地块组 / 城区 / 监狱cooldowns冷却计时数据更妙的是自动升级表结构启动时会扫描现有表的列凡是新版本需要但缺失的列会逐条ALTER TABLE补齐见 SQLSchema.java老数据库直接升级插件即可用。SQL 写入同样走异步队列与扁平文件一致所有INSERT/UPDATE/DELETE都被封装成 SQLTask 任务对象放入队列由后台线程取出自连接池中取出连接执行预编译语句见 TownySQLSource.java。插件卸载时同样会先清空队列再关闭连接池保证数据完整。 数据库迁移机制版本驱动的自动升级版本号驱动database.yml中的database.version记录当前数据库版本插件 jar 内声明了最新版本号见 DatabaseConfig.java。每次启动SQLDatabaseMigrator.java 会对比两者版本一致→ 直接跳过版本落后→ 打开插件 jar从database_migration/资源目录中取出所有「版本号大于当前版本」的.sql迁移脚本占位符替换→ 脚本中的$PREFIX_会被替换为你的实际表前缀逐条执行→ 按;拆分语句依次执行执行完毕后将database.version更新为最新版本。容错标记fail-on / fail-off迁移脚本支持-- fail-off/-- fail-on注释来声明语句的容错级别见 SQLDatabaseMigrator.java。以官方迁移脚本 2.sql 为例前段将各表metadata列升级为MEDIUMTEXT属于必须成功操作而清理旧版的冗余列如residents、assistants标记为fail-off——即便列不存在导致语句失败也不中断迁移。这种设计让升级过程既严格又稳健。配置文件也有迁移器除了数据库Towny 的 YAML 配置同样有版本迁移体系RunnableMigrations.java 通过注册式迁移函数在启动时自动把旧配置项转换为新格式例如通知显示方式、农场地块方块列表等让你升级插件时无需手动改配置。✅ 如何选择存储引擎与最佳实践场景推荐引擎理由新手服 / 玩家 100flatfile零依赖出问题可直接看文本文件大型服 / 地块数千个mysql连接池 结构化查询读写更快更稳需要多插件共享数据mysql标准 SQL 接口便于对接三条实践建议切换引擎前先备份——data/目录整体备份 flatfile 数据MySQL 侧用mysqldump备份对应数据库MySQL 用户注意Towny 的内置备份只覆盖地块快照与还原文件居民/城镇/国家等核心数据在数据库中必须自行安排 MySQL 备份插件也会贴心地在日志中反复提醒你放心升级版本无论是表结构补齐updateTable还是版本化迁移脚本migrateIfNeededTowny 都已实现自动化升级插件后重启服务器即可完成数据库迁移。一句话总结Towny 用「异步队列 双引擎数据源」把文件存储的简单和 MySQL 的强悍合二为一再靠版本驱动的迁移脚本让升级全程自动化——理解这套机制你就能放心管理任何规模服务器的 Towny 数据了。【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/Towny创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考