docker-compose-ha 主备部署验证：发现 6 个 bug（4 个阻断部署）+ OBJ_bklite mirror 停滞 + VERIFY.md 文档修正

[ericchenCW]

背景

按 deploy/docker-compose-ha/VERIFY.md 在两台跨机房主机（181=primary / 182=standby）上验证 HA 主备部署，过程中发现 6 个代码 bug（其中 4 个直接阻断部署）+ 1 个待深入的 NATS mirror 问题 + 2 处 VERIFY.md 文档不准。本次验证采用「保留 181 现有数据原地转 HA primary」的方式（复用 compose_* 数据卷 + 现有 common.env，COMPOSE_PROJECT_NAME=compose），181 数据全程保留，182 通过复制获得全量数据。

验证结论：修复下列问题后，VERIFY.md 阶段 1–6（V1–V11 + ha-status + 写入一致性）全部通过。

环境：Docker 29.5 / Compose v5.1.3，镜像源 bk-lite.tencentcloudcr.com/bklite/weopsx。

---

阻断级（不修无法完成部署）

1. telegraf 悬空依赖导致备节点（及中间 config）启动失败

• 现象：bootstrap.sh 在 docker compose pull 报 service "telegraf" depends on undefined service "server": invalid compose project。
• 根因：compose/monitor.yaml 中 telegraf depends_on: server，但 server 是 profiles:[active]、telegraf 不是。生成 docker-compose.yaml 的 config 不带 --profile active 时 server 被排除 → telegraf 悬空。备节点永不激活 profile，此问题会让 standby 彻底起不来。
• 修复：compose/ha.yaml 给 telegraf 也加 profiles:[active]（与功能同类的 fusion-collector 一致）。

2. falkordb entrypoint 路径写死且错误

• 现象：compose-falkordb-1 反复重启，日志 exec: /entrypoint.sh: not found，容器 unhealthy，bootstrap 失败。
• 根因：compose/ha.yaml 的 falkordb override 末尾 exec /entrypoint.sh，但该镜像真实入口是 /var/lib/falkordb/bin/run.sh（消费 REDIS_ARGS/FALKORDB_ARGS）。
• 修复：改为 exec /var/lib/falkordb/bin/run.sh。

3. 基础服务启动列表显式点名业务服务，导致备节点误启动

• 现象：standby 上 webhookd、nats-executor 被启动（VERIFY V4 要求它们缺失）。
• 根因：bootstrap.sh start_services() 的 docker compose up -d traefik redis ... nats-executor vector webhookd 显式点名了 nats-executor/webhookd。docker compose up 显式点名会无视 profile 强行启动。
• 修复：从该列表移除 nats-executor、webhookd（它们只应由主节点 --profile active up 拉起）。

4. 自签证书缺 clientAuth，NATS leafnode 双向 TLS 永久握手失败

• 现象：leafnode 一直连不上；181 nats 日志 TLS leafnode handshake error: x509: certificate specifies an incompatible key usage → Leafnode connection closed: TLS Handshake Failure。连锁导致 V8 失败、mirror 无数据、NATS 透传失败。
• 根因：leafnodes.tls.verify: true（双向），备节点作为 leaf 用同一证书做客户端认证；但 bin/ha-gen-certs.sh 的 extendedKeyUsage = serverAuth 缺 clientAuth。
• 修复：extendedKeyUsage = serverAuth, clientAuth，重签证书下发两端后 leafnode 稳定。

5. 主备 JetStream domain 相同 + mirror 未用 external-api，mirror 建成空的普通流

