Java 后端 / 知识点
Spring Cloud 微服务速查手册
手册条目
为内部调用配置客户端凭证或双向 TLS 身份认证。
校验服务间身份
用于阻止未授权服务伪造内部调用。常见做法是 OAuth 2.0 客户端凭证颁发短期访问令牌,或用双向 TLS 在握手阶段校验证书。需要细粒度授权时优先令牌;强调网络层身份和证书绑定时优先 mTLS;高敏链路可叠加使用。

方案选择
客户端凭证适合“服务身份 + 接口权限”场景,令牌可携带 scope、aud 等声明,并能短期失效。mTLS 适合零信任网络、合规链路或网关到后端的强身份绑定,但证书签发、分发和轮换成本更高。两者叠加时,mTLS 证明连接方身份,令牌负责业务授权。
配置客户端凭证
以下配置假设调用方同时需要访问受保护接口,并使用 Spring Security OAuth2 Client 自动获取令牌。客户端密钥只从环境变量或密钥管理系统注入,不写入仓库。
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: ${OIDC_ISSUER_URI}
client:
registration:
inventory:
provider: internal-idp
client-id: ${INVENTORY_CLIENT_ID}
client-secret: ${INVENTORY_CLIENT_SECRET}
authorization-grant-type: client_credentials
scope: inventory.read
provider:
internal-idp:
token-uri: ${OIDC_TOKEN_URI}调用请求必须统一经过带 OAuth2 过滤器的 WebClient,避免业务代码手工拼接和缓存令牌。
package com.example.security;
import static org.springframework.security.config.Customizer.withDefaults;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.client.AuthorizedClientServiceOAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientProviderBuilder;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.oauth2.client.web.reactive.function.client.ServletOAuth2AuthorizedClientExchangeFilterFunction;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.reactive.function.client.WebClient;
@Configuration
public class ServiceIdentityConfig {
@Bean
SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
return http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/health").permitAll()
.anyRequest().authenticated())
.oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults()))
.build();
}
@Bean
OAuth2AuthorizedClientManager authorizedClientManager(
ClientRegistrationRepository registrations,
OAuth2AuthorizedClientService clients) {
var provider = OAuth2AuthorizedClientProviderBuilder.builder()
.clientCredentials()
.build();
var manager =
new AuthorizedClientServiceOAuth2AuthorizedClientManager(registrations, clients);
manager.setAuthorizedClientProvider(provider);
return manager;
}
@Bean
WebClient inventoryWebClient(OAuth2AuthorizedClientManager manager) {
var oauth2 = new ServletOAuth2AuthorizedClientExchangeFilterFunction(manager);
oauth2.setDefaultClientRegistrationId("inventory");
return WebClient.builder()
.apply(oauth2.oauth2Configuration())
.build();
}
}验证令牌端点和目标服务时只输出状态码,避免把访问令牌写进终端历史或 CI 日志。
TOKEN="$(curl -fsS \
-u "${INVENTORY_CLIENT_ID}:${INVENTORY_CLIENT_SECRET}" \
-d grant_type=client_credentials \
-d scope=inventory.read \
"${OIDC_TOKEN_URI}" | jq -r '.access_token')"
curl -sS -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer ${TOKEN}" \
https://inventory.internal/api/stocks/SKU-100预期输出
200401 通常表示令牌缺失、过期、签名或 issuer 校验失败;403 表示身份已通过但缺少目标接口要求的权限。
配置双向 TLS
目标服务要求客户端证书时,将受信任客户端 CA 放入 truststore,并把 client-auth 设为 need。以下为服务端配置片段,证书文件应由内部 PKI 管理。
server:
ssl:
enabled: true
key-store: file:${SERVER_KEYSTORE}
key-store-password: ${SERVER_KEYSTORE_PASSWORD}
trust-store: file:${SERVER_TRUSTSTORE}
trust-store-password: ${SERVER_TRUSTSTORE_PASSWORD}
client-auth: need使用客户端证书验证握手和接口可达性:
curl --cert client.crt \
--key client.key \
--cacert ca.crt \
-sS -o /dev/null -w '%{http_code}\n' \
https://orders.internal/actuator/health预期输出
200未携带证书、证书过期、SAN 不匹配或 CA 不受信任时,请求会在 HTTP 之前失败,通常表现为 TLS handshake error,而不是 401。
风险与排障
禁止在配置文件、镜像层、命令行参数或日志中暴露 client-secret、私钥和访问令牌;安全替代方案是使用 Vault、Kubernetes Secret、云密钥服务或受控环境变量。证书轮换应保留新旧 CA 的短暂重叠窗口,否则会造成批量握手失败。
排查时按层次确认:先验证 DNS、时间同步和 TLS 握手,再检查令牌的 iss、aud、过期时间与 scope,最后核对目标服务的授权规则。mTLS 只证明证书身份,不等于自动获得接口权限,仍应将证书 SAN 或 Subject 映射为服务主体并执行授权。
兼容性
示例面向 Spring Boot 3.x 与 Spring Security 6。Spring Boot 2.x 使用 javax.servlet 生态且部分 OAuth2 配置 API 不同;升级时应按当前依赖版本调整导入包和安全配置写法。
统一记录时间、服务、环境、级别、请求和异常字段。
输出结构化日志
用于让日志平台稳定检索时间、服务、环境、级别、请求标识和异常信息。生产环境应输出单行 JSON 到标准输出,由采集器转发;不要依赖正则从自由文本中拆字段,也不要让每个服务自行发明字段名。
统一字段
至少固定 @timestamp、log.level、service.name、service.environment、message、request.id、http.request.method 和 url.path。异常日志再增加 error.type、error.message、error.stack_trace。业务维度使用稳定键名,例如 order_id,不要把动态值拼进字段名。
启用 JSON 输出
Spring Boot 3.4/3.5 可直接启用 ECS 结构化日志。以下配置将服务名和环境写入每条日志;容器环境建议只输出控制台,不再额外写本地滚动文件。
spring:
application:
name: order-service
logging:
structured:
format:
console: ecs
ecs:
service:
name: ${spring.application.name}
environment: ${APP_ENV:local}配置生效后,普通 log.info(...)、SLF4J 键值对和 MDC 内容都会进入 JSON 成员。若项目版本较低,可改用 logstash-logback-encoder,但字段命名仍应保持一致。
注入请求上下文
下面示例基于 Spring Boot 3.x、Java 17 和 spring-boot-starter-web。过滤器优先复用上游传入的 X-Request-Id,没有时生成新值,并在响应头中回传,便于跨服务串联查询。
package com.example.logging;
import java.io.IOException;
import java.util.Map;
import java.util.Optional;
import java.util.UUID;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.filter.OncePerRequestFilter;
@SpringBootApplication
@RestController
public class StructuredLogApplication {
private static final Logger log =
LoggerFactory.getLogger(StructuredLogApplication.class);
public static void main(String[] args) {
SpringApplication.run(StructuredLogApplication.class, args);
}
@GetMapping("/orders/{id}")
public Map<String, String> getOrder(@PathVariable String id) {
log.atInfo()
.addKeyValue("order_id", id)
.log("order fetched");
return Map.of("id", id, "status", "PAID");
}
@GetMapping("/fail")
public void fail() {
throw new IllegalStateException("demo failure");
}
@ExceptionHandler(Exception.class)
public ResponseEntity<Map<String, String>> handle(Exception ex) {
// 保留异常对象,结构化编码器才能输出类型、消息和堆栈。
log.error("request failed", ex);
return ResponseEntity.internalServerError()
.body(Map.of("error", "internal_error"));
}
}
@Component
class RequestLogContextFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain chain) throws ServletException, IOException {
String requestId = Optional.ofNullable(request.getHeader("X-Request-Id"))
.filter(value -> !value.isBlank())
.orElseGet(() -> UUID.randomUUID().toString());
response.setHeader("X-Request-Id", requestId);
// try-with-resources 确保线程复用前清理 MDC,避免请求字段串线。
try (var rid = MDC.putCloseable("request.id", requestId);
var method = MDC.putCloseable(
"http.request.method", request.getMethod());
var path = MDC.putCloseable("url.path", request.getRequestURI())) {
chain.doFilter(request, response);
}
}
}启动应用后发送一个带固定请求 ID 的失败请求,便于核对字段是否完整:
curl -sS -i \
-H 'X-Request-Id: req-1001' \
http://localhost:8080/fail预期结果
HTTP/1.1 500
X-Request-Id: req-1001
Content-Type: application/json
{"error":"internal_error"}控制台会输出一行 JSON。字段顺序、时间、进程号和堆栈内容会随运行环境变化,关键结构应类似:
{"@timestamp":"<TIME>","log.level":"ERROR","service.name":"order-service","service.environment":"local","message":"request failed","request.id":"req-1001","http.request.method":"GET","url.path":"/fail","error.type":"java.lang.IllegalStateException","error.message":"demo failure","error.stack_trace":"<STACK_TRACE>"}读取时先用 request.id 串联同一次调用,再按 service.name 和时间范围缩小范围;只有排查异常时再展开 error.stack_trace,避免大字段影响检索性能。
风险与边界
不得记录 Authorization、Cookie、会话 ID、私钥、密码、完整身份证号或原始请求体;触发泄露后会扩大到日志平台、备份和告警渠道。安全替代方案是字段白名单、脱敏器和长度上限,并只记录必要的业务标识。
MDC 基于线程上下文。使用线程池、@Async、CompletableFuture 或 Reactor 时不会自动完整传播,可能导致请求 ID 丢失或串线;应使用框架提供的上下文传播机制,并在压测中验证。高频成功请求不要默认打印堆栈或大对象,否则会放大存储成本和 GC 压力。
排障清单
日志不是 JSON 时,先检查实际生效的 profile 和 logging.structured.format.console;字段缺失时确认代码是否通过结构化键值或 MDC 写入;同一请求 ID 出现在无关请求中时,检查 MDC 是否在 finally 或 try-with-resources 中清理;采集端出现多行拆分时,确认输出编码器生成单行 JSON,而不是手工拼接字符串。
兼容性
示例按 Spring Boot 3.4/3.5 的 ECS 点号键格式编写。较早版本可使用兼容的 JSON Logback 编码器;升级到 Spring Boot 4.x 前应验证 ECS 是否改为嵌套对象,并同步更新采集器、索引模板和告警规则。
在服务调用链中传播追踪标识并写入日志上下文。
关联调用日志
用于把一次请求在网关、业务服务和下游服务中的日志串起来。Spring Boot 3.5 可由 Micrometer Tracing 解析并传播 W3C traceparent,同时把 traceId、spanId 放入 MDC;检索同一 traceId 即可还原调用链。

