监控 borgmatic 漏跑任务并控制日志外传-未完纪

本文合并译编 borgmatic 官方的 How to monitor your backups 与 Healthchecks 两篇指南。原页没有个人署名，署名采用 borgmatic 文档贡献者。所有版本注记依 2026 年 10 月 5 日读取的官方正文保留。

有备份，还需要知道它有没有按时运行

有备份当然很好，但如果不能确认它正在定期运行，备份就很难真正让人放心。这正是监控和告警要解决的问题。你可以通过多种方式观察备份是否成功，选择哪一种取决于自己的基础设施。

任务调度器的失败告警：最容易开始的是运行 borgmatic 的 cron、systemd 等调度器。不过，如果任务根本没有被调度，例如调度器本身没有运行，通常也就没有失败告警。这仍是有用的第一道防线，尤其适合与下面的其他方式组合。
第三方监控服务：borgmatic 可以与监控服务和库集成，在备份过程中发送心跳。服务可在发生错误时告警；若支持失联检测，也能在设定时间内没有收到 borgmatic 心跳时告警。这些集成提供的功能不同，一般选用其中一个就足够。详见监控配置。
传统监控软件：让现有软件消费 borgmatic 的 JSON 输出，并记录最近一次成功备份的时间。后文介绍如何取得这些输出。
Borg 托管服务：一些 Borg 托管提供商把监控告警作为服务的一部分，提供集中查看备份的仪表盘，也可能在一段时间没有收到 borgmatic 心跳后告警。
一致性检查：它严格说不属于监控，但如果要确认备份不仅在运行，而且可以恢复，还应配置适当的一致性检查，或通过脚本进行完整的提取测试。
出错时运行命令：borgmatic 的命令钩子可以在备份执行出错时运行任意命令或脚本，比如发出短信告警。不过，borgmatic 根本没有启动时，这个钩子也不会触发。具体见准备与清理步骤。

图 1：原创监控职责示意。任务报错、完全漏跑和可恢复性是不同的问题。

编者说明：配置失联告警时，外部服务需要知道预计运行周期及允许的宽限时间。仅设置 on-error 钩子捕捉不到“任务完全没启动”。即使收到了成功心跳，也不能由此推出归档可以完整恢复。

让其他脚本消费 borgmatic 的输出

在 create、repo-list、repo-info 或 info 后加入可选的 --json，可以获得 JSON 格式输出。指定该选项时，Borg 其他非 JSON 输出会被抑制，以免干扰脚本捕获的 JSON。JSON 只输出到控制台，不会出现在 syslog 中。

获取最终配置

自 2.1.3 起：需要在脚本中消费 borgmatic 计算后的配置时，可以使用 config show：

borgmatic config show --json

这会以 JSON 输出 borgmatic 的完整配置，数组中的每个元素对应一个配置文件。也可以只请求某个选项的值：

borgmatic config show --option repositories --json

编者说明：完整配置可能包含仓库地址以及凭据相关设置。不要默认把整份输出上传到外部监控平台、公开工单或公共日志；如只需要仓库列表，应优先请求对应选项，并按实际输出判断是否需要脱敏。

查询最新归档

所有接收 --archive 的 borgmatic 动作，都可以把归档名称写成 latest。这样脚本无需先手动运行 borgmatic repo-list，就能直接访问最新归档。例如：

borgmatic info --archive latest

这里的 latest 是选择归档的便捷方式，本身不包含“最近多少时间内必须有备份”的告警规则。是否足够新，仍要结合调度周期判断。

接入 Healthchecks

Healthchecks 用于发现 cron 任务悄然失败或失联的情况，borgmatic 已内置相应集成。先在服务中创建账户和项目，取得用于该检查的唯一 Ping URL，再把它写入 borgmatic 配置。你也可以使用自托管的 Healthchecks。

healthchecks:
    ping_url: https://hc-ping.com/your-uuid-here

其中 your-uuid-here 是必须替换的占位符，不是一个可使用的账户或密钥。原文使用固定示例 UUID，本文为避免误发事件改成明确占位符。Ping URL 可用于向检查发送事件，应作为凭据保护，并核对它确实指向预期的 Healthchecks 服务。

1.8.0 之前：上述 healthchecks 选项要放在配置的 hooks: 区段下。较新版本使用上面的顶层结构。

