Paw Pulse

Paw Pulse

面向可自托管大模型服务的推送式心跳与性能监控工具 （Ollama、llama.cpp、vLLM，以及任何兼容 OpenAI 的服务）。无需将服务暴露到互联网， 即可知道家中的 AI 设备何时宕机或运行变慢。

在线实例：https://pulse.dougalpaw.com

由 AI Agent Pup 构建、部署和运维，是 Dougal Paw 项目的一部分。没有账号、不会存储 IP，也不收集个人数据：监控项都是匿名的，仅通过随机 ID、接入令牌和管理令牌进行识别。

工作原理

一个小型客户端脚本（pawpulse.sh）在托管大模型服务的设备上运行，每隔几分钟向此服务发送一次心跳。如果在配置的宽限期内没有收到心跳，监控状态就会切换为 down。你的大模型服务永远不会接受入站连接。

设备上没有大模型？设置 LLM_KIND=none 即可发送普通心跳，这样同样的警报也适用于 NAS、备份任务或任何 cron 任务。

对于 Ollama，它还可以捕捉不易察觉的故障：设置 slow_tps_threshold，在生成速度变慢时收到提醒；设置 min_gpu_pct，在模型从 GPU 回退到 CPU 时收到提醒（客户端会从 /api/ps 读取 size_vram；需要 jq）。

指南：

• 如何监控 Ollama 并在服务宕机时收到提醒
• 检测 Ollama 是否回退到 CPU

技术栈

• Cloudflare Workers（免费套餐）+ D1 + Cron Triggers。
• TypeScript，使用 Hono 作为轻量路由器。
• 无其他运行时依赖。

项目结构

src/
  index.ts       Hono app: routes, pages, cron entrypoint
  service.ts     Business logic shared by REST and MCP
  db.ts          D1 queries
  state.ts       Pure state-machine logic (unit tested)
  validation.ts  Pure input validation (unit tested)
  cron.ts        Per-minute sweep: state transitions + alert dispatch
  webhook.ts     Outbound alert delivery (Discord-aware, generic JSON fallback)
  mcp.ts         Remote MCP server (Streamable HTTP, stateless)
  openapi.ts     OpenAPI 3.1 document served at /openapi.json
  llms.ts        /llms.txt content
  templates.ts   HTML pages (/, /privacy, /s/:id)
  badge.ts       Shields-style SVG badge renderer
  static/        Served static assets (pawpulse.sh)
migrations/      D1 schema (0001_init.sql)
test/            node:test unit tests for state.ts and validation.ts

API

完整规范请参阅 /openapi.json，简要概述请参阅 /llms.txt。

• POST /v1/monitors — 创建监控项。
• POST /v1/monitors/:id/beat — 发送心跳（Authorization: Bearer <ingest_token>）。
• GET /v1/monitors/:id/status — 查看当前状态；公开监控项无需认证。
• GET /v1/monitors/:id/heartbeats — 查看近期心跳。
• PATCH / DELETE /v1/monitors/:id — 管理或移除监控项（Authorization: Bearer <manage_token>）。
• GET /s/:id — 公开的 HTML 状态页。GET /badge/:id.svg — 状态徽章。
• GET /pawpulse.sh — 客户端脚本。
• POST /mcp — 远程 MCP 服务（见下文）。

MCP

https://pulse.dougalpaw.com/mcp 是一个远程 MCP 服务（Streamable HTTP）。它是无状态的：每个 POST 请求都携带一条 JSON-RPC 消息，并获得一个 JSON 响应；没有会话，也没有 SSE 流，这符合规范要求。它支持协议版本 2025-06-18、2025-03-26 和 2024-11-05。

工具：create_monitor、setup_instructions、get_status、 list_heartbeats、update_monitor、delete_monitor。这些工具使用与 REST API 相同的服务层。连接时无需认证；会更改监控项的工具会将其 manage_token 作为参数。

{ "mcpServers": { "pawpulse": { "type": "http", "url": "https://pulse.dougalpaw.com/mcp" } } }

警报

设置监控项的 webhook_url 后，在监控项宕机、运行变慢或恢复时，你就会收到消息。消息格式根据 URL 自动选择：Discord、Slack、Microsoft Teams （Workflows）、Telegram（https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>） 和 Google Chat 会收到原生消息；其他任何 https URL 都会收到通用 JSON （content、text、monitor_name、alert、state、timestamp）。 可自托管的用户可以在 wrangler.toml 中将 ALERTS_ENABLED = "false"，关闭所有警报。

开发

pnpm install
npm test         # unit tests (node:test, no network/D1 needed)
npm run typecheck

部署

npx wrangler d1 create pawpulse                 # once; copy the database_id into wrangler.toml
npx wrangler d1 migrations apply pawpulse --remote
npx wrangler deploy

Cron 每分钟运行一次（* * * * *），扫描监控项是否超过宽限期，以及是否达到慢速 TPS 阈值。每次状态变化最多触发一个 webhook，并限制每次运行的出站 webhook 请求数，以确保不超过 Workers 免费套餐的 50 次子请求限制。

隐私

请参阅 /privacy。任何地方都没有账号、Cookie、分析功能或 IP 日志。DELETE /v1/monitors/:id 会永久删除监控项及其所有心跳。

许可协议

MIT。请参阅 LICENSE。