通知、日报与备份¶
这一页写给负责配置“守护进程往外发什么、往下存什么”的操作员:日报时间,通知渠道和它们的凭据,发给外部监控的心跳,以及数据库备份和恢复。
未验证。 经 Telegram 和邮件投递,以及发给外部服务的心跳,都只用假的传输层测试过,没有任何消息真正发到过外部服务。见状态与已知限制。
现在有什么¶
| 功能 | 用什么配置 | 状态 |
|---|---|---|
| 日报 | 配置文件里的 report_time、report_timezone |
有阶段管着设备时,由 serve 生成。 |
| Telegram 渠道 | 环境变量 | 设了对应变量,serve 就会建立。 |
| 邮件渠道 | 环境变量 | 设了对应变量,serve 就会建立。 |
| 发给外部监控的心跳 | 环境变量 | 两个 URL 都设了时由 serve 构建;只设一个则拒绝启动。 |
| 数据库备份 | backup_dir、backup_interval_seconds |
配了 backup_dir,serve 就会执行。 |
这一页的所有改动都在 serve 启动时生效。配置项的说明见配置参考。
设置日报时间¶
- 停掉守护进程。
- 在配置文件里填这两项:
report_time 是 24 小时制的 HH:MM。report_timezone 是 IANA 时区名。默认值是 08:00 和 UTC。
3. 启动 serve。
之后的行为(runtime.py 的 _daily_report 和 observer/report.py):
- 本地时间过了
report_time,就生成昨天(按本地日期)的日报。只有在有阶段管着设备时才生成:从一轮里第一个阶段启动开始,到这一轮交付或中止为止。 - 停机之后会补报漏掉的每一天,从最早的开始,最多补最近七天。
- 日报包含各项读数的时间加权均值、数据覆盖率和缺口、当天的保护动作和人工干预,还有一节“Frozen readings”(读数冻结),列出当天传感器一直报同一个值的各个时段(例如
temp stuck at 24 from 08:00 to 10:05,还没结束的会标(still frozen);时段是因为传感器被移出检查而结束、并非读数又变了,会再加(no longer checked);在记录原因之前就关闭的时段标(close reason unrecorded),不能当作恢复),方便看出哪些数据段不可信。最多列五个时段,还没结束的排在前面,其余按开始时间排;多出的合并成最后一行and N more (temp, co2),写出被省略时段的传感器名。时间按日报时区显示;不在当天的时间会连日期一起显示,无法显示的时间写作“unknown time”。任何部分都不是模型写的。运行时没有传入范围、作物观察和待办,所以这几部分是空的。 - 每个项目每个日期只保存一份,存在
observer.sqlite3的observer_reports表里,并排进每个通知渠道的队列。
时区名写错,加载配置时不会报错。之后它会表现为一条类型为 tick_step、键为 report 的告警。
读取已保存的日报无路由。只能通过通知渠道看到它。
配置通知渠道¶
渠道的实现在 observer/channels.py。它们的设置只来自 serve 的进程环境,不来自配置文件。runtime.py 的 default_channels 只有在启动时某个渠道的两个必需变量都已设置,才会建立这个渠道。
| 渠道 | 必需 | 可选 |
|---|---|---|
| Telegram | GROWBRIDGE_TELEGRAM_TOKEN(机器人令牌)、GROWBRIDGE_TELEGRAM_CHAT_IDS(会话 ID,逗号分隔) |
无 |
| 邮件 | GROWBRIDGE_SMTP_HOST、GROWBRIDGE_EMAIL_TO(收件地址,逗号分隔) |
GROWBRIDGE_SMTP_PORT(默认 587)、GROWBRIDGE_SMTP_USER、GROWBRIDGE_SMTP_PASSWORD、GROWBRIDGE_SMTP_FROM |
- 停掉守护进程。
- 在启动
serve的环境里设置变量:
export GROWBRIDGE_TELEGRAM_TOKEN='YOUR_BOT_TOKEN'
export GROWBRIDGE_TELEGRAM_CHAT_IDS='YOUR_CHAT_ID'
scripts/ 里的安装脚本不会往后台服务里写环境变量,所以装成服务时,要自己把变量加进服务定义。未验证。
3. 启动 serve。
渠道的行为:
- Telegram 只向登记的会话 ID 发消息,没有任何读取来信的代码。邮件使用 STARTTLS,只有设了
GROWBRIDGE_SMTP_USER才登录。发件地址依次取GROWBRIDGE_SMTP_FROM、用户名、growbridge@localhost。 - 发出的消息有两类:每条告警发一次,格式是
[severity] message;每份日报发全文。告警解除时不发消息。 - 渠道返回
accepted、unknown或failed。没有被接收的消息 30 秒后重试,之后间隔逐次加倍,最长 30 分钟,总共最多尝试 20 次(observer/outbox.py)。这些数字是代码里的常量,不是配置项。所以结果为unknown时,同一条消息可能收到两次。
目前没有发送测试消息的命令。要确认投递是否正常,看 GET /wb/alerts:已配置渠道上的某条通知 900 秒还没投递出去时,run_health 告警里会点名 oldest_undelivered_alert。告警本身随时可以在这个路由读到,和有没有渠道无关。
一个渠道都没配时¶
两个渠道都没配置时,serve 的行为如下,已在模拟设备上核对过:
- 告警和日报都不会入队等待发送。告警照常记录,日报照常保存。
- 启动时产生警告级告警
notify_unconfigured。下次serve带着渠道启动时,它会被解除。 - 运行健康不受影响:
oldest_undelivered_alert只统计记在有发送器的渠道名下的通知。 - 以后配置了渠道并重启,所有仍未解除的告警会入队并从这个渠道发出。这期间已经解除的告警和已经生成的日报不会补发。
去掉一个渠道时也一样:已经记在它名下的通知保持 pending,不再计入运行健康;仍未解除的告警会在剩下的渠道上入队。
目前没有清空队列的命令。在已配置的渠道上用完 20 次尝试仍未被接收的通知,会让 oldest_undelivered_alert 一直不通过。
发给外部监控的心跳¶
已经实现的部分,在 observer/health.py 和 observer/channels.py 里:
- 两个信号:主机心跳每次发信号时都发;运行心跳只在运行健康正常时发。运行健康不正常时,改发失败信号,并停发运行心跳。
- 运行时每 60 秒发一次信号(
runtime.py的HEARTBEAT_SECONDS),运行健康由好变坏或由坏变好时立即再发一次。外部监控的宽限期要设得比 60 秒长。 HeartbeatChannel从某个环境变量里读 URL:发心跳时请求这个 URL,报失败时请求这个 URL 加上/fail。- 信号发不出去时,产生告警
external_monitor,键是host或run。
怎样配置¶
serve 读取两个环境变量(runtime_heartbeat.py,由 cli.py 的 _serve_auto_research 调用)。两个都填监控服务给你的 URL,例如 Healthchecks.io 的 ping 地址:
| 变量 | 信号 |
|---|---|
GROWBRIDGE_HEARTBEAT_HOST_URL |
主机心跳。 |
GROWBRIDGE_HEARTBEAT_RUN_URL |
运行心跳。失败信号发到同一个 URL 加上 /fail。 |
- 两个都设或者都不设。 两个都设时,
serve发送心跳。只设一个时,serve拒绝启动,并说明缺哪个变量:只监控一半的故障,看起来像有监控,其实没有。空白值按未设置处理。 - 都不设。 不发任何请求。运行时发出常驻警告告警
monitor_unconfigured(键heartbeats),下次serve带着两个变量启动时自动解除。 - URL 是机密。 只从环境变量读取,在发送信号时才读。它不会出现在任何日志行、告警文本、错误信息或
repr里。请求 URL 从不写进日志:serve以 INFO 级别运行,HTTP 库在这个级别会记录每个请求的 URL,所以logging_setup.py把httpx和httpcore的日志级别固定在 WARNING。这同时保护了 Telegram 机器人令牌,它是 Bot API 请求路径的一部分。 - 监控服务的宽限期要设得比 60 秒长;心跳停了,由监控服务自己向手机发告警。
未验证:心跳只用假的 HTTP 客户端测试过,没有任何信号发到过真实的监控服务。
运行健康本身每次评估都会计算,结果体现为 run_health 告警。探测项和阈值如下:
| 探测项 | 什么情况下不通过 |
|---|---|
growbridge_response |
60 秒没有收到设备的数据包。 |
executor_evaluation |
30 秒没有执行 Agent 的评估。 |
capture |
stale_seconds 秒内没有样本;有阶段管着设备时,改用运行单的 sampling.max_gap_seconds。 |
archive_write |
600 秒没有写入项目档案。 |
oldest_undelivered_alert |
已配置渠道上有通知 900 秒还没投递出去。 |
offsite_backup |
最近一次备份早于两个备份间隔。只有配了 backup_dir 才检查。 |
配置备份¶
- 停掉守护进程。
- 填写配置项:
目录要放在和数据目录不同的介质上。代码不检查这一点。间隔最小 60 秒,默认 21600(6 小时)。
3. 启动 serve。第一次备份在第一次评估时开始。完成后目录里有十二个文件:control、workflow、archive、observer、compute 和 agents,各有一个 <name>.sqlite3 和一个 <name>.sqlite3.manifest.json。
工作方式(runtime_backup.py、archive/backup.py):
- 多久一次。 六个数据库各自记着上次成功备份的时间,其中最早的那个超过间隔,就开始一次备份。备份在后台进行,不会拖住执行 Agent。
- 一致性。 每个数据库通过一个单独的只读连接、在同一个读事务里复制,所以副本是一个一致的状态,写入方也不会被阻塞。
- 完整性。 副本先用
PRAGMA integrity_check检查,通过后才替换上一份备份。复制或检查失败时,上一份备份原样保留。清单文件记录该文件的sha256、size和created_at(UTC 秒)。 - 只留一代。 每次备份都会覆盖上一份。要保留更早的副本,需要自己安排。
- 失败时。 产生带有错误信息的
backup告警,300 秒后才会再试。没配backup_dir时,backup_unconfigured警告一直挂着。
不在备份里的东西: 仅桥接模式的样本历史 growbridge.sqlite3,数据目录下 archive/ 里的文件(数据快照文件),agent_work/ 里的文件(研究报告文件),host_id 文件,以及配置文件。数据库里保存的是这些文件的记录和摘要,不是文件本身。
想手动检查一份备份,把文件和清单对一下即可,例如 shasum -a 256 /absolute/path/to/backup/control.sqlite3。这用的是产品之外的工具。
恢复备份¶
目前没有恢复命令。下面的步骤没有测试覆盖;只有一个测试打开备份文件,确认里面的记录和原库相同(tests/archive/test_archive_storage_backup.py)。
- 停掉守护进程。
- 逐个把备份文件和清单核对一遍。
- 把数据目录里这六个数据库原有的
*.sqlite3文件,以及旁边的-wal和-shm文件移走,再把六个备份文件复制进来。 - 提高恢复编号:
- 启动
serve,接着按故障处理手册里的“从备份恢复或更换写入主机”做。
恢复对恢复编号有什么影响。 把文件复制回去本身什么都不改变:恢复回来的控制数据库带着做备份那一刻的恢复编号,也没有任何机制能发现“发生过一次恢复”。让恢复变得安全的是第 4 步。它把编号加一,撤销所有写入权,作废排队的写入和所有审批,把没结束的阶段都移到 recovery_check,并让此前的会话和安全配置审批全部失效。为什么必须这样做,见控制与安全模型。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。