Actuator 监控

约 1352 字大约 5 分钟

布欧-Lewyon

2026-05-15

Actuator 为生产环境提供监控与管理端点，包括健康检查、应用信息、指标、线程 dump 等。

集成

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

启动后访问 /actuator，默认只暴露 health 端点：

{
  "_links": {
    "self": {"href": "http://localhost:8080/actuator"},
    "health": {"href": "http://localhost:8080/actuator/health"}
  }
}

常用端点

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env,loggers,threaddump,heapdump
      # exclude: threaddump  # 排除敏感端点

端点	路径	用途
`health`	`/actuator/health`	健康检查（数据库、Redis 等组件状态）
`info`	`/actuator/info`	自定义应用信息
`metrics`	`/actuator/metrics`	JVM 指标（内存、线程、GC）
`env`	`/actuator/env`	环境属性（含部分敏感值！）
`loggers`	`/actuator/loggers`	运行时查看/修改日志级别
`threaddump`	`/actuator/threaddump`	线程 dump
`heapdump`	`/actuator/heapdump`	堆转储（触发 GC pause）
`mappings`	`/actuator/mappings`	所有请求映射

健康检查

management:
  endpoint:
    health:
      show-details: when-authorized
      show-components: when-authorized

响应：

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": { "database": "PostgreSQL" }
    },
    "redis": {
      "status": "UP",
      "details": { "version": "7.2.0" }
    }
  }
}

自定义 Info

info:
  app:
    name: @project.name@
    version: @project.version@
    description: @project.description@
  java:
    version: 17

端点安全

Actuator 端点可能泄露敏感信息（env 含环境变量、heapdump 含内存中的密码等）。安全建议：

单独端口开放，不与业务端口共享：

management:
  server:
    port: 8081
  endpoints:
    web:
      base-path: /internal/actuator  # 自定义根路径

与 Spring Security 整合：

@Bean
public SecurityFilterChain actuatorFilterChain(HttpSecurity http) throws Exception {
    http
        .securityMatcher("/actuator/**")
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/actuator/health").permitAll()
            .anyRequest().hasRole("ADMIN")
        )
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

源码与架构：内嵌 Web 容器与 Actuator 端点注册

Spring Boot 启动时，ServletWebServerApplicationContext.onRefresh() 触发内嵌容器创建，同时 Actuator 的端点通过 WebEndpointServletHandlerMapping 注册到独立的 DispatcherServlet（当 management.server.port 不同时）：

ServletWebServerApplicationContext.refresh()
│
├── onRefresh()
│   └── createWebServer()
│       ├── ServletWebServerFactory.getWebServer(servletContextInitializers)
│       │   └── TomcatServletWebServerFactory → Tomcat.getServer()
│       │       ├── 创建 StandardEngine / StandardHost
│       │       ├── 添加 Connector（HTTP/1.1 或 NIO2 或 APR）
│       │       └── 注册 Servlet（DispatcherServlet）
│       │
│       └── 启动 Tomcat → 监听端口
│
└── finishRefresh()
    └── 发布 ServletWebServerInitializedEvent
        └── Actuator 在此事件后开始注册管理端点
            └── ManagementContextAutoConfiguration
                ├── 如果 management.server.port != server.port
                │   └── 创建独立的管理子上下文
                │       └── 另一个 DispatcherServlet + WebEndpointServletHandlerMapping
                └── 否则
                    └── 在主 DispatcherServlet 中注册端点

管理分离模式下（management.server.port=8081），Spring Boot 实际上创建了两个 WebApplicationContext：一个主上下文（处理业务请求），一个管理子上下文（处理 Actuator 请求），各自由不同的 DispatcherServlet 和 Tomcat Connector 处理。这意味着 Actuator 请求不会经过业务层的 Filter、Interceptor 和安全配置——独立端口的隔离效果优于在业务层做路径匹配过滤。

Tomcat Connector 线程模型

Boot 3 默认使用 Tomcat 10.x，其 NioEndpoint 基于 Java NIO 的事件驱动模型：


关键参数（在 `server.tomcat.threads.*` 中配置）：

```yaml
server:
  tomcat:
    threads:
      max: 200                # 最大 Worker 线程数（默认 200）
      min-spare: 10           # 最小空闲线程数（默认 10）
    max-connections: 8192     # 最大连接数（默认 8192）
    accept-count: 100         # 等待队列长度（默认 100）
    connection-timeout: 20000 # 连接超时（毫秒，默认 20000）

生产意识：server.tomcat.threads.max 不是越大越好。每个线程占用大约 1MB 栈空间（取决于 OS 和 JDK），200 → 400 意味着多占用约 200MB 堆外内存。更重要的是，线程数超过数据库连接池上限时，Tomcat 线程会阻塞等待连接池释放——建议 max-threads ≤ 数据库 maximum-pool-size。Boot 4 中虚拟线程默认启用后，Tomcat 的 Worker 线程切换为虚拟线程，server.tomcat.threads.max 配置不再限制虚拟线程数——虚拟线程由 JVM 调度，理论上可创建数十万虚拟线程而不耗尽内存。但在 management.server.port 独立的场景下，管理端口的线程模型与业务端口独立——建议管理端口复用默认配置或使用平台线程避免干扰业务虚拟线程调度。

运行时修改日志级别

/actuator/loggers 支持 POST 请求动态修改日志级别，无需重启：

curl -X POST http://localhost:8080/actuator/loggers/com.example.demo \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

适合排查线上问题时临时开 DEBUG，排查完记得恢复。

生产意识：生产环境不建议开放 heapdump 端点——触发堆转储会触发 Full GC 并暂停应用（Stop-The-World），这对延迟敏感的服务是严重事件。同理，开放 env 端点会暴露环境变量（包括 DB_PASSWORD 等敏感值），务必做好隔离。建议在运维层面通过独立端口（management.server.port: 8081）+ 防火墙规则限制管理端口仅允许内网访问，而不是依赖 Spring Security 做应用层拦截（因为可能被绕过或忘记配置）。

小结

Actuator 提供健康检查、指标、线程 dump 等生产级监控端点。
默认只暴露 health；按需通过 management.endpoints.web.exposure.include 开放。
env / heapdump 等端点可能泄露敏感信息，生产环境做好访问控制。
/actuator/loggers 支持运行时修改日志级别，便于临时排查。
易错：/actuator/health 返回的详细状态需要 show-details: when-authorized 配合认证才能看到组件级详情（如数据库是否正常）。生产务必对 Actuator 端点做安全限制，建议使用单独端口和独立认证。
思考任务：为项目添加 Actuator 依赖，配置 management.server.port=8081 独立端口，用 curl 访问 /actuator/health 和 /actuator/info。

上一节：Spring Security 基础

下一节：打包与容器部署