采用此配置后，borgmatic 会在备份开始、结束或出错时通知 Healthchecks，但只有运行 create、prune、compact、check 中的任一动作时才触发这组监控。不要假定单独运行任意查询动作都会产生备份心跳。

在 Healthchecks 中可以选择多种通知渠道，让服务在备份失败，或超过指定时间没有收到 borgmatic 心跳时通知你。

明确决定是否发送日志

自 1.4.11 起：动作成功完成后，borgmatic 可以在成功通知的请求体中附带日志，日志因此会显示在 Healthchecks 界面中。原文指出 Healthchecks 每次心跳可接收的日志有 100 KB 限制。

自 1.6.1 起：通过 send_logs 控制是否发送日志。若需要控制日志外传，明确设置为 false：

healthchecks:
    ping_url: https://hc-ping.com/your-uuid-here
    send_logs: false

如果确实需要把日志发送到该服务，并已经核对内容和目标，可以改成 send_logs: true。原文的启用示例使用 true；本文的可复制示例改为 false，变化已明确标注。

2.1.0 及以后：省略 send_logs 时默认不发送日志，目的是避免将私密日志信息透露给第三方服务。
2.1.0 以前：省略该选项时默认发送日志。若使用支持此选项的旧版本且不希望发送，必须显式设置 false。1.6.1 以前没有该选项，不能依赖它关闭日志发送，应先按所用版本确认能力或升级。

动作或钩子出错时，borgmatic 会通知 Healthchecks；允许发送日志时，载荷也会附带包含错误本身的日志。但只有在运行 create、prune、compact 或 check 动作时发生的错误，才包含这类错误日志。发送的详细程度还可以通过 --monitoring-verbosity 调整；--list 与 --stats 也可能有帮助，详见 create 动作。

自 2.0.0 起：可以分别通过配置项 monitoring_verbosity、list、statistics 设置这些命令行选项的默认值。减少详细程度不等于对日志进行敏感数据脱敏；是否允许外传仍应由 send_logs 及部署策略明确控制。

Healthchecks 全部配置项

下面列出原文最新版本示例涵盖的全部选项。旧版本可能不支持某些选项，应该为所安装的 borgmatic 生成对应版本的配置示例。本稿把原文偏重“展示取值”的示例改成保持 TLS 验证、默认不发日志、完整报告任务状态的配置；它仍需要替换 Ping URL 后才可使用。

healthchecks:
    # 替换成自己的 Healthchecks Ping URL 或 UUID。
    ping_url: https://hc-ping.com/your-uuid-here

    # 验证 Ping URL 主机的 TLS 证书，默认 true。
    verify_tls: true

    # 是否在 finish、fail、log 状态附带日志。2.1.0 起默认 false。
    send_logs: false

    # 最多发送的日志字节数。默认 100000；0 表示全部、不截断。
    ping_body_limit: 100000

    # 可选 start、finish、fail、log；省略时默认全部状态。
    states:
        - start
        - finish
        - fail
        - log

    # 检查不存在时是否创建。默认 false；只适用于 slug URL 方案。
    create_slug: false

ping_url：开始、结束、错误或仅发送日志时使用的 URL / UUID。不要把生产 Ping URL 写进公开文章或版本库。
verify_tls：默认 true。原文完整示例填的是 false；本文明确改为 true，因为关闭证书验证会削弱对目标主机的认证。自托管服务也应配置可信证书，而不是照搬关闭验证。
send_logs：控制 finish、fail、log 状态的日志载荷；原文示例 true 已改为 false。旧版本默认行为见上节。
ping_body_limit：字节上限，理想情况下与 Healthchecks 服务端的 PING_BODY_LIMIT 一致。原文展示 200000；本文使用默认的 100000。设置 0 会禁用 borgmatic 侧截断、发送全部日志，但不会自动改变服务端上限。
states：可以列出一个或多个 start、finish、fail、log。原文示例只列 finish；本文列全四种。只选择 finish 会改变可观察到的状态范围，不应把它与完整状态监控混淆。日志是否附带仍由 send_logs 控制。
create_slug：默认 false。设为 true 时可在检查不存在时创建，但只适用于 https://hc-ping.com/<ping-key>/<slug> 形式，而不是 https://hc-ping.com/<uuid>。原文展示 true；本文与 UUID 占位符配套使用 false。