feat(ops): keep the public tunnel up — the containers were healthy the whole time it was down

[jhfnetboy]

Why

dvt{1,2,3}.aastar.io returned Cloudflare 1033 for days while docker ps showed all three node containers Up 3 days (healthy).

Nothing local went red, and that is the point: the container healthcheck runs inside the container and never crosses the tunnel, while 1033 is emitted on Cloudflare's side. Every signal we had was pointed at something that could not fail when this failed. It surfaced only because DSR needed the public endpoints for CC-115 B5 and I probed them by hand.

Same shape as the keeper outage io.aastar.dvt-committee-keeper was written for: complete monitoring aimed at something with no supervisor.

What it does

deploy/tunnel-keepalive.sh, every 300 s via launchd:

1. Probes the public hostnames end-to-end. 200 is the only pass — a 1033/530 page is still an HTTP response, and counting "got bytes back" as success is precisely how this outage hid.
2. If down → restarts the cloudflared container.
3. Re-probes and reports whether it actually came back. A restart command that exits 0 is not a serving tunnel. A script written because something looked fine while broken does not get to make that mistake itself.

Two deliberate non-actions, each with its own exit code so a column of non-zeros keeps meaning something:

exit	meaning
0	serving (already, or recovered)
1	still down after a restart — needs a human
2	this host cannot reach Cloudflare's API. Does not restart — restarting a tunnel you cannot observe is thrashing, not recovery
3	the node containers are down. Does not restart — the tunnel would come up in front of an empty origin and go green

Probes retry before declaring an outage: one timeout on a laptop is not evidence, and should never trigger a restart.

The token thing

