新拉起来的 Nacos 服务在终端里吐出一大屏红色堆栈，第一行就顶着Unable to start embedded Tomcat。这个场面，做微服务的同学大概率不陌生。它翻译过来其实很直白：Spring Boot 内嵌的 Web 容器没起来。但问题是，Tomcat 为什么没起来？答案全藏在后面那一长串Caused by里。
这篇文章把我自己踩过、也帮别人查过的几类根因，按从易到难的排查顺序整理出来。如果你是刚接触 Nacos 的小白，能看到完整的排查链路和操作命令；如果是老手，也可以直接跳到第四节，那几个版本和环境相关的坑，很多文章不会写。
1. 报错日志的真实含义：别被表面信息带偏
1.1 先搞懂 Spring Boot 的内嵌容器启动链路
Nacos 服务端本身是基于 Spring Boot 构建的应用，它启动时会走一套标准的初始化流程：加载配置、创建 Spring 容器、初始化各种 Bean，最后启动内嵌的 Tomcat Web 服务器。Unable to start embedded Tomcat这个异常，就是在最后这一步被抛出来的。
如果用一句话概括 Spring Boot 的内嵌容器机制：它不像传统 Tomcat 那样独立安装、独立启动，而是把 Tomcat 作为依赖库打包进应用里，由应用代码在运行时把 Tomcat 实例创建出来、绑定端口、加载 Servlet 容器。这样做的好处是部署方便、版本可控。坏处是，一旦 Tomcat 初始化过程中遇到任何问题，整个应用直接就凉了，日志里最显眼的就是这个顶层异常。
所以第一点要记住：这个异常是"症状"，不是"病根"。它就像体检报告上写的"指标异常"，真正的问题在哪，你得看下面的明细项。
1.2 学会从嵌套异常里找真正的根因
Java 异常链里，每一层Caused by都指向更底层的原因。很多人一看到Unable to start embedded Tomcat就慌了，开始搜怎么解决，其实正确姿势是往下看。
一段典型的报错堆栈大概是这样的：
org.springframework.boot.web.server.WebServerException: Unable to start embedded Tomcat at org.springframework.boot.web.embedded.tomcat.TomcatWebServer.initialize(TomcatWebServer.java:142) at org.springframework.boot.web.embedded.tomcat.TomcatWebServer.<init>(TomcatWebServer.java:88) ... Caused by: java.net.BindException: Address already in use: bind at sun.nio.ch.Net.bind0(Native Method) at sun.nio.ch.Net.bind(Net.java:433) ...看到最下面那行Caused by: java.net.BindException了吗？这才是真凶：端口被占了。
但也有另一种情况，堆栈层层嵌套，最底层的根因变成了：
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: ... Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'externalDataSource' ... Caused by: com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure同样是Unable to start embedded Tomcat，但问题出在数据库连接初始化上，和端口半毛钱关系都没有。
排查这类问题有个很实用的技巧：启动日志一般会写入logs/nacos.log，不要对着终端慢慢翻，直接检索关键词：
grep -i "caused by" logs/nacos.log | tail -20把所有Caused by按顺序列出来，一眼就能看出异常是从哪一层开始恶化的。我排错的顺序也很固定：先看最底层的Caused by是什么类型，再往上追一层看它是在哪个组件初始化时触发的。这样定位问题通常不会跑偏。
2. 第一轮快速排查：端口占用与防火墙的经典陷阱
2.1 Nacos 的端口矩阵：8848、9848、9849 一个都不能少
端口占用是Unable to start embedded Tomcat里最常见的根因，没有之一。但关于端口，有一个很多人不知道的细节：Nacos 2.x 不止用 8848 一个端口。
我整理了一份 Nacos 2.x 的默认端口清单：
| 端口 | 用途 | 说明 |
|---|---|---|
| 8848 | 主 HTTP 端口 | 控制台、Open API 都走这里 |
| 9848 | gRPC 服务端端口 | 2.x 版本新增，供客户端长连接使用 |
| 9849 | gRPC 客户端端口 | 客户端连接时实际使用的端口 |
| 7848 | 集群 jraft 通信端口 | 仅集群模式使用 |
其中 9848 和 9849 是基于主端口自动偏移的：主端口 +1000、+1001。也就是说，如果你把server.port改成了 8849，那么 gRPC 相关端口会自动变成 9849 和 9850，而不是固定不变。
这里的坑在于：很多人排查端口冲突时只查 8848，发现 8848 没被占用就信誓旦旦地排除了端口问题。结果真正的冲突在 9848 上——可能是某个老版本的 Nacos 客户端、gRPC 测试工具，甚至是之前启动没杀干净的残留进程占着。所以排查时三个端口都要查。
2.2 端口占用的标准排查动作
端口排查的命令很固定，我每次都是这么操作的。Linux 和 Mac 上：
# 分别检查三个端口 lsof -i :8848 lsof -i :9848 lsof -i :9849 # 有结果会显示 PID，没有结果就是没被占用 # 确认是残留进程后直接杀掉 kill -9 <PID>Windows 上换成：
netstat -ano | findstr :8848 netstat -ano | findstr :9848 # 最后一列是 PID，然后强制结束 taskkill /F /PID <PID>有个特别容易踩的场景：机器上跑着 Docker，某个容器用-p 8848:8848做了端口映射，虽然容器已经停了，但 docker-proxy 进程还占着端口，lsof里看到的是进程名而不是你想当然的"另一个 Nacos"。这时候可以用：
docker ps -a | grep 8848把相关容器全部清理掉再启动。我遇到过不止一次，排查到最后发现是之前调试时留下的容器在作祟。
2.3 防火墙与安全组：看起来像端口问题，其实不是
还有一种情况很容易让人误判：服务本地日志显示一切正常、没有任何报错，但外部访问 Nacos 控制台就是不通。这种一般不是Unable to start embedded Tomcat的报错场景，但它和端口问题纠缠在一起，很容易混淆排查思路。
要区分"端口被占启动失败"和"端口没放行访问不了"，判断标准很简单：如果启动时抛了 BindException，那是端口冲突；如果启动成功、日志里出现了Nacos started successfully，但本机curl http://127.0.0.1:8848/nacos通、局域网或公网 IP 不通，那就是安全组或防火墙的问题。云服务器要检查安全组规则是否放行了 8848，物理机要检查 iptables 或 firewalld。别在启动报错的环境里白折腾防火墙，看日志说话。
3. 真正的高级排雷：数据源、驱动与存储模式三连坑
3.1 Nacos 的两种存储模式：内嵌 Derby 与外部 MySQL
排除了端口问题还是启动失败，下一步要看的就是数据源。Nacos 服务端本身也是一个有状态的应用，它需要存储配置信息、服务注册数据。官方支持两种存储方式：内嵌的 Derby 数据库（默认单机模式）和外部 MySQL。
这里有个很关键的设计逻辑：Nacos 在单机模式下，如果没有显式配置 MySQL，就走内嵌 Derby；一旦你在application.properties里配置了spring.datasource.platform=mysql以及db.url.0等连接参数，Nacos 就会优先连 MySQL。MySQL 连接不上，DataSource初始化失败，Spring 容器在创建依赖它的 Bean 时抛异常，最终传导到 Tomcat 启动环节，表现在日志上就是Unable to start embedded Tomcat。
我见过不少同事拿到一段网上的配置，直接复制进application.properties，连 MySQL 地址、密码都没改，然后启动报错一头雾水。说白了，Nacos 自己不会同时用两套存储，配了 MySQL 就得对 MySQL 负责。
3.2 MySQL 连接失败的典型姿势
正确的 MySQL 配置长这样：
### 指定数据源平台为 MySQL，不设置则默认走内嵌 Derby spring.datasource.platform=mysql ### 数据库实例数量，集群模式通常为 1 db.num=1 ### 连接 URL，注意时区和 SSL 参数 db.url.0=jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai db.user.0=nacos db.password.0=nacos按我的经验，最常见的失败原因集中在这么几个地方：
| 症状 | 根因 | 快速判断方法 |
|---|---|---|
| Communications link failure | MySQL 服务没启动或网络不通 | 用客户端工具连一下试试 |
| Access denied for user | 用户名/密码错误或授权不对 | 检查db.user.0和db.password.0是否和库里真实账号一致 |
| Unknown database 'nacos_config' | 数据库还没有创建 | show databases;看看有没有 |
| The server time zone value 时区异常 | 连接 URL 少了serverTimezone参数 | MySQL 8 驱动必填时区 |
| ClassNotFoundException: com.mysql.cj.jdbc.Driver | 驱动包缺失 | 检查 Nacos 安装目录的lib/下是否有mysql-connector-java的 jar 包 |
我特别想多说一句Unknown database这个坑。Nacos 的 MySQL 模式不会帮你自动建库，需要你自己提前执行建库脚本。首次部署时，官方手册要求你把conf/mysql-schema.sql导入到你创建的数据库里。很多人以为配置好连接就行，结果库是空的，启动时虽然 DB 连接成功，但后续初始化表结构时照样抛异常。建议建库操作做完后，先进 MySQL 里看一眼表是否真的建出来了。
3.3 单机模式与集群模式的边界条件
Nacos 的存储模式还和启动模式强相关：单机（standalone）模式可以用 Derby，集群（cluster）模式则必须用 MySQL，并且生产上要求至少配置一个高可用数据库。
很多新手会在这里踩一个隐形地雷：下载完 Nacos 后直接执行startup.sh不带任何参数，这时候默认是按集群模式启动。集群模式启动会尝试从conf/cluster.conf里读取集群节点列表。如果这个文件不存在，或者文件里写的是别人的机器地址，Nacos 就会一直处于寻找集群节点的状态，可能表现为长时间启动卡住，也可能直接启动失败。
我的建议是，开发环境老老实实加-m standalone参数：
sh startup.sh -m standaloneWindows 上就是：
startup.cmd -m standalone如果你已经确定要用集群模式，那就认真配置cluster.conf，写上所有节点的 IP 和端口，确保每个节点之间 7848 端口互通，再用 MySQL 作为统一存储。开发环境图省事用-m standalone就够了，别在集群模式上硬纠结。
还有一类 Derby 相关的衍生问题：单机模式跑了一段时间后，突然启动报错，日志里出现 Derby 数据库相关的冲突或锁错误。这种多半是上一次进程没有被干净地停止，数据目录data/里的 Derby 文件被锁定或损坏了。稳妥的处理方式是先备份数据目录，然后停掉所有相关 Java 进程，删除data/下的 derby 相关文件夹，重新启动。当然，这种方式会丢失本地 Derby 里已有的配置，用外部 MySQL 存储的公司内部环境基本不受影响。
4. 环境参数与版本兼容：容易被忽略的隐形地雷
4.1 JVM 内存参数：启动脚本里那点小事
Nacos 的启动脚本bin/startup.sh（Windows 是startup.cmd）里，默认给 JVM 分配了固定的内存参数。以 Linux 脚本为例，里面有一行类似这样的配置：
JAVA_OPT="${JAVA_OPT} -Xms512m -Xmx512m -Xmn256m"这表示初始堆 512 兆、最大堆 512 兆、新生代 256 兆。看着不多，但你如果是在一台只有 512M 内存的小机器上跑，进程起来操作系统就已经很吃力了，JVM 申请不到足够的堆内存，启动时直接抛Could not reserve enough space for object heap，根本走不到 Tomcat 启动那一步。
遇到这种情况，把脚本里的内存参数调小即可：
JAVA_OPT="${JAVA_OPT} -Xms256m -Xmx256m -Xmn128m"另外要提醒一点：如果JAVA_HOME没有配置或者配置错误，脚本会直接提示找不到 Java 环境，这种反而好处理。难处理的是JAVA_HOME指向了错误的 JDK 版本——比如系统里装了多个 JDK，脚本找到的是 1.7，Nacos 2.x 直接起不来。建议启动前先执行：
echo $JAVA_HOME java -version确认这两个输出的版本一致，且满足 Nacos 的要求。
4.2 JDK 版本与 Nacos 版本的兼容关系
Nacos 服务端官方要求 JDK 8 及以上，但这个"及以上"并不是无上限的。我在自己电脑上用 JDK 17 跑过 Nacos 2.2.0，启动时虽然没有直接看到Unable to start embedded Tomcat，但 JVM 输出了大量Illegal reflective access警告，某些扩展功能偶发异常。后来换回 JDK 8，一切都安静了。
个人经验是：跑 Nacos 服务端，OpenJDK 8 是性价比最高的选择。不只是因为兼容性，还因为 Nacos 官方对 JDK 8 的测试覆盖最充分，社区里的各种部署文档默认也是基于 JDK 8 写的。你要是用 JDK 11 或 17 在开发机上跑着玩没问题，但生产环境建议统一 JDK 8。
客户端侧的兼容问题更隐蔽。Spring Cloud 项目引入 Nacos 客户端时，如果版本和 Nacos 服务端 2.x 的 gRPC 机制不匹配，可能出现客户端反复重连、注册不上服务的现象，但服务端日志往往只有普通的连接日志，不容易和启动报错关联起来。这里给个大致的对应参考：
| Nacos 客户端版本 | 适配 Nacos 服务端版本 | 说明 |
|---|---|---|
| 1.x | 1.x | 老版本纯 HTTP 通信，连 2.x 服务端会缺少 gRPC 支持 |
| 2.x | 2.x | 正常使用，注意客户端版本别比服务端新太多 |
| 2.2.x | 2.2.x 及以上 | 当前的主流组合，推荐使用 |
具体到 Spring Cloud 项目，还要结合 Spring Cloud Alibaba 的版本去选 Nacos 客户端版本，这块展开能写一篇长文，这里就不跑题了。但请记住一条：报错定位的顺序永远是先看服务端能不能启动，再看客户端能不能连上。
4.3 启动模式选择：standalone 与 cluster 的正确打开方式
上一节提到，startup.sh不带参数时会默认集群模式启动。这里换个角度再补充一个细节：开发环境下你改了application.properties里的端口或者数据库配置，但启动时仍感觉没生效——先检查一下是不是有环境变量在覆盖文件里的配置。
Nacos 支持通过环境变量覆盖配置，比如NACOS_SERVER_PORT、MODE这类变量。如果系统环境变量里曾经设置过MODE=cluster，就算你在命令行写了-m standalone，也可能因为优先级问题导致实际仍按 cluster 启动。排查方法很简单，启动前打印一下相关变量：
env | grep -i nacos env | grep -i mode确认没有环境变量干扰后再启动。这类问题最迷惑的地方在于：你改了配置，但启动逻辑读的根本不是你改的那个文件。
5. 排查链路的完整复盘与验证清单
5.1 从现象到根因的完整决策链路
把上面所有排查路径整理成一张表，遇到Unable to start embedded Tomcat可以按顺序过一遍：
| 排查步骤 | 关键动作 | 预期结果 |
|---|---|---|
1. 看最底层Caused by | grep -i "caused by" logs/nacos.log | 定位异常根因类型 |
| 2. 查端口占用 | lsof -i :8848、9848、9849 | 无输出，或确认占用进程可清理 |
| 3. 检查启动模式 | 是否为-m standalone，有无环境变量干扰 | 模式与用途匹配 |
| 4. 检查数据源配置 | 确认 Derby 或 MySQL 模式；MySQL 连接必须连通、库和表已初始化 | 数据源初始化无异常 |
| 5. 检查系统资源 | 内存是否充足、JVM 参数是否合理 | JVM 正常启动 |
| 6. 检查 JDK 版本 | java -version，JDK 8 优先 | 版本兼容 |
| 7. 检查权限问题 | logs/、data/目录是否可写 | 无权限异常 |
这套顺序基本覆盖了我遇到过的所有启动失败场景。实践中有个原则：每排查一项就重新启动一次，确认问题是否还在，不要一次性改一堆配置再启动。这样可以精确知道是哪一步解决了问题，下次遇到类似情况能直接跳过无关步骤。
5.2 修复后如何确认服务真正可用
启动日志里看到Nacos started successfully只是第一步，真正要确认服务可用，我习惯做三个验证：
# 1. 健康检查接口，返回 OK 表示服务就绪 curl "http://127.0.0.1:8848/nacos/v1/console/health/readiness" # 2. 打开控制台首页，返回 HTML 而不是报错 curl -I "http://127.0.0.1:8848/nacos/" # 3. 使用默认账号测试登录 # 浏览器打开 http://127.0.0.1:8848/nacos # 默认用户名 nacos，默认密码 nacos控制台能登录、能显示服务列表和配置列表，才算真正跑通。如果你用的是外部 MySQL，进去之后随便建一个测试配置，然后去看 MySQL 里的config_info表，确认数据落到了数据库里，这样可以验证存储模式确实切换成功了。
还有一个容易被忽略的细节：健康检查返回 OK 不代表 gRPC 端口就一定正常。更严谨的做法是用一个 Nacos 客户端注册一个临时服务试试，服务能注册成功、控制台能看到心跳，这链路才是全通的。
5.3 同类问题举一反三
最后多说几句举一反三的内容。Unable to start embedded Tomcat整个异常家族在 Spring Boot 生态里非常常见，不只是 Nacos。你可能遇到Unable to start web server、Tomcat ... failed to start、Port already in use等各种变体，但底层逻辑都一样：Web 容器初始化过程中某个前置条件不满足。
我在实际排查这类问题时，养成了三个习惯，分享给大家：
第一，永远先看Caused by那行，而不是第一行异常信息。第一行只告诉你"哪里坏了"，Caused by才告诉你"为什么坏"。别在第一行异常上浪费时间搜索。
第二，改任何配置之前先备份一份原始的application.properties。我见过有人排查问题时把配置改得面目全非，最后想回退都不知道原样是什么。cp application.properties application.properties.bak这行命令，关键时刻能救命。
第三，启动环境要保持"最小可信"。开发机尽量用最接近生产环境的 JDK 版本和启动脚本，不要今天用 IDE 直接跑、明天用脚本跑，两种方式的类路径和参数可能完全不同，问题表现也可能完全不同。保证启动方式一致，排错才能高效。
排查 Nacos 启动问题本身不复杂，复杂的是被表面异常迷惑，在错误的方向上反复折腾。希望这篇复盘能帮你节省几个小时——这时间拿去休息，比对着日志发呆强多了。
