19、Spring Boot Actuator 全面解析与实践

最新推荐文章于 2025-10-30 10:21:47 发布

五行擒拿术

最新推荐文章于 2025-10-30 10:21:47 发布

阅读量73

点赞数

CC 4.0 BY-SA版权

分类专栏： Spring Boot 2实战指南：从入门到精通文章标签： Spring Boot Actuator 监控管理端点

本文链接：https://blog.youkuaiyun.com/table/article/details/149744284

Spring Boot 2实战指南：从入门到精通专栏收录该内容

26 篇文章 ¥499.90

订阅专栏¥69.90

会员秒杀 ¥9.9 重磅福利

超级会员免费看

Spring Boot Actuator 全面解析与实践

1. Spring Boot Actuator 核心端点介绍

Spring Boot Actuator 提供了一系列端点，用于监控和管理应用程序。以下是一些常见端点及其功能：
| 端点 | 功能 |
| — | — |
| /actuator/conditions | 显示自动配置报告，分为 positiveMatches 和 negativeMatches 两组 |
| /actuator/beans | 展示应用中使用的所有 Spring Bean |
| /actuator/configprops | 列出由 @ConfigurationProperties Bean 定义的所有配置属性 |
| /actuator/threaddump | 执行应用程序的线程转储，显示所有运行线程及其堆栈跟踪 |
| /actuator/env | 暴露 Spring 的 ConfigurableEnvironment 接口中的所有属性 |
| /actuator/health | 显示应用程序的健康状态 |
| /actuator/info | 显示公共应用程序信息，需在 application.properties 中添加相关信息 |
| /actuator/loggers | 显示应用中所有可用的日志记录器 |
| /actuator/loggers/{name} | 查看特定包及其日志级别 |
| /actuator/metrics | 展示当前应用程序的指标信息，如内存使用、空闲内存、正常运行时间等 |
| /actuator/mappings | 显示应用中声明的所有 @RequestMapping 路径 |
| /actuator/shutdown | 允许应用程序优雅关闭，默认未启用 |
| /actuator/httptrace | 显示跟踪信息，通常是最后几个 HTTP 请求 |

2. 端点使用示例

以下是一些端点的具体使用方法：
- /actuator/health ：默认只显示整体系统健康状态，若要查看更多详细信息，可在 application.properties 文件中添加 management.endpoint.health.show-details=always 。

management.endpoint.health.show-details=always

修改后重新运行应用程序，访问 http://localhost:8080/actuator/health 即可查看详细信息。
- /actuator/shutdown ：默认未启用，若要启用，需在 application.properties 中添加 management.endpoint.shutdown.enabled=true 。同时，为了安全起见，建议添加 spring-boot-starter-security 依赖。

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

添加依赖后，重新运行应用程序，从日志中获取默认密码，然后在终端执行以下命令关闭应用：

$ curl -i -X POST http://localhost:8080/shutdown -u user:your_password

3. 端点配置与定制

3.1 更改端点 ID

可以在 application.properties 文件中更改端点 ID，例如将 /actuator/beans 更改为 /actuator/spring：

management.endpoints.web.path-mapping.beans=spring

修改后重新运行应用程序，即可使用 /actuator/spring 访问原 /actuator/beans 端点。

3.2 配置 CORS 支持

为了允许跨域访问 Actuator 端点，可在 application.properties 中进行如下配置：

management.endpoints.web.cors.allowed-origins=http://mydomain.com
management.endpoints.web.cors.allowed-methods=GET, POST

配置完成后，停止并重新运行应用程序。

3.3 更改管理端点路径

默认情况下，Spring Boot Actuator 的管理端点根路径为 /actuator。若要更改路径，可在 application.properties 中添加：

management.endpoints.web.base-path=/monitor

重新运行应用程序后，所有端点将以 /monitor 为前缀，例如 http://localhost:8080/monitor/httptrace 。

4. 自定义 Actuator 端点

可以通过标记类和方法来创建自定义 Actuator 端点。以下是一个示例，创建一个名为 /todo-stats 的自定义端点，用于显示数据库中 ToDo 项的统计信息：

package com.apress.todo.actuator;