基本配置
以下最小项目使用 Spring Boot 3.5.16。只做日志关联时可先使用 tracing bridge;需要把链路发送到后端时,再加入 OTLP 或 Zipkin exporter,并配置对应地址。依赖版本交给 Spring Boot BOM 管理。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>trace-log-demo</artifactId>
<version>1.0.0</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>application.yml 固定关联字段格式。联调时可把采样率临时设为 1.0;生产环境应根据流量和链路后端容量下调。
spring:
application:
name: trace-log-demo
logging:
include-application-name: false
pattern:
correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "
management:
tracing:
sampling:
probability: 1.0主示例
关键点是注入自动配置的 RestClient.Builder,不要自行 RestClient.create()。下面用同一进程的两个端点模拟订单服务调用库存服务;真实部署时把基础地址改为下游服务地址或负载均衡地址。
package com.example.tracing;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClient;
@SpringBootApplication
@RestController
public class TraceLogApplication {
private static final Logger log = LoggerFactory.getLogger(TraceLogApplication.class);
private final RestClient inventoryClient;
public TraceLogApplication(RestClient.Builder builder) {
// 自动配置的 Builder 已挂载 Observation 拦截器,可传播 trace 上下文。
this.inventoryClient = builder.baseUrl("http://localhost:8080").build();
}
public static void main(String[] args) {
SpringApplication.run(TraceLogApplication.class, args);
}
@GetMapping("/orders/{id}")
OrderResponse order(@PathVariable long id) {
log.info("开始查询订单 id={}", id);
InventoryResponse inventory = inventoryClient.get()
.uri("/inventory/{id}", id)
.retrieve()
.body(InventoryResponse.class);
log.info("库存查询完成 id={}", id);
return new OrderResponse(id, inventory);
}
@GetMapping("/inventory/{id}")
InventoryResponse inventory(@PathVariable long id) {
log.info("处理库存查询 productId={}", id);
return new InventoryResponse(id, 8);
}
record OrderResponse(long orderId, InventoryResponse inventory) {}
record InventoryResponse(long productId, int available) {}
}启动并请求:
mvn spring-boot:run
curl -s http://localhost:8080/orders/42预期结果:
{"orderId":42,"inventory":{"productId":42,"available":8}}控制台会出现类似日志,<TRACE_ID> 在三行中一致,库存端点使用不同的 <SPAN_ID>;时间、线程名和标识实际值会变化。
<TIME> [trace-log-demo,<TRACE_ID>,<SPAN_ID_A>] 开始查询订单 id=42
<TIME> [trace-log-demo,<TRACE_ID>,<SPAN_ID_B>] 处理库存查询 productId=42
<TIME> [trace-log-demo,<TRACE_ID>,<SPAN_ID_A>] 库存查询完成 id=42风险与边界
management.tracing.sampling.probability=1.0 在高流量生产环境会放大 span 导出量、存储费用和后端压力;仅用于联调或小流量验证,生产改为容量允许的比例。不要把令牌、手机号、完整用户 ID 等敏感或高基数字段写入 MDC、baggage 或 span tag,安全替代是脱敏、哈希或仅记录内部低基数分类。
异步线程池、手写 Reactor 调度、消息队列和自定义 HTTP 客户端可能越过自动上下文传播边界。触发后日志会缺少标识或生成新 trace;优先使用框架已观测的客户端与执行器,确需手工操作时使用 Micrometer Context Propagation,并保证作用域关闭。
排障清单
- 日志没有
traceId:确认 Actuator、tracing bridge 和日志实现已加载,并检查自定义logging.pattern.*是否覆盖了 correlation pattern。 - 下游出现新
traceId:确认客户端来自自动配置的RestClient.Builder、WebClient.Builder或RestTemplateBuilder,同时检查网关是否删除了traceparent。 - 同一请求偶发缺链路:检查采样策略、异步切线程和消息消费端是否建立 Observation;仅检索日志时先确认 MDC 是否仍有值。
- 标识串线:排查手工
MDC.put()后未在finally中清理的代码;优先让 Micrometer 管理作用域。
兼容性
Spring Boot 3.x/4.x 使用 Micrometer Tracing;Spring Cloud Sleuth 面向旧的 Boot 2.x 体系,不应与 Micrometer Tracing 混装。Boot 4.1 可使用专用 OpenTelemetry 或 Zipkin starter,Boot 3.5 使用 bridge 与 exporter 组合;升级时以对应 Boot 版本的依赖清单和配置前缀为准。
通过 Micrometer 采集请求、JVM、连接池和业务指标。
采集服务指标
用于快速暴露请求耗时、JVM、HikariCP 和业务计数,供 Prometheus 抓取并在告警或看板中使用。Spring Boot Actuator 负责自动指标,Micrometer 的 MeterRegistry 负责注册业务指标;先验证 /actuator/metrics,再接入 /actuator/prometheus。

基本配置
以下完整项目以 Spring Boot 3.5.16 为例。spring-boot-starter-actuator 提供端点和自动采集,micrometer-registry-prometheus 把 Meter 转为 Prometheus 文本格式;依赖版本由 Spring Boot BOM 统一管理。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>metrics-demo</artifactId>
<version>1.0.0</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>仅暴露排障与抓取需要的端点,不要用 * 直接开放全部 Actuator。公共标签应保持低基数,适合放应用名、区域和环境,不适合放订单号或用户 ID。
spring:
application:
name: order-service
management:
endpoints:
web:
exposure:
include: health,metrics,prometheus
metrics:
tags:
application: ${spring.application.name}业务指标示例
HTTP、JVM 和已支持的连接池指标由 Actuator 自动注册;业务动作需要显式注册 Meter。下面的 Counter 只使用固定结果标签,避免为每个订单创建新时间序列。
package com.example.metrics;
import java.util.Map;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController
public class MetricsApplication {
private final Counter createdOrders;
public MetricsApplication(MeterRegistry registry) {
// Meter 在构造阶段注册一次;请求处理时只递增,避免重复创建。
this.createdOrders = Counter.builder("orders.created")
.description("成功创建的订单数")
.tag("result", "success")
.register(registry);
}
public static void main(String[] args) {
SpringApplication.run(MetricsApplication.class, args);
}
@PostMapping("/orders")
Map<String, String> createOrder() {
createdOrders.increment();
return Map.of("status", "created");
}
}启动、产生一次业务事件并读取 Prometheus 指标:
mvn spring-boot:run
curl -s -X POST http://localhost:8080/orders
curl -s http://localhost:8080/actuator/prometheus | grep '^orders_created_total'预期输出:
{"status":"created"}
orders_created_total{application="order-service",result="success"} 1.0Prometheus 标签顺序可能不同,但指标名应为 orders_created_total,值应随成功请求递增。诊断单个 Meter 时可访问 /actuator/metrics/orders.created;请求指标常用 http.server.requests,JVM 内存常用 jvm.memory.used,HikariCP 指标使用 hikaricp 前缀且只有数据源存在时才出现。
Prometheus 抓取
Prometheus 采用拉模式,目标地址必须能从 Prometheus 所在网络访问。以下为 prometheus.yml 片段示例;替换 <HOST>:<PORT> 并重载配置后,目标应显示为 UP,抓取内容应包含前述 orders_created_total。
scrape_configs:
- job_name: spring-order-service
metrics_path: /actuator/prometheus
scrape_interval: 15s
static_configs:
- targets:
- "<HOST>:<PORT>"风险与边界
标签值来自订单号、URL 原始路径、异常消息、用户 ID 或时间戳时,每个新值都可能创建新时间序列,最终导致应用内存增长、Prometheus 存储膨胀和查询变慢。安全替代是使用模板化 URI、固定结果枚举和有限区域标签,把明细标识留在日志或 trace 中。
直接公网暴露 /actuator/metrics 或 /actuator/prometheus 可能泄露类名、路径、资源规模和业务名称。应将管理端口放在内网,通过防火墙、反向代理或 Spring Security 限制访问;不要为省事暴露全部端点。
排障清单
/actuator/prometheus返回 404:确认 Prometheus registry 依赖存在,并在management.endpoints.web.exposure.include中包含prometheus。- 指标存在但一直为 0:先触发对应业务路径,再检查代码是否递增同一个已注册 Meter;Counter 只增不减。
- 没有 HikariCP 指标:确认应用确实使用 Hikari 数据源且连接池已初始化;指标前缀为
hikaricp。 - Prometheus 抓取失败:从 Prometheus 容器或主机执行
curl,检查 DNS、端口、防火墙、认证和管理端口配置。 - 实例维度混乱:为应用、环境、区域设置稳定公共标签,同时避免与 Prometheus 自动附加的
job、instance语义重复。
兼容性
Spring Boot 3.x 与 4.x 都以 Micrometer 为指标门面,但自动配置包名和部分属性前缀可能调整。升级时不要锁定独立 Micrometer 版本,优先使用 Spring Boot BOM;第三方监控 registry 必须与当前 Boot 管理的 Micrometer 版本匹配。
记录跨服务调用跨度并导出到追踪后端进行分析。
启用链路追踪
用于定位一次请求跨越网关、服务和下游依赖时的耗时与失败位置。Spring Boot 3 与新版本 Spring Cloud 应使用 Micrometer Tracing;下面以 Brave 桥接 Zipkin 为例,完成埋点、上下文传播、采样和导出。
调用链与数据流
每个服务为本地处理创建 Span,出站 HTTP 客户端把追踪上下文写入请求头,下游服务继续使用同一个 Trace ID。Span 异步导出到 Zipkin 后,可按 Trace ID 查看父子关系和各阶段耗时。