• 现象：ha-init-mirror-streams.sh 建出来的是带本名 subject 的普通空流而非 mirror；stream info 无 Mirror: 段，消息恒为 0。
• 根因：① bootstrap.sh generate_nats_config 给主备都写死 domain=bklite；跨 leafnode 做 mirror 时 leaf 必须用不同 domain 并通过 mirror.external.api = "$JS.<主domain>.API" 引用源流，否则 mirror 自引用拉不到数据。② ha-init-mirror-streams.sh 用 nats stream add --mirror $s --defaults，nats CLI 0.3.0 无 --mirror-domain flag、--defaults 跳过外部域设置。
• 修复：① domain 按角色区分（primary bklite / standby bklite_standby）；② mirror 脚本改用 --config JSON 指定 mirror.external.api。修复后 metrics/METRICS_ALL 同步正常（见下方 feat(middleware): 添加umami跟踪功能并移除冗余的install.run文件 #7 关于 OBJ_bklite 的遗留）。
• 遗留设计点：domain 当前按「角色」命名，failover 角色互换后 mirror 的 $JS.bklite.API 引用会与新主 domain 不一致，failover/failback 的 domain 对称性需进一步设计。

6. DOCKER_IMAGE_NATS_CLI 在脚本独立运行时为空

• 现象：独立执行 ha-status.sh 时 NATS 段误报所有流「不存在」（虽 [ALL OK]，但 NATS 检查实际失败）；ha-init-mirror-streams.sh 独立运行同样受影响。
• 根因：镜像变量由 bootstrap.sh 运行时按 REGISTRY_BASE 拼出，脚本只 source common.env 时该变量为空，docker run "" ... 失败。
• 修复：两脚本加兜底 DOCKER_IMAGE_NATS_CLI="${DOCKER_IMAGE_NATS_CLI:-${REGISTRY_BASE}/natsio/nats-box:latest}"。

---

待深入（非阻断）

7. OBJ_bklite mirror 回填在大流 + 内部删除空洞上确定性停滞

• 现象：修复 fix: 修复 FloatingOrbs 组件渲染时动画闪烁问题 #4/Refactor/bootstrap cleanup #5 后，metrics(3/3)、METRICS_ALL(0/0) mirror 正常；但 OBJ_bklite mirror 确定性卡在 2,487/10,482（删除重建复现），182 nats 日志反复 JetStream error response for create mirror consumer: stream not found (10059)。
• 源流特征：OBJ_bklite 10,482 条 / 1.3 GiB / 已删除 11,298 条 / seq 1→21,780（大量内部删除空洞）。拉完首批 2,487 条（连续段）后 consumer 在源端重建失败。
• 影响评估：对象数据本身经 MinIO 站点复制已安全同步（V11 通过），OBJ_bklite 仅为对象事件流，影响有限；但 failover 后该事件流不完整。
• 怀疑：跨 leafnode 的 external-API JetStream mirror 在需要多轮 pull / 跨删除空洞时，consumer 续建的 JS API 子主题未被正确路由。需要 NATS 拓扑层面进一步排查（leafnode + 跨域 mirror 是已知棘手场景）。

---

VERIFY.md 文档修正

• V3：curl -k https://127.0.0.1:443/ 因 web 路由规则是 Host(\<HOST_IP>`)，用 127.0.0.1作 Host 会返回 **404**。应改为curl -k https://<HOST_IP>/或带-H "Host: <HOST_IP>"`。
• V8：nats ... server report connections 用 admin 账号会报 ensure the account used has system privileges。admin 无 SYS 权限，需用 system 账号，或改用「检查两端 nats 日志 leafnode 连接 + 无 TLS handshake error」来验证。

---

本 issue 中 6 个代码 bug 的修复已在本地验证可用（实测两台机器 V1–V11 + ha-status + 一致性全部通过）。可按需拆分为独立 PR。

[ericchenCW]

迁移验证（VERIFY.md 阶段 7：故障切换演练）结果

在上述 6 个 bug 修复后，继续做 failover 演练（181 primary → 182 standby 接管），又发现 2 个脚本问题。

演练流程与结果

1. 切换前在 181 写入标记数据（_ha_probe 新增一行 + redis failover_mark），确认已复制到 182；
2. docker compose --profile active stop ...（含 telegraf）模拟 181 业务故障，保留 DB；
3. 在 182 执行 bin/ha-failover.sh。

实质结果：切换成功，数据零丢失。 9 步中 1–7 步全部通过：

