cpra

Continuous Pulse and Recovery Agent
检查服务、发送告警，并执行你配置的恢复操作。

CPRa 是一个用 Go 编写的自托管监控与恢复代理。它按计划对你的服务运行 健康检查，根据可配置的阈值开启和关闭事件，发送通知，并在服务 失败时执行恢复操作——重启容器、调用 webhook、重启或扩缩 Kubernetes 工作负载、重启 EC2 实例、重启 systemd 单元。它以单个服务器二进制文件的形式发布，内置只读仪表盘、 HTTP API 以及 cpractl 命令行客户端。它采用 MIT 许可。

文档： ziad-hsn.github.io/cpra — 快速开始 · 监控配置 · 驱动 · HTTP API · 部署 · 常见问题

文档与当前开发

文档源包含当前开发参考以及针对早期修订版本的明确标注日期的指南。 已发布站点单独更新。 版本与可用性界定了这些边界：

• 此源码包含 Raft 持久化、历史/SLO、加密管理资源、 仪表盘表单以及 SDK/CLI 采集工作流。
• 实现进度 记录了已完成的检查以及剩余的外部 worker 集成和发布门禁。
• Go SDK 记录了当前源码契约；公共 模块版本和下载消费者资格认证仍待完成。
• 早期候选指南描述固定的 410fbfb 修订版本，并不构成本开发分支的发布资格认证。

发布计划管理 发布。源码可用并不代表已完成提供商或耐久性验证。

快速开始

需要 Go 1.25 或更高版本、Make，以及 Python 3 用于下面的源码工作区。 仓库已包含构建好的仪表盘资源。

Make 会为应用程序及其本地 SDK 模块创建一个被忽略的 bin/cpra-sdk.work，因此可以从该检出构建未发布的 SDK 候选版本。 集成示例模块仍为可选启用。显式的 GOWORK 路径或 GOWORK=off 优先；Make 从不更改所选的外部工作区。

make
cp examples/monitors.yaml monitors.yaml
# Set the service address in monitors.yaml.
./bin/cpra -yaml monitors.yaml

对于直接使用 Go 命令，请在 make dev-workspace 之后显式选择工作区：

GOWORK="$PWD/bin/cpra-sdk.work" go test ./internal/cpractl/cli

官方发布构建保留 GOWORK=off，并要求单独取得资格的 模块依赖。本地工作区构建并不代表公共模块 可用性或发布就绪。

状态默认持久保存在平台的用户状态目录中（cpractl local paths）；Linux 系统服务显式使用 /var/lib/cpra。在重启期间保留该目录。显式的 -data-dir 会覆盖运行时配置和平台默认值。旧版 ./cpra-data 需要显式路径或停止迁移。使用 -runtime-config examples/runtime-memory.yaml 进行一次性运行。持久化与恢复描述了身份、未知结果和完整备份。

使用配置的 API 凭据打开 http://localhost:8060。 管理设置启用当前 SDK 命令，例如 ./bin/cpractl get monitors；这些命令使用稳定的资源 ID。缺失或格式错误的配置会停止启动。空配置需要 -allow-empty。

该示例检查一个 HTTP 端点并将事件状态转换写入 alerts.jsonl。每个监控项可以指定检查间隔、超时、失败阈值、恢复阈值、通知目标以及恢复操作。维护窗口在检查继续的同时抑制告警和恢复；它们使用五字段 cron 表达式、持续时间和 IANA 时区。

驱动

功能	默认构建	可选构建标签
检查	HTTP、TCP、ICMP、DNS、UDP、TLS、Docker、gRPC 端口可达性	redis postgres mysql mongo rabbitmq kafka
恢复	Docker、HTTP webhook	kubernetes aws systemd
告警	Log、Slack、PagerDuty、email、webhook、Telegram、Discord、Opsgenie、Mattermost、VictorOps、Pushover、Datadog	teams twilio

make BUILD_TAGS='redis postgres kubernetes'

grpc 检查测试 TCP 端口；它不调用 gRPC 健康服务。UDP 检查需要负载和回复。PagerDuty 需要 Events API v2 路由键。Email 使用带 STARTTLS 的 SMTP 中继；未实现 SMTP 用户名/密码认证。

TLS warn_days 会产生黄色告警和降级的监控状态，但不启动恢复；critical_days 会使检查失败并遵循正常的恢复策略。Pushover 紧急优先级接受以秒为单位的 retry 和 expire，默认分别为 60 和 1800。Docker 恢复在其超时被省略时保留守护进程的停止宽限期。

MongoDB 检查需要直接的 mongodb:// URI。所选驱动无法按检查截止时间限制初始 mongodb+srv:// 发现，因此 CPRa 拒绝该模式。Kubernetes 恢复支持 token、证书和集群内凭据；kubeconfig exec 凭据插件被拒绝，因为它们可能超出恢复截止时间。

访问

服务器默认监听回环地址。其他绑定地址需要认证令牌。将令牌保存在服务账户可读的文件中：

./bin/cpra -yaml monitors.yaml -web.addr 0.0.0.0:8060 -web.auth-file /run/secrets/cpra-token
./bin/cpractl --server https://monitor.example.com --token-file /run/secrets/cpra-token get monitors

