跳转至

控制与安全模型

English

这一页写给需要信任、审查或修改「从决定到 BLE 写入」这条通路的人。它说明为什么所有写入都要过同一个关口,以及这个关口在每一步做了什么。

现状。 本页描述的行为都有针对模拟 AC5 的测试覆盖,但没有一项在真实的 AC5 上验证过;真机和无线链路会怎么出故障,模拟器也演示不出来。见状态与已知限制。

要解决的问题

操作员接管后把灯调到 50%。自动日程里还排着一条「灯调到 80%」的指令,两秒后发了出去。人工设置被覆盖了,而没有任何人做过这个决定。

进程重启、从备份恢复、另一台机器、回执丢失的指令,都可能造成同类事故。控制模型用一个办法把它们全部堵住:每次写入都要出示一张带编号的许可,这张许可在字节发出的那一刻必须仍然有效,并且由同一个服务来查。 这个服务就是 control/service.py 里的 ControlService。模型角色根本调用不到它,见Agent 一览。

写入权

写入权是控制服务账本里的一行记录,写明谁可以写、写哪些通道、为哪个阶段写。每次授予都得到一个新编号(right_number),编号一旦撤销就再也不能写。

种类(RightKind) 用途 可以写什么 何时授予
stage 阶段处于 running 时的自动控制 运行单里主机控制的通道 启动、续跑、交还、切换运行单版本时
manual 人工接管期间的某一位操作员 同样的通道,且只能由这位操作员写 接管时
care 养护规则 只能写运行单养护规则里列出的「通道 + 档位」 和阶段写入权一起授予;阶段结束后继续保留
protection 保护规则 只能写已批准安全配置里列出的「通道 + 档位」 操作员批准安全配置时

从 control/rights.py 和 ControlService.grant 可以读出三条规则:

  • 普通控制同一时刻只归一方。 已经有一个阶段写入权在手时,再申请阶段写入权或人工写入权都会被拒绝,拒绝码是 right_held。工作流服务总是先撤销,再授予。
  • 写入权的范围很窄。 请求超出了写入权的通道、列出的取值、阶段或操作员,就以 scope 拒绝。运行单里交给 AC5 自己定时的通道(Ownership.DEVICE)不在任何写入权里,所以 DiAGRI 里没有任何东西能写它。
  • 用编号,不用开关。 「自动控制已开启」不是一个开关,否则迟到的指令可能恰好在不该读的时候读到它。每条指令都带着创建时的编号,下发时再核对一次这个编号。

举个例子。阶段启动时拿到阶段写入权 7。操作员暂停,7 被撤销。操作员续跑,执行 Agent 改用写入权 8。在编号 7 之下创建的指令,不管多晚到,都会被 right_invalid 拒绝。

交接和下发共用一个关口

ControlService.gate 是一把分两级优先的锁。有三件事会去拿它:下发一次写入、完成一次交接,以及 reconcile_unsettled。

  • submit 先核对请求并存下来,然后拿锁,把所有检查再做一遍,才下发。
  • handover 先撤销编号,作废这个编号名下还在排队的动作,然后拿一次锁。拿到锁,就意味着已经在途的那次写入拿到了回执。

优先级。 紧急级的排队者先于普通级;同一级内先来先得。紧急的有:保护写入权名下的写入、灌溉结束时的关泵、handover。普通的有:其余所有写入、灌溉的开泵、reconcile_unsettled。保护写入还会作废自己通道上仍在排队的普通写入,免得它们排在后面把保护写入的效果撤销(已经在途的那次写入不动);被作废的动作会写“superseded by a protection write on <通道>”。关口不会抢占:紧急的调用只等已经在途的那一次写入,不必等排在它后面的普通写入。pump_off()(联锁路径)根本不进关口。

为什么要共用一把锁:handover 返回时,旧编号名下既没有排队的写入,也没有在途的写入。交接和写入不可能交错,工作流服务这才能放心地授予下一个写入权。

检查什么,查两遍

每个请求在入队时过一遍 _authorize,进入关口后再过一遍。依次是:

  1. 配置里启用了控制。
  2. 本机是登记的写入主机。
  3. 写入权存在、没有被撤销,并且属于当前的恢复编号。
  4. 请求在写入权的范围之内。
  5. 请求不是开启水泵。
  6. 控制服务已经完成启动,关泵联锁没有生效,旧传输已确认停止。对阶段写入权和人工写入权,还要求之前没有结果未定的动作。
  7. BLE 连接正常。对阶段写入权和人工写入权,还要求遥测数据是新鲜的。