import com.apress.todo.domain.ToDo;
import com.apress.todo.repository.ToDoRepository;
import lombok.AllArgsConstructor;
import lombok.Data;
import org.springframework.boot.actuate.endpoint.annotation.*;
import org.springframework.stereotype.Component;

@Component
@Endpoint(id="todo-stats")
public class ToDoStatsEndpoint {
    private ToDoRepository toDoRepository;

    ToDoStatsEndpoint(ToDoRepository toDoRepository){
        this.toDoRepository = toDoRepository;
    }

    @ReadOperation
    public Stats stats() {
        return new Stats(this.toDoRepository.count(),this.toDoRepository.countByCompleted(true));
    }

    @ReadOperation
    public ToDo getToDo(@Selector String id) {
        return this.toDoRepository.findById(id).orElse(null);
    }

    @WriteOperation
    public Operation completeToDo(@Selector String id) {
        ToDo toDo = this.toDoRepository.findById(id).orElse(null);
        if(null != toDo){
            toDo.setCompleted(true);
            this.toDoRepository.save(toDo);
            return new Operation("COMPLETED",true);
        }
        return new Operation("COMPLETED",false);
    }

    @DeleteOperation
    public Operation removeToDo(@Selector String id) {
        try {
            this.toDoRepository.deleteById(id);
            return new Operation("DELETED",true);
        }catch(Exception ex){
            return new Operation("DELETED",false);
        }
    }

    @AllArgsConstructor
    @Data
    public class Stats {
        private long count;
        private long completed;
    }

    @AllArgsConstructor
    @Data
    public class Operation{
        private String name;
        private boolean successful; 
    }
}

同时，需要在 ToDoRepository 接口中添加 countByCompleted 方法：

package com.apress.todo.repository;

import com.apress.todo.domain.ToDo;
import org.springframework.data.repository.CrudRepository;

public interface ToDoRepository extends CrudRepository<ToDo,String> {
    public long countByCompleted(boolean completed);
}

运行应用程序后，访问 http://localhost:8080/actuator 即可看到 /todo-stats 端点。

5. 使用 JConsole 测试自定义端点

可以使用 JConsole 工具测试自定义端点：
1. 打开终端，执行 jconsole 命令。
2. 从 com.apress.todo.ToDoActuatorApplication 列表中选择并点击 Connect。
3. 点击 Insecure Connection 按钮。
4. 从主屏幕选择 MBeans 选项卡，展开 org.springframework.boot 包和 Endpoint 文件夹，找到 Todo-stats 并展开。
5. 点击 stats 项查看统计信息。
6. 点击 completeToDo 操作，在右侧输入未完成的 ToDo 项 ID（如 ebcf1850563c4de3b56813a52a95e930），然后点击 completeToDo 进行确认。
7. 再次执行 stats 操作，可看到已完成的 ToDo 项数量更新。

6. Spring Boot Actuator 健康检查

Spring Boot Actuator 的 /actuator/health 端点提供了应用程序的健康状态检查。可以通过配置 management.endpoint.health.show-details 属性来显示更多详细信息，其可能的值如下：
- never：从不显示详细信息，为默认值。
- when-authorized：仅向授权用户显示详细信息，可通过设置 management.endpoint.health.roles 属性配置角色。
- always：向所有用户显示所有详细信息。

Spring Boot Actuator 还提供了许多开箱即用的健康指示器，例如：
- CassandraHealthIndicator：检查 Cassandra 数据库是否正常运行。
- DiskSpaceHealthIndicator：检查磁盘空间是否不足。
- RabbitHealthIndicator：检查 Rabbit 服务器是否正常运行。

以下是测试健康指示器的步骤：
1. 在 ToDo 应用的 application.properties 文件中添加 management.endpoints.web.exposure.include=* 。
2. 添加 management.endpoint.health.show-details=always 属性。
3. 运行 ToDo 应用，访问 http://localhost:8080/actuator/health ，可看到 H2 数据库 DataSourceHealthIndicator 和 DiskSpaceHealthIndicator 自动配置。
4. 若使用 Maven，在 pom.xml 文件中添加以下依赖：

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

若使用 Gradle，在 build.gradle 文件中添加：

compile('org.springframework.boot:spring-boot-starter-amqp')

