监控 API¶
文档版本: 1.1.0
最后更新: 2026-09-15
Git 提交: 61384b4a
作者: Lincoln
JAiRouter 提供全面的监控 API,用于健康检查、指标收集和系统状态监控。
概述¶
监控 API 包括:
- 健康检查 - 服务和实例健康状态
- 指标 - 性能和使用统计
- 系统状态 - 整体系统健康和配置
所有监控端点都在 /actuator/* 路径下提供,为您的 JAiRouter 部署提供实时洞察。
健康检查端点¶
系统健康¶
获取整体系统健康状态:
响应:
{
"status": "UP",
"components": {
"diskSpace": {
"status": "UP",
"details": {
"total": 499963174912,
"free": 91943821312,
"threshold": 10485760,
"exists": true
}
},
"ping": {
"status": "UP"
},
"tracing": {
"status": "UP"
},
"sharedState": {
"status": "UP"
},
"rbacEndpointCoverage": {
"status": "UP",
"details": {
"missing": 0
}
}
}
}
⚠️ 组件名以实际注册的 health indicator 为准:
tracing(TracingHealthIndicator.java:28)、sharedState(SharedStateHealthIndicator.java:31)、rbacEndpointCoverage(RbacEndpointCoverageHealthIndicator.java:27)、jwtRedisHealthIndicator(JwtRedisHealthMonitor.java:21),另有 Spring Boot 标准的diskSpace等。 没有modelRouter这个组件;原文里的activeInstances/totalInstances/circuitBreakerStatus结构在代码中不存在。
详细健康信息¶
获取包括所有组件的详细健康信息:
⚠️ 没有
/actuator/health/detailed端点:只定义了liveness/readiness两个 group(config/base/monitoring-base.yml:70-84)。要看全部组件详情,请在 dev profile 下直接请求GET /actuator/health(该 profile 配了show-details: always)。
响应:
{
"status": "UP",
"components": {
"diskSpace": {
"status": "UP",
"details": {
"total": 499963174912,
"free": 91943821312,
"threshold": 10485760,
"exists": true
}
}
}
}
⚠️ 原文档在这里还列了一个
modelRouter组件(含services.*.instances[]明细)—— 该组件在代码里不存在,示例已删除;真实注册的 health 组件见本节开头的说明。
各探针该用哪个端点¶
/actuator/health 是整体健康,包含依赖组件(db、jwtRedis 等)。它适合「人看」和「告警」, 不适合直接当编排探针:依赖抖动会让副本被摘掉,而副本本身可能完全能服务。
| 消费者 | 用哪个端点 | 语义 |
|---|---|---|
| 进程存活(liveness) | /actuator/health/liveness | 只含 livenessState 与 ping,进程活着就是 UP |
| 接收流量(readiness) | /actuator/health/readiness | 只含 readinessState,默认不含 db/redis |
容器自检(Docker HEALTHCHECK) | /actuator/health/liveness | 仓库内 5 个 Dockerfile 均按此配置 |
| 告警与排障 | /actuator/health | 任一组件 DOWN 即 DOWN,这正是告警需要的信号 |
| 外部负载均衡(自建) | /actuator/health/readiness | 若希望「依赖故障就摘流」,改用整体 health 并接受误摘 |
Kubernetes 清单(
deploy/k8s/base/deployment.yaml)已经是正确做法:startupProbe/livenessProbe打/actuator/health/liveness,readinessProbe打/actuator/health/readiness。
为什么 readiness 不含依赖¶
readiness 只 include 了 readinessState(config/base/monitoring-base.yml)。原因是 Spring Boot 对 health group 的 include 做严格存在性校验:列一个当前上下文里不存在的组件名,应用会启动失败。 而 db、redis 这类组件是否装配取决于配置(例如 REDIS_ENABLED),无法在 yml 里静态列全。
代价是:Redis / 数据库不可用时,副本仍留在就绪集合,流量照进。对「依赖故障必须摘流」的部署, 需要在编排层自行聚合(额外探针查整体 health 并接受误摘),或打开 jairouter.health.readiness.include-dependencies(3.8.7 起提供,默认 false;开启后 /actuator/health/readiness 会经由 readinessDependencies 聚合器检查 db 与 redis, 依赖故障即退出就绪集合 —— 代价是滚动发布期间依赖抖动可能让新副本迟迟不就绪)。
该聚合器是恒装配的组件,因此写进 readiness 的
include不会触发上面那条严格存在性校验; 它内部只评估当前上下文里确实装配了的db/redis,没装配的依赖会被跳过而不是判 DOWN。
健康探针的设置项¶
三项都在「平台设置 → 健康探针设置」页(/system/health)可读可改,也可以直接走 API, 全部支持热改、无需重启:
| 配置键 | 默认值 | 作用 |
|---|---|---|
jairouter.health.readiness.include-dependencies | false | 就绪探针是否聚合 db / redis |
jairouter.security.jwt.redis-health.fail-health | true | Redis 不可用时 jwtRedis 是否把整体 health 判 DOWN |
# 读取当前值
curl -s -H "Authorization: Bearer <token>" http://localhost:8080/api/config/health
# 只改其中一项(部分更新)
curl -s -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-d '{"jwtRedisFailHealth": false}' http://localhost:8080/api/config/health
多副本下 jwtRedis 组件的影响¶
同时开启 jairouter.security.jwt.persistence.redis.enabled 与 jairouter.security.jwt.blacklist.redis.enabled(多副本部署必须开启)后,jwtRedisHealthIndicator 会做真实 Redis 往返;Redis 连不上时它返回 DOWN,整体 /actuator/health 随之 503。
3.8.7 起可以用 jairouter.security.jwt.redis-health.fail-health=false 把它降级为 UP (details 中注明影响面:限流与配额 fail-open、黑名单可能失效),以免 Redis 抖动导致副本被误摘。
指标端点¶
应用指标¶
获取 Prometheus 格式的指标:
响应:
# HELP jvm_memory_used_bytes 已使用内存量
# TYPE jvm_memory_used_bytes gauge
jvm_memory_used_bytes{area="heap",id="PS Eden Space",} 2.38026752E8
jvm_memory_used_bytes{area="heap",id="PS Survivor Space",} 1048576.0
jvm_memory_used_bytes{area="heap",id="PS Old Gen",} 4.2991616E7
# HELP jairouter_requests_total 请求总数
# TYPE jairouter_requests_total counter
jairouter_requests_total{service="chat",method="POST",status="200",} 1247.0
jairouter_requests_total{service="chat",method="POST",status="500",} 23.0
jairouter_requests_total{service="chat",method="POST",status="200",} 1156.0
jairouter_requests_total{service="chat",method="POST",status="500",} 18.0
# HELP jairouter_request_duration_seconds 请求持续时间(秒)
# TYPE jairouter_request_duration_seconds histogram
jairouter_request_duration_seconds_bucket{service="chat",method="POST",le="0.1",} 234.0
jairouter_request_duration_seconds_bucket{service="chat",method="POST",le="0.5",} 892.0
jairouter_request_duration_seconds_bucket{service="chat",method="POST",le="1.0",} 1156.0
jairouter_request_duration_seconds_bucket{service="chat",method="POST",le="+Inf",} 1270.0
# HELP jairouter_circuit_breaker_state 熔断器状态 (0=关闭, 1=打开, 2=半开)
# TYPE jairouter_circuit_breaker_state gauge
jairouter_circuit_breaker_state{service="chat",method="POST",} 0.0
jairouter_circuit_breaker_state{service="chat",method="POST",} 0.0
# HELP jairouter_rate_limit_remaining 限流剩余请求数
# TYPE jairouter_rate_limit_remaining gauge
jairouter_rate_limit_remaining{service="chat",client_ip="192.168.1.100",} 45.0
jairouter_rate_limit_remaining{service="chat",client_ip="192.168.1.101",} 38.0
指标摘要¶
获取人类可读的指标摘要:
🔑 这些运维端点需要管理员凭据:下列 /actuator/** 调用走正常认证链 —— 只有 /actuator/health(含
liveness/readiness子路径)、/actuator/info、/actuator/prometheus允许匿名(供 k8s 探针与 Prometheus 抓取),其余都需要 ADMIN 角色。不带凭据会得到401 AUTH_MISSING。 (修复前即使带了 ADMIN JWT 也会 401:认证链被整段排除,与hasRole("ADMIN")互相抵消,见 issue #340。)取 JWT 与调用示例(本机实测通过):
响应:
{
"names": [
"jvm.memory.used",
"jvm.memory.max",
"jvm.gc.pause",
"http.server.requests",
"jairouter_requests_total",
"jairouter_request_duration_seconds",
"jairouter_circuit_breaker_state",
"jairouter_rate_limit_remaining",
"jairouter_loadbalancer_selections_total"
]
}
特定指标详情¶
获取特定指标的详细信息:
响应:
{
"name": "jairouter_requests_total",
"description": "模型路由器处理的请求总数",
"baseUnit": null,
"measurements": [
{
"statistic": "COUNT",
"value": 2647.0
}
],
"availableTags": [
{
"tag": "service",
"values": ["chat", "embedding", "rerank", "tts", "stt", "imgGen", "imgEdit"]
},
{
"tag": "method",
"values": ["POST", "GET"]
},
{
"tag": "status",
"values": ["200", "400", "500"]
}
]
}
系统信息¶
应用信息¶
获取应用程序信息:
响应:
{
"app": {
"name": "JAiRouter",
"version": "3.2.2",
"description": "AI 模型服务路由器和负载均衡器"
},
"build": {
"version": "3.2.2",
"artifact": "model-router",
"name": "model-router",
"group": "org.unreal",
"time": "2025-08-19T08:15:30.123Z"
},
"git": {
"branch": "main",
"commit": {
"id": "3418d3f6",
"time": "2025-08-19T08:00:00Z"
}
},
"java": {
"version": "17.0.8",
"vendor": "Eclipse Adoptium"
}
}
⚠️
build/git段需要 pom 里启用build-info目标(当前pom.xml未配置), 默认的/actuator/info不会返回这两段;上面是示意输出。当前工程版本为 3.2.2。
环境信息¶
获取环境和配置详情:
⚠️
env不在默认暴露清单内(config/base/monitoring-base.yml:60只暴露 health / info / metrics / prometheus / jairouter-metrics / error-tracking;prod 见application-prod.yml:40)。 需要它时先把env加进management.endpoints.web.exposure.include。
响应:
{
"activeProfiles": ["default"],
"propertySources": [
{
"name": "server.ports",
"properties": {
"local.server.port": {
"value": 8080
}
}
},
{
"name": "applicationConfig: [classpath:/application.yml]",
"properties": {
"model-router.load-balancer.default-strategy": {
"value": "ROUND_ROBIN"
},
"model-router.rate-limit.default-algorithm": {
"value": "TOKEN_BUCKET"
},
"model-router.circuit-breaker.failure-threshold": {
"value": 5
}
}
}
]
}
⚠️ 上面是示意输出:本项目的配置键全部在
jairouter.*前缀下, 不存在model-router.*键(全仓src/main/resources无匹配)。
自定义监控端点¶
系统健康状态¶
获取系统整体健康状态:
监控配置¶
获取当前监控配置:
热改基础配置(写操作只改内存,重启后回到配置文件;每次成功变更写一条 MONITORING_CONFIG_CHANGED 审计):
PUT /api/monitoring/config/enabled
PUT /api/monitoring/config/prefix
PUT /api/monitoring/config/collection-interval
PUT /api/monitoring/config/categories
PUT /api/monitoring/config/sampling
PUT /api/monitoring/config/performance
sampling六项取值为 0~1(请求 / 后端 / 基础设施 / 链路 / 链路处理 / 链路分析);performance要求batchSize ≥ 1且bufferSize ≥ batchSize,越界返回 400。 这些端点需要monitoring:config:write(默认授 ADMIN 与 OPERATOR),不建议用/actuator/metrics/*替代:后者只对 ADMIN 开放;取值校验两边共用(见下节),但它不发配置变更事件、 也不写审计。
应急操作执行前的影响面预览(只读,不发审计):
action 取值:clear-cache / reset-errors / force-recovery / breaker-open / breaker-close。 响应的 impact 字段按动作不同:清缓存给出条目数与键名样例,错误重置给出键数、错误总数与 top 键, 强制恢复给出当前降级级别、采样率与自动模式,熔断开合给出状态、失败率、失败数与请求数。明细最多返回 20 条、总数单独给出。该端点需要 monitoring:config:read(默认授 ADMIN 与 OPERATOR)—— 页面可见与 能否改配置是两件事,写操作仍要求 monitoring:config:write。
内部运维接口(/actuator/metrics/*)¶
MetricsManagementController 在 /actuator/metrics 下另有一套配置与应急端点。整族由 SecurityConfiguration 的 hasRole('ADMIN') 保护,是留给运维做 break-glass 排障的旁路,控制台不消费它:
GET /actuator/metrics/status
GET /actuator/metrics/performance
GET /actuator/metrics/memory
GET /actuator/metrics/circuit-breaker
GET /actuator/metrics/sampling
POST /actuator/metrics/sampling # 已标注 @Deprecated
GET /actuator/metrics/performance-config
POST /actuator/metrics/performance-config # 已标注 @Deprecated
POST /actuator/metrics/memory/cleanup
POST /actuator/metrics/memory/clear-cache
POST /actuator/metrics/metrics-pipeline/circuit-breaker/{action}
POST /actuator/metrics/circuit-breaker/{action}
GET /actuator/metrics/error-handler
POST /actuator/metrics/error-handler/reset
GET /actuator/metrics/degradation
POST /actuator/metrics/degradation/level
POST /actuator/metrics/degradation/auto-mode
POST /actuator/metrics/degradation/force-recovery
其中 POST /sampling 与 POST /performance-config 与 PUT /api/monitoring/config/* 功能重叠: 取值校验共用(采样率 0~1、batchSize ≥ 1 且 bufferSize ≥ batchSize,越界同样返回 400), 差别在它们直接改内存里的配置对象 —— 不发配置变更事件、不写 MONITORING_CONFIG_CHANGED 审计。 常规运维与控制台请用 /api/monitoring/config/*。
前缀重叠提醒:
/actuator/metrics/sampling与内置的/actuator/metrics/{metricName}同前缀。 生产默认只暴露health,info,prometheus,threaddump(见application-prod.yml), 因此这两个自定义写端点通常只在 dev 可用,不要把它们当作生产热改入口。
指标处理链路熔断器统计¶
获取指标处理链路熔断器(MetricsCircuitBreaker)的统计信息:
作用域:该熔断器保护的是监控指标处理链路(指标异步处理),与实例路由使用的
CircuitBreakerManager不是同一个对象。这里的统计与开关都不会改变任何实例的路由熔断状态, 也不会让实例被熔断。旧路径
GET /api/monitoring/circuit-breaker/stats为兼容别名(代码中已标记@Deprecated), 与新路径共用同一实现,行为完全一致。
降级状态¶
获取服务降级状态:
错误统计¶
获取错误统计信息:
缓存统计¶
获取缓存统计信息:
注意: 以上端点为 JAiRouter(当前版本 3.2.2)实际提供的自定义监控端点,逐条对应
MonitoringController.java:65,226,240,268,309,390,426。更多端点请参考 管理 API 文档。
监控集成¶
Prometheus 集成¶
JAiRouter 在 /actuator/prometheus 端点暴露 Prometheus 格式的指标。配置 Prometheus 抓取这些指标:
# prometheus.yml
scrape_configs:
- job_name: 'jairouter'
static_configs:
- targets: ['localhost:8080']
metrics_path: '/actuator/prometheus'
scrape_interval: 15s
Grafana 仪表板¶
导入 JAiRouter Grafana 仪表板进行可视化:
- 仪表板 ID: 即将推出
- 指标: 请求速率、响应时间、错误率、熔断器状态
- 告警: 高错误率、熔断器打开、实例宕机
健康检查集成¶
配置外部监控工具检查 JAiRouter 健康状态:
# 简单健康检查(进程存活)
curl -f http://localhost:8080/actuator/health/liveness || exit 1
# 特定组件的详细健康检查
curl -f http://localhost:8080/actuator/health/tracing || exit 1
监控最佳实践¶
关键监控指标¶
- 请求指标
- 请求速率(请求/秒)
- 响应时间(p50、p95、p99)
错误率(百分比)
实例健康
- 实例可用性
- 健康检查响应时间
熔断器状态
资源使用
- JVM 内存使用
- CPU 利用率
磁盘空间
限流
- 限流利用率
- 被拒绝的请求
- 客户端特定限制
告警规则¶
为关键条件设置告警:
# Prometheus 告警规则
groups:
- name: jairouter
rules:
- alert: 高错误率
expr: rate(jairouter_requests_total{status="500"}[5m]) / rate(jairouter_requests_total[5m]) > 0.1
for: 2m
labels:
severity: warning
annotations:
summary: "检测到高错误率"
- alert: 熔断器打开
expr: jairouter_circuit_breaker_state > 0
for: 1m
labels:
severity: critical
annotations:
summary: "熔断器已打开"
- alert: 实例宕机
expr: up{job="jairouter"} == 0
for: 1m
labels:
severity: critical
annotations:
summary: "JAiRouter 实例已宕机"
日志监控¶
监控应用日志以发现:
- 错误模式
- 性能问题
- 配置变更
- 安全事件
故障排除¶
常见问题¶
- 高响应时间
- 检查实例健康状态
- 查看负载均衡器分布
监控资源使用
熔断器打开
- 检查实例连接性
- 查看错误日志
验证实例配置
超出限流限制
- 查看限流配置
- 检查客户端请求模式
- 考虑增加限制
调试端点¶
启用调试日志以获得详细监控:
访问调试信息:
⚠️
loggers不在默认暴露清单内,需先加进management.endpoints.web.exposure.include才能访问。
安全考虑¶
监控端点安全¶
在生产环境中保护监控端点:
# application.yml
management:
endpoints:
web:
exposure:
include: health,info,prometheus
endpoint:
health:
show-details: when-authorized
security:
enabled: true
敏感信息¶
避免在指标中暴露敏感数据:
- API 密钥
- 内部 URL
- 用户信息
- 配置机密
下一步¶
- 管理 API - 配置管理
- 统一 API - OpenAI 兼容端点
- OpenAPI 规范 - 交互式 API 文档
只读监控面:37 个未在前端调用、也未文档化的管理端点¶
这些端点没有前端入口,此前也没有文档(#454 的对账结果)。按维护者裁定,它们作为只读监控 / 运维诊断面保留,在此补齐说明。
授权来源说明:这些端点没有方法级
@PreAuthorize,鉴权由/api/**的PermissionAuthorizationManager按PermissionRuleRegistry的 URL 规则统一裁决。下表的权限码就是当前实际生效的规则,不是设计意图。
动态指标注册(MetricRegistrationController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
DELETE | /api/monitoring/metrics/batch | monitoring:metrics:write |
GET | /api/monitoring/metrics/category/{} | monitoring:metrics:read |
POST | /api/monitoring/metrics/cleanup | monitoring:metrics:write |
GET | /api/monitoring/metrics/exists/{} | monitoring:metrics:read |
GET | /api/monitoring/metrics/list | monitoring:metrics:read |
GET | /api/monitoring/metrics/metadata | monitoring:metrics:read |
GET | /api/monitoring/metrics/metadata/{} | monitoring:metrics:read |
PUT | /api/monitoring/metrics/metadata/{} | monitoring:metrics:write |
POST | /api/monitoring/metrics/register | monitoring:metrics:write |
POST | /api/monitoring/metrics/register/batch | monitoring:metrics:write |
GET | /api/monitoring/metrics/search | monitoring:metrics:read |
GET | /api/monitoring/metrics/statistics | monitoring:metrics:read |
POST | /api/monitoring/metrics/validate | monitoring:metrics:write |
DELETE | /api/monitoring/metrics/{} | monitoring:metrics:write |
PUT | /api/monitoring/metrics/{}/configuration | monitoring:metrics:write |
调用历史(ApiCallHistoryController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
DELETE | /api/call-history/cleanup | 未登记写规则 ⇒ 默认拒绝(RbacUnmatchedPolicy DENY_ALL,仅 ADMIN) |
GET | /api/call-history/count | callhistory:read |
GET | /api/call-history/errors | callhistory:read |
GET | /api/call-history/recent | callhistory:read |
POST | /api/call-history/record | **摄取面豁免**(RbacExemptEndpoints,#454) |
GET | /api/call-history/trace/{} | callhistory:read |
GET /api/call-history/** 的响应正文按主体裁剪:持 callhistory:full-content 时详情会解密 FULL 级别记录的正文并记一次 FULL_CONTENT_ACCESS 审计,否则(含只持 callhistory:read 的运维)返回的记录里加密字段一律为 null,只保留摘要列。
路由监控(RoutingMonitorController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
PUT | /api/v1/routing-monitor/config | lb:config:write |
DELETE | /api/v1/routing-monitor/history/{} | lb:config:write |
GET | /api/v1/routing-monitor/history/{} | monitoring:routing:read |
GET | /api/v1/routing-monitor/stats/{} | monitoring:routing:read |
熔断历史(CircuitBreakerConfigController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/config/circuit-breaker/history/instance | config:circuitbreaker:read |
GET | /api/config/circuit-breaker/history/service-type | config:circuitbreaker:read |
GET | /api/config/circuit-breaker/history/time-range | config:circuitbreaker:read |
适配器模板(AdapterTemplateController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/config/adapter/templates/{} | config:adapters:read |
POST | /api/config/adapter/templates/{}/create | config:adapters:write |
异常管理(ExceptionManagementController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/exceptions/dashboard | monitoring:exceptions:read |
GET | /api/exceptions/recent/{} | monitoring:exceptions:read |
慢查询分析(SlowQueryAnalysisController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/monitoring/slow-queries/stats/{} | monitoring:slowquery:read |
GET | /api/monitoring/slow-queries/trends | monitoring:slowquery:read |
DELETE | /api/monitoring/slow-queries/stats | monitoring:slowquery:write(#468 新增;修前该写操作无规则,靠默认 DENY_ALL 兜住) |
健康状态 SSE(HealthStatusSseController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/health-status/stream | 已认证即可(/api/health-status/** → authenticated()) |
该 SSE 通道每 5 秒推送一次实例健康快照。快照在所有连接之间共享同一次计算(
#866起), 打开多个控制台标签页不会再成倍放大数据库查询;推送间隔可用jairouter.health-status.stream-interval-ms(默认5000,下限100)调整。
限流监控(RateLimitMonitorController)¶
| 方法 | 路径 | 生效的权限码 |
|---|---|---|
GET | /api/rate-limiter/status | rl:monitoring:read |
状态持久化(StatePersistenceManagementController)¶
历史:
POST /api/state-persistence/test/save-circuit-breaker/{}是测试夹具端点(手写死值state=OPEN/failureCount=5直接写进持久层),#483先把它隔离到@Profile("!prod"), 随后已移除 —— 主代码不该保留造数端点;该链路(真实状态 → 持久层 → 启动恢复)改由测试包内CircuitBreakerStatePersistenceAdapterTest覆盖。
两个需要注意的口径¶
/api/monitoring/metrics/**的写操作已有显式规则 —— 读monitoring:metrics:read、写monitoring:metrics:write(#454补)。此前写操作没有规则、只靠RbacUnmatchedPolicy的默认DENY_ALL(仅ROLE_ADMIN)兜住,属「碰巧安全」;现在「谁能注册指标」是一条可授的权限,OPERATOR模板按「所有:read/:write码」自动获得它。/api/call-history/**只登记了 GET 规则(callhistory:read),写面靠默认拒绝与豁免 ——POST /record在RbacExemptEndpoints摄取面豁免清单上(仅要求认证);DELETE /cleanup没有登记写规则,因此落入DENY_ALL默认姿态(仅 ADMIN 可用),不是被callhistory:read放行。#514修的是「callhistory:view曾经连读写删一起放行」这个缺陷,现状已由「GET 一条规则 + 写面默认拒绝 + 摄取豁免」取代。