It refetches the tunnel run token from the API on each restart instead of trusting deploy/.env.testnet, because CLOUDFLARE_TUNNEL_TOKEN there is a Cloudflare API token while the compose service needs a run token — two different secrets behind one name (#317). Without this, docker compose up cloudflared crash-loops with Provided Tunnel token is not valid., which is exactly why the tunnel could not come back on its own.

The token is never written to disk and never logged. When #317 is fixed this block becomes redundant, not wrong.

Verification — by breaking it, not by reading it

docker stop dvt-cloudflared          # public dvt1 -> HTTP 530
./deploy/tunnel-keepalive.sh
[..] DOWN 0/3 public endpoints serving
[..] restarting cloudflared
[..] RECOVERED 3/3 public endpoints serving after restart   exit 0, 19s

Also checked: healthy path exits 0 without restarting; --check never restarts; the nodes_running predicate returns false for a container that does not exist.

The launchd interval was verified with launchctl print → run interval = 300 seconds, not with plutil -lint — the nested-StartInterval bug documented in the plist passes lint while launchd ignores the key. The agent has since fired on its own schedule and logged OK 3/3.

Scope

Ops only — no product code, no contract, no change to the pinned 4.11.0 deployment or to node versions. The three node containers were never touched during any of this (Up 3 days, version 1.13.1 unchanged).

Requested by the user after the CC-115 B5 tunnel restore. Related: #317 (the token-name collision, filed, deliberately not fixed during the RepCredit freeze).

[clestons]

❌ REQUEST_CHANGES — #318 @ 99caec0b8d45f8981a786fe29f1a1820f0e016d9

作者想达成的是：给「只在公网那一侧才会失败」的东西装一个能看见它的监视器，并在它死时把隧道拉回来。 主路径达成了，我复核了。

但你点名要我挑的那个地方，答案和你担心的相反 —— --force-recreate 不会波及 depends_on（我构造实验证伪了）。真正的问题在它旁边：depends_on 用的是 service_healthy，而 nodes_running() 判的是 Running。这两个谓词不一致，而落在它们的差里时，这个脚本会把「三分之一降级」变成「三个全挂」。

---

阻塞项

[Medium] deploy/tunnel-keepalive.sh:83 — nodes_running() 判 Running，compose 的门是 service_healthy；差集里这个脚本会亲手扩大故障

先回答你的问题：--force-recreate 不波及依赖服务 —— 实验，不是文档

我在同一台机器、同一个 Compose 版本（Docker 29.4.0 / Compose v5.1.2）上搭了最小夹具：dep 带 healthcheck，main 用 depends_on: dep: condition: service_healthy。

before   dep=d273646ae660   main=8f55f3609b27
运行     docker compose up -d --force-recreate main
after    dep=d273646ae660  ← 未变       main=a05b9f359a17  ← 变了

判定：依赖服务未被重建 ✓
正对照：main 的 Id 确实变了，所以这次调用真的生效了 ✓

你观察到的「三个节点全程 Up 3 days 未被重建」是对的，而且现在有了机械依据，不再只是一次观察。 你自己说「这是我观察到的，不是我从 compose 语义证明的」—— 这一格补上了。

但同一组实验里掉出了另一件事

我把 dep 改成 Running=true 但 Health=unhealthy（模拟「节点在跑但不健康」），再跑同一条命令：

exit code 1，10.9 秒返回。stderr：
    Container fr-probe-main Recreate
    Container fr-probe-main Recreated          ← 先把目标容器销毁重建了
    Container fr-probe-dep  Waiting
    Container fr-probe-dep  Error dependency dep failed to start
    dependency failed to start: container fr-probe-dep is unhealthy

事后：main Id=318dea17232d（又变了 ⇒ 原来那个容器已被销毁）
      Running=false  Status=created          ← 建出来了，但从未启动

它不是「不干活」，它是「先把活着的那个拆了，然后拒绝启动新的」。

为什么这个状态不是边角，而是被触发条件精确对齐的

节点 healthcheck（x-dvt-node）:  node -e "fetch('http://127.0.0.1:'+PORT+'/health') …"
本脚本 probe_one:               curl https://<host>/health   ← 同一个 endpoint

两者探的是同一个 /health。 所以：

某个节点 unhealthy
  ⇒ 它的 /health 不返回 200
  ⇒ probe_all 得到 serving=2，脚本走 DOWN 分支（:118 只有 ==3 才算过）
  ⇒ nodes_running() 问 .State.Running → true，:130 那道闸门放行
  ⇒ :151 docker compose up -d --force-recreate cloudflared
  ⇒ compose 因 depends_on:service_healthy 拒绝启动，但 cloudflared 已被销毁
  ⇒ 本来还在服务的 dvt1 / dvt3 也没了 —— 2/3 变成 0/3

触发这个脚本的那个条件，和让 compose 拒绝的那个条件，是同一件事。 不是「碰巧同时发生」。

而且这不是一次性的：节点若持续不健康（autoheal 每 10s 重启但它一直起不来），launchd 每 300 秒就再做一次，每 5 分钟把另外两台好的重新拆一遍。

四条反驳我都试过了，也交给 Codex 独立挑过

autoheal 会不会快到让这个状态不可达？restart: unless-stopped 会不会把那个 created 容器带起来？exit 1「需要人」是不是已经够了？

• autoheal 只是缩短窗口，节点真坏时它会一直重启一直不健康 —— 窗口不是短，是常驻。
• restart: unless-stopped 管的是已启动过的容器退出后重启，Status=created（从未启动）不在它管辖内 —— 这一格是实测出来的状态，不是推断。
• exit 1 确实会喊人，但它喊的是这个脚本自己造成的全站中断。一个 keepalive 把可用性从 2/3 打到 0/3，然后如实报告「还是不通」，不是可接受的结果。

R3 Codex 独立复核（真 Codex，产物首行 CHALLENGER: codex，8437 字节）：

SELF-CHECK — Confirmed: `nodes_running` tests `.State.Running`;
             `cloudflared` dependencies require `condition: service_healthy`.
[CONFIRM] F1 — Autoheal leaves a race; probes can show 2/3; restart policy cannot start
              never-started containers; exit 1 cannot excuse script-induced total outage.
[CHALLENGE] F2 — No separate equal-or-worse issue is established by the supplied script excerpts.

处方 —— 让闸门用 compose 真正把守的那个谓词

:80-86，把判据从 Running 换成 Health.Status，exit code 与那段说理都不用改，因为它们本来就适用：

# 和 compose 自己把守的谓词对齐：cloudflared 的 depends_on 要求 condition: service_healthy，
# 所以「节点在跑但不健康」同样是一个「重启隧道不可能成功」的状态 —— 而尝试本身会销毁
# 正在为其它主机服务的那个容器。与 exit 3 同一个理由，同一个出口。
nodes_healthy() {
  local c st
  for c in "${CONTAINERS[@]}"; do
    st=$(docker inspect -f '{{.State.Health.Status}}' "$c" 2>/dev/null)
    [ "$st" = "healthy" ] || return 1
  done
  return 0
}

:130 改调 nodes_healthy，:131 那句文案里的 “is not running” 改成 “is not running or not healthy”。

顺带一句这个换法的副作用方向是对的：容器若没有 healthcheck，.State.Health.Status 是空串 → 不等于 healthy → exit 3。fail-closed，正是这里想要的方向。（三个节点目前都经 x-dvt-node 带了 healthcheck，所以现状不受影响。）

怎么验（照你自己那套「杀掉它，不是读它」）：

docker exec dvt-node-2 sh -c 'kill 1' 2>/dev/null || docker pause dvt-node-2   # 让它 Running 但不健康
# 等到:  docker inspect -f '{{.State.Running}}/{{.State.Health.Status}}' dvt-node-2  → true/unhealthy
./deploy/tunnel-keepalive.sh
# 期望: exit 3，日志出现 NODES DOWN，且 docker inspect -f '{{.Id}}' dvt-cloudflared 前后不变

判据是「cloudflared 的容器 Id 前后不变」，不是「脚本退出码好看」—— 现在这版会让那个 Id 变掉。

---

我验过没问题、不用重做的部分

① --force-recreate 的作用域 —— 见上，实验 + 正对照。你那句「只作用于 cloudflared 这一个 service」成立。

② 「200 是唯一通过」这条判据是对的，而且它正是这次故障藏身之处的解药

probe_one() { curl -s -o /dev/null -w "%{http_code}" --max-time 10 "https://$1/health"; }
[ "$code" = "200" ] && ok=$((ok + 1))

1033 / 530 / 502 都是成功的 HTTP 响应。把「收到字节」当通过，正是让容器全绿而公网全挂的那类判据。这里没犯。

③ 三个 exit code 的划分是承重的，不是装饰

2（本机连不上 Cloudflare）和 3（节点没跑）各自都对应一个「重启隧道证明不了任何事」的状态，而且注释写清了理由。我的阻塞项恰恰是说这套划分是对的、只是漏了一格 —— 不是要你去掉它。

④ launchd 那一格你验得比 lint 硬

plist 注释里写明用 launchctl print … | grep "run interval" 必须打印 300，并点名「嵌套的 StartInterval 能过 plutil -lint 而 launchd 会忽略」。「一个绿的 lint 不是这个 job 会触发的证据」 —— 这是判据层面的正确认识，值得留在那儿。

⑤ token 处理：CLOUDFLARE_TUNNEL_TOKEN="$RUNTOKEN" docker compose … 是前缀赋值，只进那个子进程的环境；不落盘、不打日志、fetch_run_token 的 stderr 单独重定向到 LOG 而 stdout 只被变量捕获。没有可挑的。

---

驳回的 finding（DeepSeek R1a / R1b 共 5 条，逐条给依据）

#	它说什么	驳回依据（我跑了什么）
R1a-1 / R1a-3 / R1b-1	plist 硬编码 /Users/jason 不可移植，[High]	同目录另外三个 plist 全都硬编码：apply-rotation 6 次、committee-health 6 次、committee-keeper 7 次、本 PR 6 次。这是既有约定，不是本 PR 引入的偏差；且 launchd 的 ProgramArguments 只接受绝对路径，「用相对路径」这条处方不可执行
R1a-2	unset RUNTOKEN 之后 token 可能残留在子进程环境，建议「scope 到子 shell」	VAR=value cmd 这个前缀形式本身就只把变量放进那一个子进程，从不进父 shell 环境。它建议的正是代码已经在做的事
R1b-3/4/5	tunnel ID / 主机名 / 容器名硬编码，建议移到 env	tunnel UUID 不是密钥（它就在 DNS CNAME 里）；主机名与容器名是这个部署的标识，移进 env 只是把同一份常量换个地方放，并不减少任何东西。无安全含义

R1b 把这些标成 SECURITY_FINDINGS 而 SECURITY_TRIAGE: low —— 它自己也没认为有运行时问题。

---

CI（post 时现读，并核了 run 的 head sha）

run 33943388933  head_sha = 99caec0b8d45f8981a786fe29f1a1820f0e016d9   ← 与本 PR head 相同
Build pass · CI Success pass · Code Quality pass · CodeQL pass · CodeQL Analysis pass
Security Audit pass · Smart Contracts pass · Tests pass          8/8

CI 全绿与这个阻塞项无关也不冲突：没有任何一条 check 会去跑这个 launchd 脚本，更不会构造「节点 Running 但 unhealthy」。这正是本 PR 自己在讲的那件事的又一个实例 —— 全绿的信号面里没有一个能看见这个状态。

---

收掉 nodes_running 那一格就 APPROVE。 其余我没有要改的；这个脚本对「什么才算证据」的把握（200 唯一通过、重启后回读验证、launchctl print 而非 lint）比它修的那个故障本身更值钱。

轮次说明（如实）

3 轮：R1a + R1b DeepSeek(v4-flash) 实跑（5 条全驳，见上表）→ 我自己的构造实验 → R3 Codex 实跑对抗（bash scripts/codex_pk.sh，产物 8437 字节、首行 CHALLENGER: codex、CONFIRM F1）。未跑 Opus R2 / R4。

如实标明：本轮的独立判断是我做的，不是 Opus 做的，所以不写 4-round。花在构造实验上的预算换来的是：这个阻塞项不是从代码读出来的推测，而是在同一台机器、同一个 Compose 版本上跑出来的容器 Id 与状态。

[clestons]

✅ APPROVE — #318 @ 9008d7918f04742e1c36f458e14ef2b2bb5f2ba1

阻塞项收干净了。我没有靠读新代码判断它对 —— 上一版读起来也合理。我把两个谓词都抽出来，喂给五个我自己构造的容器状态跑了一张真值表。

---

1. 真值表：两个谓词、五个状态，含一个必须仍然放行的对照组

把 nodes_running（旧 head）与 nodes_healthy（新 head）逐字抽出来，用同一批我自己起的探针容器驱动（不碰真实 dvt 栈）：

状态	旧 nodes_running	新 nodes_healthy
全健康（对照组）	0 放行	0 放行	← 这一格是承重的
Running 但 unhealthy	0 放行	1 拦下	← 缺陷态，已分道
容器已停止	1 拦下	1 拦下
完全没有 healthcheck	0 放行	1 拦下	← fail-closed，已分道
容器不存在	1 拦下	1 拦下

（0 = 放行、继续去重启 cloudflared；1 = 拦下、exit 3）

对照组那一行是我最想指出的一格。 一个「永远拦下」的闸门同样能让缺陷态变绿，而它会顺手废掉整个脚本 —— 你那次 docker stop dvt-cloudflared → RECOVERED 3/3 的回归测正是在防这个，我这张表从谓词那一侧独立确认了同一件事：它只在该分道的两格分道，其余三格与旧版逐格相同。

2. 「空串 = 不健康」我实测过，而且它走的是一条你可能没预期的路径

你注释里写「Empty status (a container with no healthcheck defined) counts as NOT healthy」。我构造了一个真正没有 healthcheck 的容器：

docker inspect -f '{{.State.Health.Status}}' nh-nohc2   →  输出为空，且 exit code = 1

不是「字段是空字符串」，是这个 Go 模板在 .State.Health 为 nil 时报错、写 stderr、非零退出。 你那句 2>/dev/null 把它吞掉，st 因此为空 → != "healthy" → return 1。

结论与你写的一致（fail-closed），但成立的机制是「命令失败」而不是「字段为空」。值得知道的原因：如果哪天有人把 2>/dev/null 去掉来 debug，这一格会开始往日志里吐模板错误；那不是新 bug，是这条路径本来的样子。

⚠️ 顺带一个我自己踩到的坑，写出来免得你以后按我第一版的方式验：我第一个「无 healthcheck」探针根本不是那个状态 —— 它报 starting 而不是空。原因是 aastar-dvt:latest 这个镜像自带 HEALTHCHECK：

docker image inspect aastar-dvt:latest -f '{{.Config.Healthcheck.Test}}'
→ [CMD-SHELL node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health')…"]

所以 compose 里不写 healthcheck: 也照样有一个。要造出真空态得显式 healthcheck: {disable: true}。「探针没造出我以为的那个状态」和「被测代码答对了」在输出上分不开 —— 这一格我是先看到 starting 才发现的。

3. 控制流与残留

:147  if ! nodes_healthy; then
:152      exit 3
:160  say "restarting cloudflared"
:170      up -d --force-recreate cloudflared

闸门在重启之前。grep -c 'nodes_running' → 0（无残留调用），正对照 grep -c 'nodes_healthy' → 2（定义 + 调用点各一），所以那个 0 是真的。

4. 你写进注释的那段因果，与我上一轮量到的一致

compose DESTROYS the old cloudflared container before evaluating that condition

这正是我 FACT 2 里的顺序（main Recreate → main Recreated → dep Waiting → Error）。把「先销毁、后校验」这个顺序写进代码旁边，比写「注意 depends_on」有用得多 —— 它是下一个人判断能不能放宽这道闸门时唯一需要的那条事实。

5. CI

run 33943960510  head_sha = 9008d7918f04742e1c36f458e14ef2b2bb5f2ba1  ← 与本 PR head 相同
Build · CI Success · Code Quality · CodeQL · CodeQL Analysis · Security Audit
Smart Contracts · Tests · Trivy · Type Check · cla-check              11/11 pass

和上一轮一样：没有任何一条 check 会构造「节点 Running 但 unhealthy」，所以 11/11 对这条阻塞项既不证实也不证伪。真正的证据是上面那张表。

---

一条注记（不阻塞，是这次修复之后剩下的那个形状）

修好之后，这个栈有一条由 compose 拓扑决定、而非由本脚本决定的性质：

cloudflared.depends_on = { dvt-node-1, dvt-node-2, dvt-node-3 } × condition: service_healthy
⇒ 任意一个节点不健康，cloudflared 就无法被 compose 启动
⇒ 此时另外两台健康节点的公网入口也无法恢复

这不是本 PR 的缺陷 —— 恰恰相反，本 PR 的修复正是「诚实地承认这个状态下重启不可能成功」。 但它值得写在某处，因为下一次故障很可能长这样：一个节点坏了，运维看到 exit 3 的日志说「隧道不是问题」，而三个公网域名全都不通。脚本说的是对的，读的人容易理解成「那另外两个应该还在」。

我不开处方：放宽 depends_on 会换来「隧道挂在空 origin 前面」这个你明确拒绝过的形态，这两者之间怎么取舍是你的判断，不是我的。我只是把这个取舍点标出来。（如果要收，README-heartbeat.md 里 exit 3 那一格加半句「此时三个域名都不通，不只是坏的那个」就够。）

---

结论：APPROVE，这棵树可以合。

这一轮值得记的是：你没有照单收，先自己核了差集才改。 你把「让 probe 失败的条件」和「让 compose 拒绝的条件」是同一件事这一点独立复述了一遍 —— 那不是转述我的话，那是重跑了那条推理。上一轮我在别的仓库刚被作者证明过我某条判断是错的，所以这个习惯是对的，请继续。

轮次说明（如实）

1 轮（我自己）+ 谓词真值表实测。R1 DeepSeek 未跑 —— 增量 = 修我自己上一轮的 finding（ABSOLUTE CONSTRAINT #5 的第二条结构性豁免）：整个增量就是一个谓词函数、一段注释、一句日志文案，全部出自我上一轮写下的那一条。未跑 Opus / Codex。

预算花在构造五个容器状态并对两个版本的谓词各跑一遍上 —— 因为「这个修复对不对」的正确判据是差分行为，不是代码读起来合不合理。