Nacos 3.2.2 下载、安装、配置与启动文档（Windows / Linux）,连接数据库(MySQL、SQLServer)

本文档记录了 Nacos 3.2.2 在 Windows 和 Linux 系统上的完整部署过程，以及Nacos配置数据库的步骤，包括常见问题的解决方案。

一、环境要求

JDK：17 或更高版本（Nacos 3.2.2 依赖 Java 17+，本文使用 JDK 21(Windows系统) 和 JDK 26(Linux系统) 验证通过）
操作系统：Windows 10/11，Linux（CentOS/Ubuntu/Alibaba Cloud Linux 等）
数据库（可选）：默认使用嵌入式 Derby，生产环境推荐 MySQL / PostgreSQL / SQL Server（通过插件支持）

二、下载 Nacos Server

官方下载地址
Windows 点我下载
Linux 下载:
wget https://download.nacos.io/nacos-server/nacos-server-3.2.2.zip

三、Windows 系统安装步骤

1. 解压安装包
   将下载的 nacos-server-3.2.2.zip 解压到你希望的目录，
   例如 D:\Work\Nacos\nacos-server-3.2.2。
2. 配置 JDK
   确保系统已安装 JDK 17+，并配置环境变量 JAVA_HOME。
   若系统有多个 JDK，可修改 bin/startup.cmd，在@echo off后面另起两行添加配置,这样 Nacos 启动时会强制使用指定 JDK：

set JAVA_HOME=D:\Program Files\Java\jdk21(这里调整为你自己的jdk安装路径) 
set PATH=%JAVA_HOME%\bin;%PATH%

3. 配置鉴权密钥（可以避免启动时的交互式输入）
   这里的配置可以跳过,启动时也会提示配置, 如果启动前在文件中配置好,启动时就不会提示配置了,编辑 conf\application.properties文件,分别找到以下配置行：

nacos.core.auth.plugin.nacos.token.secret.key=
nacos.core.auth.server.identity.key=
nacos.core.auth.server.identity.value=

并配置: secret.key,是要自己生成的密钥,方式可以自己浏览器搜索, 需要注意的是原文必须大于32个字符,然后 Base64 编码,将输出结果填入 token.secret.key。
identity.key和identity.value 是自定义的key和value

nacos.core.auth.plugin.nacos.token.secret.key=你的Base64密钥（原文至少32字节） 
nacos.core.auth.server.identity.key=myIdentityKey 
nacos.core.auth.server.identity.value=myIdentityValue

4. 启动 Nacos（单机模式）
   打开命令提示符（CMD），进入解压缩的nacos bin目录并执行启动脚本：

cd D:\Work\Nacos\nacos-server-3.2.2\bin startup.cmd -m standalone

5. 验证启动
   查看日志logs\start.out，看到Nacos started successfully in stand alone mode即成功。
   访问控制台：http://localhost:8080（默认用户名/密码均为nacos）。
   能看到nacos后台证明启动成功, 这个时候nacos使用的是自带的derby数据库,如果想链接其他数据库请看第七章数据库持久化相关操作步骤,另外 配置数据库中间会遇到的问题以及启动成功前后遇到的问题请查看本章第6点Windows 常见问题及解决方案。
6. Windows 常见问题及解决方案

• cmd脚本启动时报错: UnsupportedClassVersionError
  原因: 使用了低版本 JDK 运行
  解决办法: 修改 startup.cmd 强制使用 JDK 17+（见上文）
• cmd脚本启动时报错: 系统找不到指定的批处理标签 - Process_required_config
  原因: 脚本中的标签调用问题
  解决办法: 若已手动配置鉴权密钥, 忽略该报错或注释掉 startup.cmd 中三行 call :Process_required_config …（在每行前加 ”rem ”,注意空格）, 或者可能启动脚本修改过,检查一下哪里不对
• cmd脚本启动时报错: Derby 数据库锁定（Another instance of Derby may have already booted）
  原因: 上次未正常关闭或残留进程
  解决办法: 杀掉残留 Nacos 进程（taskkill /F /PID xxx）
