Skip to content

监控运维 PRD ​

文档信息 ​

项目内容
文档编号PRD-02-05
文档名称监控运维
产品名称PMForge 项目管理平台
所属模块infra
文档版本v2.2
最后更新2026-11-18
文档状态已更新
实施状态已实现(接入 server)
优先级P1

1. 功能概述 ​

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 监控✅P0Redis 运行信息、内存使用、命令统计
应用监控(JVM)✅P1JVM 参数、内存分布、线程状态、GC 统计
服务健康检查✅P1服务实例状态、依赖组件连通性
监控概览仪表盘✅(规划中)P2汇总展示关键监控指标

2. 用户场景 ​

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 毫秒"的模糊匹配 ③ 列表默认按创建时间倒序 ④ 分页查询响应时间 < 1sP0
US-02作为运维人员,我希望查看 API 访问日志详情① 展示完整的请求参数(Query + Body) ② 展示响应结果 ③ 展示执行时长(精确到毫秒) ④ 展示链路追踪编号,可关联错误日志P0
US-03作为运维人员,我希望导出 API 访问日志① 按当前筛选条件导出 Excel ② 单次导出不超过 10 万条 ③ 导出响应时间 < 30sP1
US-04作为运维人员,我希望查看 API 错误日志并按处理状态筛选① 支持按处理状态(未处理/已处理/已忽略)筛选 ② 列表展示异常名称和异常消息摘要 ③ 未处理错误以醒目颜色标识P0
US-05作为运维人员,我希望查看错误日志的完整异常信息① 展示异常类全名和异常消息 ② 展示完整异常堆栈轨迹 ③ 展示异常发生的类名、方法名、行号 ④ 展示请求参数P0
US-06作为运维人员,我希望更新错误日志的处理状态① 支持标记为"已处理"或"已忽略" ② 自动记录处理人和处理时间 ③ 已处理/已忽略不可逆回"未处理" ④ 操作记录到操作日志P1
US-07作为运维人员,我希望导出 API 错误日志① 按当前筛选条件导出 Excel ② 包含异常堆栈等完整信息P1
US-08作为运维人员,我希望查看 Redis 运行信息① 展示 Redis 版本、运行模式、运行天数、连接数 ② 展示内存使用量和最大限制 ③ 展示命令调用 TOP 10 排行 ④ 数据为实时查询,响应时间 < 2sP0
US-09作为运维人员,我希望分析 Redis Key 分布① 展示当前 Key 总数 ② 展示各数据库 Key 分布P2
US-10作为运维人员,我希望查看 JVM 运行时信息① 展示 JVM 版本、供应商、启动参数 ② 展示堆内存各区域使用情况 ③ 展示线程状态分布 ④ 展示 GC 收集器统计 ⑤ 堆内存使用率 > 85% 时高亮告警P1
US-11作为运维人员,我希望检查服务健康状态① 展示各服务实例的健康状态 ② 展示依赖组件(数据库、Redis 等)连通性 ③ 异常组件以红色高亮 ④ 响应时间 < 5sP1
US-12作为技术经理,我希望查看监控概览仪表盘① 展示 API 调用量、错误率、平均响应时间 ② 展示 Redis/JVM 关键指标 ③ 展示服务健康状态一览P2

3. 功能需求 ​

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 数据字段 ​

字段名类型必填说明
idLong是日志编号
traceIdString否链路追踪编号,用于串联同一次请求的所有日志
userIdLong否用户编号(未登录的公开接口为空)
userTypeInteger否用户类型(1-会员、2-管理员)
applicationNameString是应用名(微服务名称)
requestMethodString是请求方法(GET/POST/PUT/DELETE)
requestUrlString是请求地址
requestParamsString否请求参数(Query + Body,最大 8000 字符)
responseBodyString否响应结果(截断后最大 512 字符)
userIpString是用户 IP 地址
userAgentString否浏览器 UserAgent
operateModuleString否操作模块名称
operateNameString否操作名称
operateTypeInteger否操作分类(OperateTypeEnum)
beginTimeDateTime是开始请求时间
endTimeDateTime是结束请求时间
durationInteger是执行时长(毫秒)
resultCodeInteger是结果码(0 表示成功)
resultMsgString否结果提示(最大 512 字符)
createTimeDateTime是创建时间

3.2.4 接口设计 ​