检查不通过就是 Denied(code),拒绝码见拒绝码与事件类型。保护规则的写入权不做第 6 项检查,原因见下文「保护规则不随阶段写入权失效」。

先记意图:动作账本

每次写入都先记录,再下发。记录依次经过这些状态:

状态(ActionState) 含义
pending 意图已落库,还没有发出任何东西。
maybe_sent 字节发出之前写下。
confirmed 回读到了计划的档位。
failed 设备拒绝,或回读到的档位、模式不对。
unknown 写入可能生效了,也可能没有。
void 下发之前被取消:交接、第二遍检查没通过、同一通道上的保护写入,或进程重启。

为什么需要 maybe_sent。设想设备已经执行了指令,进程却在回执落库之前崩溃。账本如果只认得 pending,重启后就会把这条指令再发一次。有了 maybe_sent,启动时会把这个动作标为 unknown,并且不重放(_close_unfinished)。

请求按 request_id 幂等。同一个编号、同样的参数,返回已存的记录;同一个编号、不同的参数,以 request_id_reused 拒绝。账本的代码在 control/ledger.py,每条记录包含哪些内容见数据、档案与可追溯性。

回读与结果未知

设备上看得到,才算写成了。下发之后,control/device.py 的 DeviceIO.write 最多读三次设备(READBACK_POLLS),要求档位等于计划值,并且通道处于手动模式(modeType 为 0)。没等到回复、连接中断,或者回读做不了,结果就是 unknown。

对 unknown 的处理原则是:去核对设备,绝不重发。

  • 只要还有未定的 unknown 动作,阶段写入权和人工写入权名下的写入都以 unsettled 拒绝。
  • 执行 Agent 上报 RESULT_UNKNOWN,运行中的阶段随之暂停。
  • reconcile_unsettled 读一次设备,在动作记录上写明「已生效」或「未生效」。操作员续跑或接管时,以及阶段尝试退出 recovery_check 时,都会执行它。它从不处理水泵动作。
  • 操作员登记现场核对后,所有 unknown 动作都算已核对(onsite_check)。

为什么不重发:对多数通道来说,同一条指令再发一次并无害处,但程序无从知道,现在的情形是否还是当初下这条指令时的情形。这要由人,或者一次新的回读来判断。

读不到状态,不等于状态一致

执行 Agent 会拿设备的实际状态和自己最后确认过的状态比较。如果这次回读本身失败了,答案是「不知道」,执行 Agent 绝不把它当成「设备和预期一致」。executor/engine.py 分三种情况处理:

  • 阶段运行期间。 短暂的失败可以容忍。读不到状态的时间一旦超过运行单的 sampling.max_gap_seconds,执行 Agent 就上报 READINGS_STALE,其中 detail.reason = "state_unreadable",阶段随之暂停。只要成功读到一次,计时就清零。
  • 掉线恢复之后。 读不到状态按「设备与预期不符」处理,这次掉线因此上报为 DISCONNECT_AFFECTS。
  • 保护规则正在维持某个档位时。 见下文的重发规则。

以 max_gap_seconds = 120 为例:连接正常,传感器数据包也在不断到达,但状态查询一直失败。头 120 秒阶段照常运行,之后暂停,等操作员处理。对应的测试在 tests/executor/test_executor_unreadable.py。

水泵