重新运行应用程序，访问 /actuator/health 端点。由于添加了 spring-boot-starter-amqp 依赖，RabbitHealthIndicator 将自动配置。若 RabbitMQ 服务器未运行，可能会显示系统状态为 down；启动 RabbitMQ 服务器后，刷新健康端点，系统状态将恢复正常。

通过以上步骤，你可以全面了解和使用 Spring Boot Actuator 的各种功能，实现对应用程序的有效监控和管理。

graph LR
    A[启动应用程序] --> B[/actuator/health 检查健康状态]
    B --> C{是否需要详细信息}
    C -- 是 --> D[配置 management.endpoint.health.show-details=always]
    C -- 否 --> E[/actuator/health 默认显示]
    D --> F[/actuator/health 显示详细信息]
    A --> G[/actuator/beans 查看 Spring Bean]
    A --> H[/actuator/configprops 查看配置属性]
    A --> I[/actuator/threaddump 线程转储]
    A --> J[/actuator/env 查看环境属性]
    A --> K[/actuator/info 查看公共信息]
    A --> L[/actuator/loggers 查看日志记录器]
    A --> M[/actuator/metrics 查看指标信息]
    A --> N[/actuator/mappings 查看请求映射]
    A --> O[/actuator/shutdown 关闭应用程序]
    A --> P[/actuator/httptrace 查看 HTTP 跟踪信息]
    A --> Q[创建自定义端点 /todo-stats]
    Q --> R[使用 JConsole 测试自定义端点]

Spring Boot Actuator 全面解析与实践

7. 端点安全配置

为了确保 Actuator 端点的安全性，可以通过添加 spring-boot-starter-security 依赖并配置 WebSecurityConfigurerAdapter 来实现。以下是一个示例配置：

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class ToDoActuatorSecurity extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
           .requestMatcher(EndpointRequest.toAnyEndpoint())
           .authorizeRequests()
           .anyRequest().hasRole("ENDPOINT_ADMIN")
           .and()
           .httpBasic();
    }
}

在上述配置中，要求访问端点的用户具有 ENDPOINT_ADMIN 角色。同时，需要在 pom.xml （Maven）或 build.gradle （Gradle）中添加 spring-boot-starter-security 依赖：
- Maven ：

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

Gradle ：

compile('org.springframework.boot:spring-boot-starter-security')

添加依赖后，默认会启用安全机制，用户名是 user ，密码会打印在日志中。也可以使用内存、数据库或 LDAP 用户来建立更好的安全机制。

8. 端点缓存配置

默认情况下，Actuator 端点会对不接受任何参数的读操作进行缓存。如果需要更改此行为，可以使用 management.endpoint.<endpoint-name>.cache.time-to-live 属性。例如，更改 /actuator/beans 端点的缓存时间：

management.endpoint.beans.cache.time-to-live=10s

将上述配置添加到 application.properties 文件中，即可将 /actuator/beans 端点的缓存时间设置为 10 秒。

9. 禁用端点

出于安全考虑，可以禁用 Actuator 端点。有两种方法可以实现：
- 方法一 ：在 application.properties 中添加 management.endpoints.enabled-by-default=false ，这将禁用所有默认启用的端点。
- 方法二 ：在 application.properties 中添加 management.server.port=-1 ，这将禁用管理端点的端口。

10. 总结与实践建议

graph LR
    A[应用启动] --> B[配置安全依赖 spring-boot-starter-security]
    B --> C[配置 WebSecurityConfigurerAdapter]
    C --> D{是否需要缓存配置}
    D -- 是 --> E[配置 management.endpoint.<endpoint-name>.cache.time-to-live]
    D -- 否 --> F[不配置缓存]
    E --> G[端点缓存生效]
    F --> H[端点无缓存]
    A --> I{是否需要禁用端点}
    I -- 是 --> J[选择禁用方法]
    J --> K{方法一: management.endpoints.enabled-by-default=false}
    J --> L{方法二: management.server.port=-1}
    I -- 否 --> M[端点正常启用]
    K --> N[默认端点禁用]
    L --> O[管理端口禁用]

通过以上对 Spring Boot Actuator 的详细介绍和实践操作，你可以更好地掌握其使用方法，实现对应用程序的高效监控和管理。在实际开发中，根据具体需求灵活运用这些功能，将有助于提高应用程序的稳定性和可维护性。