接口名称请求方式接口路径权限标识说明
获取 API 访问日志详情GET/admin-api/infra/api-access-log/getinfra:api-access-log:query获取单条访问日志
获取 API 访问日志分页GET/admin-api/infra/api-access-log/pageinfra:api-access-log:query分页查询访问日志
导出 API 访问日志 ExcelGET/admin-api/infra/api-access-log/export-excelinfra:api-access-log:export按筛选条件导出

分页查询请求参数:

参数名类型必填说明
userIdLong否用户编号
userTypeInteger否用户类型
applicationNameString否应用名(模糊匹配)
requestUrlString否请求地址(模糊匹配)
durationInteger否执行时长下限(毫秒),筛选 >= 该值的记录
resultCodeInteger否结果码
beginTimeDateTime[]否请求时间范围
pageNoInteger是页码(从 1 开始)
pageSizeInteger是每页条数(默认 10)

3.3 API 错误日志监控 ​

3.3.1 页面描述 ​

详情弹窗(含处理操作):

3.3.2 错误处理状态机 ​

3.3.3 业务规则 ​

规则编号规则描述为什么这样设计
R-01API 请求发生异常时,由全局异常处理器自动捕获并记录错误日志统一捕获,避免遗漏;业务代码无需关心日志记录
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 数据字段 ​

字段名类型必填说明
idLong是日志编号
traceIdString否链路追踪编号
userIdLong否用户编号
userTypeInteger否用户类型
applicationNameString是应用名(微服务名称)
requestMethodString是请求方法
requestUrlString是请求地址
requestParamsString否请求参数(最大 8000 字符)
userIpString是用户 IP
userAgentString否浏览器 UserAgent
exceptionTimeDateTime是异常发生时间
exceptionNameString是异常类全名(如 NullPointerException)
exceptionMessageString否异常消息
exceptionRootCauseMessageString否根异常消息(包装异常时取最内层原因)
exceptionStackTraceString否异常堆栈轨迹(完整)
exceptionClassNameString否异常发生的类全名
exceptionFileNameString否异常发生的类文件名
exceptionMethodNameString否异常发生的方法名
exceptionLineNumberInteger否异常发生的方法行号
processStatusInteger是处理状态(0-未处理、1-已处理、2-已忽略)
processTimeDateTime否处理时间
processUserIdLong否处理用户编号
createTimeDateTime是创建时间

3.3.5 接口设计 ​

接口名称请求方式接口路径权限标识说明
获取 API 错误日志详情GET/admin-api/infra/api-error-log/getinfra:api-error-log:query获取单条错误日志
获取 API 错误日志分页GET/admin-api/infra/api-error-log/pageinfra:api-error-log:query分页查询错误日志
更新错误日志处理状态PUT/admin-api/infra/api-error-log/update-statusinfra:api-error-log:update-status标记处理状态
导出 API 错误日志 ExcelGET/admin-api/infra/api-error-log/export-excelinfra:api-error-log:export按筛选条件导出

分页查询请求参数:

参数名类型必填说明
userIdLong否用户编号
userTypeInteger否用户类型
applicationNameString否应用名(模糊匹配)
requestUrlString否请求地址(模糊匹配)
exceptionTimeDateTime[]否异常发生时间范围
processStatusInteger否处理状态(0-未处理、1-已处理、2-已忽略)
pageNoInteger是页码(从 1 开始)
pageSizeInteger是每页条数(默认 10)

更新处理状态请求参数:

