BackupX/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/operations/monitoring.md

sidebar_position, title, description

sidebar_position	title	description
3	监控与告警	健康探针、Prometheus 指标、初始告警规则和运维验证。

监控与告警

BackupX 提供低开销健康端点和独立 Prometheus Registry。监控既要覆盖控制面，也要覆盖备份、恢复、验证和复制的实际结果。

探针

端点	含义	预期响应
/health	存活：HTTP 进程可响应	HTTP 200，status: live
/ready	就绪：进程可访问 SQLite	正常为 HTTP 200 与 status: ready；数据库故障为 HTTP 503
/api/health	带 API 前缀的存活别名	与 /health 相同
/api/ready	带 API 前缀的就绪别名	与 /ready 相同
/metrics	Prometheus 指标	指标启用时为 HTTP 200

/health 用作 liveness，/ready 用作 readiness 或负载均衡流量判断。外部存储暂时不可用不应直接触发进程重启，应通过任务和存储目标告警处理。

curl -fsS http://127.0.0.1:8340/health
curl -fsS http://127.0.0.1:8340/ready
curl -fsS http://127.0.0.1:8340/metrics | head

这些端点不需要认证，只允许编排器和监控网段访问。

Prometheus 抓取

scrape_configs:
  - job_name: backupx
    scheme: https
    metrics_path: /metrics
    static_configs:
      - targets: [backup.example.com]

Nginx 终止 TLS 时，应只放行 Prometheus 源地址访问 /metrics。内部采集器每 30 秒刷新存储、节点、命令队列和 SLA Gauge。

BackupX 指标

指标	类型	标签	用途
backupx_app_info	gauge	version	当前版本元数据
backupx_task_run_total	counter	status、task_type	备份结果
backupx_task_run_duration_seconds	histogram	task_type	备份耗时分布
backupx_task_bytes_total	counter	task_type	备份产出字节数
backupx_task_running	gauge	无	当前备份并发
backupx_storage_used_bytes	gauge	target_name、target_type	按目标记录的使用量
backupx_node_online	gauge	node_name、role	节点在线状态，1 或 0
backupx_agent_command_queue_depth	gauge	node_name、role	待处理与已派发命令
backupx_agent_command_running	gauge	node_name、role	Agent 长任务数
backupx_agent_command_timeout_total	gauge	node_name、role	超时命令数快照
backupx_verify_run_total	counter	status	验证结果
backupx_restore_run_total	counter	status	恢复结果
backupx_replication_run_total	counter	status	复制结果
backupx_sla_breach_tasks	gauge	无	超出已配置 RPO 的启用任务数

同一端点还注册了标准 Go Runtime 与进程指标。

初始告警规则

应根据各环境计划与 RPO 调整窗口和阈值：

groups:
  - name: backupx
    rules:
      - alert: BackupXTargetDown
        expr: up{job="backupx"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: BackupX metrics endpoint is unreachable

      - alert: BackupXNotReady
        expr: probe_success{job="backupx-ready"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: BackupX readiness check is failing

      - alert: BackupXBackupFailure
        expr: sum(increase(backupx_task_run_total{status="failed"}[15m])) > 0
        labels:
          severity: warning
        annotations:
          summary: A BackupX backup failed

      - alert: BackupXSLABreach
        expr: backupx_sla_breach_tasks > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: One or more backup tasks are outside RPO

      - alert: BackupXAgentOffline
        expr: backupx_node_online{role="agent"} == 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: BackupX Agent is offline

      - alert: BackupXAgentQueueBacklog
        expr: backupx_agent_command_queue_depth > 20
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: BackupX Agent command queue is growing

BackupXNotReady 示例假定存在名为 backupx-ready 的 Blackbox 探针任务。未部署 Blackbox Exporter 时，应改用负载均衡或编排器的 readiness 信号。

运维仪表盘

建议同时展示：

• 按任务类型统计成功率与失败率。
• P50、P95、最大执行时长及其与备份窗口的关系。
• 产出字节数与预期数据变化率。
• 当前任务数与 backup.max_concurrent。
• 离线 Agent、队列深度、运行命令和超时数变化。
• 存储增长、提供商剩余容量和保留策略清理。
• SLA 违约数及关键任务最近成功备份时间。
• 验证、恢复和复制成功率。

Prometheus 存储使用量来自 BackupX 记录元数据，不一定等同于提供商计费容量，应另行监控提供商配额和文件系统剩余空间。

部署后验证

安装、升级、代理变更或恢复后：

1. 分别从本机和公开代理检查存活与就绪。
2. 确认 Prometheus 只看到一个活动 Master，并带有预期版本标签。
3. 确认所有预期 Agent 的 backupx_node_online == 1。
4. 执行小型备份并确认成功 Counter 增长。
5. 执行验证或隔离恢复并确认对应 Counter 增长。
6. 触发测试通知并验证告警投递链路。

探针或指标异常时继续参考故障排查。