水泵开着的时候如果连接断开,程序无法保证及时把它关上。所以任何自动路径都不允许开泵:会开泵的定时动作、照料规则或反馈规则都会让运行单被拦下(pump_action)。

  • submit 从不开泵。 档位不为 0 的水泵请求,不管用哪种写入权,都以 pump_on_forbidden 拒绝。执行 Agent 在更早的一步就已经拒绝,执行结束动作时也会跳过水泵。
  • 只有 irrigate 能开泵。 入口是 POST /wb/irrigation,以下条件必须全部满足:操作员会话来自局域网入口;阶段处于 manual,且人工写入权属于这位操作员;时长大于 0 且不超过 max_pump_seconds;距离上次灌溉已超过冷却时间 pump_cooldown_seconds,并且没有另一次灌溉正在进行。
  • 计划内浇水也是同一次运行,只是从阶段页启动。 运行单把浇水写成 irrigation 类人工任务并给出 seconds(最多 60 秒)。到期时,局域网入口上的操作员用 POST /wb/stages/{stage_id}/manual-tasks/irrigate 启动。控制服务在阶段写入权下运行它(irrigate(..., planned=True)),只接受指向该写入权自己阶段的请求,且阶段必须处于 running;阶段继续运行,不需要接管(接管会记为干预)。上面的其他条件全部照旧:必须有人在现场启动、时长上限、冷却时间、没有另一次灌溉在进行、联锁,以及关泵。运行期间,执行器在外部改动检查里不比较水泵。动作记录保存水泵运行的秒数(ran_seconds),提前结束的运行还会记下原因(ended_early)。完整且得到确认的运行会记为该任务已完成,被缩短或没有得到确认的记为部分完成,每次任务最多开一次泵(见运行一轮研究)。
  • 关泵一定会执行。 开泵在关口内完成,等待在关口外进行,关泵回到关口内执行,最多试两次(PUMP_OFF_TRIES)。交接、保护规则的写入或一次 pump_off 调用,都会让这次灌溉提前结束。

关泵联锁。 关泵得不到确认时,控制服务在账本里置上联锁标志。标志生效期间:

  • 阶段写入权和人工写入权名下的写入以 interlock 拒绝,阶段也不能启动或续跑;
  • 执行 Agent 每次 tick 第一件事就是调用 pump_off。这条路径只能写「关泵」并回读;
  • 关泵仍然得不到确认时,执行 Agent 上报 PUMP_OFF_UNCONFIRMED,尚在进行的阶段进入 recovery_check;
  • 保护规则的写入照常放行。旧传输已确认停止时,关口也放行水泵以外通道的养护写入。

关泵得到确认、且旧传输已确认停止后,联锁解除;操作员登记现场核对也能解除。重启时如果还有结果未定的水泵动作,联锁会再次置上。操作员这一侧怎么做,见人工接管、灌溉与交还。

旧传输停止确认

撤销编号,只能让本进程不再写。它证明不了更早的写入方已经停下:辅助进程或某个 BLE 会话手里可能还有排队的指令。所以控制服务要去问传输层,也就是真正握着 BLE 连接的那一层。

WriteTransport.halt() 只有在传输层自己能作保时才返回真:macOS 上是辅助进程确认已经退出,其他平台是 BLE 会话确认已经断开(transport.py)。超时和出错都算「未确认」。控制服务在启动时和恢复编号变化之后各问一次,并把结果存下来。

结果是「未确认」期间,除保护规则以外的写入都以 unsettled 拒绝;执行 Agent 上报 TRANSPORT_UNCONFIRMED,尚在进行的阶段进入 recovery_check。另一条出路是操作员登记现场核对。

保护规则不随阶段写入权失效

每次暂停、接管、停止和重启,阶段写入权都会被撤销。过热保护如果用的是它,就会恰好在出了状况的时候失效。所以保护规则有自己的写入权:

  • 它由 approve_safety 签发,这是一次单独的审批;进程启动时会重新签发。任何阶段交接都不会撤销它。
  • 关口不对它做第 6 项检查。暂停、人工接管、recovery_check 和联锁期间,保护规则的写入都能通过。
  • 只要连接正常,执行 Agent 每次 tick 都会评估保护规则,而且排在阶段逻辑之前。阶段处于什么状态都一样,没有阶段时也一样。

其余检查它照样要过:控制已启用、写入主机已登记、恢复编号是当前的、连接有效、取值在清单内,而且永远不能开泵。

维持档位。 规则的触发条件持续成立期间,执行 Agent 每次 tick 都核对设备是否处在保护档位。设备显示的是别的档位,就立即再写一次。档位读不回来不算确认,执行 Agent 会重发,但每个通道每 PROTECTION_RESEND_SECONDS(30 秒)最多重发一次。加这个限制,是为了不让每秒一次的 tick 往账本里每秒塞一条记录。

边界。 恢复编号变化之后,在安全配置重新获批之前,没有保护规则可用。没有 BLE 连接时什么都写不了,所以离线时也必须兜住的风险,要靠 AC5 自身的限值或独立硬件。保护规则作用的通道如果在运行单里交给了设备自管,就构成冲突,阶段无法启动(safety_conflict)。代码只保证保护规则的写入权写不出清单以外的值;这些值是否朝着降低风险的方向,由操作员在批准安全配置时把关。