依赖与配置
在每个参与追踪的 Spring Boot 服务中加入以下依赖。版本由 Spring Boot 的依赖管理统一提供,不要为这三个组件分别指定版本。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
<groupId>io.zipkin.reporter2</groupId>
<artifactId>zipkin-reporter-brave</artifactId>
</dependency>
</dependencies>在 application.yml 中设置采样、传播格式和 Zipkin 地址。排障时可临时全采样;生产环境通常应降低比例,避免追踪后端和网络被大量 Span 压满。
spring:
application:
name: order-service
management:
tracing:
sampling:
probability: 1.0
propagation:
type: w3c
zipkin:
tracing:
endpoint: http://localhost:9411/api/v2/spans
logging:
pattern:
correlation: "[%X{traceId:-},%X{spanId:-}] "配置生效后,服务端请求、受支持的数据库访问以及通过 Spring 自动配置构建器创建的 HTTP 客户端会生成 Observation/Span。跨服务必须在所有服务使用兼容的传播格式,并通过 RestClient.Builder、WebClient.Builder、RestTemplateBuilder 或受管理的 Feign 客户端发起调用;直接 new 客户端可能丢失上下文。
启动后端并验证
下面启动本地 Zipkin,并检查其 HTTP 入口。需要本机已安装 Docker;容器 ID 是动态值。
docker run --rm -d --name zipkin -p 9411:9411 openzipkin/zipkin:3
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:9411/zipkin/预期输出:
<CONTAINER_ID>
200随后调用一条确实会从 order-service 访问下游服务的业务接口,等待数秒让批量导出完成,再查询最近一条 Trace。以下命令需要 jq。
curl -sS 'http://localhost:9411/api/v2/traces?serviceName=order-service&limit=1' \
| jq '.[0] | {spanCount: length, oneTrace: ((map(.traceId) | unique | length) == 1), linked: any(.parentId != null)}'预期输出结构:
{
"spanCount": <COUNT>,
"oneTrace": true,
"linked": true
}spanCount 的实际值取决于调用层数和已启用的埋点;oneTrace=true 表示这些 Span 共用一个 Trace ID,linked=true 表示至少存在父子关系。若返回 null,先确认业务请求已执行、服务名匹配,并等待导出缓冲刷新。
关键配置
management.tracing.sampling.probability 取值范围为 0.0 到 1.0,表示请求被采样的概率。management.tracing.propagation.type 应在所有服务保持一致;management.zipkin.tracing.endpoint 必须指向可从应用容器或主机访问的 Zipkin V2 接收地址。
追踪数据通常包含 URL、错误信息和自定义标签。不要把密码、令牌、身份证号、完整请求体等敏感数据写入 Span 标签或 baggage;需要关联业务对象时,优先使用脱敏后的内部 ID。
排障清单
没有 Trace 时,依次检查采样概率是否为零、Zipkin 地址是否可达、Reporter 依赖是否存在,以及应用日志中是否有导出失败。只有单服务 Span 时,检查出站客户端是否由 Spring 管理、代理是否移除了 traceparent 或 B3 请求头、上下游传播格式是否一致。
Trace 存在但耗时异常时,先按父子 Span 找到最长阶段,再对照错误标签和服务日志中的 Trace ID。全采样只适合短时排障;持续使用 1.0 可能增加 CPU、网络与存储开销,安全替代方案是按容量设定较低采样率,并对错误请求使用后端侧保留策略。
兼容性
Spring Boot 3 及对应 Spring Cloud 版本使用 Micrometer Tracing。Spring Cloud Sleuth 3.1 是旧路线,不支持 Spring Boot 3;升级时应移除 Sleuth 依赖并选择 Brave 或 OpenTelemetry 桥接实现,避免两套追踪组件同时生成重复 Span。
在运行期间临时修改指定包的日志级别以辅助排查。
调整日志级别
用于在不重启服务的情况下临时提高某个包或类的日志级别,快速观察请求参数、分支选择和下游调用。推荐通过 Spring Boot Actuator 的 loggers 端点操作,并在排障结束后立即恢复原级别。
开放管理端点
项目需要 spring-boot-starter-actuator。只暴露本次需要的端点,不要使用 * 将全部管理能力公开到业务网络。
management:
endpoints:
web:
exposure:
include: health,info,loggers配置生效后可访问 /actuator/loggers。若项目启用了 Spring Security,应让该端点仅对运维身份或内网管理入口开放;暴露配置只决定端点是否发布,不等于已经完成鉴权。
查询、修改与恢复
下面假设服务位于 http://localhost:8080,目标 logger 为 com.example.order,且初始有效级别为 INFO。一次脚本完成查询、切换到 DEBUG、复查并恢复继承级别。
BASE_URL='http://localhost:8080'
LOGGER='com.example.order'
curl -sS "$BASE_URL/actuator/loggers/$LOGGER"
printf '\n'
curl -sS -o /dev/null -w '%{http_code}\n' \
-X POST "$BASE_URL/actuator/loggers/$LOGGER" \
-H 'Content-Type: application/json' \
-d '{"configuredLevel":"DEBUG"}'
curl -sS "$BASE_URL/actuator/loggers/$LOGGER"
printf '\n'
curl -sS -o /dev/null -w '%{http_code}\n' \
-X POST "$BASE_URL/actuator/loggers/$LOGGER" \
-H 'Content-Type: application/json' \
-d '{"configuredLevel":null}'预期输出:
{"configuredLevel":null,"effectiveLevel":"INFO"}
204
{"configuredLevel":"DEBUG","effectiveLevel":"DEBUG"}
204configuredLevel 是当前 logger 显式设置的级别;为 null 时表示继承父 logger。effectiveLevel 是综合父级配置后真正生效的级别。POST 返回 204 表示修改成功且没有响应体;恢复时发送 null,而不是猜测原级别。
常用级别选择
排查业务分支时通常把精确包名或类名调到 DEBUG;只有在日志量可控且持续时间很短时才使用 TRACE。若只想减少噪声,可把高频第三方包临时调到 WARN,但必须确认不会遮蔽当前故障的关键错误。
优先从最窄的类或包开始,例如 com.example.order.client.InventoryClient,确认信息不足后再扩大到 com.example.order。不要直接调整根 logger,根级别变更会影响整个进程并产生大量无关日志。
风险与边界
运行时修改仅保存在当前进程内,应用重启、实例替换或重新部署后会恢复配置文件中的级别。集群有多个实例时,请求可能落到未修改的节点;应通过实例级管理地址逐台调整,或在短时配置变更中明确目标实例。
DEBUG 和 TRACE 可能记录请求头、SQL 参数或对象内容。触发条件是目标代码本身包含这些日志语句;后果可能是敏感信息泄露、日志磁盘写满和请求延迟上升。安全替代方案是缩小 logger 范围、限定观察窗口、先确认脱敏策略,并同步监控日志吞吐与磁盘使用率。
典型失败处理
返回 404 时,检查 Actuator 依赖、loggers 是否在 exposure 列表以及管理端口或上下文路径是否不同。返回 401 或 403 时,不要绕过安全控制,应使用已授权的运维凭据,并检查自定义 SecurityFilterChain 和 CSRF 策略。
返回 400 时,确认请求头为 application/json,级别值使用 TRACE、DEBUG、INFO、WARN、ERROR、FATAL 或 OFF 等当前日志系统支持的名称。修改成功但没有新增日志时,检查 logger 名是否与代码中的实际包名一致、相关代码路径是否被执行,以及日志采集器是否过滤了该级别。
完成排障后先发送 {"configuredLevel":null} 恢复继承,再复查 effectiveLevel。这比固定写回 INFO 更安全,因为父级原本可能是 WARN 或其他环境特定值。
隔离外部依赖并验证控制器、业务逻辑和异常处理。
编写服务测试
用分层测试隔离数据库、消息队列和远程客户端:控制器只验证路由、参数和错误响应,业务类只验证规则与协作调用。这样失败时能快速判断是接口适配问题还是业务逻辑问题。
测试边界
- 控制器:使用
MockMvc,把业务服务替换为 Mockito mock,验证状态码和 JSON。 - 业务逻辑:实例化真实业务类,只 mock 仓储、网关或消息发布器。
- 异常处理:让 mock 主动抛出业务异常,验证
@RestControllerAdvice的状态码和错误码。
不要在同一个测试里同时启动真实数据库、注册中心和远程服务;那属于集成测试,应单独分组运行。
主示例
下面的 OrderServiceTest.java 可放入已引入 spring-boot-starter-web 与 spring-boot-starter-test 的项目。示例在一个文件内覆盖控制器成功响应、异常映射和业务依赖调用。
package com.example.order;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.Map;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.springframework.http.HttpStatus;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
class OrderServiceTest {
interface InventoryGateway {
void reserve(String sku, int quantity);
}
record OrderView(String status, String sku, int quantity) {}
static class OrderService {
private final InventoryGateway inventoryGateway;
OrderService(InventoryGateway inventoryGateway) {
this.inventoryGateway = inventoryGateway;
}
OrderView place(String sku, int quantity) {
if (quantity <= 0) {
throw new IllegalArgumentException("quantity must be positive");
}
inventoryGateway.reserve(sku, quantity);
return new OrderView("accepted", sku, quantity);
}
}
@RestController
static class OrderController {
private final OrderService orderService;
OrderController(OrderService orderService) {
this.orderService = orderService;
}
@PostMapping("/orders/{sku}")
OrderView place(@PathVariable String sku, @RequestParam int quantity) {
return orderService.place(sku, quantity);
}
}
@RestControllerAdvice
static class ApiExceptionHandler {
@ExceptionHandler(IllegalArgumentException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
Map<String, String> badRequest(IllegalArgumentException exception) {
return Map.of(
"code", "INVALID_ARGUMENT",
"message", exception.getMessage());
}
}
@Nested
class ControllerTests {
private OrderService orderService;
private MockMvc mvc;
@BeforeEach
void setUp() {
orderService = mock(OrderService.class);
mvc = MockMvcBuilders
.standaloneSetup(new OrderController(orderService))
.setControllerAdvice(new ApiExceptionHandler())
.build();
}
@Test
void returnsAcceptedOrder() throws Exception {
when(orderService.place("sku-1", 2))
.thenReturn(new OrderView("accepted", "sku-1", 2));
mvc.perform(post("/orders/{sku}", "sku-1")
.param("quantity", "2"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.status").value("accepted"))
.andExpect(jsonPath("$.quantity").value(2));
}
@Test
void mapsBusinessException() throws Exception {
when(orderService.place("sku-1", 0))
.thenThrow(new IllegalArgumentException(
"quantity must be positive"));
mvc.perform(post("/orders/{sku}", "sku-1")
.param("quantity", "0"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.code")
.value("INVALID_ARGUMENT"));
}
}
@Test
void businessServiceCallsExternalBoundaryOnce() {
InventoryGateway gateway = mock(InventoryGateway.class);
OrderService service = new OrderService(gateway);
OrderView result = service.place("sku-1", 2);
assertThat(result.status()).isEqualTo("accepted");
verify(gateway).reserve("sku-1", 2);
}
}运行指定测试类:
mvn -Dtest=OrderServiceTest test预期输出:
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESSTests run: 3 对应控制器正常路径、异常响应和业务协作三项;任一状态码、JSON 字段或网关调用不匹配都会使构建失败。
断言重点
优先断言客户端可观察结果:HTTP 状态码、稳定错误码、必要响应字段,以及外部边界是否被调用。不要绑定完整日志、随机 ID、时间戳或 JSON 字段顺序,否则正常重构也会造成误报。
风险与边界
触发条件:所有测试都使用 @SpringBootTest 并加载完整上下文。可能后果:测试变慢,还可能误连真实注册中心、数据库或消息中间件。安全替代:控制器使用 MockMvc 或 MVC 切片,业务类使用纯 Mockito;只把少量关键链路留给集成测试。
触发条件:把被测业务类本身也 mock。可能后果:断言只验证预设返回值,真实规则从未执行。安全替代:只 mock 进程外依赖和不可控边界,被测类始终使用真实实例。
兼容性
示例使用 JUnit 5、Mockito 与 MockMvcBuilders.standaloneSetup,不依赖完整 Spring 上下文。若改用 MVC 切片,Spring Boot 当前文档推荐 @WebMvcTest 配合 @MockitoBean;旧项目应按自身 Spring Boot 基线选择对应 mock 注解,避免跨版本混用。:contentReference[oaicite:0]{index=0}
使用模拟服务验证 Feign 请求、响应和容错行为。
测试远程调用
使用 WireMock 启动随机端口的模拟 HTTP 服务,再让 Feign 客户端指向该地址。测试同时验证 URL、请求头、响应反序列化和失败回退,避免只 mock Java 接口而漏掉真实 HTTP 契约错误。
请求链路

关键点是让 Spring 属性 catalog.base-url 由测试中的 WireMock 注入,而不是写死端口;这样并行测试不会端口冲突,也不会意外请求真实服务。
测试依赖
片段示例:项目应已通过 Spring Cloud BOM 管理 Spring Cloud 依赖版本。WireMock Spring Boot 集成会启动模拟服务并向 Spring 环境注入指定的基础地址。:contentReference[oaicite:1]{index=1}
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.wiremock.integrations</groupId>
<artifactId>wiremock-spring-boot</artifactId>
<version>4.0.9</version>
<scope>test</scope>
</dependency>
</dependencies>生效验证:测试启动后,catalog.base-url 应是形如 http://localhost:<PORT> 的随机地址;实际端口每次运行可能不同。
主示例
将下面文件保存为 CatalogClientTest.java。成功用例验证请求路径、请求头和 JSON 映射;失败用例验证 HTTP 500 时执行 fallback。
package com.example.catalog;
import static com.github.tomakehurst.wiremock.client.WireMock.equalTo;
import static com.github.tomakehurst.wiremock.client.WireMock.get;
import static com.github.tomakehurst.wiremock.client.WireMock.getRequestedFor;
import static com.github.tomakehurst.wiremock.client.WireMock.okJson;
import static com.github.tomakehurst.wiremock.client.WireMock.serverError;
import static com.github.tomakehurst.wiremock.client.WireMock.urlEqualTo;
import static org.assertj.core.api.Assertions.assertThat;
import com.github.tomakehurst.wiremock.WireMockServer;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.cloud.openfeign.EnableFeignClients;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestHeader;
import org.wiremock.spring.ConfigureWireMock;
import org.wiremock.spring.EnableWireMock;
import org.wiremock.spring.InjectWireMock;
@SpringBootTest(
classes = CatalogClientTest.TestApplication.class,
properties = "spring.cloud.openfeign.circuitbreaker.enabled=true")
@EnableWireMock(@ConfigureWireMock(
name = "catalog-api",
baseUrlProperties = "catalog.base-url"))
class CatalogClientTest {
@Autowired
private CatalogClient catalogClient;
@InjectWireMock("catalog-api")
private WireMockServer catalogApi;
@Test
void mapsResponseAndSendsRequiredHeader() {
catalogApi.stubFor(get(urlEqualTo("/products/p-1"))
.withHeader("X-Trace-Id", equalTo("trace-1"))
.willReturn(okJson(
"{\"id\":\"p-1\",\"name\":\"Keyboard\"}")));
Product product = catalogClient.get("p-1", "trace-1");
assertThat(product)
.isEqualTo(new Product("p-1", "Keyboard"));
catalogApi.verify(1, getRequestedFor(
urlEqualTo("/products/p-1"))
.withHeader("X-Trace-Id", equalTo("trace-1")));
}
@Test
void usesFallbackOnRemoteServerError() {
catalogApi.stubFor(get(urlEqualTo("/products/p-2"))
.willReturn(serverError()));
Product product = catalogClient.get("p-2", "trace-2");
assertThat(product)
.isEqualTo(new Product("p-2", "UNAVAILABLE"));
}
@SpringBootApplication
@EnableFeignClients(clients = CatalogClient.class)
static class TestApplication {
@Bean
CatalogFallback catalogFallback() {
return new CatalogFallback();
}
}
@FeignClient(
name = "catalog",
url = "${catalog.base-url}",
fallback = CatalogFallback.class)
interface CatalogClient {
@GetMapping("/products/{id}")
Product get(
@PathVariable("id") String id,
@RequestHeader("X-Trace-Id") String traceId);
}
static class CatalogFallback implements CatalogClient {
@Override
public Product get(String id, String traceId) {
return new Product(id, "UNAVAILABLE");
}
}
record Product(String id, String name) {}
}运行指定测试类:
mvn -Dtest=CatalogClientTest test预期输出:
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS第一项通过说明 Feign 的路径、请求头和响应映射与契约一致;第二项通过说明 500 错误没有向上传播,而是返回了约定的降级对象。
覆盖重点
- 正常响应:至少断言关键字段,并通过 WireMock
verify检查方法、路径和必要请求头。 - 错误响应:分别覆盖 4xx、5xx、连接失败或超时中实际会触发的行为,不要只测一个笼统异常。
- 容错结果:断言稳定的 fallback 返回值或业务异常,同时确认不会误返回看似正常但数据不完整的对象。
风险与边界
触发条件:直接使用生产 URL 或固定端口。可能后果:测试误调用真实服务、修改真实数据,或在 CI 并行运行时端口冲突。安全替代:始终使用随机端口,并通过测试属性注入 Feign 的基础地址。
触发条件:只用 Mockito mock CatalogClient。可能后果:URL、请求头、编码、状态码解码和 JSON 反序列化错误全部被跳过。安全替代:业务单元测试可 mock 客户端,但客户端契约必须另用 WireMock 做 HTTP 级验证。
触发条件:配置了 fallback 却未启用 Spring Cloud CircuitBreaker 或缺少实现依赖。可能后果:远程异常直接抛出,降级测试失败。安全替代:显式加入 CircuitBreaker 实现并设置 spring.cloud.openfeign.circuitbreaker.enabled=true;OpenFeign 官方说明 fallback 类还必须注册为 Spring bean。:contentReference[oaicite:2]{index=2}
兼容性
WireMock 官方 JUnit 5 扩展支持自动管理服务生命周期和在每个测试前重置请求记录;本例改用其 Spring Boot 集成,以便把随机基础地址直接注入 Spring 属性。不同项目应选择与自身 Spring Boot、Spring Cloud BOM 和 Java 基线兼容的 WireMock 版本。:contentReference[oaicite:3]{index=3}
验证路由匹配、过滤器、鉴权、限流和错误响应。
测试网关路由
用于路由规则、过滤器、安全配置或限流策略变更后的快速回归。下面的脚本从客户端视角依次验证正常路由、响应过滤器、未授权请求、限流和不存在的路径,并在任一断言失败时立即退出。
前置条件
网关默认地址为 http://localhost:8080。把 ROUTE_PATH 改成确定存在且正常应返回 2xx 的业务路径;TOKEN 改成有效令牌;FILTER_HEADER 改成该路由过滤器实际写入的响应头名称。限流测试默认最多发送 30 次请求。
一键验证
#!/usr/bin/env bash
set -euo pipefail
GATEWAY="${GATEWAY:-http://localhost:8080}"
ROUTE_PATH="${ROUTE_PATH:-/api/orders/42}"
TOKEN="${TOKEN:-test-token}"
FILTER_HEADER="${FILTER_HEADER:-X-Request-Id}"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TMP_DIR"' EXIT
request() {
local name="$1"
shift
curl -sS -o "$TMP_DIR/$name.body" \
-D "$TMP_DIR/$name.headers" \
-w '%{http_code}' "$@"
}
status="$(request route \
-H "Authorization: Bearer $TOKEN" \
"$GATEWAY$ROUTE_PATH")"
[[ "$status" =~ ^2[0-9][0-9]$ ]] || {
echo "FAIL route_match: HTTP $status"
cat "$TMP_DIR/route.body"
exit 1
}
echo "PASS route_match: $status"
filter_value="$(
grep -i "^${FILTER_HEADER}:" "$TMP_DIR/route.headers" \
| head -n 1 | cut -d: -f2- | xargs || true
)"
[[ -n "$filter_value" ]] || {
echo "FAIL filter_header: missing $FILTER_HEADER"
exit 1
}
echo "PASS filter_header: $FILTER_HEADER=$filter_value"
status="$(request auth "$GATEWAY$ROUTE_PATH")"
[[ "$status" == "401" || "$status" == "403" ]] || {
echo "FAIL auth_missing: HTTP $status"
exit 1
}
echo "PASS auth_missing: $status"
limited=0
for i in $(seq 1 30); do
status="$(request "limit-$i" \
-H "Authorization: Bearer $TOKEN" \
"$GATEWAY$ROUTE_PATH")"
if [[ "$status" == "429" ]]; then
limited=1
break
fi
done
[[ "$limited" == "1" ]] || {
echo "FAIL rate_limit: no 429 in 30 requests"
exit 1
}
echo "PASS rate_limit: observed 429"
status="$(request not-found \
-H "Authorization: Bearer $TOKEN" \
"$GATEWAY/__gateway_route_not_found__")"
[[ "$status" == "404" ]] || {
echo "FAIL not_found: HTTP $status"
exit 1
}
echo "PASS not_found: $status"预期输出(鉴权失败码可能是 401 或 403,动态头值以 <ID> 表示):
PASS route_match: 200
PASS filter_header: X-Request-Id=<ID>
PASS auth_missing: 401
PASS rate_limit: observed 429
PASS not_found: 404脚本首先失败的位置就是优先排查层级。正常路由失败先看谓词与上游;过滤器头缺失再看过滤器绑定和顺序;鉴权或限流断言失败则分别检查安全链和限流器配置。
结果定位
| 现象 | 优先检查 |
|---|---|
| 正常路径返回 404 | Path 谓词、StripPrefix/RewritePath、路由配置是否已刷新 |
| 正常路径返回 502/503 | 上游实例、服务发现、DNS、连接超时和负载均衡 URI |
| 有令牌仍返回 401/403 | 令牌过期、签名、issuer/audience、网关安全规则 |
| 过滤器响应头缺失 | 过滤器是否挂在目标路由、执行顺序、是否只修改了请求头 |
| 30 次请求没有 429 | 限流键解析器、Redis 连接、突发容量和路由过滤器绑定 |
| 未知路径不是 404 | 全局兜底路由、异常处理器或安全规则提前拦截 |
风险与边界
不要把高频循环直接指向生产环境。触发条件是脚本中的限流阶段,可能造成真实流量突增、告警或封禁;安全替代方案是在测试环境执行,或把次数降到略高于已知突发容量。令牌不要硬编码进脚本仓库,可通过临时环境变量传入并在执行后清理 Shell 历史。
curl 的连接失败、TLS 握手失败和 DNS 失败发生在请求进入网关之前,不能据此判断路由配置错误。404 也可能由上游返回,应结合网关访问日志、路由 ID 和上游日志确认响应来源。
使用容器统一启动注册中心、配置中心、消息系统和数据库。
启动本地依赖
使用 Docker Compose 一次启动本地微服务常见依赖:Nacos 同时承担注册中心和配置中心,RabbitMQ 提供消息服务,PostgreSQL 提供业务数据库。配置固定端口、持久化卷和健康检查,便于团队复现同一套开发环境。
依赖拓扑
宿主机运行 Spring Cloud 服务时连接映射端口;服务也放进同一 Compose 网络时,应改用容器服务名,不要使用 localhost。

Compose 配置
将以下内容保存为 compose.yaml。示例凭据只适合本机开发,Nacos 关闭鉴权以减少本地接入步骤。
services:
nacos:
image: nacos/nacos-server:v2.4.3
container_name: local-nacos
environment:
MODE: standalone
NACOS_AUTH_ENABLE: "false"
ports:
- "8848:8848"
- "9848:9848"
volumes:
- nacos-data:/home/nacos/data
- nacos-logs:/home/nacos/logs
restart: unless-stopped
networks:
- micro
rabbitmq:
image: rabbitmq:3.13-management
container_name: local-rabbitmq
environment:
RABBITMQ_DEFAULT_USER: dev
RABBITMQ_DEFAULT_PASS: devpass
ports:
- "5672:5672"
- "15672:15672"
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 10s
timeout: 5s
retries: 12
volumes:
- rabbitmq-data:/var/lib/rabbitmq
restart: unless-stopped
networks:
- micro
postgres:
image: postgres:16-alpine
container_name: local-postgres
environment:
POSTGRES_DB: app
POSTGRES_USER: app
POSTGRES_PASSWORD: devpass
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 3s
retries: 20
volumes:
- postgres-data:/var/lib/postgresql/data
restart: unless-stopped
networks:
- micro
networks:
micro:
volumes:
nacos-data:
nacos-logs:
rabbitmq-data:
postgres-data:在 compose.yaml 所在目录启动并查看状态:
docker compose up -d
docker compose ps
docker compose logs --tail=100 nacos rabbitmq postgres预期输出中三个容器均为 Up,RabbitMQ 和 PostgreSQL 最终显示 healthy;启动耗时会因机器性能不同而变化:
NAME STATUS
local-nacos Up <TIME>
local-rabbitmq Up <TIME> (healthy)
local-postgres Up <TIME> (healthy)就绪验证
容器处于 Up 不代表服务接口已经可用。用以下命令分别验证 Nacos、RabbitMQ 管理 API 和 PostgreSQL 查询:
curl -fsS http://localhost:8848/nacos/v1/console/health/liveness
curl -fsS -u dev:devpass http://localhost:15672/api/overview >/dev/null \
&& echo "rabbitmq=UP"
PGPASSWORD=devpass docker exec local-postgres \
psql -U app -d app -tAc 'select 1;'预期输出:
UP
rabbitmq=UP
1宿主机应用使用 127.0.0.1:8848、127.0.0.1:5672 和 jdbc:postgresql://127.0.0.1:5432/app。同一 Compose 网络中的应用改用 nacos:8848、rabbitmq:5672 和 jdbc:postgresql://postgres:5432/app。
常用操作
# 停止但保留数据卷,下一次启动仍保留注册配置、队列和数据库数据
docker compose down
# 仅重启一个依赖,避免整套环境全部中断
docker compose restart rabbitmq
# 查看单个组件最近日志
docker compose logs -f --tail=200 nacos预期结果分别是容器被停止并保留卷、RabbitMQ 单独重启、终端持续输出 Nacos 日志;这些命令成功时通常不产生固定业务响应。
风险与排障
docker compose down -v 会删除所有声明卷。触发条件是带 -v 停止环境,后果是数据库、队列和 Nacos 本地数据不可恢复;安全替代方案是使用 docker compose down,需要清库时先导出数据或确认卷可丢弃。
出现 port is already allocated 时,用 lsof -i :<PORT> 或 netstat 找到占用进程,再修改左侧宿主机端口。Nacos 控制台可访问但服务注册失败时,检查 9848 是否映射和放行。PostgreSQL 修改密码后仍认证失败,通常是旧数据卷保留了初始化凭据;优先在库内修改密码,只有确认数据可删除时才移除卷。
将微服务打包为精简、可配置且使用非 root 用户的镜像。
构建容器镜像
使用 Spring Boot Maven 插件和 Cloud Native Buildpacks 将微服务直接构建为 OCI 镜像。该路径自动拆分依赖与应用层,并以非 root 用户运行;配置通过环境变量注入,不需要维护基础镜像和系统包安装脚本。
构建前提
项目需使用 Spring Boot Maven 插件,机器或 CI Runner 能访问 Docker daemon。先确认测试已在流水线通过,再决定是否使用 -DskipTests;镜像标签应使用版本号或提交摘要,避免只发布 latest。
主用法
在项目根目录执行以下命令。imageName 同时决定本地镜像名和后续推送地址;示例先构建本地镜像,再读取运行用户和镜像大小。
./mvnw -DskipTests spring-boot:build-image \
-Dspring-boot.build-image.imageName=order-service:1.0.0
docker image inspect order-service:1.0.0 \
--format 'user={{.Config.User}} size={{.Size}}'预期输出中的耗时、用户标识和字节数会随构建器及平台变化;user 不应为空、root 或 0。
[INFO] Successfully built image 'docker.io/library/order-service:1.0.0'
user=<NON_ROOT_USER> size=<BYTES>需要直接推送私有仓库时,先完成 docker login registry.example.com,再将镜像名改为完整仓库地址并增加 -Dspring-boot.build-image.publish=true。不要把仓库密码写进命令历史或 POM。
运行时配置
镜像保持环境无关,端口和 Profile 在启动容器时传入。敏感配置应通过 Kubernetes Secret、Docker Secret 或平台密钥服务挂载,不要固化进镜像层。
docker run --rm --name order-service \
-p 18080:8080 \
-e SPRING_PROFILES_ACTIVE=prod \
-e LOGGING_LEVEL_ROOT=INFO \
order-service:1.0.0预期结果是应用监听容器内 8080,宿主机通过 18080 访问;启动时间是动态值。
Started OrderServiceApplication in <SECONDS> seconds风险与边界
触发条件:使用 -DskipTests 且流水线没有其他测试阶段。可能后果:缺陷镜像被发布。安全替代:在构建镜像前执行 ./mvnw verify,仅在测试已通过的独立镜像阶段跳过重复测试。
触发条件:将令牌、证书或密码作为构建参数,或写入 Dockerfile。可能后果:秘密进入镜像历史、缓存或构建日志。安全替代:运行时挂载 Secret,并定期扫描镜像与 SBOM。
排障清单
Cannot connect to the Docker daemon:检查 Docker 服务、当前 context 和 Runner 权限。- 拉取 builder 超时:验证代理、DNS、私有镜像仓库认证及出站网络。
- 容器立即退出:先执行
docker logs order-service,再核对 Java 版本、Profile 和必需环境变量。 - 平台不匹配:在构建节点使用目标架构,或在支持的 Spring Boot 版本中显式设置
imagePlatform。
兼容性
spring-boot:build-image 自 Spring Boot 2.3 起可用;命令行 imagePlatform 参数自 3.4 起提供。当前官方插件文档明确说明 CNB 镜像以非 root 用户构建和运行。:contentReference[oaicite:0]{index=0}
在服务及关键依赖准备完成后再接收业务流量。
配置就绪探针
使用 Spring Boot Actuator 的 readiness 健康组控制实例何时进入服务端点。应用启动未完成或关键依赖不可用时返回非 2xx,Kubernetes 会停止向该 Pod 转发新流量,但不会仅因就绪失败而重启容器。
配置端点
以下依赖是 pom.xml 片段示例。加入 Actuator 后,把探针额外暴露到主业务端口:/livez 用于存活检查,/readyz 用于就绪检查。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>示例假定服务已配置 DataSource,因此把数据库加入 readiness;没有数据库,或数据库故障时仍可降级运行,应删除 db,避免所有实例同时摘流。
management:
endpoints:
web:
exposure:
include: health
endpoint:
health:
probes:
enabled: true
add-additional-paths: true
group:
readiness:
include: readinessState,db生效后,应用完成启动且数据库健康时 /readyz 返回 200;启动中或数据库健康检查失败时返回 503。默认不需要公开其他 Actuator 端点。

部署探针
以下清单同时创建 Deployment 和 Service。port: http 引用容器端口名称,避免端口变更时同时修改多处配置。
apiVersion: apps/v1
kind: Deployment
metadata:
name: order-service
spec:
replicas: 2
selector:
matchLabels:
app: order-service
template:
metadata:
labels:
app: order-service
spec:
containers:
- name: order-service
image: registry.example.com/order-service:1.0.0
ports:
- name: http
containerPort: 8080
readinessProbe:
httpGet:
path: /readyz
port: http
periodSeconds: 5
timeoutSeconds: 2
failureThreshold: 3
successThreshold: 1
---
apiVersion: v1
kind: Service
metadata:
name: order-service
spec:
selector:
app: order-service
ports:
- name: http
port: 80
targetPort: http保存为 deployment.yaml 后执行:
kubectl apply -f deployment.yaml
kubectl rollout status deployment/order-service
kubectl get pod -l app=order-service预期结果是资源创建成功;Pod 在 readiness 成功后显示 1/1,实际 Pod 名称和耗时不同。
deployment.apps/order-service created
service/order-service created
deployment "order-service" successfully rolled out
order-service-<ID> 1/1 Running 0 <TIME>验证结果
先在本机端口转发后直接访问业务端口,确认响应码和健康状态,再检查 Service 对应的 EndpointSlice。
kubectl port-forward deployment/order-service 18080:8080预期输出如下,转发进程需保持运行:
Forwarding from 127.0.0.1:18080 -> 8080另开终端执行:
curl -i http://localhost:18080/readyz
kubectl get endpointslice -l kubernetes.io/service-name=order-service健康时的核心响应如下;响应头、地址和资源名称可能不同。
HTTP/1.1 200
{"status":"UP"}风险与边界
触发条件:把共享数据库、缓存和所有下游服务都加入 readiness。可能后果:单个公共依赖故障导致所有副本同时摘流,入口出现无可用端点。安全替代:只纳入实例无法提供核心能力时必须依赖的检查;可降级依赖交给超时、熔断和降级处理。
触发条件:探针访问独立 management 端口。可能后果:管理端口正常但主业务端口线程池或连接器失效,产生假阳性。安全替代:使用 add-additional-paths 将 /readyz 暴露在主端口。
排障清单
/readyz返回404:确认 Actuator 依赖存在、配置已加载,并检查管理端点路径是否被自定义。- 返回
503:查看/actuator/health/readiness、应用日志及数据库健康检查;不要先盲目调大阈值。 - Pod 长期
0/1:执行kubectl describe pod <POD>,读取Readiness probe failed事件中的状态码或超时。 - 启动慢但被重启:问题通常在 liveness;增加
startupProbe,不要用放宽 readiness 代替启动保护。
兼容性
Spring Boot 在 Kubernetes 环境中自动提供 /actuator/health/liveness 与 /actuator/health/readiness 健康组;额外路径 /livez、/readyz 可通过 management.endpoint.health.probes.add-additional-paths=true 开启。:contentReference[oaicite:1]{index=1}
识别无法自行恢复的服务实例并触发平台重启。
配置存活探针
用于让 Kubernetes 只在进程进入无法自行恢复的状态时重启容器。Spring Boot Actuator 提供独立的 liveness 健康组;探针持续返回成功时实例保持运行,连续失败达到阈值后由 kubelet 重启容器。

应用配置
片段示例:项目需已引入 Actuator;在现有 application.yml 中显式启用探针,并把 /livez 暴露在业务主端口,避免管理端口正常但业务端口失效时仍误判存活。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>management:
endpoint:
health:
probes:
enabled: true
add-additional-paths: true生效后,liveness 健康组可通过主端口的 /livez 访问;标准 Actuator 路径仍为 /actuator/health/liveness。不要把数据库、缓存或第三方接口加入存活组,这类共享依赖故障不应触发全部实例重启。
Kubernetes 配置
以下片段放入容器定义。startupProbe 先保护慢启动过程,成功后再开始执行 livenessProbe;示例最多允许约 120 秒启动时间,存活检查连续失败 3 次后才重启。
ports:
- name: http
containerPort: 8080
startupProbe:
httpGet:
path: /livez
port: http
periodSeconds: 5
timeoutSeconds: 2
failureThreshold: 24
livenessProbe:
httpGet:
path: /livez
port: http
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3配置生效行为:启动探针通过前不会执行存活探针;运行期 /livez 连续 3 次超时或返回非成功状态后,kubelet 重启该容器。实际检测时间还会受请求耗时和调度偏差影响。
验证结果
部署后可转发业务端口并读取状态码与响应体。
kubectl port-forward deploy/orders 8080:8080 >/tmp/orders-port-forward.log 2>&1 &
PF_PID=$!
trap 'kill "$PF_PID" 2>/dev/null || true' EXIT
sleep 2
curl -sS -o /tmp/livez.json -w '%{http_code}\n' http://127.0.0.1:8080/livez
cat /tmp/livez.json预期输出
200
{"status":"UP"}200 表示探针请求成功,status 为 UP 表示当前应用存活状态正常。端口、Deployment 名称和上下文路径不同时,应替换为实际值。
风险与边界
存活探针依赖数据库、Redis 或外部 API 时,共享依赖短暂故障会触发所有副本反复重启,造成级联故障;安全替代是把必要依赖放入 readiness 检查,并由熔断、降级和告警处理。
阈值过小或未配置 startupProbe 时,长时间初始化、Full GC 或瞬时负载会形成重启循环;应根据真实启动分位数和最长暂停时间设置超时,并保留连续失败容错。
排障清单
出现 404 时检查 Actuator 依赖、management.endpoint.health.probes.enabled、上下文路径以及探针端口;出现 401 或 403 时,仅向集群内部放行 /livez,不要扩大全部 Actuator 端点权限。
kubectl describe pod <POD>
kubectl logs <POD> --previous --tail=100预期重点字段
Restart Count: <COUNT>
Last State: Terminated
Reason: <REASON>Restart Count 持续增长说明容器正在重启循环;结合 Events 和上一实例日志确认是探针超时、应用卡死、OOM 还是启动时间不足。
停止接收新请求并等待正在执行的请求安全完成。
启用优雅停机
用于在发布、缩容或节点驱逐时先停止接收新请求,再给正在执行的请求和关闭钩子留出完成时间。核心是让 JVM 收到 SIGTERM、Spring Boot 执行优雅关闭,并让平台终止宽限期大于应用实际排空时间。

应用与平台配置
在 application.yml 中显式声明优雅关闭,并为每个关闭阶段设置上限。平台宽限期应覆盖应用排空、关闭钩子、连接池释放以及少量网络传播缓冲。
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 20sDeployment 中给 Pod 预留更长的终止时间;以下 30 秒是基线示例,若存在长请求、消息消费或较慢的资源释放,应按压测结果提高。
spec:
template:
spec:
terminationGracePeriodSeconds: 30
containers:
- name: orders
image: example/orders:<TAG>
ports:
- name: http
containerPort: 8080生效后,Spring Boot 收到正常关闭信号会停止接受新请求并等待在途请求完成,直到关闭阶段完成或达到 20 秒上限;Kubernetes 在 30 秒宽限期结束前等待进程退出,超期后可能强制终止。
确保信号到达 JVM
容器入口必须使用 exec 形式,使 Java 进程直接接收 SIGTERM。Shell 形式若没有 exec,信号可能只到达外层 shell,表现为没有优雅关闭日志并在宽限期结束后被强杀。
FROM eclipse-temurin:21-jre
COPY target/app.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]验证方法:查看容器内 PID 1,应为 java;若必须通过脚本启动,脚本最后一行使用 exec java -jar /app/app.jar 替换自身进程。
验证停机
以下命令在本机启动应用并发送与 Kubernetes 相同类型的终止信号。应用必须已构建为可执行 JAR。
java -jar target/app.jar > /tmp/app-shutdown.log 2>&1 &
APP_PID=$!
sleep 3
kill -TERM "$APP_PID"
wait "$APP_PID" || true
grep -E 'graceful shutdown|Graceful shutdown' /tmp/app-shutdown.log预期输出
<TIME> ... Commencing graceful shutdown. Waiting for active requests to complete
<TIME> ... Graceful shutdown complete日志格式和线程名可能不同,但应先出现开始排空,再出现完成关闭。只有开始日志而没有完成日志,通常表示在途请求、关闭钩子或后台任务超过超时。
风险与边界
terminationGracePeriodSeconds 小于应用关闭总耗时时,平台会发送 SIGKILL,可能造成连接重置、事务中断或消息重复处理;安全替代是扩大宽限期、限制单请求耗时,并让写操作和消息消费保持幂等。
盲目增加 preStop: sleep 会在发送 SIGTERM 前消耗同一终止宽限期,反而压缩应用排空时间;只有确认负载均衡摘流存在传播延迟时才使用,并把等待时间计入总预算。
优雅停机只保证给任务完成机会,不保证无限等待。无法中断的线程、无超时的远程调用和阻塞式关闭钩子仍会拖到上限,应为外部调用设置超时并让后台任务响应中断。
排障清单
没有优雅关闭日志时,确认 Pod 因正常删除、滚动发布或缩容收到 SIGTERM,而不是 OOM、节点故障或人工 kill -9;同时检查 PID 1 和启动脚本是否正确转发信号。
新请求仍持续进入时,检查 readiness 探针、Service EndpointSlice、Ingress 或云负载均衡的连接排空策略;长连接和 HTTP keep-alive 可能让少量旧连接继续存在。
Pod 总在宽限期末尾消失时,按顺序检查慢请求、线程池、消息监听器、数据库连接池和自定义 @PreDestroy。先缩短单项超时并记录关闭阶段耗时,再决定是否扩大平台宽限期。
通过健康检查和分批替换实例降低发布中断风险。
实施滚动发布
通过就绪检查、受控并发和可回退的镜像替换,让新旧实例在一段时间内并存,只有验证通过的新实例才接收流量。以下示例以 Kubernetes Deployment 承载 Spring Boot 服务为例。
发布前检查
发布前确认新旧版本能够同时访问数据库、缓存和消息系统;/actuator/health/readiness 返回 HTTP 200;应用能在终止信号后停止接收新请求,并在宽限期内完成在途请求。数据库变更应先扩展、后迁移、最后删除旧字段,避免新旧实例并存时互不兼容。
滚动策略
片段示例:以下内容放在 Deployment 的 spec 下。maxUnavailable: 0 保证替换期间不主动减少可用副本,maxSurge: 1 允许额外启动一个新实例;集群必须留有相应 CPU、内存和调度容量。
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
minReadySeconds: 15
template:
spec:
terminationGracePeriodSeconds: 30
containers:
- name: order-service
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: 8080
periodSeconds: 5
failureThreshold: 3新 Pod 只有连续通过就绪检查并保持 15 秒后才进入可用状态;旧 Pod 会在新容量建立后逐个退出。

执行与验证
先替换镜像,再等待控制器完成滚动;不要只看命令返回成功,还要核对所有目标 Pod 的 READY、重启次数和版本标签。
kubectl -n production set image deployment/order-service \
order-service=registry.example.com/order-service:<IMAGE_TAG>
kubectl -n production rollout status deployment/order-service --timeout=5m
kubectl -n production get pods -l app=order-service -o wide预期输出
deployment.apps/order-service image updated
deployment "order-service" successfully rolled out
NAME READY STATUS RESTARTS AGE
order-service-<ID> 1/1 Running 0 <TIME>实际 Pod 名称、年龄和节点会不同。只有全部目标副本为 1/1 Running,且监控中的错误率、延迟和请求量没有异常,才可判定发布完成。
失败回退
当就绪检查持续失败、错误率明显升高或关键依赖不兼容时,立即回退到上一个 Deployment 修订版本。
kubectl -n production rollout undo deployment/order-service
kubectl -n production rollout status deployment/order-service --timeout=5m预期输出
deployment.apps/order-service rolled back
deployment "order-service" successfully rolled out回退只恢复工作负载模板,不会自动回滚已经执行的数据库变更、消息格式或外部配置,因此这些变更必须提前设计为向后兼容。
风险与边界
当集群没有额外容量时,maxSurge: 1 可能让新 Pod 长时间处于 Pending,发布随之停滞;安全替代是先扩容节点或临时降低副本资源请求。若就绪检查依赖所有下游服务,短暂抖动可能阻塞整批发布;应只检查本实例是否具备接流量条件,并为下游故障设置合理超时和降级。对有本地会话或长连接的服务,直接终止旧实例会造成会话中断;应使用外部会话存储、连接排空和足够的终止宽限期。
速查结论:先保证新旧版本兼容,再以就绪门禁逐批替换;发布异常时优先暂停或回退,不要用关闭健康检查的方式强行上线。
检查注册中心地址、网络、认证、服务名称和健康状态。
排查服务未注册
按应用存活、配置生效、网络连通、认证授权、服务标识和健康状态的顺序检查,可以把未注册问题快速定位到客户端、链路或注册中心,而不是反复重启实例。
排查顺序
先确认应用进程已完成启动并保持健康,再核对当前 Profile 下的注册中心地址和服务名。随后验证 DNS、端口、TLS 和鉴权,最后到注册中心确认实例是否因健康检查失败被摘除。不要从注册中心页面直接下结论,客户端日志和本地健康状态同样关键。

一次性连通性检查
下面的命令同时验证应用健康端点和注册中心 HTTP 入口。示例使用 Eureka 地址;替换为当前环境的真实地址后执行。
APP_URL=http://127.0.0.1:8080
REGISTRY_URL=http://127.0.0.1:8761/eureka/apps
curl -fsS "$APP_URL/actuator/health" >/dev/null && echo app-health=ok
curl -fsS -H 'Accept: application/json' "$REGISTRY_URL" >/dev/null && echo registry-reachable=ok预期输出
app-health=ok
registry-reachable=ok若第一行未出现,优先处理应用未启动、健康状态为 DOWN、端口错误或 Actuator 未暴露;若第二行未出现,检查地址、DNS、路由、防火墙、代理、TLS 证书以及 401/403 鉴权失败。curl -f 会把 HTTP 4xx 和 5xx 视为失败。
配置核对
Eureka 客户端至少要有稳定的服务名、启用注册以及正确的服务端地址。以下为完整配置示例,实际生产地址通常由环境变量或配置中心覆盖。
spring:
application:
name: order-service
eureka:
client:
enabled: true
register-with-eureka: true
service-url:
defaultZone: http://eureka.prod.svc:8761/eureka/生效行为:应用启动后以 order-service 注册,并周期性续约。验证时重点确认当前 Profile 确实加载了这组值,容器环境变量没有把地址覆盖为空值或旧环境地址。服务名大小写、命名空间、分组或区域不一致时,实例可能已注册但调用方查询不到。
日志与状态判断
启动日志中出现连接拒绝或超时,通常是网络、DNS 或地址错误;出现 401/403,通常是令牌、账号或权限问题;持续注册后又被摘除,通常是健康检查路径、端口或返回码不符合注册中心要求。若日志完全没有注册客户端初始化信息,检查对应 discovery starter 是否存在、自动配置是否被排除,以及 spring.cloud.discovery.enabled 是否被关闭。
在注册中心侧同时核对实例 IP、端口、状态和最后心跳时间。容器内注册了不可路由的回环地址、宿主机错误网卡或重复实例 ID,会导致看似注册成功但实际不可调用。
风险与边界
不要通过关闭鉴权、跳过 TLS 校验或永久关闭健康检查来换取注册成功;这会把网络中间人、错误实例和未就绪实例带入流量池。安全替代是修复信任链、最小化授权并校准健康端点。/actuator/env 可能暴露敏感配置,不应为排障直接公开到公网;优先在受控环境检查启动参数、环境变量和配置中心审计记录。
兼容性
Eureka 重点检查 eureka.client.service-url.defaultZone 与续约;Consul 重点检查 spring.cloud.consul.host、端口和 HTTP 健康检查;Nacos 重点检查 spring.cloud.nacos.discovery.server-addr、命名空间、分组和认证。不同实现的属性名与健康判定不同,但排查顺序保持一致:应用健康、有效配置、链路可达、认证通过、标识匹配、心跳正常。
速查结论:先用本地健康与注册中心连通性把问题分层,再查实际生效配置和客户端日志;不要用降级安全控制的方式掩盖注册失败。
定位实例发现、DNS、端口、超时、序列化和下游异常问题。
排查服务调用失败
用于把“服务调用失败”拆成可验证的故障层:实例发现、名称解析、TCP 连接、HTTP 超时、响应反序列化和下游业务异常。按链路从前往后检查,先确认请求是否到达目标实例,再决定排查客户端还是下游服务。

定位顺序
先看客户端异常类型,不要一开始就扩大日志范围。No servers available 或负载均衡选不到实例,优先查注册中心、实例健康状态、服务名和元数据;UnknownHostException 查 DNS;Connection refused 查端口和进程;ReadTimeout 查下游耗时、连接池和超时配置;HTTP 4xx/5xx 已说明网络链路通常可达,应转向接口参数、鉴权或下游异常。
主验证命令
在与调用方相同的容器、Pod 或主机中执行,避免只在个人电脑验证。将主机名、端口和路径替换为真实值;命令同时给出 DNS 结果、远端 IP、连接耗时、总耗时、状态行和响应体前 300 字节。
HOST="${HOST:-orders-service}"
PORT="${PORT:-8080}"
PATH_TO_CHECK="${PATH_TO_CHECK:-/actuator/health}"
URL="http://${HOST}:${PORT}${PATH_TO_CHECK}"
# 先验证名称解析,再用同一地址完成 TCP 与 HTTP 检查。
getent hosts "$HOST"
curl -sS \
--connect-timeout 2 \
--max-time 5 \
-D /tmp/call.headers \
-o /tmp/call.body \
-w 'http_code=%{http_code} remote_ip=%{remote_ip} remote_port=%{remote_port} connect=%{time_connect}s total=%{time_total}s\n' \
"$URL"
head -n 1 /tmp/call.headers
head -c 300 /tmp/call.body
printf '\n'预期输出
<IP> orders-service
http_code=200 remote_ip=<IP> remote_port=8080 connect=0.004s total=0.018s
HTTP/1.1 200
{"status":"UP"}<IP> 和耗时会随环境变化。curl 退出码 6 表示无法解析主机,7 表示无法连接目标端口,28 表示达到超时;HTTP 返回 500 时命令仍可能执行成功,应以 http_code 和响应体判断业务结果。
高频问题判断
服务发现失败时,确认调用名与 spring.application.name 一致,并检查实例是否因健康检查、区域或元数据过滤而不可选。DNS 成功但端口拒绝连接,通常是容器端口、Service targetPort、进程监听地址或安全组不匹配。连接快但总耗时接近超时上限,重点查看下游线程池、数据库、消息系统和连接池等待时间。
收到 2xx 仍报调用异常时,核对 Content-Type、字符集和响应结构。常见情况是接口返回 HTML 错误页、字段类型变化、空响应体或客户端 DTO 与服务端契约不一致。用同一 traceId 对齐调用方、网关和目标实例日志,确认异常发生在发送前、等待中还是反序列化阶段。
风险与边界
不要通过无限重试掩盖超时。对非幂等写请求启用自动重试,可能造成重复扣款、重复创建或消息重复投递;安全替代是仅对明确幂等操作重试,并使用幂等键、退避和总时限。不要在生产环境直接把连接与读取超时整体调大,这会放大线程占用和级联阻塞;应先定位慢点,再调整单次超时、调用预算和熔断阈值。
健康检查成功只证明检查端点可达,不代表目标业务接口、数据库或外部依赖正常。最终必须使用与真实调用相同的协议、路径、请求头和身份信息验证;涉及敏感令牌时使用受控终端和临时凭据,避免把认证头写入共享日志。
排障清单
- 实例列表是否为空,目标实例是否健康且未被区域、权重或元数据过滤。
- 服务名能否解析,解析结果是否指向预期地址。
- 目标进程是否监听正确端口与网卡,容器端口和转发端口是否一致。
- 连接耗时、总耗时和客户端超时分别是多少,是否存在连接池等待。
- HTTP 状态、响应头和响应体是否符合接口契约。
- 调用方与下游是否能用同一
traceId对齐,最早异常出现在哪一跳。
兼容性
getent 常见于 Linux;macOS 可改用 dscacheutil -q host -a name "$HOST" 或 dig。精简容器若没有诊断工具,应使用同网络命名空间的临时调试容器。使用 HTTPS、服务网格或双向 TLS 时,还要检查证书、SNI、代理端口和 sidecar 状态,不能只依据明文 HTTP 结果。
检查配置来源、环境标识、加载顺序和动态刷新范围。
排查配置未生效
用于确认配置到底从哪里加载、当前激活了哪个环境、同名键被谁覆盖,以及运行中的 Bean 是否支持动态刷新。先读取应用实际 Environment,再判断配置中心、Profile、优先级或刷新范围,避免只检查远端配置页面。

先确认实际值和来源
需要启用并授权 Actuator env 端点,同时本机安装 curl 和 jq。下面命令读取当前激活的 Profile,并按属性源列出目标键;列表中靠前的匹配项通常优先级更高,最终值应以应用实际返回为准。
BASE_URL="${BASE_URL:-http://127.0.0.1:8080}"
KEY="${KEY:-feature.checkout.enabled}"
curl -fsS "${BASE_URL}/actuator/env" |
jq --arg key "$KEY" '{
activeProfiles: .activeProfiles,
matches: [
.propertySources[]
| select(.properties[$key] != null)
| {
source: .name,
value: .properties[$key].value,
origin: (.properties[$key].origin // null)
}
]
}'预期输出
{
"activeProfiles": [
"prod"
],
"matches": [
{
"source": "<HIGH_PRIORITY_SOURCE>",
"value": "true",
"origin": "<ORIGIN_OR_NULL>"
},
{
"source": "<LOW_PRIORITY_SOURCE>",
"value": "false",
"origin": "<ORIGIN_OR_NULL>"
}
]
}<HIGH_PRIORITY_SOURCE>、<LOW_PRIORITY_SOURCE> 和来源描述会随 Spring Boot、配置中心及部署方式变化。没有 matches 说明键未进入当前 Environment;有多条匹配且最终值不符合预期,通常是更高优先级来源覆盖;activeProfiles 不正确时,应先修正启动参数或环境变量。
检查加载入口
Spring Boot 2.4 及之后通常通过 spring.config.import 导入远端配置。确认导入地址、服务名、Profile 和标签与配置中心中的数据集一致,并检查启动日志中是否出现拉取失败、认证失败或可选导入被跳过。若使用 optional:,远端不可用时应用可能继续启动,但会回退到本地或默认值。
环境变量键名会做规范化映射,例如 FEATURE_CHECKOUT_ENABLED 可覆盖 feature.checkout.enabled。命令行参数、系统属性、环境变量和本地文件可能比远端来源优先,不能仅凭配置中心页面判断最终值。容器编排平台还应检查 ConfigMap、Secret、启动脚本和 Helm values 是否注入了同名键。
验证绑定和刷新范围
Environment 中的值正确但业务行为未变化,说明问题多半在绑定层。检查属性前缀、字段名、类型转换和 Bean 是否真正读取该键。构造器中复制到普通字段、静态变量或手工缓存的值不会自动变化;@ConfigurationProperties 是否可重绑定、@Value 是否位于刷新作用域,以及所用 Spring Cloud 版本都会影响刷新结果。
需要动态刷新时,先确认应用包含 Spring Cloud Context,并显式暴露受保护的刷新端点。单实例可按变更流程调用刷新;多实例应逐实例验证,或使用消息总线统一传播。刷新后再次读取 /actuator/env 并访问真实业务端点,不能只以刷新接口返回成功作为生效证据。
风险与边界
/actuator/env 可能暴露数据库口令、令牌或内部地址。触发条件是端点对外暴露、未鉴权或脱敏规则不足,后果是敏感配置泄漏;安全替代是仅在管理网络开放、启用认证、最小化暴露端点,并保持敏感值脱敏。排障结束后应恢复端点暴露策略。
刷新会重新绑定部分 Bean,可能导致连接池、线程池或客户端在运行中重建。直接在全部生产实例同时刷新,可能造成瞬时抖动或配置不一致;安全替代是先在单个实例或小流量分组验证,记录配置版本,再逐批执行并检查业务指标。对必须重启才能生效的配置,不要反复调用刷新端点,应安排滚动重启。
排障清单
activeProfiles是否与部署环境一致,Profile 名称和大小写是否准确。- 远端配置是否真正导入,应用名、Profile、标签、命名空间和认证是否匹配。
- 同名键是否被命令行、系统属性、环境变量、ConfigMap、Secret 或本地文件覆盖。
- 属性键、前缀、字段类型和绑定类是否一致,是否存在旧值缓存或静态字段。
- 目标 Bean 是否属于可刷新范围,刷新端点是否存在、暴露且已鉴权。
- 刷新或重启后,
Environment、业务端点和运行日志是否同时证明新值生效。
兼容性
旧版 Spring Cloud 项目可能依赖 bootstrap 上下文和 bootstrap.yml,新版项目通常使用 Config Data 导入;两套机制混用时应先确认依赖和启动方式。Actuator 端点结构、默认暴露范围和脱敏行为会随 Spring Boot 版本变化,因此命令中的字段以当前应用实际响应为准。若没有 Actuator,只能通过启动日志、受控诊断接口或测试 Bean 输出来源和值,避免在业务日志长期打印敏感配置。
检查断言条件、路径重写、服务发现和过滤器执行结果。
排查网关路由失败
用于定位请求在 Spring Cloud Gateway 中出现 404、503、错误下游路径或被过滤器提前终止的问题。排查时先确认“路由是否已加载”,再按断言、路径改写、服务发现、过滤器和下游响应的顺序收敛,避免一开始就修改注册中心或全局配置。
排障链路
网关路由失败通常不是单点问题:请求先经过断言匹配,再执行过滤器和路径改写,lb:// 路由还要从注册中心选择实例。先记录请求方法、Host、原始路径和请求头,再沿同一个请求 ID 对照网关与下游日志。

核对生效路由
先临时开放只读 Gateway Actuator,再检查实际加载的 route_id、predicate、filters 和 uri。不要只看配置中心文件;配置未刷新、Profile 不一致或路由定义解析失败时,运行态内容可能与文件不同。当前官方文档中,Gateway Actuator 默认关闭,需要显式开放访问。:contentReference[oaicite:0]{index=0}
spring:
cloud:
gateway:
server:
webflux:
routes:
- id: order-api
uri: lb://order-service
predicates:
- Path=/api/orders/**
filters:
- RewritePath=/api/?(?<segment>.*), /$\{segment}
management:
endpoint:
gateway:
access: read-only
endpoints:
web:
exposure:
include: health,gateway,metrics该配置应把 /api/orders/42 改写为 /orders/42,再转发到注册名为 order-service 的实例。RewritePath 在 YAML 中需要写成 /$\{segment},否则占位表达式可能在绑定阶段被错误处理。:contentReference[oaicite:1]{index=1}
执行以下命令,同时比较网关、路由定义和直连下游。将地址、路由 ID 与接口路径替换成现场值。
GATEWAY_URL="http://localhost:8080"
UPSTREAM_URL="http://localhost:8081"
ROUTE_ID="order-api"
curl -sS "${GATEWAY_URL}/actuator/gateway/routes/${ROUTE_ID}"
printf '\n'
curl -sS -o /dev/null -w 'gateway status=%{http_code} total=%{time_total}s\n' "${GATEWAY_URL}/api/orders/42"
curl -sS -o /dev/null -w 'upstream status=%{http_code} total=%{time_total}s\n' "${UPSTREAM_URL}/orders/42"预期输出
{"route_id":"order-api","predicate":"(Paths: [/api/orders/**], match trailing slash: true)","filters":["[[RewritePath /api/?(?<segment>.*) = '/${segment}'], order = 1]"],"uri":"lb://order-service","order":0}
gateway status=200 total=<SECONDS>s
upstream status=200 total=<SECONDS>s<SECONDS> 会随网络和下游耗时变化。若路由查询返回 404,说明路由未加载或 ID 不一致;若直连成功而网关失败,故障位于断言、改写、过滤器或服务发现层。
结果判读
- 网关 404、Actuator 中无该路由:检查配置源、激活 Profile、路由刷新结果和启动日志中的绑定异常。
- 网关 404、路由存在:逐项核对
Path、Host、Method、Header 和 Query 断言;多个断言默认同时满足。 - 网关 503、
uri为lb://...:检查服务名大小写、注册中心健康实例数量、命名空间和网关是否加载 DiscoveryClient/LoadBalancer。 - 网关 200/4xx 但下游收到错误路径:对照
RewritePath、StripPrefix、PrefixPath的执行顺序,并在下游访问日志确认最终 URI。 - 网关与下游都返回 5xx:路由已命中,继续排查下游;不要把业务异常误判为网关未路由。
Gateway 的路由详情接口会直接给出断言、过滤器、目标 URI 与顺序,适合确认“运行时到底执行了什么”。:contentReference[oaicite:2]{index=2}
风险与边界
生产环境不要把 Gateway Actuator 设置为匿名 unrestricted,否则可能暴露路由拓扑,甚至开放动态增删路由能力。安全做法是使用 read-only、限制管理端口来源,并在排障后收回暴露范围。
不要长期开启 Netty wiretap 或全量请求体日志。高流量下会显著增加日志量、CPU 与磁盘压力,还可能记录令牌和敏感参数;优先使用路由指标、访问日志和短时请求 ID 追踪。
兼容性
Spring Cloud Gateway 5.x 的 WebFlux 配置前缀为 spring.cloud.gateway.server.webflux;较早的 4.x 项目常见 spring.cloud.gateway.routes。Web MVC 版本使用 spring.cloud.gateway.server.webmvc,不要混用两套前缀和过滤器写法。当前属性清单也明确区分 WebFlux 与 Web MVC。:contentReference[oaicite:3]{index=3}
检查连接池、超时配置、下游耗时、线程阻塞和重试放大。
排查 Feign 超时
用于定位 Feign 调用出现 Connect timed out、Read timed out、连接池等待或调用线程长期阻塞的问题。先判断时间花在连接前、建立连接、等待响应还是重试,再分别检查客户端配置、连接池、下游耗时和线程栈。
区分超时位置
connectTimeout 控制建立连接阶段,readTimeout 从连接建立后开始约束等待响应的时间。除此之外,连接池借用、DNS/TLS、负载均衡选址、调用线程排队和下游数据库也会消耗时间,因此“总耗时超过 readTimeout”不一定代表配置未生效。:contentReference[oaicite:4]{index=4}

配置并复现
为单个客户端设置较小但可解释的超时,并只开启 BASIC 日志。配置键 order-service 必须与 @FeignClient(name = "order-service") 的名称一致;名称不匹配时会继续使用默认配置。
spring:
cloud:
openfeign:
client:
config:
order-service:
connectTimeout: 1000
readTimeout: 3000
loggerLevel: basic
logging:
level:
com.example.client.OrderClient: DEBUGFeign 日志只有在对应接口 Logger 为 DEBUG 时才输出;BASIC 会记录方法、URL、状态码和耗时,适合生产短时排查,FULL 会包含请求与响应头、正文,存在泄密和日志放大风险。:contentReference[oaicite:5]{index=5}
用同一业务参数分别调用“经过 Feign 的入口”和下游直连接口。下游地址应从注册中心实例信息或部署配置获取,不要绕过鉴权访问公网生产接口。
CALLER_URL="http://localhost:8080"
UPSTREAM_URL="http://localhost:8081"
curl -sS --max-time 8 -o /dev/null -w 'caller status=%{http_code} total=%{time_total}s\n' "${CALLER_URL}/api/orders/42"
curl -sS --max-time 8 -o /dev/null -w 'upstream status=%{http_code} total=%{time_total}s\n' "${UPSTREAM_URL}/orders/42"预期输出
caller status=<HTTP_STATUS> total=3.<MILLISECONDS>s
upstream status=200 total=5.<MILLISECONDS>s当下游约 5 秒返回、Feign readTimeout 为 3 秒时,调用方通常在约 3 秒失败;<HTTP_STATUS> 取决于应用的异常映射,常见为 500 或 504。若直连也在 3 秒内失败,应先排查下游或网络,而不是继续放大 Feign 超时。
判读异常与线程
Connection refused:目标端口立即拒绝,通常不是等待到connectTimeout;检查实例端口、容器监听地址和健康状态。Connect timed out:网络不可达、防火墙丢包、TLS 握手或错误地址更常见;同时检查 DNS 解析耗时。Read timed out:连接已建立,但下游在窗口内未返回;对照下游访问日志、慢 SQL、外部依赖和线程池队列。- 日志中没有下游请求,线程停在连接管理器:连接池可能耗尽,重点看 leased、available、pending 指标以及连接泄漏。
- 大量
BLOCKED、业务线程池队列持续增长:调用前已发生线程争用;增加 Feign 超时只会让拥塞更严重。
必要时抓取一次 JVM 线程快照,确认调用线程是在 socket 读取、连接池等待还是业务锁上。存在多个 Java 进程时先执行 export PID=<PID> 指定目标进程,避免抓错实例。
PID="${PID:-$(jcmd | awk 'NR==1 {print $1}')}"
test -n "${PID}" || { echo "no Java process found"; exit 1; }
jcmd "${PID}" Thread.print |
grep -E -A8 'BLOCKED|WAITING|TIMED_WAITING|feign|httpclient'预期输出
"<THREAD_NAME>" #<ID> TIMED_WAITING
at <HTTP_CLIENT_OR_POOL_WAIT_FRAME>
at feign.SynchronousMethodHandler.executeAndDecode(<SOURCE>)实际线程名、行号和 HTTP 客户端栈帧会不同;连续两次快照若大量线程停在同一位置,才说明该位置具有排障价值。
检查重试放大
Spring Cloud OpenFeign 默认创建 Retryer.NEVER_RETRY,但 Gateway、LoadBalancer、Spring Retry、Resilience4j 或自定义 ErrorDecoder 仍可能在其他层重试。逐层确认实际次数,并用请求 ID 对照下游访问日志;一次入口请求出现多条相同下游记录,就是重试放大的直接证据。:contentReference[oaicite:6]{index=6}
对非幂等写操作不要直接开启自动重试,可能造成重复扣款、重复发消息或重复创建数据。安全替代是先建立幂等键、限制最大尝试次数、设置总时间预算,并只对连接失败或明确可重试状态执行退避重试。
风险与兼容性
不要把 readTimeout 一次性调到几十秒掩盖慢调用。触发条件是下游持续变慢或连接池已拥塞,后果是线程和连接被更久占用,最终把局部延迟扩大为调用方雪崩;应先修复下游瓶颈,并让超时小于上游整体请求预算。
Spring Cloud OpenFeign 4 起不再支持 Apache HttpClient 4,使用 Apache HttpClient 5 时连接池和 TLS 参数名称与旧项目不同。升级后若超时行为变化,应同时核对 Release Train、HTTP 客户端实现和客户端级配置是否仍被绑定。:contentReference[oaicite:7]{index=7}