浏览器登录使用用户名 cpra 和令牌作为密码。API 接受 Bearer 令牌。服务器和 CLI 还会读取 CPRA_AUTH_TOKEN 和 CPRA_AUTH_TOKEN_FILE。远程访问需要 HTTPS 反向代理；内置监听器提供 HTTP。

清单以进程账户的权限授权检查、通知目标和恢复操作。使用可信配置。-ssrf-protect 在连接时阻止非公共 HTTP 目标；它不限制其他协议或本地操作。性能分析为可选启用。将令牌文件和包含凭据的清单保存在版本控制之外。

行为与限制

• 单节点 Raft 在分发前提交事件状态和操作意图。已启动但结果中断的外部操作在重启后保持为未知；健康检查恢复。这是单节点持久化，没有分布式故障转移。
• 每个事件允许一个恢复操作。成功恢复后必须跟随配置的连续成功检查。检查提供商记录以了解未知操作；重启不会自动重复它们。
• 通知端点结果是独立的。一个成功的端点不会因为另一个端点失败而被重复。已确认的可重试拒绝允许每个端点最多三次尝试。传输接受并不确认已送达个人。
• /api/v2/healthz 报告存活状态。/api/v2/readyz 要求已初始化的准入、控制器进度和可用存储；显式空配置可以就绪。仪表盘投影新鲜度单独报告。提供商中断不会使进程死亡。
• 机群视图增量更新，保留数字路由并添加稳定的 monitor_id 值。页面有界。/api/v1/history 保留事件和操作事件 30 天；/api/v1/state 暴露持久化和未知操作；/api/v1/slo 暴露测量的延迟分布。所有内容保持只读并使用现有认证。
• 不保留原始健康检查历史。当前计数器和聚合 SLO 窗口在重启后保留；测量覆盖中的缺口是明确的。参见测量的 SLO 定义。
• JSON 增量解码。YAML 要求监控项使用块序列，并将每个条目和元数据限制为 1 MiB。两种格式都有解压输入预算。内存使用随监控项数量增长；容量取决于检查间隔、目标和主机资源。
• Worker 扩缩使用 Erlang C 并带有 Allen-Cunneen 可变性调整和 15% 默认余量。到达间隔和执行时间使用最新的 256 个观测值。该模型估计平均延迟。观测到的百分位反馈使用 30 秒控制窗口、有界增长以及在降低容量前的健康保持。五分钟健康检查目标为 p99 队列延迟 ≤250 ms 和计划到提交结果 ≤5 秒。Worker 限制仍然存在；这些是测量目标而非 SLA 保证。
• 配置在启动前加载。不支持实时重载和运行时队列迁移。

检查与打包

make check
make test-all-drivers

重建仪表盘需要 Node.js 24.21.0、pnpm 11.22.0 和 Python 3：

make dashboard-build dashboard-check
make release VERSION=v0.1.0

记录的发布配方使用校验和固定的 Go 1.27.1 编译器和显式源码身份。它生成未剥离符号、 优化的服务器/客户端归档，适用于 Linux、macOS 和 Windows 的 amd64/arm64， Linux 软件包、源码归档和证据清单。Go 1.25 兼容性 是单独的测试。原生执行门禁对每个平台进行资格认证；仅成功 交叉构建并不代表支持。

版本化安装只需要 Go 和已提交的内嵌资源：

go install github.com/ziad-hsn/cpra@VERSION
go install github.com/ziad-hsn/cpra/cmd/cpractl@VERSION
cpractl local init
cpra -capabilities

将 VERSION 替换为实际已发布的版本。原生安装 记录了全驱动构建、标准路径、原生监督器、本地所有权 以及停止的备份/恢复。初始配置故意为空。

生产镜像使用相同的分阶段发布可执行文件；源码构建 使用 docker/Dockerfile.dev。生产 Compose 使用稳定的命名卷、 只读配置、UID 1001、有界日志和回环发布的 API。 Helm chart 使用一个 StatefulSet 所有者并保留存储，支持大型 基于文件的清单，并区分 Helm 3 和 4 操作。遵循 容器和 Helm 指南以在启动任一途径前准备认证和 配置。

发布证据

Go SDK 和可选的 外部 worker 库 是独立模块。 cpractl 使用公共 SDK 进行管理和观测请求，具有稳定的 资源 ID 和游标分页。Worker 协议仍需要其 单独的服务器资格认证；这两个模块均未由本工作发布。 四个 SDK 集成课程演示队列 注册、AWS 注销、Kubernetes Service 发现以及 DAO/SMS worker。SDK 指南和完整 API 参考描述了它们的方法、字段和验证边界。

SDK 状态记录了剩余门禁， SDK 验证区分 已执行的测试与待定的服务器和发布证据。根 go test ./... 不包含嵌套模块；使用上面的源码工作区运行 make sdk-check。官方发布保留 GOWORK=off，并要求 SDK 版本 首先发布。

持久化实现是发布候选版本。完整提供商验证和百万监控项 24 小时耐久性门禁需要完成的证据，才能提出完整的发布就绪声明。用户配置的实时验证覆盖 33 种驱动类型，并且从不通过缺失的配置。验证说明区分本地操作、提供商账户、比较和耐久性。