冻结读数

传感器一直报同一个数值,那不是读数,而是传感器卡住了。观察者会记下一个冻结时段并发出告警,但只有当阶段依赖这个传感器时才暂停:运行单的反馈规则用到它,或者保护规则用到它(vpd 上的规则算作用到了 temp 和 humi)。没有任何规则依赖的传感器冻结,只产生告警。保护规则用到该传感器时,告警升为严重。只有处于 running 的阶段会被暂停,每个时段、每个阶段只暂停一次,而且第一次暂停已经让阶段暂停后不再发第二次:同一次检查里开了两个时段时,第二个要等操作员恢复阶段后的下一次检查才会暂停它。保护规则用到的传感器的时段先处理。原始样本从不修改;冻结时段是单独的、只追加的记录。

恢复编号

备份里的写入权和审批都是过去签发的,而现场的设备可能已经变了。growbridge recovery bump 把恢复编号加一,旧编号之下签发的一切随即失效:

  • 所有写入权被撤销,所有排队的动作被作废(bump_recovery);
  • 所有尚未结束的阶段进入 recovery_check,它们的审批全部作废;
  • 绑定旧编号的操作员会话被拒绝;
  • 安全配置不再有效,要等操作员重新批准。之后阶段才能退出 recovery_check,并且回到 pending_review 重新审批。

这条命令只能在守护进程停止时执行。

写入主机

每台设备只登记一台机器(growbridge host register)。先登记的机器占有这台设备,其他机器得到 host_unregistered。在没有登记的机器上,BLE 连接根本不会打开;授予写入权、写入、批准安全配置和 pump_off 也一律被拒绝。原因是:两个守护进程同时写一台 AC5 时,各自的检查都能通过。

入口:请求从哪里进来

有些操作只有操作员站在帐篷旁边时才安全。所以服务端要判定请求走的是哪个入口(Entry),判定逻辑在 workbench/auth.py 的 entry_for:

  • 局域网入口:连接由 lan_port 上的监听接受,并且 Host 是 lan_hosts 之一。
  • 覆盖网络入口:连接由 port 上的主监听接受,并且 Host 是 overlay_hosts 之一。
  • 其他情况不属于任何入口,操作员既不能登录,也不能操作。没有设置 lan_port 时,局域网入口根本不存在。

起决定作用的是监听端口,单凭 Host 头什么也选不了。远程客户端经覆盖网络的代理连到主端口时,Host 可以随便填,却改变不了连接是被哪个监听接受的。操作员会话也绑定在登录时所用的入口上。灌溉只在局域网入口提供。

这个模型管不到的地方

控制服务独占的只是 GrowBridge 这一侧的 BLE 写入。AC5 面板和 Spider Farmer App 仍然可以直接改设备。DiAGRI 只能事后通过回读发现,并上报 EXTERNAL_CHANGE。

水泵是例外:实验期间没有人会手动开泵,水泵也从不交给 AC5 定时器,所以 DiAGRI 没有灌溉时水泵插座读回为开,一律算意外。执行 Agent 的水泵看门狗每个 tick 检查一次:发现后通过专用的 pump_off(触发方为 watchdog)关泵,发出 pump_unexpected 严重告警,并在当前阶段记一条 unexpected_watering 干预(没有活动阶段时看门狗照样运行,但这时只有账本记录和告警,不记干预)。pump_off 还会把插座模式重置为手动,AC5 面板上设的定时器因此被清掉。插座读不出来时只发 pump_unreadable 警告,不动手。看门狗只在已连接、且没有未确认的关泵时动作;关泵没有确认就交给关泵联锁。

看门狗的 pump_unreadable 和 pump_watchdog 两种告警是锁存的:条件一直存在时,看门狗每 5 分钟重新写入一次告警(文字有变化时最多每分钟一次),等某一步表明条件已经消失才把它解决。重新写入一条仍然打开的告警只会让计数加一:已读标记保留,也不会再发通知。因此,条件还在时手动关掉的告警(控制台只能标为已读,这里指直接在数据库里把它解决)会在 5 分钟内作为一条新告警回来,并再发一次通知。要让它消失,只能消除原因。告警写不进去时,看门狗在下一步就重试,不等 5 分钟;解决没能写进去时同样在下一步重试。锁存状态只在内存里:重启后第一步会再写入一次告警,这只会让仍然打开的那条告警计数加一。

另见


页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。