多数据源插件

Nacos 通过数据源方言插件适配不同数据库。插件负责处理 SQL 方言、分页、函数、主键返回方式，以及 Nacos 逻辑表对应的 mapper 实现。

从 Nacos 2.2.0 开始，数据源方言可以通过 SPI 扩展。当前 Nacos next 版本的官方默认实现已经支持 4 种数据库：derby、mysql、postgresql 和 oracle。

官方支持的数据库

默认数据源实现位于 Nacos 代码仓库的 plugin-default-impl/nacos-default-datasource-plugin 模块。每个数据库类型都同时注册 DatabaseDialect 和表级 Mapper SPI。

选择数据库类型

推荐使用 spring.sql.init.platform 指定数据库类型：

spring.sql.init.platform=mysql

为了兼容旧版本，Nacos 仍然兼容 spring.datasource.platform。新部署建议统一使用 spring.sql.init.platform。

如果没有显式指定数据库类型，Nacos 会根据运行模式选择默认存储：

生产环境建议使用外置数据库，并在启动 Nacos 前导入对应数据库的 schema。

外置数据库配置

以 PostgreSQL 为例：

spring.sql.init.platform=postgresql
db.num=1
db.url.0=jdbc:postgresql://127.0.0.1:5432/nacos
db.user=nacos
db.password=nacos
db.pool.config.driverClassName=org.postgresql.Driver
db.pool.config.connectionTestQuery=SELECT 1

以 Oracle 12c 及以上版本为例：

spring.sql.init.platform=oracle
db.num=1
db.url.0=jdbc:oracle:thin:@127.0.0.1:1521:XE
db.user=nacos
db.password=nacos
db.pool.config.driverClassName=oracle.jdbc.OracleDriver
db.pool.config.connectionTestQuery=SELECT 1 FROM dual

db.pool.config.* 会传递给 HikariCP。可以按需配置 connectionTimeout、maximumPoolSize、minimumIdle 等连接池参数。

配置多个数据库连接

db.num 表示外置数据库连接数量。Nacos 会对多个连接做健康检查和主库选择。多个连接应属于同一种数据库类型。

spring.sql.init.platform=mysql
db.num=2
db.url.0=jdbc:mysql://db-0:3306/nacos?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
db.url.1=jdbc:mysql://db-1:3306/nacos?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
db.user.0=nacos
db.password.0=nacos_password_0
db.user.1=nacos
db.password.1=nacos_password_1

如果所有连接使用同一个用户名和密码，也可以只配置 db.user 和 db.password。

社区数据源插件

除官方内置的 4 种数据库外，Nacos 社区在 nacos-group/nacos-plugin 仓库维护了一批扩展数据源插件。当前仓库中包含以下数据源扩展模块：

社区插件的版本兼容性、schema、驱动依赖和部署方式以插件仓库对应 README 为准。生产使用前，请在测试环境完成 schema、启动、读写、升级和回滚验证。

部署外部插件

如果使用社区插件或自定义插件，通常需要：

1. 选择与 Nacos 版本匹配的插件版本。
2. 编译插件并取得插件 JAR。
3. 将插件 JAR 和数据库驱动 JAR 放到 ${nacos.home}/plugins，或者通过启动参数追加到 classpath。
4. 在 application.properties 中设置 spring.sql.init.platform 为插件声明的数据库类型。
5. 导入对应数据库 schema。
6. 重启 Nacos，并检查启动日志中是否加载了目标 dialect 和 mapper。

自定义数据源插件

自定义数据源插件至少需要实现两类 SPI：

一个数据库类型的 dialect 和 mapper 必须一起打包和加载。只提供 dialect 或只提供 mapper 都会导致启动或运行时失败。

当前 mapper 覆盖范围包括：

• 配置表：config_info、config_info_beta、config_info_gray、config_info_tag、config_tags_relation、his_config_info；
• 容量和命名空间表：tenant_info、tenant_capacity、group_capacity；
• 配置迁移查询；
• AI 资源表：ai_resource、ai_resource_version。

开发时可以参考官方默认实现中的 derby、mysql、postgresql 和 oracle 模块。插件需要在 META-INF/services 下注册：

com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect
com.alibaba.nacos.plugin.datasource.mapper.Mapper

排障建议