• cmd脚本启动时报错: Caused by: java.lang.RuntimeException: Driver com.mysql.cj.jdbc.Driver claims to not accept jdbcUrl, jdbc:sqlserver://***.**.**.*:****;databaseName=123;encrypt=false;trustServerCertificate=true
  原因: 开启数据库连接后(conf/application.properties配置文件配置了数据库连接: spring.sql.init.platform=***),但Nacos 默认用 com.mysql.cj.jdbc.Driver（MySQL 驱动），即使你配了 spring.sql.init.platform=mssql或sqlserver，驱动类也不会自动切换。MySQL 驱动不认识 jdbc:sqlserver:// 格式的 URL，所以报错。
  解决办法:如果配置的是MySQL,请检查数据库地址配置的是否正确,如果配置的是SQLServer数据库, 需要在配置文件里添加驱动配置, 并且检查插件是否已放到对应位置(本文第七章数据库持久化有说这里不多赘述)

# 根据版本不一样本行配置有的版本连接SQLServer数据库的值是mssql
spring.sql.init.platform=sqlserver
db.num=1
# 加上这一行↓↓↓↓↓↓↓↓
db.pool.config.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver

db.url.0=*************************
db.user=*****
db.password=*******

• cmd脚本启动时报错: TLS10 is not accepted by client preferences \[TLS13, TLS12\]
  原因: 你的 SQL Server 只支持 TLS 1.0，但你使用的 JDK 21 默认禁用了 TLS 1.0 和 TLS 1.1，只接受 TLS 1.2+。即使 JDBC URL 中配置了 encrypt=false，MSSQL JDBC 驱动在登录阶段仍会尝试 SSL 握手，TLS 版本不匹配导致握手失败。
  解决办法:添加配置
  修改 startup.cmd — 添加 JVM 参数 在set NACOS\_OPTS 附近添加

rem Allow TLS 1.0/1.1 for SQL Server connection (disabled by default in JDK 21) 
set "NACOS_OPTS=%NACOS_OPTS% -Djdk.tls.client.protocols=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3" 
set "NACOS_OPTS=%NACOS_OPTS% -Djava.security.properties=%BASE_DIR%/conf/java-security.properties"

并在nacos的conf目录新建文件 java-security.properties 覆盖安全策略

# Custom security properties to allow TLS 1.0/1.1 for SQL Server connections
# JDK 21+ disables TLSv1 and TLSv1.1 by default, but older SQL Server only supports TLS 1.0
# This file removes TLSv1 and TLSv1.1 from the disabled algorithms list
jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, ECDH

如果这样还是报同样的错误,那么可能JDK也同样禁用了 TLS 1.0 和 TLS 1.1,找到JDK安装目录下\conf\security\java.security文件 查找内容为jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1替换为填： jdk.tls.disabledAlgorithms=SSLv3, TLSv1.1,保存后重试

• cmd脚本启动时报错: [MapperManager] Failed to find the datasource,dataSource:mssql
  原因: MSSQL 插件在 Nacos 内部注册的数据源名称是 sqlserver，但你配置的 spring.sql.init.platform=mssql，Nacos 按 mssql 去查找 Mapper 自然找不到。
  解决办法: 修改 application.properties文件 spring.sql.init.platform=mssql mssql改为 sqlserver

