主题
监控运维 PRD
文档信息
| 项目 | 内容 |
|---|---|
| 产品名称 | PMForge - 监控运维 |
| 文档版本 | v2.0 |
| 创建日期 | 2026-09-17 |
| 最后更新 | 2026-09-24 |
| 文档状态 | 评审中 |
| 优先级 | P1 |
| 所属模块 | 基础设施层 |
一、功能概述
1.1 功能定位
如果把 PMForge 比作一辆行驶中的汽车，监控运维模块就是驾驶员面前的仪表盘——它让你随时知道发动机转速、油量、水温是否正常，一旦有异常指示灯亮起，你能第一时间发现问题并处理。
监控运维为系统提供全方位的可观测性能力，涵盖五大子模块：
- API 访问日志监控：记录每一次接口调用的完整信息，帮助发现慢接口、分析调用趋势
- API 错误日志监控：捕获每一次接口异常，提供完整的错误堆栈，并支持"发现→处理→关闭"的闭环管理
- Redis 监控：实时查看缓存服务器的运行状态、内存使用和命令调用情况
- 应用监控（JVM）：实时查看 Java 应用的内存、线程、垃圾回收等运行时指标
- 服务健康检查：一键检查应用自身及其依赖组件（数据库、缓存、消息队列等）是否正常连通
与日志审计模块的关系： 日志审计模块（01-08）侧重于"谁在什么时候做了什么"的行为记录与安全审计；本模块侧重于"系统跑得怎么样"的运行时监控与运维诊断。两者在 API 访问日志和 API 错误日志上共享同一张数据表，但分析视角不同——日志审计看"行为"，监控运维看"性能"。
1.2 目标用户
| 用户类型 | 核心诉求 | 典型使用频率 |
|---|---|---|
| 运维工程师小吴 | 实时掌握系统健康状态，第一时间发现和处理故障，确保服务不中断 | 每天多次 |
| 后端开发小李 | 排查接口异常原因，定位性能瓶颈，快速修复 Bug | 每天 1-3 次 |
| 架构师老王 | 评估系统整体性能趋势，为容量规划和架构优化提供数据支撑 | 每周 1-2 次 |
| 技术经理老张 | 查看系统运行概览和 SLA 指标，协调团队处理线上问题 | 每天 1 次 |
1.3 业务价值
- 降低故障发现时间（MTTD）：通过实时监控和异常告警，将故障发现时间从"用户投诉后才知道"缩短到"分钟级自动发现"
- 加速问题定位（MTTR）：通过完整的异常堆栈、链路追踪编号、请求参数等信息，开发人员无需复现即可定位问题根因
- 持续优化性能：通过慢接口排行、Redis 命令统计、JVM GC 分析等数据，持续发现性能瓶颈并优化
- 闭环管理异常：每个 API 错误都有"未处理→已处理/已忽略"的生命周期，确保没有异常被遗漏
- 保障服务可用性：通过健康检查确认所有依赖组件正常，避免"应用正常但数据库挂了"的隐性故障
1.4 功能范围
| 功能分类 | 后台管理端 | 优先级 | 说明 |
|---|---|---|---|
| API 访问日志监控 | ✅ | P0 | 接口访问记录、性能分析、慢接口统计、导出 |
| API 错误日志监控 | ✅ | P0 | 异常记录、处理流程、错误统计、导出 |
| Redis 监控 | ✅ | P0 | Redis 运行信息、内存使用、命令统计 |
| 应用监控（JVM） | ✅ | P1 | JVM 参数、内存分布、线程状态、GC 统计 |
| 服务健康检查 | ✅ | P1 | 服务实例状态、依赖组件连通性 |
| 监控概览仪表盘 | ✅（规划中） | P2 | 汇总展示关键监控指标 |
二、用户场景
2.1 用户角色
| 角色 | 描述 | 核心诉求 |
|---|---|---|
| 运维工程师 | 一线技术保障人员 | 实时监控系统状态，快速发现和处理故障，确保服务稳定运行 |
| 后端开发 | 研发工程师 | 排查接口异常原因，定位性能瓶颈，快速修复 Bug |
| 架构师 | 技术架构负责人 | 分析系统整体运行趋势，评估容量规划，发现架构隐患 |
| 技术经理 | 技术团队管理者 | 查看系统健康概览，了解 SLA 指标，协调问题处理 |
2.2 使用场景
场景1：后端开发小李排查慢接口
- 用户：后端开发小李
- 背景：用户反馈"加载课程列表特别慢"
- 场景：小李收到慢接口告警通知 → 登录后台进入"API 访问日志"页面 → 在"执行时长"筛选项中输入
>=1000（毫秒）→ 列表按执行时长倒序展示，第一个就是课程列表接口，平均耗时 3200ms → 点击"查看详情"，看到请求参数中categoryId=5且pageNo=1→ 分析响应结果发现返回了 5000 条数据 → 定位到是缺少分页限制导致的全表扫描 → 提交优化需求，添加分页限制和索引优化 - 期望：支持按响应时间筛选、展示慢接口排行、可查看接口完整请求参数和响应结果
场景2：运维工程师小吴处理 API 异常
- 用户：运维工程师小吴
- 背景：监控系统显示过去 1 小时内错误数激增
- 场景：小吴进入"API 错误日志"页面 → 筛选处理状态为"未处理" → 看到 15 条未处理异常，其中 12 条是同一个
NullPointerException→ 点击查看详情，看到异常堆栈指向OrderService.createOrder第 87 行 → 通过链路追踪编号abc123跳转到对应的访问日志，发现是某个订单的会员信息为 null → 将状态标记为"已处理"，系统自动记录处理人"小吴"和处理时间 → 通知后端开发修复 - 期望：异常信息完整、支持处理状态流转、可通过链路追踪编号关联访问日志
场景3：运维工程师小吴监控 Redis 健康
- 用户：运维工程师小吴
- 背景：日常巡检，检查缓存服务是否正常
- 场景：小吴进入"Redis 监控"页面 → 查看基本信息：Redis 6.2.10，已运行 45 天，连接数 32 → 检查内存使用：已用 2.1GB / 最大 4GB，使用率 52.5%，状态正常 → 查看命令统计：
GET命令调用最多（占 45%），其次是SET（占 20%）→ 一切正常，完成巡检 - 期望：展示 Redis 完整运行信息、内存使用可视化、命令调用 TOP 排行
场景4：运维工程师小吴进行 JVM 健康诊断
- 用户：运维工程师小吴
- 背景：收到 JVM 堆内存使用率超过 85% 的告警
- 场景：小吴进入"应用监控"页面 → 查看堆内存：已使用 3.4GB / 最大 4GB，使用率 85% → 查看 GC 统计：最近 1 小时内 Full GC 发生了 3 次，每次耗时约 800ms → 查看线程信息：当前线程 280 个，其中 BLOCKED 状态 5 个 → 判断可能是内存泄漏，需要开发介入排查 → 截图保存当前状态作为排查依据
- 期望：JVM 参数一目了然、GC 统计清晰、线程状态实时可查、异常指标高亮提示
场景5：运维工程师小吴做服务上线前健康检查
- 用户：运维工程师小吴
- 背景：新版本 v2.3.0 刚部署到生产环境
- 场景：小吴进入"服务健康检查"页面 → 查看服务实例：pmforge-server 2 个实例均为 UP 状态 → 查看依赖组件：数据库（UP）、Redis（UP）、消息队列（UP）、对象存储（UP）→ 所有组件健康 → 确认可以开放流量，新版本上线成功
- 期望：一键检查所有依赖、状态清晰直观、异常依赖高亮提示
场景6：技术经理老张查看每日运行概览
- 用户：技术经理老张
- 背景：每日早晨了解系统昨日运行情况
- 场景：老张进入监控概览仪表盘 → 查看 API 概览：昨日调用量 52 万次，平均响应时间 120ms，错误率 0.02% → 查看错误概览：昨日新增错误 104 条，未处理 12 条 → 查看资源概览：Redis 内存使用率 52%，JVM 堆内存使用率 65% → 查看服务健康：所有服务均为 UP → 对当日运行状况心中有数
- 期望：概览信息一目了然、关键指标突出、异常有明确提示
2.3 用户故事与验收标准
| 编号 | 用户故事 | 验收标准 | 优先级 |
|---|---|---|---|
| US-01 | 作为运维人员，我希望查看 API 访问日志分页列表并按执行时长筛选 | ① 支持按用户编号、应用名、请求地址、执行时长、结果码、时间范围筛选 ② 执行时长筛选支持">=N 毫秒"的模糊匹配 ③ 列表默认按创建时间倒序 ④ 分页查询响应时间 < 1s | P0 |
| US-02 | 作为运维人员，我希望查看 API 访问日志详情 | ① 展示完整的请求参数（Query + Body） ② 展示响应结果 ③ 展示执行时长（精确到毫秒） ④ 展示链路追踪编号，可关联错误日志 | P0 |
| US-03 | 作为运维人员，我希望导出 API 访问日志 | ① 按当前筛选条件导出 Excel ② 单次导出不超过 10 万条 ③ 导出响应时间 < 30s | P1 |
| US-04 | 作为运维人员，我希望查看 API 错误日志并按处理状态筛选 | ① 支持按处理状态（未处理/已处理/已忽略）筛选 ② 列表展示异常名称和异常消息摘要 ③ 未处理错误以醒目颜色标识 | P0 |
| US-05 | 作为运维人员，我希望查看错误日志的完整异常信息 | ① 展示异常类全名和异常消息 ② 展示完整异常堆栈轨迹 ③ 展示异常发生的类名、方法名、行号 ④ 展示请求参数 | P0 |
| US-06 | 作为运维人员，我希望更新错误日志的处理状态 | ① 支持标记为"已处理"或"已忽略" ② 自动记录处理人和处理时间 ③ 已处理/已忽略不可逆回"未处理" ④ 操作记录到操作日志 | P1 |
| US-07 | 作为运维人员，我希望导出 API 错误日志 | ① 按当前筛选条件导出 Excel ② 包含异常堆栈等完整信息 | P1 |
| US-08 | 作为运维人员，我希望查看 Redis 运行信息 | ① 展示 Redis 版本、运行模式、运行天数、连接数 ② 展示内存使用量和最大限制 ③ 展示命令调用 TOP 10 排行 ④ 数据为实时查询，响应时间 < 2s | P0 |
| US-09 | 作为运维人员，我希望分析 Redis Key 分布 | ① 展示当前 Key 总数 ② 展示各数据库 Key 分布 | P2 |
| US-10 | 作为运维人员，我希望查看 JVM 运行时信息 | ① 展示 JVM 版本、供应商、启动参数 ② 展示堆内存各区域使用情况 ③ 展示线程状态分布 ④ 展示 GC 收集器统计 ⑤ 堆内存使用率 > 85% 时高亮告警 | P1 |
| US-11 | 作为运维人员，我希望检查服务健康状态 | ① 展示各服务实例的健康状态 ② 展示依赖组件（数据库、Redis 等）连通性 ③ 异常组件以红色高亮 ④ 响应时间 < 5s | P1 |
| US-12 | 作为技术经理，我希望查看监控概览仪表盘 | ① 展示 API 调用量、错误率、平均响应时间 ② 展示 Redis/JVM 关键指标 ③ 展示服务健康状态一览 | P2 |
三、功能需求
3.1 后台管理端
3.1.1 功能清单
| 功能 | 优先级 | 说明 |
|---|---|---|
| API 访问日志分页查询 | P0 | 查看接口访问记录列表，支持多维度筛选 |
| API 访问日志详情 | P0 | 查看请求参数、响应结果、执行时长等完整信息 |
| API 访问日志导出 | P1 | 按筛选条件导出 Excel |
| 慢接口统计 | P2 | 按接口维度汇总平均耗时、最大耗时、调用次数 |
| API 错误日志分页查询 | P0 | 查看 API 异常记录列表，支持按处理状态筛选 |
| API 错误日志详情 | P0 | 查看异常堆栈、异常定位信息 |
| API 错误日志处理状态更新 | P1 | 标记已处理/已忽略，记录处理人 |
| API 错误日志导出 | P1 | 按筛选条件导出 Excel |
| Redis 监控信息查看 | P0 | 查看 Redis 基本信息、内存使用、命令统计 |
| Redis Key 分析 | P2 | 分析 Key 数量、类型分布 |
| JVM 应用监控 | P1 | 查看 JVM 参数、内存分布、线程状态、GC 统计 |
| 服务健康检查 | P1 | 查看服务实例状态、依赖组件连通性 |
| 监控概览仪表盘 | P2 | 汇总展示关键监控指标（规划中） |
3.2 API 访问日志监控
3.2.1 页面描述
详情弹窗：
3.2.2 业务规则
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 每次 API 请求自动记录访问日志，通过全局拦截器实现，业务代码无需手动调用 | 对业务零侵入，确保所有接口都被监控到 |
| R-02 | 记录完整的请求信息：请求方法、URL、参数（Query + Body）、响应结果、执行时长 | 排障时需要完整上下文，仅有 URL 不够定位问题 |
| R-03 | 请求参数最大长度 8000 字符，超出部分截断 | 防止超大请求体（如文件上传）撑爆数据库，同时保留足够的排障信息 |
| R-04 | 响应结果消息最大长度 512 字符，超出部分截断 | 同上，仅保留结果摘要用于快速判断 |
| R-05 | 执行时长精确到毫秒 | 毫秒级精度是性能分析和慢接口定位的基础 |
| R-06 | 应用名读取 spring.application.name 配置，用于区分不同微服务的日志来源 | 多服务部署时能快速定位问题出在哪个服务 |
| R-07 | 操作分类：0-其它、1-查询、2-新增、3-修改、4-删除、5-导出、6-导入 | 按操作类型统计可以了解系统的读写比例 |
| R-08 | 通过链路追踪编号（traceId）可串联访问日志、错误日志和操作日志 | 全链路排障的关键，一次请求的所有日志通过 traceId 串联 |
| R-09 | 日志默认保留 7 天，可配置保留策略 | 访问日志数据量大（日均 50 万条），需要在排障需求和存储成本之间平衡 |
| R-10 | 日志记录采用异步写入，写入延迟 < 100ms，对业务接口性能影响 < 5% | 监控不能拖慢业务，这是监控系统的底线要求 |
3.2.3 数据字段
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 日志编号 |
| traceId | String | 否 | 链路追踪编号，用于串联同一次请求的所有日志 |
| userId | Long | 否 | 用户编号（未登录的公开接口为空） |
| userType | Integer | 否 | 用户类型（1-会员、2-管理员） |
| applicationName | String | 是 | 应用名（微服务名称） |
| requestMethod | String | 是 | 请求方法（GET/POST/PUT/DELETE） |
| requestUrl | String | 是 | 请求地址 |
| requestParams | String | 否 | 请求参数（Query + Body，最大 8000 字符） |
| responseBody | String | 否 | 响应结果（截断后最大 512 字符） |
| userIp | String | 是 | 用户 IP 地址 |
| userAgent | String | 否 | 浏览器 UserAgent |
| operateModule | String | 否 | 操作模块名称 |
| operateName | String | 否 | 操作名称 |
| operateType | Integer | 否 | 操作分类（OperateTypeEnum） |
| beginTime | DateTime | 是 | 开始请求时间 |
| endTime | DateTime | 是 | 结束请求时间 |
| duration | Integer | 是 | 执行时长（毫秒） |
| resultCode | Integer | 是 | 结果码（0 表示成功） |
| resultMsg | String | 否 | 结果提示（最大 512 字符） |
| createTime | DateTime | 是 | 创建时间 |
3.2.4 接口设计
| 接口名称 | 请求方式 | 接口路径 | 权限标识 | 说明 |
|---|---|---|---|---|
| 获取 API 访问日志详情 | GET | /admin-api/infra/api-access-log/get | infra:api-access-log:query | 获取单条访问日志 |
| 获取 API 访问日志分页 | GET | /admin-api/infra/api-access-log/page | infra:api-access-log:query | 分页查询访问日志 |
| 导出 API 访问日志 Excel | GET | /admin-api/infra/api-access-log/export-excel | infra:api-access-log:export | 按筛选条件导出 |
分页查询请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 否 | 用户编号 |
| userType | Integer | 否 | 用户类型 |
| applicationName | String | 否 | 应用名（模糊匹配） |
| requestUrl | String | 否 | 请求地址（模糊匹配） |
| duration | Integer | 否 | 执行时长下限（毫秒），筛选 >= 该值的记录 |
| resultCode | Integer | 否 | 结果码 |
| beginTime | DateTime[] | 否 | 请求时间范围 |
| pageNo | Integer | 是 | 页码（从 1 开始） |
| pageSize | Integer | 是 | 每页条数（默认 10） |
3.3 API 错误日志监控
3.3.1 页面描述
详情弹窗（含处理操作）：
3.3.2 错误处理状态机
3.3.3 业务规则
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | API 请求发生异常时，由全局异常处理器自动捕获并记录错误日志 | 统一捕获，避免遗漏；业务代码无需关心日志记录 |
| R-02 | 记录完整的异常信息：异常类全名、异常消息、根异常消息、完整堆栈、异常发生的类/方法/行号 | 开发只需看日志就能定位问题，无需复现 |
| R-03 | 请求参数最大长度 8000 字符，超出部分截断 | 与访问日志保持一致的截断策略 |
| R-04 | 处理状态枚举：0-未处理（INIT）、1-已处理（DONE）、2-已忽略（IGNORE） | 三态设计覆盖所有场景：需要修复的标记"已处理"，不需要修复的（如预期内的异常）标记"已忽略" |
| R-05 | 更新处理状态时自动记录处理人（当前登录用户 ID）和处理时间 | 明确责任人，便于追溯 |
| R-06 | 通过链路追踪编号（traceId）可关联对应的访问日志和操作日志 | 全链路排障 |
| R-07 | 错误日志默认保留 90 天，长于访问日志的 7 天 | 错误日志量小但价值高，需要更长的保留期用于历史问题排查 |
| R-08 | 状态只能单向流转：未处理 → 已处理/已忽略，不可逆 | 防止已处理的问题被误操作回未处理状态，保证处理流程的严肃性 |
3.3.4 数据字段
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 日志编号 |
| traceId | String | 否 | 链路追踪编号 |
| userId | Long | 否 | 用户编号 |
| userType | Integer | 否 | 用户类型 |
| applicationName | String | 是 | 应用名（微服务名称） |
| requestMethod | String | 是 | 请求方法 |
| requestUrl | String | 是 | 请求地址 |
| requestParams | String | 否 | 请求参数（最大 8000 字符） |
| userIp | String | 是 | 用户 IP |
| userAgent | String | 否 | 浏览器 UserAgent |
| exceptionTime | DateTime | 是 | 异常发生时间 |
| exceptionName | String | 是 | 异常类全名（如 NullPointerException） |
| exceptionMessage | String | 否 | 异常消息 |
| exceptionRootCauseMessage | String | 否 | 根异常消息（包装异常时取最内层原因） |
| exceptionStackTrace | String | 否 | 异常堆栈轨迹（完整） |
| exceptionClassName | String | 否 | 异常发生的类全名 |
| exceptionFileName | String | 否 | 异常发生的类文件名 |
| exceptionMethodName | String | 否 | 异常发生的方法名 |
| exceptionLineNumber | Integer | 否 | 异常发生的方法行号 |
| processStatus | Integer | 是 | 处理状态（0-未处理、1-已处理、2-已忽略） |
| processTime | DateTime | 否 | 处理时间 |
| processUserId | Long | 否 | 处理用户编号 |
| createTime | DateTime | 是 | 创建时间 |
3.3.5 接口设计
| 接口名称 | 请求方式 | 接口路径 | 权限标识 | 说明 |
|---|---|---|---|---|
| 获取 API 错误日志详情 | GET | /admin-api/infra/api-error-log/get | infra:api-error-log:query | 获取单条错误日志 |
| 获取 API 错误日志分页 | GET | /admin-api/infra/api-error-log/page | infra:api-error-log:query | 分页查询错误日志 |
| 更新错误日志处理状态 | PUT | /admin-api/infra/api-error-log/update-status | infra:api-error-log:update-status | 标记处理状态 |
| 导出 API 错误日志 Excel | GET | /admin-api/infra/api-error-log/export-excel | infra:api-error-log:export | 按筛选条件导出 |
分页查询请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 否 | 用户编号 |
| userType | Integer | 否 | 用户类型 |
| applicationName | String | 否 | 应用名（模糊匹配） |
| requestUrl | String | 否 | 请求地址（模糊匹配） |
| exceptionTime | DateTime[] | 否 | 异常发生时间范围 |
| processStatus | Integer | 否 | 处理状态（0-未处理、1-已处理、2-已忽略） |
| pageNo | Integer | 是 | 页码（从 1 开始） |
| pageSize | Integer | 是 | 每页条数（默认 10） |
更新处理状态请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 错误日志编号 |
| processStatus | Integer | 是 | 处理状态（1-已处理、2-已忽略） |
3.4 Redis 监控
3.4.1 页面描述
3.4.2 业务规则
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 通过 Redis INFO 命令获取服务器运行信息 | INFO 是 Redis 官方提供的标准信息查询方式，数据权威可靠 |
| R-02 | 通过 DBSIZE 命令获取当前数据库 Key 数量 | 快速了解缓存数据规模 |
| R-03 | 通过 INFO commandstats 获取各命令的调用次数和 CPU 耗时 | 发现高频命令和耗时命令，优化缓存使用策略 |
| R-04 | 命令统计结果按调用次数降序排列，默认展示 TOP 10 | 聚焦最关键的命令，避免信息过载 |
| R-05 | 监控数据为实时查询，不做持久化存储 | Redis 监控是"快照"式数据，历史趋势应交给专业监控系统（如 Prometheus） |
| R-06 | 内存使用率超过 80% 时在前端以警告色展示 | 内存用尽会导致 Redis 拒绝写入，需要提前预警 |
| R-07 | 内存碎片率 > 1.5 或 < 1.0 时提示可能存在内存碎片问题 | 碎片率异常意味着内存利用率低下，可能需要重启或调整配置 |
3.4.3 数据字段
Redis 监控响应数据结构：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| info | Properties | 是 | Redis INFO 命令返回的完整属性集 |
| dbSize | Long | 是 | 当前数据库 Key 数量 |
| commandStats | List<CommandStat> | 是 | 命令统计结果列表 |
CommandStat 子结构：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| command | String | 是 | Redis 命令名称（如 get、set、hget） |
| calls | Long | 是 | 该命令的累计调用次数 |
| usec | Long | 是 | 该命令的累计 CPU 耗时（微秒） |
Redis INFO 关键属性说明：
| 属性分组 | 关键属性 | 说明 |
|---|---|---|
| Server | redis_version, os, tcp_port, uptime_in_days | 版本、操作系统、端口、运行天数 |
| Clients | connected_clients, blocked_clients | 当前连接数、阻塞连接数 |
| Memory | used_memory, used_memory_human, used_memory_peak, maxmemory, mem_fragmentation_ratio | 内存使用详情 |
| Stats | total_connections_received, total_commands_processed, instantaneous_ops_per_sec | 连接/命令统计 |
| Keyspace | db0, db1, ... | 各数据库 Key 数量和过期 Key 数量 |
3.4.4 接口设计
| 接口名称 | 请求方式 | 接口路径 | 权限标识 | 说明 |
|---|---|---|---|---|
| 获取 Redis 监控信息 | GET | /admin-api/infra/redis/get-monitor-info | infra:redis:get-monitor-info | 获取 Redis 运行信息 |
返回结果：
| 字段名 | 类型 | 说明 |
|---|---|---|
| info | Object | Redis INFO 完整属性（键值对形式） |
| dbSize | Long | 当前数据库 Key 数量 |
| commandStats | List | 命令统计列表 |
| commandStats[].command | String | 命令名称 |
| commandStats[].calls | Long | 累计调用次数 |
| commandStats[].usec | Long | 累计 CPU 耗时（微秒） |
3.5 应用监控（JVM）
3.5.1 页面描述
3.5.2 业务规则
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 通过 Java JMX（Java Management Extensions）和 Runtime API 获取 JVM 运行时信息 | JMX 是 Java 标准的监控接口，无需额外依赖 |
| R-02 | 内存信息区分堆内存（Eden / Survivor / Old / Metaspace）各区域 | 不同区域的内存问题含义不同：Old Gen 满可能意味着内存泄漏，Eden 频繁回收是正常的 |
| R-03 | 线程信息包含各状态分布（RUNNABLE / BLOCKED / WAITING 等） | BLOCKED 线程过多意味着存在锁竞争，WAITING 过多可能有线程饥饿 |
| R-04 | GC 统计展示各收集器的收集次数和耗时 | Full GC 耗时过长会导致应用暂停（Stop The World），需要重点关注 |
| R-05 | 监控数据为实时查询，不做持久化存储 | 与 Redis 监控同理，历史趋势交给专业监控系统 |
| R-06 | 堆内存使用率超过 85% 时在前端以警告色展示 | 堆内存接近上限会频繁触发 Full GC，严重影响性能 |
| R-07 | 存在死锁线程时在前端以告警色高亮提示 | 死锁会导致相关线程永久阻塞，必须立即处理 |
3.5.3 数据字段
JVM 监控响应数据结构：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| JVM 基本信息 | |||
| jvmVersion | String | 是 | JVM 版本号 |
| jvmVendor | String | 是 | JVM 供应商 |
| jvmName | String | 是 | JVM 名称 |
| startTime | DateTime | 是 | JVM 启动时间 |
| uptime | Long | 是 | 运行时长（毫秒） |
| jvmArgs | String | 是 | JVM 启动参数 |
| 堆内存信息 | |||
| heapMemoryUsed | Long | 是 | 堆内存已使用（字节） |
| heapMemoryMax | Long | 是 | 堆内存最大值（字节） |
| heapMemoryCommitted | Long | 是 | 堆内存已分配（字节） |
| nonHeapMemoryUsed | Long | 是 | 非堆内存已使用（字节） |
| 内存池详情 | |||
| memoryPools | List<MemoryPool> | 是 | 各内存池详情 |
| memoryPools[].name | String | 是 | 内存池名称（如 Eden Space、Old Gen） |
| memoryPools[].type | String | 是 | 类型（Heap/Non-Heap） |
| memoryPools[].used | Long | 是 | 已使用（字节） |
| memoryPools[].max | Long | 否 | 最大值（字节） |
| 线程信息 | |||
| threadCount | Integer | 是 | 当前线程总数 |
| daemonThreadCount | Integer | 是 | 守护线程数 |
| peakThreadCount | Integer | 是 | 峰值线程数 |
| deadlockedThreads | List<Long> | 否 | 死锁线程 ID 列表（无死锁为空） |
| threadStateStats | Map<String, Integer> | 是 | 各状态线程数量统计 |
| GC 统计 | |||
| gcCollectors | List<GcCollector> | 是 | GC 收集器列表 |
| gcCollectors[].name | String | 是 | 收集器名称 |
| gcCollectors[].collectionCount | Long | 是 | 累计收集次数 |
| gcCollectors[].collectionTime | Long | 是 | 累计收集耗时（毫秒） |
3.5.4 接口设计
| 接口名称 | 请求方式 | 接口路径 | 权限标识 | 说明 |
|---|---|---|---|---|
| 获取 JVM 监控信息 | GET | /admin-api/infra/app-monitor/get-jvm-info | infra:app-monitor:get-jvm-info | 获取 JVM 运行时信息 |
3.6 服务健康检查
3.6.1 页面描述
3.6.2 业务规则
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 基于 Spring Boot Actuator 的 /actuator/health 端点获取服务健康信息 | Actuator 是 Spring Boot 官方提供的生产级监控能力，开箱即用 |
| R-02 | 健康状态枚举：UP（正常）、DOWN（异常）、OUT_OF_SERVICE（下线）、UNKNOWN（未知） | 四态覆盖所有可能的服务状态 |
| R-03 | 依赖检查包括：数据库、Redis、消息队列、对象存储、磁盘空间等 | 应用正常但依赖挂了场景很常见，需要独立检查每个依赖 |
| R-04 | 各依赖组件健康检查结果独立展示，某一组件异常不影响其他组件检查 | 避免一个组件超时导致整个检查失败，提供最大化的诊断信息 |
| R-05 | 健康检查数据为实时查询，每次进入页面实时获取 | 健康状态是瞬时的，缓存可能导致误判 |
| R-06 | 任一服务实例或依赖组件状态为 DOWN 时，在前端以红色告警色展示 | 视觉上第一时间引起注意 |
3.6.3 数据字段
服务健康检查响应数据结构：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 服务实例信息 | |||
| serviceInstances | List<ServiceInstance> | 是 | 服务实例列表 |
| serviceInstances[].serviceId | String | 是 | 服务标识 |
| serviceInstances[].instanceId | String | 是 | 实例标识 |
| serviceInstances[].host | String | 是 | 主机地址 |
| serviceInstances[].port | Integer | 是 | 端口 |
| serviceInstances[].status | String | 是 | 健康状态 |
| serviceInstances[].uptime | Long | 否 | 运行时长（毫秒） |
| 依赖组件健康信息 | |||
| components | List<ComponentHealth> | 是 | 依赖组件健康列表 |
| components[].name | String | 是 | 组件名称 |
| components[].status | String | 是 | 组件状态 |
| components[].details | Map | 否 | 组件详细信息 |
| 总体状态 | |||
| overallStatus | String | 是 | 整体健康状态 |
| checkTime | DateTime | 是 | 检查时间 |
3.6.4 接口设计
| 接口名称 | 请求方式 | 接口路径 | 权限标识 | 说明 |
|---|---|---|---|---|
| 获取服务健康信息 | GET | /admin-api/infra/health/check | infra:health-check:query | 获取服务实例健康状态 |
| 获取依赖组件健康 | GET | /admin-api/infra/health/components | infra:health-check:query | 获取依赖组件连通性 |
3.7 监控概览仪表盘（规划中，P2）
3.7.1 功能描述
监控概览仪表盘是运维人员的"每日第一屏"，将各子模块的关键指标汇总在一个页面上，让运维人员无需逐个查看各子模块就能掌握系统整体运行状况。
3.7.2 展示内容
| 指标区域 | 展示内容 | 优先级 |
|---|---|---|
| API 概览 | 今日调用量、平均响应时间、错误率、较昨日变化趋势 | P2 |
| 错误概览 | 今日错误数、未处理错误数、较昨日变化趋势 | P2 |
| 资源概览 | Redis 内存使用率、Redis 连接数 | P2 |
| JVM 概览 | 堆内存使用率、GC 次数、线程数 | P2 |
| 服务健康概览 | 各服务健康状态一览（绿色/红色指示灯） | P2 |
四、非功能需求
4.1 性能需求
| 指标 | 要求 | 说明 |
|---|---|---|
| API 访问日志分页查询 | < 1s（当日数据） | 通过 tenant_id + begin_time 联合索引优化 |
| API 错误日志分页查询 | < 1s（30 天内数据） | 通过 tenant_id + process_status 联合索引优化 |
| Redis 监控信息获取 | < 2s | 包含 INFO、DBSIZE、commandstats 三次命令调用 |
| JVM 监控信息获取 | < 1s | JMX 本地调用，延迟极低 |
| 服务健康检查 | < 5s（含所有依赖检查） | 各依赖检查并行执行 |
| 日志记录写入延迟 | < 100ms | 异步写入，不阻塞业务 |
| 日志对业务性能影响 | < 5% | 异步 + 批量写入策略 |
| 日志导出 | < 30s（10 万条） | 流式写入 Excel |
4.2 数据量预估与存储策略
| 数据类型 | 日均数据量 | 月均数据量 | 存储策略 |
|---|---|---|---|
| API 访问日志 | ~50 万条 | ~1500 万条 | 保留 7 天，到期自动归档/清理 |
| API 错误日志 | ~1 千条 | ~3 万条 | 保留 90 天 |
| Redis 监控数据 | 实时查询 | 不持久化 | 不存储 |
| JVM 监控数据 | 实时查询 | 不持久化 | 不存储 |
| 服务健康数据 | 实时查询 | 不持久化 | 不存储 |
为什么访问日志只保留 7 天？ 访问日志日均 50 万条，月均 1500 万条，如果长期保留会导致数据库膨胀严重影响查询性能。7 天的保留期已覆盖绝大多数排障场景。如需长期保留，建议通过定时任务导出归档到冷存储（如 OSS），或接入专业的日志分析平台（如 ELK）。
4.3 安全需求
| 安全项 | 要求 | 说明 |
|---|---|---|
| 访问权限控制 | 监控数据查看和导出需要对应权限 | 防止越权访问敏感监控数据 |
| 敏感信息保护 | Redis 监控中不暴露密码、AUTH 等敏感配置 | INFO 命令返回结果中的敏感字段需过滤 |
| 日志不可篡改 | API 日志写入后不支持修改和删除 | 错误日志仅支持标记处理状态，不支持修改日志内容 |
| 请求参数脱敏 | API 日志中的密码、Token 等敏感字段需脱敏存储 | 在日志写入前对敏感字段进行掩码处理 |
| 操作留痕 | 日志导出操作本身记录到操作日志 | 防止数据泄露后无法追溯 |
4.4 可用性需求
| 要求 | 说明 |
|---|---|
| 日志记录不阻塞业务 | 日志写入采用异步方式，即使写入失败也不影响业务接口正常执行 |
| 监控查询不影响服务 | 监控数据查询操作应对业务服务产生最小性能影响 |
| Redis 不可用时降级 | Redis 监控接口在 Redis 不可用时返回友好错误提示，而非抛出异常 |
| 大数据量查询优化 | 日志表通过分页查询和索引优化避免全表扫描 |
五、数据设计
5.1 核心表关系
5.2 API 访问日志表（infra_api_access_log）
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT | PK, AUTO_INCREMENT | 日志主键 |
| trace_id | VARCHAR(64) | - | 链路追踪编号 |
| user_id | BIGINT | - | 用户编号 |
| user_type | TINYINT | - | 用户类型（1-会员、2-管理员） |
| application_name | VARCHAR(50) | - | 应用名（微服务名称） |
| request_method | VARCHAR(16) | - | 请求方法（GET/POST/PUT/DELETE） |
| request_url | VARCHAR(512) | - | 请求地址 |
| request_params | TEXT | - | 请求参数（最大 8000 字符） |
| response_body | TEXT | - | 响应结果 |
| user_ip | VARCHAR(50) | - | 用户 IP |
| user_agent | VARCHAR(512) | - | 浏览器 UserAgent |
| operate_module | VARCHAR(50) | - | 操作模块 |
| operate_name | VARCHAR(50) | - | 操作名 |
| operate_type | INT | - | 操作分类（0-其它、1-查询、2-新增、3-修改、4-删除、5-导出、6-导入） |
| begin_time | DATETIME | - | 开始请求时间 |
| end_time | DATETIME | - | 结束请求时间 |
| duration | INT | - | 执行时长（毫秒） |
| result_code | INT | - | 结果码（0-成功） |
| result_msg | VARCHAR(512) | - | 结果提示 |
| tenant_id | BIGINT | NOT NULL | 租户编号 |
| creator | VARCHAR(64) | - | 创建者 |
| create_time | DATETIME | NOT NULL | 创建时间 |
| updater | VARCHAR(64) | - | 更新者 |
| update_time | DATETIME | NOT NULL | 更新时间 |
| deleted | BIT(1) | NOT NULL, DEFAULT 0 | 删除标记 |
索引设计：
| 索引名 | 字段 | 类型 | 说明 |
|---|---|---|---|
| idx_user_id | user_id | 普通索引 | 按用户查询 |
| idx_request_url | request_url(191) | 普通索引 | 按请求地址查询 |
| idx_duration | duration | 普通索引 | 按执行时长筛选慢接口 |
| idx_result_code | result_code | 普通索引 | 按结果码筛选 |
| idx_begin_time | begin_time | 普通索引 | 按请求时间范围查询 |
| idx_tenant_begin | tenant_id, begin_time | 联合索引 | 高频场景：租户 + 时间范围查询 |
| idx_application | application_name | 普通索引 | 按应用名筛选 |
5.3 API 错误日志表（infra_api_error_log）
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT | PK, AUTO_INCREMENT | 日志主键 |
| trace_id | VARCHAR(64) | - | 链路追踪编号 |
| user_id | BIGINT | - | 用户编号 |
| user_type | TINYINT | - | 用户类型 |
| application_name | VARCHAR(50) | - | 应用名 |
| request_method | VARCHAR(16) | - | 请求方法 |
| request_url | VARCHAR(512) | - | 请求地址 |
| request_params | TEXT | - | 请求参数（最大 8000 字符） |
| user_ip | VARCHAR(50) | - | 用户 IP |
| user_agent | VARCHAR(512) | - | 浏览器 UserAgent |
| exception_time | DATETIME | - | 异常发生时间 |
| exception_name | VARCHAR(128) | - | 异常类全名 |
| exception_message | TEXT | - | 异常消息 |
| exception_root_cause_message | TEXT | - | 根异常消息 |
| exception_stack_trace | TEXT | - | 异常堆栈轨迹 |
| exception_class_name | VARCHAR(256) | - | 异常发生的类全名 |
| exception_file_name | VARCHAR(256) | - | 异常发生的类文件名 |
| exception_method_name | VARCHAR(256) | - | 异常发生的方法名 |
| exception_line_number | INT | - | 异常发生的方法行号 |
| process_status | TINYINT | NOT NULL, DEFAULT 0 | 处理状态（0-未处理、1-已处理、2-已忽略） |
| process_time | DATETIME | - | 处理时间 |
| process_user_id | BIGINT | - | 处理用户编号 |
| tenant_id | BIGINT | NOT NULL | 租户编号 |
| creator | VARCHAR(64) | - | 创建者 |
| create_time | DATETIME | NOT NULL | 创建时间 |
| updater | VARCHAR(64) | - | 更新者 |
| update_time | DATETIME | NOT NULL | 更新时间 |
| deleted | BIT(1) | NOT NULL, DEFAULT 0 | 删除标记 |
索引设计：
| 索引名 | 字段 | 类型 | 说明 |
|---|---|---|---|
| idx_user_id | user_id | 普通索引 | 按用户查询 |
| idx_request_url | request_url(191) | 普通索引 | 按请求地址查询 |
| idx_exception_time | exception_time | 普通索引 | 按异常时间范围查询 |
| idx_process_status | process_status | 普通索引 | 按处理状态筛选 |
| idx_tenant_process | tenant_id, process_status | 联合索引 | 高频场景：租户 + 处理状态查询 |
| idx_application | application_name | 普通索引 | 按应用名筛选 |
| idx_trace_id | trace_id | 普通索引 | 按链路追踪编号关联查询 |
5.4 数据字典
| 字典类型 | 字典标识 | 字典值 | 说明 |
|---|---|---|---|
| 用户类型 | system_user_type | 1-会员、2-管理员 | 用户类型 |
| 操作分类 | infra_operate_type | 0-其它、1-查询、2-新增、3-修改、4-删除、5-导出、6-导入 | API 操作分类 |
| 错误处理状态 | infra_api_error_process_status | 0-未处理、1-已处理、2-已忽略 | API 错误日志的处理状态 |
| 健康状态 | infra_health_status | UP-正常、DOWN-异常、OUT_OF_SERVICE-下线、UNKNOWN-未知 | 服务健康检查状态 |
六、跨模块联动
6.1 联动关系总览
| 关联模块 | 联动方式 | 数据流向 | 联动说明 |
|---|---|---|---|
| 日志审计（01-08） | 共享数据 + 链路追踪 | 双向 | API 访问日志和 API 错误日志共享同一数据表；通过 trace_id 串联操作日志，实现全链路排障 |
| 用户管理（01-01） | 数据引用 | 单向读取 | 日志中的 user_id 关联系统用户表，展示用户昵称等可读信息 |
| 租户管理（01-07） | 数据隔离 | 隐式 | 所有日志表包含 tenant_id，按租户隔离数据 |
| 通知模块（规划中） | 事件触发 | 单向推送 | 当错误日志数量超过阈值或服务健康状态变为 DOWN 时，触发告警通知 |
| 定时任务（02-03） | 任务调度 | 协同 | 日志清理/归档任务通过定时任务模块调度执行 |
6.2 关键联动流程
6.2.1 全链路排障流程
6.2.2 日志生命周期管理
6.3 数据一致性要求
| 一致性场景 | 要求 | 保障措施 |
|---|---|---|
| 访问日志写入 | 异步写入，允许极少量丢失 | 日志写入失败不影响业务接口执行 |
| 错误日志处理状态更新 | 实时更新，不可丢失 | 数据库事务保证 |
| trace_id 关联一致性 | 同一次请求的访问日志和错误日志 trace_id 必须一致 | 在请求入口处生成 trace_id，贯穿整个请求链路 |
七、附录
7.1 名词解释
| 术语 | 解释 | 类比 |
|---|---|---|
| API 访问日志 | 记录每一次接口调用的完整信息（谁调的、调了什么、传了什么参数、返回了什么结果、花了多长时间） | 相当于公司的"来访登记簿"，记录每个来访者的完整信息 |
| API 错误日志 | 记录接口调用中发生异常的详细信息，包含完整的错误堆栈和定位信息 | 相当于"事故报告"，记录每次事故的详细经过和原因分析 |
| 链路追踪编号（traceId） | 一次请求从进入到结束的唯一标识，用于串联同一次请求产生的所有日志 | 相当于"快递单号"，通过一个单号可以追踪包裹的所有流转环节 |
| 慢接口 | 执行时长超过设定阈值（默认 1000ms）的 API 接口 | 相当于"排长队的窗口"，说明这个环节效率低需要优化 |
| Redis INFO | Redis 服务器提供的信息查看命令，返回服务器运行状态的各项指标 | 相当于查看汽车的仪表盘——油量、水温、转速一目了然 |
| CommandStats | Redis 命令统计信息，记录每种命令被调用了几次、总共花了多少 CPU 时间 | 相当于统计每个窗口办理了多少笔业务、平均办理时长 |
| JVM（Java 虚拟机） | Java 应用的运行时环境，负责执行 Java 程序 | 相当于汽车的发动机——Java 代码是燃油，JVM 是燃烧燃油产生动力的发动机 |
| GC（垃圾回收） | JVM 的自动内存管理机制，自动回收不再使用的内存空间 | 相当于保洁人员定期清理办公桌上的废弃物 |
| 堆内存（Heap） | JVM 管理的核心内存区域，所有对象实例都存储在这里 | 相当于办公室的公共桌面空间——所有正在处理的文件都放在这里 |
| Full GC | 对整个堆内存进行回收的垃圾回收操作，耗时长，会导致应用短暂停顿 | 相当于全公司大扫除——所有人都要停下来配合打扫 |
| 健康检查（Health Check） | 检查应用自身及其依赖组件是否正常运行的机制 | 相当于出门前检查——手机带了没？钥匙带了没？钱包带了没？ |
| Spring Boot Actuator | Spring Boot 提供的生产级监控和管理功能模块，暴露各种运行时指标 | 相当于汽车自带的诊断接口，4S 店通过它读取车辆状态 |
| MBean | Java 管理扩展（JMX）中的可管理资源，用于暴露运行时信息 | 相当于传感器——把发动机的温度、转速等数据暴露给仪表盘 |
| MTTD | Mean Time To Detect，平均故障发现时间——从故障发生到被发现的时间间隔 | 越短越好，说明监控系统灵敏 |
| MTTR | Mean Time To Repair，平均故障修复时间——从故障发现到修复完成的时间间隔 | 越短越好，说明团队响应和处理效率高 |
| 内存碎片率 | Redis 已分配内存与实际使用内存的比值，理想值接近 1.0 | 相当于图书馆书架的空间利用率——太高说明书摆得太松，太低说明塞得太满 |
7.2 权限配置
| 权限标识 | 权限名称 | 说明 |
|---|---|---|
| infra:api-access-log:query | 查看 API 访问日志 | 查看 API 访问日志列表和详情 |
| infra:api-access-log:export | 导出 API 访问日志 | 导出 API 访问日志 Excel |
| infra:api-error-log:query | 查看 API 错误日志 | 查看 API 错误日志列表和详情 |
| infra:api-error-log:update-status | 处理 API 错误日志 | 更新 API 错误日志的处理状态 |
| infra:api-error-log:export | 导出 API 错误日志 | 导出 API 错误日志 Excel |
| infra:redis:get-monitor-info | 查看 Redis 监控 | 查看 Redis 运行信息和命令统计 |
| infra:app-monitor:get-jvm-info | 查看应用监控 | 查看 JVM 运行时信息 |
| infra:health-check:query | 查看服务健康检查 | 查看服务实例和依赖组件健康状态 |
7.3 接口汇总
| 序号 | 接口名称 | 请求方式 | 路径 | 权限标识 | 说明 |
|---|---|---|---|---|---|
| 1 | API 访问日志详情 | GET | /admin-api/infra/api-access-log/get | infra:api-access-log:query | 获取单条访问日志 |
| 2 | API 访问日志分页 | GET | /admin-api/infra/api-access-log/page | infra:api-access-log:query | 分页查询 |
| 3 | API 访问日志导出 | GET | /admin-api/infra/api-access-log/export-excel | infra:api-access-log:export | 导出 Excel |
| 4 | API 错误日志详情 | GET | /admin-api/infra/api-error-log/get | infra:api-error-log:query | 获取单条错误日志 |
| 5 | API 错误日志分页 | GET | /admin-api/infra/api-error-log/page | infra:api-error-log:query | 分页查询 |
| 6 | 更新错误处理状态 | PUT | /admin-api/infra/api-error-log/update-status | infra:api-error-log:update-status | 标记处理状态 |
| 7 | API 错误日志导出 | GET | /admin-api/infra/api-error-log/export-excel | infra:api-error-log:export | 导出 Excel |
| 8 | Redis 监控信息 | GET | /admin-api/infra/redis/get-monitor-info | infra:redis:get-monitor-info | 获取 Redis 运行信息 |
| 9 | JVM 监控信息 | GET | /admin-api/infra/app-monitor/get-jvm-info | infra:app-monitor:get-jvm-info | 获取 JVM 运行时信息 |
| 10 | 服务健康检查 | GET | /admin-api/infra/health/check | infra:health-check:query | 获取服务健康状态 |
| 11 | 依赖组件健康 | GET | /admin-api/infra/health/components | infra:health-check:query | 获取依赖组件状态 |
7.4 变更记录
| 版本 | 日期 | 修改内容 | 修改人 |
|---|---|---|---|
| v1.0 | 2026-09-17 | 初始版本 | PM Team |
| v2.0 | 2026-09-19 | 全面重写：增强业务场景描述（含命名用户）、添加验收标准、新增跨模块联动章节、补充名词解释（含类比）、替换运营需求为跨模块联动、添加 ASCII 页面原型 | PM Team |
本文档为监控运维模块 PRD，如有问题请联系产品负责人。