在一个控制台中持续检查页面、接口与基础网络目标，并保留可判断的失败证据。
PulseGuard（脉守）是一个面向个人、小团队和内网环境的 UI/API 探活与轻量监测控制台。
控制台面向桌面与笔记本浏览器，明确不做手机视口兼容；UI 探测任务的 H5 页面模式和移动目标视口不受影响。
它把定时检查、手动调试、运行历史、失败证据、健康状态、告警和多节点执行放在一个本地优先的单实例系统中。适合检查后台页面、登录前置流程、健康接口、批处理心跳、证书、TCP/DNS 和基础网络可达性。
PulseGuard 不试图替代完整 E2E 测试平台、公开状态页或 incident/on-call 系统。它解决的是一个更具体的问题：
当服务分散在本机、局域网和不同网络节点时，如何用较低成本持续确认它们是否仍然可用，并快速判断失败来自目标还是执行环境。
- 定时检查需要登录或准备页面上下文的后台 UI；
- 监测内部 API、健康接口和关键响应字段；
- 接收批处理、定时任务或设备主动上报的心跳；
- 监测 TLS 到期、HTTP 内容、重定向、静态资源、TCP 和 DNS；
- 从一个主节点统一调度本机、局域网和跨网络执行节点；
- 在失败时保留截图、Response Body 和可选 Trace；
- 区分业务目标失败与浏览器、节点、依赖或数据库等 Runner 异常。
- 支持定时、手动、批量与重跑；
- UI 支持结构化步骤、前置脚本和多浏览器类型；
- API 支持请求配置、字段预览、基础断言和高级脚本；脚本可先获取令牌、签名或动态参数，再发起目标请求，健康规则检查最后一次响应，无需重复请求；
- 编辑器试运行不污染正式健康状态或告警统计。
在“项目管理 → 公共方法”集中维护 Python 函数，同一项目的 API、UI 和前置脚本通过 ctx.modules.use("模块名") 复用请求准备、签名和解析逻辑。
- 列表、新建、编辑和保存即生效，编辑器提供模块与函数补全；
- 保存前检查 Python 编译错误、模块导出及已有任务引用，阻止删除仍被引用的方法；
- 新运行使用最新保存的源码，已开始的运行和重试继续使用捕获的源码快照；
- 项目配置导出包含当前生效库，导入时检查同名源码冲突和任务引用。
使用方式见 项目公共方法库；动态 API 请求与规则示例见 API 健康判定。
PulseGuard 不把单次抖动直接等同于故障。系统区分：
健康 → 疑似故障 → 故障 → 疑似恢复 → 健康
同时保留未知、观测陈旧和停用等状态。浏览器崩溃、节点不可用、依赖缺失或数据库异常会归类为 Runner 异常，不会伪装成目标故障。
- 失败摘要、截图和 Response Body；
- API 预览与运行详情保留最近请求记录、规则结果和编译诊断，分别展示目标请求耗时与全程探测耗时；
- 可选 Playwright Trace，默认关闭；
- 24 小时、7 天、30 天和自定义时间段趋势；
- 成功响应时间的平均值、P95、P99 与失败次数；
- 相似失败滚动保留，避免证据无限增长。
支持三种执行来源：
主节点
├── local：内置本机执行
├── direct worker：主节点直连局域网子节点
└── relay worker：子节点主动出站连接，不开放入站端口
多节点和多浏览器组合会生成统一分组的运行记录，并明确展示节点状态、浏览器类型、失败来源、耗时和证据。
- 任务、运行、趋势、异常周期、版本、项目审计和运行告警按项目隔离；
- 目标执行告警使用项目渠道，系统异常告警只使用全局系统渠道；
- 支持项目默认、标签和任务级运行告警策略；
- 支持冷却与恢复通知；
- 提供项目范围的 JSON、Prometheus 和受令牌保护的只读快照；
- 系统配置包与项目配置包分离，支持脱敏导出、导入预检与版本恢复。
通过独立安装的本地 stdio MCP 服务，让 AI 客户端按项目查询任务与运行记录、分析失败、对比成功基线，并读取已保留的截图。控制台“Skill / MCP”页面可生成当前项目的连接配置并下载操作 Skill。
连接默认只读；显式启用执行后，可在用户授权范围内运行已有任务。真实执行可能更新健康状态并发送告警。安装、配置和工具说明见 Skill + MCP 接入。
推荐使用 Docker Compose：
git clone https://github.com/liyanqing90/PulseGuard.git
cd PulseGuard
docker compose up --build -d默认发布到 0.0.0.0:8787：
- 本机：
http://127.0.0.1:8787 - 局域网：
http://<本机局域网 IP>:8787
检查状态：
docker compose ps
docker compose logs --tail 80 pulseguard
curl http://127.0.0.1:8787/api/health如只允许本机访问，在 .env 中设置：
PULSEGUARD_PUBLISH_HOST=127.0.0.1
PULSEGUARD_HOST=0.0.0.0
PULSEGUARD_PORT=8787
PULSEGUARD_PUBLISH_PORT=8787
PULSEGUARD_ALERT_DETAIL_BASE_URL=http://127.0.0.1:8787主节点启用 Relay：
export PULSEGUARD_RELAY_PUBLIC_HOST="<主节点公网 IP>"
docker compose -f docker-compose.yml -f docker-compose.relay.yml up --build -d默认只需开放公网 TCP 9443。worker 不映射 8788 到宿主机，只通过 relay-client 主动连接主节点。
Relay 使用自签 TLS、server fingerprint pinning、一次性部署凭据、Token 哈希/加密存储和内部控制网络。完整部署与安全说明见 运维与运行参考。
| 层级 | 技术 |
|---|---|
| Backend | FastAPI、SQLite、Playwright Python、uv |
| Frontend | React、TypeScript、Vite、Ant Design |
| Runtime | Docker Compose 或本地开发进程 |
| Storage | SQLite、data/、reports/ |
| Remote execution | Direct worker、WebSocket Relay |
- 单实例、本地或 LAN 优先；
- 默认 SQLite，不要求外部数据库；
- 子节点只执行任务，不拥有调度、告警或主数据；
- 自定义 Python 脚本是可信本地能力，不是安全沙箱；
- 失败证据有保留策略，不把完整运行产物永久保存；
- 录制器不是主线，多步骤探活优先使用模板、结构化规则和前置脚本。
| 文档 | 内容 |
|---|---|
| 运维与运行参考 | 本地开发、浏览器池、多节点、Relay、Token、接口和排障 |
| 项目公共方法库 | Python 方法复用、保存校验、执行快照与项目导入导出 |
| API 健康判定 | 动态请求、最后响应校验与执行诊断 |
| Skill + MCP 接入 | AI 项目查询、失败诊断、截图与授权探活 |
| 中国网络环境部署 | 国内镜像与依赖环境部署 |
| 火山与本地节点部署 | 火山主节点、本地子节点和迁移流程 |
| English README | English overview and setup |
后端：
uv run python -m unittest discover -s backend/tests -p 'test_*.py' -v前端：
cd frontend
npm run build锁文件与部署检查：
uv lock --check
.\scripts\deploy.ps1backend/ FastAPI 后端、存储、运行器、告警、测试
frontend/ React 前端、页面、组件和样式
integrations/mcp/ 独立安装的 stdio MCP 服务、锁文件和集成测试
.agents/skills/ 可分发的 PulseGuard AI 操作 Skill
data/ SQLite 数据目录
reports/ 截图、Trace、Response Body 和归档摘要
docs/ 部署、设计和运行文档
Dockerfile 主节点镜像
docker-compose.yml 主节点部署
docker-compose.relay.yml Relay 服务
Dockerfile.worker 子节点镜像
docker-compose.worker.yml 子节点部署
PulseGuard 由 青野 创建和维护。