Feinian Ids Platform Docs main platform-observability-and-health.md

平台可观测性与健康检查

文档目标

本文档用于说明平台当前可用的健康检查、运维视图、失败聚合与依赖状态入口，帮助平台侧建立统一的日常巡检、发布后验证和第一轮排障顺序。

适用角色

  • 平台运维
  • 系统管理员
  • 实施支持

适用场景

  • 发布后可用性确认
  • 平台日常健康巡检
  • 登录、配置、联邦或供给异常的第一轮定位
  • 外部监控平台对接前的入口确认

覆盖范围 / 不覆盖范围

覆盖：

  • /health/live、/health/ready 健康检查
  • ops_summary、ops_health_detail、ops_detail 运维摘要与排障接口
  • 系统后台与租户后台首页运维视图
  • 配置、数据库、证书、联邦、供给相关的提醒与失败聚合
  • 平台侧如何把 MCP 作为只读辅助排障入口使用

不覆盖：

  • 外部 OpenTelemetry、OTLP、Prometheus exporter 接入细节
  • 统一告警推送器或外部 alert sink 的产品内配置
  • 宿主机、容器编排或云平台的专属运维手册

核心入口与系统落点

  • 健康检查：/health/live、/health/ready
  • 运维接口：GET /api/system/ops_summary、GET /api/system/ops_health_detail、POST /api/system/ops_detail
  • 系统后台：首页 Operations
  • 租户后台：首页运维视图
  • 只读运维入口：平台 MCP 运维参考

后台查看方式

系统后台

系统后台首页适合用于查看全局运维态势，包括：

  • 健康状态总览
  • 依赖状态与问题数量
  • 失败 key 聚合
  • 协议分布与租户分布
  • 最近一小时 / 一天失败窗口
  • 小时趋势与近期失败记录

租户后台

租户后台首页适合用于查看当前租户范围内的运维视角，包括：

  • 当前租户相关的健康状态
  • 配置、联邦、供给等提醒
  • 当前租户近期失败与趋势
  • 当前租户可见范围内的排障入口

建议处理顺序

  1. 先用 /health/live 判断进程是否在线。
  2. 再用 /health/ready 判断数据库和配置等依赖是否具备对外服务条件。
  3. 进入 Operations 查看提醒、失败 key 聚合、协议分布、租户分布和近期失败。
  4. 如需进一步定位，用 ops_detail 或 平台 MCP 运维参考 继续筛查。
  5. 如确认问题集中在审计、安全、租户边界或协议配置，再切换到对应专题。

常见判断原则

  • liveness 正常但 readiness 降级，通常表示实例仍存活，但数据库、配置或某些依赖没有达到可服务状态。
  • 健康检查正常但失败趋势上升，通常说明基础依赖还在线，但某条业务链路正在集中失败，应继续查看失败明细、审计和协议分布。
  • 提醒中出现证书、联邦或供给问题时，应优先回到对应治理页核查，而不是只盯着健康端点本身。
  • 当前版本不内建外部 telemetry / exporter 与统一告警推送器；如果部署侧需要外部监控，建议复用健康端点和平台内运维接口结果完成对接。

常见问题解释

liveness 正常但 readiness 降级

通常表示进程仍在线，但数据库连接、配置校验或某些依赖状态存在问题。优先查看 ops_health_detail 中的 checks 与 details。

提醒里出现证书、联邦或供给问题

这通常意味着配置存在缺失、启用了功能但未完成必要字段填写，或证书状态需要关注。建议回到对应治理页逐项核对。

近期失败增长但健康检查仍显示正常

这通常表示依赖仍可用，但某条业务链路出现集中失败。优先查看失败 key 聚合、协议分布和近期失败明细，再结合审计与治理页定位。

当前边界

当前能力已经满足平台内运维总览和基础排障，明确边界如下：

  • 平台排障主路径优先走健康端点、后台运维视图、管理 API 与只读 MCP。
  • 当前文档不假设额外的外部监控系统或自动修复工具已经到位。
  • MCP 只提供只读查询与配置建议，不直接改配置、不修复数据。

关联文档