• 启动后查询配置列表报错: SQL [SELECT id, quota, `usage` , max_size, ... FROM group_capacity WHERE group_id = ?] "`"附近有语法错误。
  原因: GroupCapacityPersistService 中使用了 MySQL 的反引号（`）来转义列名，但 SQL Server 不支持反引号语法，需要用方括号 [] 代替。具体来说，usage 是 SQL Server 保留字，需要改为 [usage]。这是 nacos-mssql-datasource-plugin-ext-1.0.0-SNAPSHOT.jar 插件的一个 Bug 它没有完全覆盖所有 SQL 语句的方言转换。Capacity 相关的 SQL 仍然使用了 MySQL 语法。
  解决办法: 下载nacos的插件包（下载方式请看第七章数据库持久化, 这里路径是develop分支）找到nacos-plugin-develop\nacos-datasource-plugin-ext\nacos-mssql-datasource-plugin-ext\src\main\java\com\alibaba\nacos\plugin\datasource\impl\mssql\GroupCapacityMapperBySqlServer.java以及同目录下TenantCapacityMapperBySqlServer.java两个文件,然后修改这两个文件中所有的`usage`改为 [usage]
  修改完成后重新打包该插件并放到nacos的/plugins文件夹下,重新启动nacos
  

• 启动后日志有SQL 报错: DELETE FROM his_config_info WHERE gmt_modified < ? ORDER BY id OFFSET 0 ROWS FETCH NEXT ? ROWS ONLY
  原因: SQL Server 的 DELETE 语句不支持 ORDER BY 和 OFFSET...FETCH，需改用子查询方式。这也是插件代码 Bug，无法配置规避。影响的是历史配置自动清理，不清理也不影响核心功能。
  解决办法: 同样修改插件包的SQL, 找到nacos-plugin-develop\nacos-datasource-plugin-ext\nacos-mssql-datasource-plugin-ext\src\main\java\com\alibaba\nacos\plugin\datasource\impl\mssql\HistoryConfigInfoMapperBySqlServer.java打开文件找到 removeConfigHistory(MapperContext context)方法, 把原来的SQL 字符串拼接赋值改为:DELETE FROM his_config_info WHERE nid IN ( SELECT nid FROM his_config_info WHERE gmt_modified < ? ORDER BY nid OFFSET 0 ROWS FETCH NEXT ? ROWS ONLY )
  修改完成后重新打包该插件并放到nacos的/plugins文件夹下,重新启动nacos

• 启动后查询配置列表报错: his_config_info 表的 publish_type字段不存在
  原因: 版本新增数据库字段, 插件里组装SQL时没有组装该字段, nacos查询结果接收类默认有这个字段,SQL没查返回空,类校验为空,而报错
  解决办法: 首先确保数据库表是对应版本的SQL脚本创建的,并检查his_config_info表是否有该字段. 如果确认已有该字段,则修改插件包的SQL,找到nacos-plugin-develop\nacos-datasource-plugin-ext\nacos-mssql-datasource-plugin-ext\src\main\java\com\alibaba\nacos\plugin\datasource\impl\mssql\HistoryConfigInfoMapperBySqlServer.java
  打开文件找到pageFindConfigHistoryFetchRows(MapperContext context)方法,把原来的SQL赋值逻辑中SELECT部分调整一下改为SELECT nid, data_id, group_id, tenant_id, app_name, content, md5, src_ip, src_user, op_type, gmt_create, gmt_modified, publish_type, gray_name, ext_info
  
  这里增加了: content, md5, publish_type, gray_name, ext_info 字段的查询,前面两个是修其他问题加上的具体原因忘记了, 后面三个都是版本新增字段,不返回都会报错的
  修改完成后重新打包该插件并放到nacos的/plugins文件夹下,重新启动nacos

• 启动后查询配置列表, 返回数据的 配置格式 显示异常,只会显示格式为TEXT
  原因: 因为格式字段没返回前端默认的是TEXT格式(新版控制台是,旧版控制台好像是为空则不显示)总而言之出现这个情况的原因还是插件代码 Bug, SQL拼装时没有查询对应字段
  解决办法: 修改插件包的SQL,找到nacos-plugin-develop\nacos-datasource-plugin-ext\nacos-mssql-datasource-plugin-ext\src\main\java\com\alibaba\nacos\plugin\datasource\impl\mssql\ConfigInfoMapperBySqlServer.java打开文件找到findConfigInfo4PageFetchRows(MapperContext context)方法和findConfigInfoLike4PageFetchRows(MapperContext context)方法,分别对应模糊搜索和精确搜索的查询, 修改两个方法SQL拼接逻辑中的SELECT部分改为 SELECT id,data_id,group_id,tenant_id,app_name,content,md5,c_desc,type,encrypted_data_key FROM config_info 除了添加查询type字段外,这里多加了content,md5两个参数,可以不加
  
  修改完成后重新打包该插件并放到nacos的/plugins文件夹下,重新启动nacos

• 其他查询报错问题
  原因: 基本都是SQLServer插件的SQL拼接逻辑问题,找到对应的文件和拼接SQL的方法补充完整就好了

四、Linux 系统安装步骤

1. 下载,解压安装包
   先跳转到想要安装的目录下,然后执行下载和解压命令

cd /opt wget https://download.nacos.io/nacos-server/nacos-server-3.2.2.zip 
unzip nacos-server-3.2.2.zip -d /opt/ 
# 如果要移动 比如移动到/home/apps/nacos 或其他目录 
mv /opt/nacos-server-3.2.2 /home/apps/nacos

2. 配置 JDK（必须 17+）
   安装 OpenJDK 17 ：

sudo yum install java-17-openjdk -y

设置 JAVA_HOME（可添加到 ~/.bashrc）：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-$(arch)
export PATH=$JAVA_HOME/bin:$PATH
source ~/.bashrc

验证：java -version。

3. 配置鉴权密钥（同 Windows）
   这里的配置可以跳过,启动时也会提示配置, 如果启动前在文件中配置好,启动时就不会提示配置了
   编辑 conf/application.properties，添加：

nacos.core.auth.plugin.nacos.token.secret.key=你的Base64密钥 
nacos.core.auth.server.identity.key=myIdentityKey 
nacos.core.auth.server.identity.value=myIdentityValue

生成密钥（Linux）：

openssl rand -base64 32

需要注意的是原文必须大于32个字符,然后 Base64 编码,将输出结果填入token.secret.key。

4. 启动 Nacos（单机模式）

cd /home/apps/nacos/bin sh startup.sh -m standalone

5. 验证启动
   查看启动日志：
   看到Nacos started successfully 即成功。
   访问控制台：http://服务器IP:8080（默认用户名/密码均为 nacos）。
   若无法访问，检查防火墙是否开放 8080/8848 端口

tail -f /home/apps/nacos/logs/startup.log

6. Linux 常见问题及解决方案(未列出的可以参考第三章win安装时的常见问题及解决方案)

问题现象	原因	解决方案
UnsupportedClassVersionError	JDK 版本低于 17	升级 JDK 至 17+
Derby 数据库锁定（Another instance of Derby may have already booted）	残留进程或非正常关闭	杀掉所有 Nacos 进程：pkill -9 -f nacos-server.jar；删除 data/derby-data 目录（测试环境）
启动时交互式询问密钥	未配置鉴权属性	按上文配置application.properties
启动后进程自动退出	内存不足或配置错误	查看logs/startup.log 和 logs/nacos.log 定位错误

五、便捷启动脚本（简化命令）

Windows 系统 创建 startup-standalone.cmd，内容如下：

@echo off call startup.cmd -m standalone

放置在bin目录，之后直接双击或执行该文件即可。
Linux 系统 创建 startup-standalone.sh，内容如下：

#!/bin/bash sh /home/apps/nacos/bin/startup.sh -m standalone "$@"

赋予执行权限：

chmod +x startup-standalone.sh

之后使用 ./startup-standalone.sh 或 sh startup-standalone.sh 启动。

六、停止 Nacos

Windows：在bin目录下执行shutdown.cmd
Linux：在bin目录下执行shutdown.sh或pkill -9 -f nacos-server.jar

七、数据库持久化（生产环境建议）

nacos默认使用嵌入式 Derby，数据存储在data/derby-data，重启数据不丢失，但集群和稳定性受限。

1. 配置 MySQL 示例:
   创建数据库: 在数据库执行 conf/mysql-schema.sql 脚本。
   修改 conf/application.properties 文件：

spring.sql.init.platform=mysql 
db.num=1 
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useSSL=false&serverTimezone=UTC 
db.user.0=root 
db.password.0=yourpassword

2. 配置 SQL Server数据库
   创建数据库: Nacos没有提供SQLServer创建脚本, 可以用conf/mysql-schema.sql 脚本进行转换,找AI转换或者有其他工具都行。
   另外, 需要使用SQLServer数据源插件:

• 下载SQLServer插件 点我访问nacos插件库
  注意根据nacos版本下载对应的插件合集压缩包,上面提供的连接是跳转develop分支
  下载好后解压,解压完成后打开cmd命令进入到解压后的nacos-plugin-develop目录, 输入命令进行打包(要先装maven):mvn clean package -DskipTests=true
  
  然后打开解压后的nacos-plugin-develop文件夹,进入目录:\nacos-plugin-develop\nacos-datasource-plugin-ext\nacos-mssql-datasource-plugin-ext\target
  把nacos-mssql-datasource-plugin-ext-1.0.0-SNAPSHOT.jar包放到nacos安装目录的plugins文件夹下
• 从微软官方网站下载适用于SQL Server的JDBC驱动JAR包
  点我下载
  下载后解压进入:sqljdbc_13.4\chs\jars 找到jar包（例如 mssql-jdbc-x.x.x.jre11.jar）,注意确保 JDBC 驱动版本与JDK 版本兼容,同样放到nacos安装目录的plugins文件夹下
• 修改Nacos 的配置文件, 安装目录下:conf/application.properties文件

# 有的版本本行的配置值为: mssql
spring.sql.init.platform=sqlserver
db.num=1

# 虽然配置了其他数据库为了防止nacos启动时仍然默认加载mysql驱动,加上这一行↓
db.pool.config.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver

db.url.0=jdbc:sqlserver://数据库ip:端口号;databaseName=数据库名;encrypt=false;trustServerCertificate=true
db.user=<账号>
db.password=<密码>

• 启动nacos验证
  如果启动报错,报错原因及解决方法请看本文第三章6. Windows 常见问题及解决方案