• PG pg_promote 成功，182 转为可写 primary（pg_is_in_recovery()=f）
• Redis/FalkorDB REPLICAOF NO ONE 转 master
• NATS 三条 mirror 流 stream edit --no-mirror 转为可写流成功
• 业务进程在 182 全部拉起、server healthy、https://10.10.24.182/ 返回 200 登录页
• RPO 校验：切换前最后写入的 _ha_probe 行（含时间戳）与 redis failover_mark 在 182 上均存活，未丢

8. ha-failover.sh 因 DB_NAME 未绑定，自检在 8b 提前中止（致 8c/8d/9 跳过）

• 现象：脚本输出末尾 bin/ha-failover.sh: 行 126: DB_NAME: 未绑定的变量，随后 8c（traefik 探活）、8d（NATS publish 探活）、9/9（DNS 切换提示）均未执行。
• 根因：8b PG 写入探活用 psql ... -d "$DB_NAME"，但 DB_NAME 定义在 db.env，而 ha-failover.sh 只 source common.env / ha.env，未 source db.env；脚本开了 set -u，未绑定变量直接中止。
• 影响：切换实质成功（业务已起），但最关键的 9/9 DNS 切换目标提示没有打印，运维拿不到「该把 A 记录指向哪个 IP」的提示；8c/8d 健康自检也被跳过。
• 修复：ha-failover.sh 增加 source ./db.env 2>/dev/null || true（已同步给 ha-failback.sh 防回归）。修复后 8b 探活通过。

6（补充影响范围）：DOCKER_IMAGE_NATS_CLI 为空同样影响 failover/failback

• 原 issue Refactor/bootstrap cleanup #6 的同一问题在 ha-failover.sh（步骤 6 mirror 转可写、8d NATS 探活）与 ha-failback.sh（步骤 3 mirror 转可写）中同样存在，独立执行时 $DOCKER_IMAGE_NATS_CLI 为空会使这些 docker run 失败。
• 修复：两脚本均加同样的 ${DOCKER_IMAGE_NATS_CLI:-${REGISTRY_BASE}/natsio/nats-box:latest} 兜底。

接下来继续 VERIFY 阶段 8（回切演练），预计会触发 issue #5 中标注的「failover 后 JetStream domain 角色对称性」问题，将另行补充。

[ericchenCW]

迁移验证（VERIFY.md 阶段 8：回切演练）结果

继续做 failback 演练（182 → 181 切回），又发现 3 个问题，其中 #9 是阻断 failover/failback NATS 接管的核心缺陷。

演练流程与结果（最终成功，但需多处手动干预）

1. 在 182（当前主）写回切标记（_ha_probe +1 行 id=4、redis failback_mark）；
2. 181 改 HA_ROLE=standby + 清空 compose_postgres 卷，重跑 bootstrap：PG 从 182 成功 basebackup（timeline 2）、redis/falkordb replicaof 182、NATS mirror 经 domain 覆盖指向 182，ha-status [ALL OK]，数据反向追平（id=4 标记 + failback_mark 均同步到 181）；
3. 181 改回 HA_ROLE=primary，执行 ha-failback.sh → 在 step 2 因 SSH 失败中止（见 fix：更新CMDB介绍文档 #10）；
4. 手动完成剩余步骤（停 182 业务 / 181 promote / redis-falkordb REPLICAOF NO ONE / NATS 流接管 / 起业务）；
5. 最终 181 恢复为活跃主：PG recovery=f 可写、业务容器全 running、https://10.10.24.181/ 返回 200、数据完整（_ha_probe 含全部标记）。

9.【严重】NATS mirror 流无法转为可写，failover/failback 的「NATS 流接管」从根上失效

• 现象：ha-failover.sh(步骤6) / ha-failback.sh(步骤3) 用 nats stream edit "$s" --no-mirror --defaults 接管流，但：
  1. stream edit 子命令不支持 --defaults（仅 stream add 支持）→ 报 error: unknown long flag '--defaults'，命令整体失败；
  2. 即使去掉 --defaults，NATS 服务端直接拒绝移除 mirror：stream mirror configuration can not be updated (10055)——mirror 配置 immutable。
