工程案例 No. 02 / 04
PulseGuard： 把多个项目的前端与 API 探活纳入日常质量工作
独立研发并应用于公司多个项目的 UI/API 探活平台。围绕持续检查、失败归因、跨网络执行和证据诊断，把分散的可用性检查整理为可维护的质量工具。
- 状态
- 持续迭代
- 时间
- 持续应用与迭代 · 2026.09 更新
- 证据
- 4 项代码 / 文档 / 持续集成
- 关联项目
- PulseGuard
01角色
我的角色与范围
独立产品设计、全栈开发、部署与持续维护，持续应用与迭代 · 2026.09 更新。
02问题
要解决什么
多个项目都需要检查前端页面与 API 是否可用。接口有响应并不一定代表页面流程正常；一次失败也可能来自浏览器或执行节点。质量工作需要能够持续执行、保留失败现场并区分失败来源的探活工具。
我将自研 PulseGuard 应用于公司多个项目的前端页面与 API 探活。公开案例说明通用设计与实现，内部业务地址、账号和运行数据不展示。应用范围来自实际工作，通用能力可通过开源代码与文档复查。
03范围
目标与不做事项
目标
- 统一管理前端与 API 的定时探测、健康状态、失败证据和告警。
- 支持本机、局域网和主动出站节点的执行需求。
- 让失败诊断能够回看响应、截图、规则结果与执行环境。
不做事项
- 完整 E2E 回归仍由专门的自动化框架或测试平台承担。
- 不承担公开事件状态页或复杂值班管理。
04约束
现实边界
- 采用本地优先、单实例主控与 SQLite 存储。
- 执行节点只执行任务，调度、告警和主数据由主控拥有。
- 自定义 Python 脚本面向可信使用者，不提供通用脚本安全沙箱。
05决策
真正影响结果的取舍
-
决策 1：将目标故障与执行环境异常分开
通过健康状态机表达疑似故障、故障和恢复，同时把浏览器崩溃、节点不可用等归为 Runner 异常，帮助使用者先判断失败来自哪里。
-
决策 2：统一主控与可出站的远程节点
本机、直连 Worker 和 Relay Worker 使用统一运行记录。Relay 节点主动出站连接，使不便开放入站端口的环境也有执行路径。
-
决策 3：公共方法复用与运行快照并存
项目公共 Python 库减少请求准备、签名和解析的重复维护；已经开始的运行及重试使用捕获的源码快照，让在途执行保持一致。
-
决策 4：给 AI 提供有边界的诊断入口
MCP 默认只读，允许查询任务、失败与成功基线及保留截图。执行已有任务需要明确启用并处于用户授权范围，真实执行仍可能更新健康状态或发送告警。
06主流程
架构与实现
任务配置与公共脚本 → 主控调度 → 本机 / 直连 Worker / Relay Worker → 真实 UI 或 API 探测 → 运行证据与失败分类 → 健康状态和告警。
主控拥有任务、调度、健康状态、告警与主数据，执行节点负责实际运行和证据回传。React / TypeScript 提供控制台，FastAPI / SQLite 管理业务状态，Playwright 承担页面探测，Docker Compose 支持部署。
07证据
如何确认它真的工作
共 4 项证据，其中 4 项附公开链接，可以自己打开核对。
-
代码
公开代码与能力说明
固定到 2026-09-09 的仓库版本，可核对健康状态、执行节点、失败证据与使用边界。
-
文档
公共脚本库与源码快照
说明公共方法复用、保存校验、引用保护，以及在途运行与重试使用源码快照的行为。
-
文档
MCP 连接与授权执行
说明默认只读、按项目查询、失败诊断、成功基线和显式启用执行的边界。
-
持续集成
Worker 镜像工作流
对应公开版本的 Docker Worker Image 工作流通过；这是该版本的构建验证记录。
08结果
已经产生的影响
- 已在公司多个项目中用于前端页面与 API 探活。
- 形成由我独立设计、开发、部署和持续维护的质量工具。
- 通用实现已开源，可按固定版本查看代码、文档与构建记录。
09边界
限制与后续
当前限制
- 本案例未公开公司运行数据，因此不提供任务规模、故障降幅或节省工时等量化结论。
- 单实例与本地优先设计面向个人、小团队和内网使用，不能据此推断大规模可用性。
后续
- 结合实际使用继续完善规则维护、失败诊断和执行稳定性。