本地正常、上线就 Connection refused,日志却同样写着 Started------「启动成功但接口调不通」最磨人的地方,是日志先骗了你。这篇给一套从外到内的 7 步排查顺序,每步看哪行日志、跑哪条命令都列清楚,看完能直接照着定位。
上周帮同事看的就是这个:重启、改端口、怀疑打包漏了 Controller,折腾一上午。最后 ss -lntp 里一行说明白------应用在服务器上只监听 127.0.0.1:8080,压根没对外开。
这类问题不止绑定地址一种。404、405、401、超时、服务间调用失败,各有各的查法。文末有流程图、速查卡和上线前清单,存下来下次直接过一遍。
先把 7 步摆出来。 这一段可以单独存,图看不清的时候照着走:
-
确认应用是否真正启动 ------ 认
Started XxxApplication和Tomcat started on port(s) -
确认监听的 IP 和端口 ------
ss -lntp/netstat -ano,看是不是0.0.0.0 -
确认 URL 和请求方式 ------ context-path、HTTP 方法、尾斜杠
-
确认 Controller 与路径映射 ------ 问
/actuator/mappings -
检查拦截器与 Spring Security ------
permitAll()、CSRF、Token -
检查防火墙、Docker、反向代理 ------ 本机 → 内网 → 公网三层 curl
-
检查服务发现与调用链路 ------ 注册中心实例列表 + 直连实例做二分
第 1 步 · 先别急着改代码,确认「启动成功」是真的
现象 :日志里能看到 Tomcat initialized with port(s): 8080 (http),甚至能看到端口打印,但请求全挂。
原因:初始化不等于启动完成。容器线程起来了,Bean 还在初始化,中途抛异常没打全日志;或者旧进程还占着 8080,你看到的日志是另一个实例的;K8s 里更常见------进程在跑,readinessProbe 没过,流量压根没切过来。
检查方法:只认两行日志,缺一不可。
bash
tail -n 100 app.log | grep -E "Started|Tomcat started|APPLICATION FAILED|Caused by"
# Windows PowerShell
Select-String -Path app.log -Pattern "Started|Tomcat started|APPLICATION FAILED|Caused by" | Select-Object -Last 30
jps -l
ps -ef | grep java
docker logs --tail 100 order-service
要看到 Tomcat started on port(s): 8080 (http) with context path '/api' 和最后的 Started OrderApplication in x seconds。另外往上翻 100 行,别漏掉 APPLICATION FAILED TO START 下面的 Caused by------很多人只看最后 10 行,正好把根因翻过去。
解决与验证:进程在、两行日志都在、本地 health 能通,才算第一层过。
bash
curl -i http://127.0.0.1:8080/api/actuator/health
返回 {"status":"UP"} 再往下走。这一步不通,后面六步都是白跑。
第 2 步|Connection refused
现象 :curl: (7) Failed to connect to 127.0.0.1 port 8080: Connection refused,或者 Feign 抛 java.net.ConnectException。请求根本没进 Tomcat。
原因 :目标端口没有进程监听。四种可能------应用没真起来;端口被 --server.port、环境变量或配置中心覆盖了;测试代码里写了 server.port=0 用随机端口;应用只绑了 127.0.0.1 或 IPv6 的 ::1。
检查与验证:
bash
# Linux / macOS:重点看 Local Address 是 0.0.0.0、127.0.0.1 还是 :::
ss -lntp | grep 8080
lsof -i :8080
# Windows
netstat -ano | findstr :8080
tasklist | findstr java
顺手确认最终生效的配置:spring.profiles.active 是不是你以为的那份,命令行有没有带 --server.port。我见过最隐蔽的一次,是 CI 启动脚本里写死了 --server.port=8081,开发对着 application-dev.yml 里的 8080 查了一下午。
第 3 步|405 Method Not Allowed
现象 :Request method 'POST' not supported,响应头带 Allow: GET,HEAD。
原因 :路径对,方法不对。前端发 POST、后端写 @GetMapping;网关或中间层改写了方法;CORS 预检的 OPTIONS 被当成业务请求拦了。
检查与验证 :Allow 头就是答案,它直接列出这个路径接受哪些方法。
bash
curl -i -X POST http://127.0.0.1:8080/api/order/list
curl -i -X OPTIONS \
-H "Origin: http://localhost:5173" \
-H "Access-Control-Request-Method: POST" \
http://127.0.0.1:8080/api/order/list
浏览器 DevTools 里「Copy as cURL」把前端真实请求复制出来跑一遍,比对着代码猜快得多。这一步顺带把 context-path、Content-Type、参数位置一起核对掉,能挡掉后面一大半的 404。
第 4 步|404 Not Found
现象 :连得上,返回 Whitelabel 错误页,或者 {"status":404,"error":"Not Found","path":"/order/list"}。
原因:路径没有对应的 Handler 映射。按出现频率排:
-
漏了 context-path ------ 配了
/api却请求/order/list。严格说这是上一步该拦住的,但因为它表现为 404,放这里一起讲。 -
Controller 没被扫到 ------
@SpringBootApplication默认只扫启动类同包及子包,启动类挪到别的包、Controller 留在原包,就直接不注册。 -
注解写错 ------ 用了
@Controller没加@ResponseBody,返回的是视图名不是 JSON。 -
Spring Boot 3 的尾斜杠 ------ Spring Framework 6 起
useTrailingSlashMatch默认关掉,/order/list/不再自动命中/order/list。从 Boot 2 升级上来最容易中招。 -
网关削前缀 ------ Gateway 的
StripPrefix或 Nginx rewrite 把路径改了,到后端时已经不是原来那个 URL。
检查与验证:直接问应用「你到底注册了哪些映射」。
bash
curl -s http://127.0.0.1:8080/api/actuator/mappings | grep order
# Windows:把 grep 换成 findstr
查不到,就回启动日志看 Mapped "{[/order/list]}" onto ... 有没有打印,再查扫描包和注解。开头那份配置里已经把 RequestMappingHandlerMapping 调到 TRACE,会打出完整注册明细。
这里有个坑:/actuator/mappings 自己也可能返回 404。Actuator 默认 Web 只暴露 health 和 info,不配 management.endpoints.web.exposure.include,排查工具本身就先把你带偏一次。
第 5 步 · 401 / 403 与请求超时:两类「软故障」
5.1 401 和 403
现象:401 Unauthorized、403 Forbidden,或者被重定向到登录页------前端框架拿到一段 HTML 当 JSON 解析,看起来像接口挂了。
原因 :最常见的是引入了 spring-boot-starter-security 却没自定义 SecurityFilterChain。默认规则是所有请求都要 HTTP Basic,用户名 user,密码在启动日志里随机生成。
bash
grep "Using generated security password" app.log
其它几类:permitAll() 没覆盖该路径;Security 默认对 POST / PUT / DELETE 开启 CSRF,没带 token 直接 403;JWT 过期、Header 名写错、漏了 Bearer 前缀;@PreAuthorize 方法级权限。还有一种容易误判的------401 是网关鉴权返回的,根本不是业务服务的响应,先看响应体和服务标识再动手。
检查与验证 (开头配置里已开 org.springframework.security: DEBUG):
bash
# 返回 401 且带 WWW-Authenticate: Basic,基本坐实是 Security 默认配置
curl -i http://127.0.0.1:8080/api/order/list
# 显式带 token 对比
curl -i -H "Authorization: Bearer TOKEN" http://127.0.0.1:8080/api/order/list
DEBUG 下 FilterChainProxy 会逐个打印经过的 Filter,卡在哪一层一目了然。本地或测试环境可以临时 permitAll() 做二分定位,测完记得还原。
要自己接管规则,最小配置长这样(Spring Boot 3 / Spring Security 6 用 requestMatchers;Security 5.x 是 antMatchers):
bash
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/health", "/order/list").permitAll()
.anyRequest().authenticated())
.csrf(csrf -> csrf.disable()); // 仅为定位问题,生产按实际评估
return http.build();
}
}
注意 requestMatchers 里写的是去掉 context-path 之后 的路径,所以是 /order/list 而不是 /api/order/list。csrf.disable() 只是排查期的临时手段,别原样抄进生产。
5.2 请求超时(不是独立一步,是沿各层继续定位)
现象 :java.net.SocketTimeoutException: Read timed out、Feign 的 Read timed out executing GET ...、网关 504、前端一直转圈。
原因 :接口本身慢(慢 SQL、外部 HTTP 调用没设超时、大对象序列化);Tomcat 工作线程打满(默认 max 200)或 HikariCP / HTTP 连接池耗尽;下游级联拖慢;网关和 Feign 的超时设得比业务耗时短;只配了 connectTimeout 忘了 readTimeout;卡在分布式锁或数据库行锁上。
检查与验证:先把「慢」量化,再决定往哪查。
bash
# 业务接口耗时
curl -w "connect=%{time_connect} total=%{time_total}\n" -o /dev/null -s \
http://127.0.0.1:8080/api/order/list
# 对照:一个几乎不干活的健康检查
curl -w "total=%{time_total}\n" -o /dev/null -s \
http://127.0.0.1:8080/api/actuator/health
jcmd PID Thread.print > thread.txt
健康检查也慢,问题在全局(线程池、连接池、GC);只有业务接口慢,去看 SQL 和外部调用。线程 dump 里如果一大片线程停在 JDBC、socketRead 或锁等待,方向就定了。
Feign 的超时配置项换过路径,下面两块按你的 Spring Cloud 版本二选一,不要同时复制:
bash
# 选 A:Spring Cloud 2022.x / OpenFeign 4.x
spring:
cloud:
openfeign:
client:
config:
default:
connectTimeout: 3000
readTimeout: 10000
bash
# 选 B:早期 Hoxton / OpenFeign 2.x
feign:
client:
config:
default:
connectTimeout: 3000
readTimeout: 10000
照着旧博客抄错路径,配置会静默不生效,接口照样超时。
第 6 步 · 本地能调、服务器调不了:网络层的几个断点
这个我自己踩过。Windows 上跑了个本地服务,想用 cloudflared 隧道暴露出去,隧道配置指向 127.0.0.1:8080,结果怎么都连不上。查到最后是 8080 只绑了 IPv6 的 ::1,没绑 127.0.0.1------应用活着,隧道也活着,两边就是没对上。
现象 :开发机 localhost:8080 正常,换成服务器 IP 就连接失败或超时;或者服务器本机 curl 通,办公网不通。
原因 :绑定地址只对内;Linux firewalld / iptables 或云厂商安全组没放通;Docker 没做 -p 8080:8080,或者容器内应用绑到了容器自己的 127.0.0.1;反向代理 proxy_pass 指错(容器里写 localhost 指向的是代理容器自己,不是宿主机);公司网络只放行 80/443。
★
方法卡 · 三层 curl 服务器本机 → 同网段内网 IP → 公网 IP,依次打一遍,哪一层开始断,问题就在那一层 。 第一层通、第二层断 → 查
server.address和防火墙;前两层通、第三层断 → 查安全组、DNS 和反向代理。 一句话能讲清,不用装任何工具,也最适合直接丢到技术群里。
bash
# 第一层:应用本身
curl -i http://127.0.0.1:8080/api/actuator/health
# 第二层:绑定地址 / 防火墙
curl -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
nc -zv INNER_IP 8080
firewall-cmd --list-all
iptables -L -n
# 第三层:链路与代理
docker ps # 看 PORTS 列有没有 0.0.0.0:8080->8080/tcp
docker inspect order-service
nginx -t && nginx -T | grep proxy_pass
第 7 步 · 微服务场景:注册中心看得到,调用链路却断了
现象 :A 调 B 报 java.net.UnknownHostException: order-service、No instances available for ORDER-SERVICE 或 Load balancer does not contain an instance for the service。可 B 的日志好好的,直接 curl B 也返回数据。
原因 :服务名对不上(spring.application.name 与 @FeignClient(name = ...)、网关 lb:// 在大小写或中划线上不一致);B 没注册上(缺 discovery 依赖、server-addr 写错、namespace / group 不一致、到注册中心网络不通);注册了但健康检查失败被摘除;容器里注册的是容器内部 IP,别的节点访问不到;客户端服务列表缓存还没刷新;Feign 调用路径漏了 B 的 context-path。
★
方法卡 · 直连二分 绕过服务发现,直接
curl http://实例IP:端口/接口。 直连通、走服务名不通 → 问题在注册中心或负载均衡层;直连就不通 → 回到第 1~6 步,毛病在 B 自己身上。 两分钟定下「到底是谁的锅」,比两边团队互相猜快得多。
bash
spring:
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848
namespace: dev-space-id
group: DEFAULT_GROUP
bash
# ① 注册中心里到底有没有这个实例(注意带上实际 namespaceId / groupName)
curl -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"
# ② 绕过服务发现,直连实例
curl -i http://INSTANCE_IP:8080/api/order/list
# ③ 看负载均衡实际选了谁:打开开头配置里注释掉的两行 DEBUG
两个版本上的旧结论别再套:新版 Spring Cloud Alibaba 不需要 @EnableDiscoveryClient,照着老教程加这个注解,反而会让人误以为「没开注解所以没注册」;Spring Cloud 2020 之后 Ribbon 已移除,换成 Spring Cloud LoadBalancer,服务列表的缓存行为不一样。
顺带说一句,服务注册和配置中心是两码事。Nacos 配置改了应用没生效,属于配置刷新链路的问题(配置变更通知、Spring Environment 更新、Bean 刷新是三件事),跟这里讲的「实例能不能被发现」不是一条线,别混着查。那部分单独一篇再展开。
把 7 步串起来
单看每一类问题都不难,难的是顺序。跳步最常见的结果,就是改了半天配置,其实只是 URL 少写了个 /api。下面三张图各管一件事,手机上看不清就点开大图:
先理清顺序 ------ 七步从外到内,每步标了看哪行日志、查哪个配置、跑哪条命令,底部还有现象到方向的速判。

Spring Boot 接口故障排查流程图
再按报错查方向 ------ Connection refused、404、405、401、403、超时、服务器不通、服务间调用失败,八类现象各配一条验证命令。

HTTP 错误码与排查方向速查卡
发布前最后过一遍 ------ 12 条勾选式清单,从绑定地址到服务发现,打印或截图存手机都能用。

上线前接口检查清单
一键排查命令包 ,按 7 步顺序排好,整块复制即可。TOKEN、INNER_IP、INSTANCE_IP、PID 按实际替换。
bash
# Linux / macOS
# 1 启动
tail -n 100 app.log | grep -E "Started|Tomcat started|APPLICATION FAILED|Caused by"
jps -l
# 2 监听
ss -lntp | grep 8080
# 3 URL 与方法
curl -i -X POST http://127.0.0.1:8080/api/order/list
# 4 映射
curl -s http://127.0.0.1:8080/api/actuator/mappings | grep order
# 5 权限与耗时
curl -i http://127.0.0.1:8080/api/order/list
curl -w "total=%{time_total}\n" -o /dev/null -s http://127.0.0.1:8080/api/actuator/health
jcmd PID Thread.print > thread.txt
# 6 网络
curl -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
nc -zv INNER_IP 8080
firewall-cmd --list-all
docker ps
nginx -T | grep proxy_pass
# 7 服务发现
curl -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"
curl -i http://INSTANCE_IP:8080/api/order/list
bash
# Windows PowerShell ------ 注意这里必须写 curl.exe
# PowerShell 里的 curl 是 Invoke-WebRequest 的别名,参数完全不通用
# 1 启动
Select-String -Path app.log -Pattern "Started|Tomcat started|APPLICATION FAILED|Caused by" | Select-Object -Last 30
jps -l
# 2 监听
netstat -ano | findstr :8080
# 3 URL 与方法
curl.exe -i -X POST http://127.0.0.1:8080/api/order/list
# 4 映射
curl.exe -s http://127.0.0.1:8080/api/actuator/mappings | findstr order
# 5 权限与耗时
curl.exe -i http://127.0.0.1:8080/api/order/list
curl.exe -w "total=%{time_total}" -o NUL -s http://127.0.0.1:8080/api/actuator/health
jcmd PID Thread.print > thread.txt
# 6 网络
curl.exe -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
Test-NetConnection -ComputerName INNER_IP -Port 8080
docker ps
# 7 服务发现
curl.exe -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"
curl.exe -i http://INSTANCE_IP:8080/api/order/list
这类问题没有诀窍,就是别跳步。我现在会先敲一条 ss -lntp,把「应用到底在不在」钉死,再往下走。查到最后,毛病多半不在代码里,而在某个没人想起来核对过的配置上。上面那份清单是按这个顺序整理的,下次碰到,从头过一遍就够了。
bye!关注我!我们下期再见!