• 实测后果：切换后三条流仍是只读 mirror。已分别在 182（failover 后）和 181（failback 后）确认，新主无法向 metrics/OBJ_bklite/METRICS_ALL 写入。业务进程能起来只是因为 metrics 发布失败不致命（消息被静默丢弃），但 JetStream 持久化实际是坏的。
• 正确做法：接管 mirror 流只能删除 mirror 流再重建为普通流（mirror 内已有的本地消息会丢失，metrics 这类短保留流可接受；metrics 需按 bootstrap 的 stream add metrics --subjects=metrics.*... 重建）。本次回切即手动 stream rm + 重建 metrics 普通流后业务才正常。
• 建议：把步骤 6/3 改为「stream rm <s> -f 后按主节点定义 stream add 重建」；至少先去掉 --defaults 并改 stream rm + add。

10. failover/failback 依赖两节点间双向免密 SSH，但 bootstrap 不配置、文档未列为前置

• 现象：ha-failback.sh step 2 远程停 182 业务时报 Host key verification failed → FATAL: 无法远程停止当前主业务进程，脚本中止。
• 根因：脚本用 ssh root@$PEER_HOST ... 远程操作对端，要求双向免密 SSH + known_hosts。实测原 primary（181）侧根本没有 SSH 客户端私钥（~/.ssh 仅 authorized_keys）。正向 failover（182→181）碰巧能用，反向 181→182 不通。
• 影响：failback（及主节点失联外的 failover 远程停业务）无法端到端执行。
• 建议：在 Readme/VERIFY「网络与运维准备」中明确列出「两节点 root 双向免密 SSH」为前置，或脚本对 SSH 失败给出更明确的手动指引（而非直接 die）。

11. 原主回归当 standby 时，旧的源流残留为普通流，mirror 初始化被跳过

• 现象：181 以 standby 重新加入后，ha-init-mirror-streams.sh 对 metrics/OBJ_bklite「[skip] 已存在」——因为 181 当主时创建的旧普通流仍在（OBJ_bklite 还带着 1 万多条旧数据），脚本判定「已存在」就跳过，导致这些流不是 mirror、不会反向同步。
• 影响：回切前置的「反向追平」对 NATS 不完整；需手动 stream rm 旧流后重跑 mirror 初始化。
• 建议：standby 初始化时对目标流名若存在但非 mirror，应删除重建为 mirror（而非简单跳过）。

关于 #5 的「domain 对称性」遗留 —— 已实测确认

failback 时当前主（182）domain=bklite_standby，181 当 standby 需用不同 domain 且 mirror 指向 182 的 domain。本次通过在 181 ha.env 手动设置 NATS_JS_DOMAIN=bklite + HA_HUB_JS_DOMAIN=bklite_standby 才让反向 mirror 工作。即 failover/failback 的 NATS domain 不是自动对称的，需要运维手动指定。建议把 domain 改为「按节点固定」并让 mirror 源 domain 可由 ha.env 配置（已加 NATS_JS_DOMAIN/HA_HUB_JS_DOMAIN 覆盖开关，但默认值仍假设主=bklite）。

---

迁移验证总结

• 正向 failover（181→182）：数据零丢失、业务接管成功（RPO=0）；NATS 流接管静默失效（feature: 更新token获取方式 #9）。
• 反向 failback（182→181）：数据反向追平 + 回切成功；但全程需手动绕过 feature: 更新token获取方式 #9/fix：更新CMDB介绍文档 #10/fix: align playground auth flow and mlops proxy endpoints #11。
• 数据面（PG 流复制 / Redis-FalkorDB replicaof / MinIO SR）在两个方向都工作良好；问题集中在 NATS JetStream 的切换接管逻辑（feature: 更新token获取方式 #9 最严重）与运维前置（SSH fix：更新CMDB介绍文档 #10）。