把单实例 Nacos 用 MySQL 做持久化存储这件事我帮同事和朋友前前后后折腾过十来回。大多数人第一次装 Nacos 都是直接双击startup.cmd或执行startup.sh跑起来注册中心、配置中心都正常然后某天服务器重启发现之前保存的配置和服务注册信息全没了——不是没保存是内置 Derby 数据库的数据根本没落在你预期的地方。Nacos 单机部署看似简单但如果没接上 MySQL这个“轻量”会让你在重启后欲哭无泪。这篇内容就把单机部署 Nacos 并完成 MySQL 持久化的完整链路讲清楚从版本选型、数据库初始化到配置修改、常见坑排查再到鉴权和 Docker Compose 的高级玩法一条线走到底。涉及内容注册中心 Nacos、单机模式部署、MySQL 持久化配置、启动闪退处理、鉴权开启、命名空间划分、Docker Compose 部署 Nacos 3.x 等。适合刚接触 Nacos、被内置数据库坑过、或者准备把 Nacos 用于生产环境的同学参考。下面直接进入实操。1. 为什么单实例也要接 MySQLDerby 的坑与持久化价值1.1 内置 Derby 在单机模式下的真实表现Nacos 从早期版本开始就内置了 Derby 数据库默认情况下单机模式启动后所有配置、服务注册数据、服务实例列表都存在这个内嵌数据库里。听起来很方便零依赖解压即用。但实际使用中有一个非常隐蔽的问题Derby 的数据文件存储位置和 Nacos 的启动方式强相关。如果你在 IDE 里直接运行Nacos主类Derby 的数据会写到当前工作目录下的data文件夹如果你用startup.cmd启动数据又可能写到 Nacos 安装目录下的data如果通过 Docker 启动容器一删数据跟着彻底消失。很多人在多环境切换、升级版本、迁移部署路径之后发现之前配置的命名空间和数据全部空白本质上就是 Derby 的数据文件没有随你一起走。再一个坑是并发和一致性问题。Derby 作为内嵌数据库本身不擅长处理高并发读写。单机模式下你同时操作配置中心、多个服务注册注销偶尔会出现死锁或者连接超时的错误日志。虽然多数时候不影响核心功能但日志里那些Derby相关的异常足以让排查问题的人分心。1.2 MySQL 持久化的收益与适用场景接上 MySQL 之后最直接的变化是数据真正掌握在你手里。MySQL 作为独立进程数据文件落盘位置由你控制备份、恢复、迁移都可以用常规的 MySQL 工具完成。Nacos 重启、升级、换机器只要数据库还在注册中心和配置中心的数据就不会丢。更重要的是MySQL 持久化是后续扩展的基础。你今天单机部署明天可能就要做 Nacos 集群或者把多个环境开发、测试、生产的 Nacos 统一管理。如果从一开始就使用 MySQL后续切换集群模式时只需要改 Nacos 配置文件里的节点列表和数据库连接业务方无感知。如果一直用 Derby到了集群化的时候还得先迁移数据那时候的麻烦就是几何级增长。所以我的建议是只要是认真用的 Nacos不管是单机还是集群一律接 MySQL。除非你只是在本地跑个 demo想 5 分钟体验一下功能。对于后者也会在最后给一个快速方案但持久化之前一定要想清楚。2. 版本选型Nacos 与 MySQL 的兼容性一张表讲清2.1 Nacos 各版本对 MySQL 和 JDBC 驱动的要求版本选型是部署前最容易被忽略但出问题最频繁的环节。Nacos 官方文档里其实写得很清楚但很多人没注意Nacos 2.x 版本之后默认使用 MySQL 8 作为推荐的持久化数据库而 MySQL 5.7 仍然兼容。如果你用的是 MySQL 8需要注意 JDBC 驱动的版本以及连接 URL 里时区参数。先把常见 Nacos 版本与 MySQL 版本的匹配关系整理成表省得大家来回查Nacos 版本推荐 MySQL 版本MySQL Connector/J 版本注意事项Nacos 1.4.xMySQL 5.7 / 8.08.0.x支持 MySQL 8但需要手动指定时区Nacos 2.2.xMySQL 5.7 / 8.08.0.x兼容性较好社区使用量最大Nacos 2.3.xMySQL 8.08.0.x开始对 MySQL 8 做更多适配Nacos 2.4.x / 2.5.xMySQL 8.08.0.x / 8.1推荐 MySQL 85.7 仍可用但不在重点测试范围Nacos 3.xMySQL 8.08.0.x新内核配置中心有较大变化需对应版本从热词里看到不少人关注 MySQL 8.4.11 和 Windows 下 Nacos 的匹配问题。MySQL 8.4 是 LTS 版本连接协议和 JDBC 驱动与 MySQL 8.0 基本兼容所以只要 Nacos 能连 MySQL 8.0一般也能连 8.4。唯一要留意的是 MySQL 8.4 安装时默认的认证插件是caching_sha2_passwordNacos 的配置里如果用了密码需要保证用户的认证方式能正常通信。这个在后面的踩坑部分会细说。2.2 从热词看大家最关心的版本问题搜“Nacos 单机部署”的人里很多都在问 Windows 启动时该用哪个版本的 Nacos。其实 Windows 下不需要特殊版本Nacos 官方发行版就是跨平台的Windows 启动走bin\startup.cmdLinux 走bin\startup.sh。但要注意 JDK 版本Nacos 2.x 支持 JDK 8 和 JDK 11Nacos 2.5 对 JDK 8 依然兼容不过如果你系统里装的是 JDK 17建议优先用 Nacos 2.4 以上版本否则可能会遇到反射或模块访问的异常。ARM 架构的机器比如树莓派、部分国产服务器一般下载官方包普通版本也能跑因为 Nacos 是纯 Java 应用只要对应平台有 JDK 就行。MySQL 连接和硬件架构无关所以不存在“ARM 专版”。有时候搜到别人做的 arm 镜像那只是把 JRE 和应用一起打包了本质没区别。还有个比较特殊的热词是“Nacos 连接达梦数据库”。那是国产化环境里的需求Nacos 通过 JDBC 标准接口连接数据库理论上只要把驱动换成达梦的驱动并修改连接 URL 就能工作但 Nacos 命令行脚本里初始化 SQL 是兼容 MySQL 语法的达梦可能要做部分语法适配。这个场景比较窄平时用不到的可以忽略只要能理解 Nacos 的持久化本质是“通过 JDBC 访问外部数据库”就够了。2.3 环境准备JDK、MySQL 8、初始化脚本在动手部署之前把环境准备好JDK建议使用 JDK 8 或 JDK 11并配置好JAVA_HOME环境变量。用命令行执行java -version确认版本。MySQL本地或远程均可建议 8.0。单机部署时 MySQL 可以和 Nacos 同机生产环境推荐分开。Nacos 安装包从 GitHub Releases 下载选nacos-server-x.x.x.zipWindows或nacos-server-x.x.x.tar.gzLinux。初始化 SQL 脚本Nacos 安装目录下conf文件夹中自带nacos-mysql.sql这个脚本就是用来创建 Nacos 所需的表结构和默认数据的。注意一点下载 Nacos 安装包时别只看版本号一致还要确认是否官方发行版。一些第三方改造包可能会把 Derby 相关配置改掉导致你按照文档操作却连不上 MySQL。建议只在官方地址下载并核对压缩包的校验值。3. 单机部署完整步骤从下载到 MySQL 持久化生效3.1 初始化数据库执行 nacos-mysql.sql 的注意事项先在你的 MySQL 里创建一个独立数据库命名建议nacos_config避免和其他业务库混在一起。字符集要指定为utf8mb4排序规则默认即可。原因很简单Nacos 的表里既有服务名、分组名又有配置内容含中文的场景很常见如果不指定字符集默认的latin1会导致中文乱码或索引超长。创建数据库的 SQL 可以这样CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;然后进入 Nacos 解压目录的conf文件夹找到nacos-mysql.sql。用命令行导入mysql -u root -p nacos_config nacos-mysql.sql如果你用的是图形化客户端如 MySQL Workbench、Navicat直接打开这个 SQL 文件并选中数据库执行也可以。执行完之后可以在nacos_config库里看到config_info、config_info_beta、config_info_tag、his_config_info、tenant_info、user等一批表。看到这些表出现说明初始化成功。这里有个特别常见的错误很多人直接把nacos-mysql.sql在任意一个数据库里执行导致 Nacos 连接后找不到表。记住这个脚本必须在你自己创建的专用库里执行而且后续 Nacos 配置里的数据库名要和这里一致。3.2 修改 application.properties 的核心参数与说明初始化完数据库接下来修改 Nacos 的配置文件。在 Windows 上是conf\application.propertiesLinux 上同样是conf/application.properties。打开文件找到数据库相关配置段默认情况下大部分是被注释掉的需要自己取消注释并修改。以下是需要修改的核心配置项### 指定数据源为 MySQL spring.datasource.platformmysql ### 数据库实例数量单机部署固定为 1 db.num1 ### 数据库连接地址需要包含数据库名和时区参数 db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneAsia/Shanghai ### 数据库用户名/密码 db.user.0nacos db.password.0你的密码逐项说一下理由spring.datasource.platformmysql这是告诉 Nacos 不要使用默认的 Derby而是走 MySQL 数据源。这个参数在 Nacos 2.x 和 3.x 里仍然有效。db.num1表示只有一个数据库连接地址。每个地址对应db.url.x、db.user.x、db.password.x三个配置项。单机部署就是 0 号连接。db.url.0里必须带serverTimezoneMySQL 8 的驱动要求显式指定时区否则报The server time zone value Öйú±ê׼ʱ¼ä is unrecognized。建议写成Asia/Shanghai。useSSLfalse本地部署不使用 SSL 加密避免证书校验报错。connectTimeout和socketTimeout设成 1000ms 和 3000ms 是经验值避免数据库临时不可用时 Nacos 无限等待导致启动卡死。除了数据库配置如果你使用的是 Nacos 2.5 版本可能还需要关注### 开启鉴权强烈建议 nacos.core.auth.enabledtrue nacos.core.auth.plugin.nacos.token.secret.key你的base64密钥鉴权后面专门讲这里先把配置文件的完整形态搞对。3.3 启动服务并验证持久化效果修改完配置文件后启动服务。Windows 下在 Nacos 解压目录的bin文件夹里打开命令行执行startup.cmd -m standaloneLinux 下sh startup.sh -m standalone-m standalone是显式指定单机模式虽然 Nacos 默认单机模式也是 standalone但写清楚省得某些版本默认模式含糊。等待启动完成看到控制台输出Nacos started successfully in stand alone mode. use embedded storage或者访问http://localhost:8848/nacos出现登录界面。这里注意如果控制台输出里出现use embedded storage说明 Nacos 用的仍然是内置 Derby而不是 MySQL。正确连接 MySQL 时启动日志里通常会有加载 MySQL 数据源的信息或者你在 MySQL 里执行SHOW PROCESSLIST;能看到来自 Nacos 的连接。验证持久化有一个标准操作在 Nacos 控制台的配置管理里新建一个配置写入任意内容。然后在 MySQL 中查询SELECT * FROM nacos_config.config_info;能看到刚才创建的配置数据说明持久化已经生效。接下来重启 Nacos再回控制台看配置是否还在。如果还在那么你的 Nacos 单机 MySQL 持久化算是真正落地了。4. 实操中的高频问题与排查思路4.1 MySQL 8 连接失败时区、认证插件、驱动我在实际帮人排查时十个里有七个是 MySQL 8 连接问题。第一个是时区错误报错信息通常带有server time zone字样解决方案就是在db.url.0中加上serverTimezoneAsia/Shanghai。第二个是认证插件问题错误信息是Public Key Retrieval is not allowed这个最闹心。MySQL 8 默认的caching_sha2_password插件要求客户端在建立连接时做更严格的认证老的 JDBC 驱动或不带allowPublicKeyRetrievaltrue的 URL 会直接拒绝连接。解决方案是在连接 URL 上增加参数db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue第三个是驱动本身版本太老。Nacos 2.2 之前自带的 MySQL 驱动有可能只支持 MySQL 5.x连接 MySQL 8 时虽然能握手但编码或协议不匹配。解决方法是手动替换 Nacos 安装目录下lib/mysql-connector-java-*.jar。优先选择与 MySQL 8.0/8.4 匹配的 8.0.x 驱动比如mysql-connector-j-8.0.33.jar。4.2 Nacos 启动闪退与日志查看启动时双击startup.cmd窗口一闪而过通常说明启动脚本在执行时遇到了异常但异常信息没来得及停留。正确姿势是用命令行运行并在脚本前加上set NACOS_DEBUGtrue或用以下方式让窗口暂停startup.cmd -m standalone如果还是闪退可以直接看日志。Nacos 的启动日志在logs目录下主要有两个文件logs/start.out标准输出日志记录了启动过程的所有输出包括异常堆栈。logs/nacos.logNacos 框架日志数据库连接、鉴权等关键信息都会在这里。打开能看到类似ERROR [main] ...的报错。90% 的启动失败是这三类端口被占用8848 端口被其他进程占日志会显示Unable to start web server。解决方法是改端口在application.properties里改server.port或者杀掉占用进程。注意 Nacos 系列端口还有 9848、9849如果被占用同样可能启动失败。JDK 版本不对JDK 17 启动 Nacos 2.2 可能遇到InaccessibleObjectException这是模块化限制导致的反射报错。换 JDK 8/11或者升级 Nacos 版本。数据库连不上日志里会直接输出Failed to execute和Communications link failure。这时候检查 MySQL 服务是否正常、用户名密码是否对、网络是否通、db.num和db.url.x是否配套。排查时不要只盯着控制台一定要学会看logs/nacos.log。这个文件里信息量非常全跟着异常栈走大部分问题都能定位。4.3 配置未持久化或数据丢失的排查链路还有一种现象是配置在控制台能看到但重启后全没了。排查链路应该是首先确认application.properties里是否设置了spring.datasource.platformmysql。如果没有Nacos 会继续用 Derby配置自然消失。其次确认连接的是不是正确的数据库。如果 MySQL 里建了多个实例或多个库你导入 SQL 时导到 A 库Nacos 连接却在 B 库自然读不到表。再确认db.num后面的配置编号是否全部存在。如果只写了db.url.0但db.user.0和db.password.0没写全Nacos 可能默认用了其他配置。最后检查 MySQL 字符集和存储引擎。如果表是 MyISAM 且字符集不是utf8mb4配置内容写入时可能因为编码或锁问题失败但日志里不一定有明显报错。排查时一个快速手段是直接查询数据库如果config_info表里有记录说明数据落库了如果没有说明 Nacos 写的时候走了别的路径。MySQL 持久化的问题大多数是“配置没生效”而不是“数据没写入”所以优先检查配置文件。4.4 一条完整的排查命令序列最后给一个实际排查顺序按顺序执行基本不会遗漏# 1. 检查 Nacos 进程是否存在 ps -ef | grep nacos # 2. 检查 8848 端口是否监听 netstat -anp | grep 8848 # 3. 检查 MySQL 端口是否可连 telnet 127.0.0.1 3306 # 4. 看 Nacos 日志 tail -200 logs/nacos.log # 5. 在 MySQL 中查看表数据 mysql -u nacos -p -e use nacos_config; select * from config_info limit 5;这套组合拳下来无论问题是出在网络、进程还是数据源基本都能定位到。千万别一上来就乱改配置按顺序排除才高效。5. 单机部署进阶鉴权、命名空间与 Docker Compose 方式5.1 开启鉴权防止 namespaces 未授权访问从热词里看到了“Nacos namespaces 未授权访问漏洞【原理扫描】”。这是真实存在过的安全风险Nacos 默认情况下如果未开启鉴权任何能访问 8848 端口的人都可以通过 API 读取、写入配置甚至查看用户的敏感信息。Nacos 从 2.x 开始提供了鉴权机制但默认是关闭的。开启方式在application.properties里增加如下配置nacos.core.auth.enabledtrue nacos.core.auth.plugin.nacos.token.secret.keyVGhpc0lzTXlDdXN0b21TZWNyZXRLZXlWZXJ5TG9uZ0FuZFVucmVhZGFibGUtoken.secret.key需要不小于 32 字节的 Base64 编码字符串不能用默认值。可以使用下面命令生成echo -n 你的自定义任意长度字符串 | base64开启鉴权后控制台访问会要求登录。默认用户名nacos、密码nacos登录后建议立刻修改密码。API 访问也需要在请求头里带上Authorization: Bearer token才能正常读写配置。这里要特别提醒鉴权配置和 MySQL 持久化配置没有依赖关系但生产环境必须同时开启。你不需要担心配置多几行会增加复杂度漏配的代价远比配置成本高。5.2 使用命名空间实现配置分层持久化和鉴权都搞定后单机 Nacos 完全可以承担多环境配置管理的职责。此时学会用命名空间Namespace就很重要。Nacos 的配置模型是“命名空间 分组 配置 ID”三层结构命名空间相当于独立的环境隔离区。假设你有开发、测试、生产三套环境可以在控制台创建三个命名空间分别拿到命名空间 ID类似dev-1、test-2、prod-3。同一份配置 ID比如application.yml在不同命名空间里互不影响。这样单机 Nacos 就可以模拟集群环境的效果省钱省力。在配置bootstrap.ymlSpring Cloud 客户端时用spring.cloud.nacos.config.namespace指定命名空间 IDspring: cloud: nacos: config: server-addr: 127.0.0.1:8848 namespace: dev-1 group: DEFAULT_GROUP命名空间的数据同样存储在 MySQL 的tenant_info表里重启后不会丢。这种分层方式不仅是管理技巧也是排查问题时的思路——先确认配置在哪个命名空间再查配置内容不要只看配置 ID。5.3 用 Docker Compose 部署 Nacos 3.x 并复用 MySQL如果你不想在宿主机装 JDK、解压、修改配置Docker Compose 是一条更省心的路。特别是一些人已经用 Docker 管理 MySQL再用容器起一个 Nacos 顺理成章。下面是基于 Nacos 3.x 的 Docker Compose 示例MySQL 可以直接使用已有的服务也可以用一个轻量的 MySQL 容器。这里演示复用宿主机的 MySQL services: nacos: image: nacos/nacos-server:v3.0.0 container_name: nacos-standalone environment: - MODEstandalone - SPRING_DATASOURCE_PLATFORMmysql - MYSQL_SERVICE_HOST192.168.1.100 - MYSQL_SERVICE_PORT3306 - MYSQL_SERVICE_DB_NAMEnacos_config - MYSQL_SERVICE_USERnacos - MYSQL_SERVICE_PASSWORD你的密码 - MYSQL_SERVICE_DB_PARAMcharacterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue - NACOS_AUTH_ENABLEtrue ports: - 8848:8848 - 9848:9848 volumes: - ./logs:/home/nacos/logs几点理解起来可能有帮助的地方MODEstandalone对应单机模式但如果你还想要集群模式用 Docker Compose 起三个服务节点会更方便。环境变量里有MYSQL_SERVICE_HOST和SPRING_DATASOURCE_PLATFORM它们和第 3 节手工改application.properties的效果一样。Docker 镜像里的启动脚本会读取这些环境变量去生成配置。卷挂载./logs:/home/nacos/logs是为了持久化日志建议保留。如果你要连接 MySQL 8.4需要关注驱动兼容性。Nacos 3.x 镜像内置的驱动通常较新基本都能直接连如果遇到认证问题同样检查allowPublicKeyRetrieval参数。在 Docker 方式下初始化数据库的操作不能省。仍然要先把 Nacos 的nacos-mysql.sql导入到 MySQL 中再启动容器。这个 SQL 文件可以从 GitHub 仓库的distribution/conf路径下载也可以先启动一个临时容器把 SQL 复制出来docker run --rm -d --name nacos-tmp nacos/nacos-server:v3.0.0 docker cp nacos-tmp:/home/nacos/conf/mysql-schema.sql ./mysql-schema.sql docker stop nacos-tmpNacos 2.x 的初始化脚本叫nacos-mysql.sql3.x 里可能叫mysql-schema.sql下载时留意对应版本。最后提醒一句Docker 部署的 Nacos数据持久化靠的是 MySQL不是容器卷。MySQL 连接配置正确后即使把 Nacos 容器删掉重建配置和服务数据也都在。这也是为什么我坚持所有部署方式都用 MySQL 的根本原因。6. 写在最后的几点实操体会单机 Nacos MySQL 持久化做得多了会发现绝大多数坑集中在“版本匹配”和“配置缺行”上反而和数据本身关系不大。我的习惯是每部署一套新环境都先做一次“重启验证”写一个测试配置重启 Nacos再确认配置还在。整个过程不到一分钟却能在正式接入业务之前就把持久化链路彻底确认掉。如果你用的是 Windows 且开发机恰好装了 MySQL 8.4建议直接测一遍allowPublicKeyRetrievaltrue和serverTimezoneAsia/Shanghai这两个参数几乎每次都能遇到至少一个。如果你用的是 ARM 架构的开发板JDK 装好之后正常跑Nacos 没有特殊限制。如果你打算上 Nacos 3.x先看看它的配置中心 API 是否有变化再决定是否迁移。最后再分享一个小技巧在application.properties里加一行nacos.naming.clean.empty-service.enabledtrue定期清理空服务列表避免配置中心和服务注册信息越积越多影响查看。这个参数不影响核心功能但对使用体验的改善很明显。Nacos 的路子很宽单机部署只是第一步把这一步走稳了后面无论集群、服务发现还是配置热更新都会顺畅很多。