参数名类型必填说明
idLong是错误日志编号
processStatusInteger是处理状态(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 监控响应数据结构:

字段名类型必填说明
infoProperties是Redis INFO 命令返回的完整属性集
dbSizeLong是当前数据库 Key 数量
commandStatsList<CommandStat>是命令统计结果列表

CommandStat 子结构:

字段名类型必填说明
commandString是Redis 命令名称(如 get、set、hget)
callsLong是该命令的累计调用次数
usecLong是该命令的累计 CPU 耗时(微秒)

Redis INFO 关键属性说明:

属性分组关键属性说明
Serverredis_version, os, tcp_port, uptime_in_days版本、操作系统、端口、运行天数
Clientsconnected_clients, blocked_clients当前连接数、阻塞连接数
Memoryused_memory, used_memory_human, used_memory_peak, maxmemory, mem_fragmentation_ratio内存使用详情
Statstotal_connections_received, total_commands_processed, instantaneous_ops_per_sec连接/命令统计
Keyspacedb0, db1, ...各数据库 Key 数量和过期 Key 数量

3.4.4 接口设计 ​

接口名称请求方式接口路径权限标识说明
获取 Redis 监控信息GET/admin-api/infra/redis/get-monitor-infoinfra:redis:get-monitor-info获取 Redis 运行信息

返回结果:

字段名类型说明
infoObjectRedis INFO 完整属性(键值对形式)
dbSizeLong当前数据库 Key 数量
commandStatsList命令统计列表
commandStats[].commandString命令名称
commandStats[].callsLong累计调用次数
commandStats[].usecLong累计 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-04GC 统计展示各收集器的收集次数和耗时Full GC 耗时过长会导致应用暂停(Stop The World),需要重点关注
R-05监控数据为实时查询,不做持久化存储与 Redis 监控同理,历史趋势交给专业监控系统
R-06堆内存使用率超过 85% 时在前端以警告色展示堆内存接近上限会频繁触发 Full GC,严重影响性能
R-07存在死锁线程时在前端以告警色高亮提示死锁会导致相关线程永久阻塞,必须立即处理

3.5.3 数据字段 ​

JVM 监控响应数据结构:

字段名类型必填说明
JVM 基本信息
jvmVersionString是JVM 版本号
jvmVendorString是JVM 供应商
jvmNameString是JVM 名称
startTimeDateTime是JVM 启动时间
uptimeLong是运行时长(毫秒)
jvmArgsString是JVM 启动参数
堆内存信息
heapMemoryUsedLong是堆内存已使用(字节)
heapMemoryMaxLong是堆内存最大值(字节)
heapMemoryCommittedLong是堆内存已分配(字节)
nonHeapMemoryUsedLong是非堆内存已使用(字节)
内存池详情
memoryPoolsList<MemoryPool>是各内存池详情
memoryPools[].nameString是内存池名称(如 Eden Space、Old Gen)
memoryPools[].typeString是类型(Heap/Non-Heap)
memoryPools[].usedLong是已使用(字节)
memoryPools[].maxLong否最大值(字节)
线程信息
threadCountInteger是当前线程总数
daemonThreadCountInteger是守护线程数
peakThreadCountInteger是峰值线程数
deadlockedThreadsList<Long>否死锁线程 ID 列表(无死锁为空)
threadStateStatsMap<String, Integer>是各状态线程数量统计
GC 统计
gcCollectorsList<GcCollector>是GC 收集器列表
gcCollectors[].nameString是收集器名称
gcCollectors[].collectionCountLong是累计收集次数
gcCollectors[].collectionTimeLong是累计收集耗时(毫秒)

3.5.4 接口设计 ​

接口名称请求方式接口路径权限标识说明
获取 JVM 监控信息GET/admin-api/infra/app-monitor/get-jvm-infoinfra: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 数据字段 ​

服务健康检查响应数据结构:

字段名类型必填说明
服务实例信息
serviceInstancesList<ServiceInstance>是服务实例列表
serviceInstances[].serviceIdString是服务标识
serviceInstances[].instanceIdString是实例标识
serviceInstances[].hostString是主机地址
serviceInstances[].portInteger是端口
serviceInstances[].statusString是健康状态
serviceInstances[].uptimeLong否运行时长(毫秒)
依赖组件健康信息
componentsList<ComponentHealth>是依赖组件健康列表
components[].nameString是组件名称
components[].statusString是组件状态
components[].detailsMap否组件详细信息
总体状态
overallStatusString是整体健康状态
checkTimeDateTime是检查时间

3.6.4 接口设计 ​

接口名称请求方式接口路径权限标识说明
获取服务健康信息GET/admin-api/infra/health/checkinfra:health-check:query获取服务实例健康状态
获取依赖组件健康GET/admin-api/infra/health/componentsinfra:health-check:query获取依赖组件连通性

3.7 监控概览仪表盘(规划中,P2) ​

3.7.1 功能描述 ​

监控概览仪表盘是运维人员的"每日第一屏",将各子模块的关键指标汇总在一个页面上,让运维人员无需逐个查看各子模块就能掌握系统整体运行状况。

3.7.2 展示内容 ​

指标区域展示内容优先级
API 概览今日调用量、平均响应时间、错误率、较昨日变化趋势P2
错误概览今日错误数、未处理错误数、较昨日变化趋势P2
资源概览Redis 内存使用率、Redis 连接数P2
JVM 概览堆内存使用率、GC 次数、线程数P2
服务健康概览各服务健康状态一览(绿色/红色指示灯)P2

4. 非功能需求 ​

4.1 性能需求 ​

指标要求说明
API 访问日志分页查询< 1s(当日数据)通过 tenant_id + begin_time 联合索引优化
API 错误日志分页查询< 1s(30 天内数据)通过 tenant_id + process_status 联合索引优化
Redis 监控信息获取< 2s包含 INFO、DBSIZE、commandstats 三次命令调用
JVM 监控信息获取< 1sJMX 本地调用,延迟极低
服务健康检查< 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. 数据设计 ​

5.1 核心表关系 ​

5.2 API 访问日志表(infra_api_access_log) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT日志主键
trace_idVARCHAR(64)-链路追踪编号
user_idBIGINT-用户编号
user_typeTINYINT-用户类型(1-会员、2-管理员)
application_nameVARCHAR(50)-应用名(微服务名称)
request_methodVARCHAR(16)-请求方法(GET/POST/PUT/DELETE)
request_urlVARCHAR(512)-请求地址
request_paramsTEXT-请求参数(最大 8000 字符)
response_bodyTEXT-响应结果
user_ipVARCHAR(50)-用户 IP
user_agentVARCHAR(512)-浏览器 UserAgent
operate_moduleVARCHAR(50)-操作模块
operate_nameVARCHAR(50)-操作名
operate_typeINT-操作分类(0-其它、1-查询、2-新增、3-修改、4-删除、5-导出、6-导入)
begin_timeDATETIME-开始请求时间
end_timeDATETIME-结束请求时间
durationINT-执行时长(毫秒)
result_codeINT-结果码(0-成功)
result_msgVARCHAR(512)-结果提示
tenant_idBIGINTNOT NULL租户编号
creatorVARCHAR(64)-创建者
create_timeDATETIMENOT NULL创建时间
updaterVARCHAR(64)-更新者
update_timeDATETIMENOT NULL更新时间
deletedBIT(1)NOT NULL, DEFAULT 0删除标记

索引设计:

索引名字段类型说明
idx_user_iduser_id普通索引按用户查询
idx_request_urlrequest_url(191)普通索引按请求地址查询
idx_durationduration普通索引按执行时长筛选慢接口
idx_result_coderesult_code普通索引按结果码筛选
idx_begin_timebegin_time普通索引按请求时间范围查询
idx_tenant_begintenant_id, begin_time联合索引高频场景:租户 + 时间范围查询
idx_applicationapplication_name普通索引按应用名筛选

5.3 API 错误日志表(infra_api_error_log) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT日志主键
trace_idVARCHAR(64)-链路追踪编号
user_idBIGINT-用户编号
user_typeTINYINT-用户类型
application_nameVARCHAR(50)-应用名
request_methodVARCHAR(16)-请求方法
request_urlVARCHAR(512)-请求地址
request_paramsTEXT-请求参数(最大 8000 字符)
user_ipVARCHAR(50)-用户 IP
user_agentVARCHAR(512)-浏览器 UserAgent
exception_timeDATETIME-异常发生时间
exception_nameVARCHAR(128)-异常类全名
exception_messageTEXT-异常消息
exception_root_cause_messageTEXT-根异常消息
exception_stack_traceTEXT-异常堆栈轨迹
exception_class_nameVARCHAR(256)-异常发生的类全名
exception_file_nameVARCHAR(256)-异常发生的类文件名
exception_method_nameVARCHAR(256)-异常发生的方法名
exception_line_numberINT-异常发生的方法行号
process_statusTINYINTNOT NULL, DEFAULT 0处理状态(0-未处理、1-已处理、2-已忽略)
process_timeDATETIME-处理时间
process_user_idBIGINT-处理用户编号
tenant_idBIGINTNOT NULL租户编号
creatorVARCHAR(64)-创建者
create_timeDATETIMENOT NULL创建时间
updaterVARCHAR(64)-更新者
update_timeDATETIMENOT NULL更新时间
deletedBIT(1)NOT NULL, DEFAULT 0删除标记

索引设计:

索引名字段类型说明
idx_user_iduser_id普通索引按用户查询
idx_request_urlrequest_url(191)普通索引按请求地址查询
idx_exception_timeexception_time普通索引按异常时间范围查询
idx_process_statusprocess_status普通索引按处理状态筛选
idx_tenant_processtenant_id, process_status联合索引高频场景:租户 + 处理状态查询
idx_applicationapplication_name普通索引按应用名筛选
idx_trace_idtrace_id普通索引按链路追踪编号关联查询

5.4 数据字典 ​

字典类型字典标识字典值说明
用户类型system_user_type1-会员、2-管理员用户类型
操作分类infra_operate_type0-其它、1-查询、2-新增、3-修改、4-删除、5-导出、6-导入API 操作分类
错误处理状态infra_api_error_process_status0-未处理、1-已处理、2-已忽略API 错误日志的处理状态
健康状态infra_health_statusUP-正常、DOWN-异常、OUT_OF_SERVICE-下线、UNKNOWN-未知服务健康检查状态

6. 跨模块联动 ​

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. 附录 ​

7.1 名词解释 ​

术语解释类比
API 访问日志记录每一次接口调用的完整信息(谁调的、调了什么、传了什么参数、返回了什么结果、花了多长时间)相当于公司的"来访登记簿",记录每个来访者的完整信息
API 错误日志记录接口调用中发生异常的详细信息,包含完整的错误堆栈和定位信息相当于"事故报告",记录每次事故的详细经过和原因分析
链路追踪编号(traceId)一次请求从进入到结束的唯一标识,用于串联同一次请求产生的所有日志相当于"快递单号",通过一个单号可以追踪包裹的所有流转环节
慢接口执行时长超过设定阈值(默认 1000ms)的 API 接口相当于"排长队的窗口",说明这个环节效率低需要优化
Redis INFORedis 服务器提供的信息查看命令,返回服务器运行状态的各项指标相当于查看汽车的仪表盘——油量、水温、转速一目了然
CommandStatsRedis 命令统计信息,记录每种命令被调用了几次、总共花了多少 CPU 时间相当于统计每个窗口办理了多少笔业务、平均办理时长
JVM(Java 虚拟机)Java 应用的运行时环境,负责执行 Java 程序相当于汽车的发动机——Java 代码是燃油,JVM 是燃烧燃油产生动力的发动机
GC(垃圾回收)JVM 的自动内存管理机制,自动回收不再使用的内存空间相当于保洁人员定期清理办公桌上的废弃物
堆内存(Heap)JVM 管理的核心内存区域,所有对象实例都存储在这里相当于办公室的公共桌面空间——所有正在处理的文件都放在这里
Full GC对整个堆内存进行回收的垃圾回收操作,耗时长,会导致应用短暂停顿相当于全公司大扫除——所有人都要停下来配合打扫
健康检查(Health Check)检查应用自身及其依赖组件是否正常运行的机制相当于出门前检查——手机带了没?钥匙带了没?钱包带了没?
Spring Boot ActuatorSpring Boot 提供的生产级监控和管理功能模块,暴露各种运行时指标相当于汽车自带的诊断接口,4S 店通过它读取车辆状态
MBeanJava 管理扩展(JMX)中的可管理资源,用于暴露运行时信息相当于传感器——把发动机的温度、转速等数据暴露给仪表盘
MTTDMean Time To Detect,平均故障发现时间——从故障发生到被发现的时间间隔越短越好,说明监控系统灵敏
MTTRMean 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 接口汇总 ​

序号接口名称请求方式路径权限标识说明
1API 访问日志详情GET/admin-api/infra/api-access-log/getinfra:api-access-log:query获取单条访问日志
2API 访问日志分页GET/admin-api/infra/api-access-log/pageinfra:api-access-log:query分页查询
3API 访问日志导出GET/admin-api/infra/api-access-log/export-excelinfra:api-access-log:export导出 Excel
4API 错误日志详情GET/admin-api/infra/api-error-log/getinfra:api-error-log:query获取单条错误日志
5API 错误日志分页GET/admin-api/infra/api-error-log/pageinfra:api-error-log:query分页查询
6更新错误处理状态PUT/admin-api/infra/api-error-log/update-statusinfra:api-error-log:update-status标记处理状态
7API 错误日志导出GET/admin-api/infra/api-error-log/export-excelinfra:api-error-log:export导出 Excel
8Redis 监控信息GET/admin-api/infra/redis/get-monitor-infoinfra:redis:get-monitor-info获取 Redis 运行信息
9JVM 监控信息GET/admin-api/infra/app-monitor/get-jvm-infoinfra:app-monitor:get-jvm-info获取 JVM 运行时信息
10服务健康检查GET/admin-api/infra/health/checkinfra:health-check:query获取服务健康状态
11依赖组件健康GET/admin-api/infra/health/componentsinfra:health-check:query获取依赖组件状态

7.4 变更记录 ​

版本日期修改内容修改人
v1.02026-09-17初始版本PM Team
v2.02026-09-19全面重写:增强业务场景描述(含命名用户)、添加验收标准、新增跨模块联动章节、补充名词解释(含类比)、替换运营需求为跨模块联动、添加 ASCII 页面原型PM Team

本文档为监控运维模块 PRD,如有问题请联系产品负责人。

代码对齐(自动生成) ​

本节由 tools/docs/prd-align.mjs 从源码与 SQL 解析生成,请勿手工编辑;重跑 npm run prd:align 会整体替换。

1. 模块规模 ​

控制器接口权限点数据表
161134816

2. 控制器清单 ​

控制器基础路径接口数权限点数代码位置
ApiAccessLogController/infra/api-access-log32modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/logger/ApiAccessLogController.java
ApiErrorLogController/infra/api-error-log43modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/logger/ApiErrorLogController.java
AppFileController/infra/file30modules/infra/src/main/java/com/pmforge/module/infra/controller/app/file/AppFileController.java
CodegenController/infra/codegen116modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/codegen/CodegenController.java
ConfigController/infra/config85modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/config/ConfigController.java
DataSourceConfigController/infra/data-source-config64modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/db/DataSourceConfigController.java
Demo01ContactController/infra/demo01-contact75modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo01/Demo01ContactController.java
Demo02CategoryController/infra/demo02-category65modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo02/Demo02CategoryController.java
Demo03StudentErpController/infra/demo03-student-erp195modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo03/erp/Demo03StudentErpController.java
Demo03StudentInnerController/infra/demo03-student-inner95modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo03/inner/Demo03StudentInnerController.java
Demo03StudentNormalController/infra/demo03-student-normal95modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo03/normal/Demo03StudentNormalController.java
FileConfigController/infra/file-config84modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/file/FileConfigController.java
FileController/infra/file82modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/file/FileController.java
JobController/infra/job116modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/job/JobController.java
JobLogController/infra/job-log32modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/job/JobLogController.java
RedisController/infra/redis11modules/infra/src/main/java/com/pmforge/module/infra/controller/admin/redis/RedisController.java

3. 接口对照 ​

本文引用 11 个接口,代码中存在 8 个(命中率 73%)。

本文接口代码中对应真实接口
/infra/api-access-log/get✅
/infra/api-access-log/page✅
/infra/api-access-log/export-excel✅
/infra/api-error-log/get✅
/infra/api-error-log/page✅
/infra/api-error-log/update-status✅
/infra/api-error-log/export-excel✅
/infra/redis/get-monitor-info✅
/infra/app-monitor/get-jvm-info❌—
/infra/health/check❌/system/captcha/check
/infra/health/components❌—

❌ 记 3 个接口在代码中不存在:可能是尚未实现(应移入「规划」),也可能是命名与实现不一致(以「对应真实接口」列修正)。

4. 数据表 ​

表名说明
infra_api_access_logApiAccessLogDO
infra_api_error_logApiErrorLogDO
infra_codegen_columnCodegenColumnDO
infra_codegen_tableCodegenTableDO
infra_configConfigDO
infra_data_source_configDataSourceConfigDO
infra_fileFileDO
infra_file_configFileClientConfigTypeHandler
infra_file_contentFileContentDO
infra_jobJobDO
infra_job_logJobLogDO
pmforge_demo01_contactDemo01ContactDO
pmforge_demo02_categoryDemo02CategoryDO
pmforge_demo03_courseDemo03CourseDO
pmforge_demo03_gradeDemo03GradeDO
pmforge_demo03_studentDemo03StudentDO

5. 说明 ​

  • 模块码:infra(基础设施);PRD 编号:02-05。
  • 「接口对照」只统计本文用反引号显式写出的 /admin-api/... 路径;未写接口的章节不代表没有实现。
  • 代码位置为相对仓库根的路径,行号可在功能卡或 docs/code/api/ 中查到。