droboticflow-new/docs/dashboard-stability.zh-CN.md
2026-10-26 11:48:13 +08:00

11 KiB
Raw Permalink Blame History

看板持续运行与故障恢复

状态:2026-10-26 已按本聊天明确批准的计划部署到 Fanyu,并完成看板只读验收。线上源码提交 521acce5,基于原线上 44e66a68 与第一轮修复 8dff3517。本页补充并更新初步调查报告;整个平台的生产写入及故障注入验收仍未完成。

本轮落实的保障

统计口径、历史作者/供应商、三种旧 run 关联方式、15 分钟最大陈旧时间和角色权限保持原契约。没有放宽超时/容量上限,没有截断历史后返回“成功”,没有清理原始历史。

  • 关联查询 ID 去重并分批(每批最多 256),避免查询表达式随累计任务数无限增长;run 并集按 ID 去重。
  • 人员工作事件仅加载解释器使用的三种送检事件;humanEvents 仅加载终审证据。阶段别名 acceptance、prepackage_acceptance、final_acceptance 全部保留。筛选集合由统计模块提供,存储层与解释器共用,避免两份规则漂移。
  • 保存、领取等非统计过程历史不再占用返回载荷预算。相关复合索引使数据库可按报告所需键定位,原索引保留以服务其他业务。
  • 失败次数、最近失败阶段/类别/时间/耗时保存在现有共享协调记录中;刷新重试不能抹掉失败证据,成功发布才清除活跃失败。旧租约 owner 不能增加新 owner 的失败次数或释放其租约。
  • 成功代次附带构建准备耗时(读取、计算与编码,不含发布写入)、压缩/解压体积、part 数和来源 BSON 字节/文档数。序列化仅一次;没有为监控复制一份完整数据集。
  • 构建时间或任一载荷达到保护预算的 80% 时生成 output_snapshot_capacity_warning 日志;刷新失败继续有阶段化错误日志。失败计数及容量指标也能通过下述只读接口查看。
  • 发布策略强制运行真实本地 Mongo 的规模、兼容、权限与恢复门禁。测试跳过、缺失或运行器失败均不能算通过。

只读健康检查

GET /api/dashboard/annotation-output/health 仅允许组织管理员。使用当前组织与当前正式统计项目范围,不接受查询参数扩权,不返回人员/任务正文、其他组织或项目 ID、原始错误文本、数据库地址、凭据。

这个接口只读取配置及协调元数据;不会申请租约、触发重建、续租或写入统计集合。Cache-Control: no-store。它说明快照协调状态,不校验压缩 blob 完整性,也不替代一次真实看板读取。

HTTP 200 只说明检查成功,必须解析 status 与 available:

status 含义 检查脚本退出码
healthy 代次未过期、无已知失败或容量预警 0
idle 无已知刷新失败,旧代次已过期;原设计无访问不刷新 0(available=false,不能当作业务读成功)
degraded 有刷新失败或容量预警,可能仍能服务旧的有效代次 1
unavailable 已知刷新失败,且没有有效代次 2
not_built / building 尚无可验证的已完成代次 3,状态未知

数据库不可达、401/403、重定向、响应格式错误及未知状态均退出 3,不伪装成健康。脚本只进行一次 GET,不自动登录、轮询或刷新:

python3 scripts/check_dashboard_health.py \
  --url https://<platform-origin> \
  --cookie-jar /absolute/path/to/existing-admin-cookies.txt

Cookie 文件为既有的 Netscape 格式会话文件,应按凭据文件保护。会话过期必须由既定认证流程处理,检查器不创建账号、扩大权限或自动写登录记录。没有新增未认证的监控入口。

建议将退出码 1/2/3 接到现有监控,保留失败原因与快照年龄;日志系统可匹配 output_snapshot_build_failed、output_snapshot_lease_renew_failed、output_snapshot_cleanup_failed、output_snapshot_capacity_warning。本次提供了接口、日志及检查器,未创建线上监控任务、修改告警配置或向外发送通知。告警接入需确定现有监控系统和运行身份。

存储、索引与兼容

内部快照的 schema 仍为 annotation-output-facts/v1,统计 payload 未变。仅向既有协调记录/代次元数据添加可选字段:consecutiveFailures、lastFailure、metrics、activeKey、activeEpoch;无新集合或业务文档迁移。

旧记录缺少指标时显示未知,而非零;旧 failed 标志按“至少一次失败”处理。混合版本运行时,旧写入者可能覆盖新增可选诊断元数据,因此完整故障计数保证以 API 全部升级为前提。activeEpoch 与 epoch 配对,旧写入者沿用过期 activeKey 时不会误报当前刷新者。旧应用可继续读取快照格式,回退不需要回滚客户数据。

候选启动的 EnsureIndexes 会尝试创建以下三个非唯一索引,均需在生产变更计划中列出并单独授权:

集合 名称 键顺序
runs organizationId_taskId organizationId, taskId
humanEvents organizationId_itemId_stageId organizationId, itemId, stageId
annotationWorklogEvents organizationId_projectId_eventType organizationId, projectId, eventType

不删除/修改现有索引。部署前宜受控预建、检查名称与键一致并观察数据库负载,不能把索引创建当作无影响写入。回退时索引可保留。发布流程仍按 docs/release/README.md 执行,新的策略摘要会使旧发布计划失效,必须重新准备。

自动验证与证据

python3 scripts/test_dashboard_stability.py
python3 -m unittest discover -s tests/release -p 'test_*.py'
go build ./...

稳定性门禁固定连接 mongodb://127.0.0.1:27018,由测试创建/清理独立合成数据库,不能传入生产 URI。运行前应核实端口确实属于本机副本。缺少本地 Mongo、关键测试 skipped、测试名称消失、超时或 race 失败均阻止门禁通过。

已验证:

  • 原查询超过关联批次上限的回归先失败后通过;600 与 24000 条/来源均保留所有相关事实、旧关联及组织隔离。
  • 200 条非统计过程事件曾使小预算查询失败;筛选后通过,三种终审别名完整保留。
  • 共享快照、多实例、重启、遗弃租约、旧 owner、失败退避、损坏代次、私有集合权限,以及新持久化故障状态与旧记录兼容。
  • 管理员诊断权限及范围撤销;诊断本身不触发来源加载。路由快照从真实路由生成,仅新增上述管理员 GET。
  • 完整门禁在 race 下通过,无 skipped;24,000 条/来源规模读取约 1.82 秒(本机、并发测试、race 开启,不能当作生产容量承诺)。既有真实 HTTP 快照规模场景同时通过。
  • 39 项发布工具测试通过;go build ./... 通过。
  • 独立本地副本真实 HTTP:先登录合成管理员,检查器返回 not_built / 退出 3;读取报表返回 200;随后检查器返回 healthy、available=true / 退出 0。验证后停止副本。

原始本地 HTTP 证据在本分支工作树的 local-data/verification/dashboard-stability-20261026/,生成的账号/会话均为本地合成、Git 忽略。未使用生产客户数据写测试。生产复验结果见下节;本地测试不能替代其他未执行的生产业务验收。

线上发布与验收(2026-10-26)

已取得本聊天用户对三个索引、具体镜像发布与只读测试的明确批准。发布记录: local-data/releases/dashboard-stability-20261026-521acce5/release.json;计划摘要 4a8fd68a09c970cfa23eb76ae8bebcf20364ef7016ad23f13e8ef65c67ba6aa7。 该记录与本节证据位于本隔离工作树,均由 Git 忽略。

  • 三个批准的非唯一索引创建成功并独立读回核对,未删除或替换现有索引。
  • 处理器 2/2 就绪后才滚动更新 API;API 4/4 就绪,均为提交 521acce5353250c4285766f229b371b97a7aec46。
  • 已上传、拉取并核实 linux/amd64 镜像及 OCI revision;不可变镜像为 ccr-29eug8s3-pub.cnc.bj.baidubce.com/fanyu/droboticflow-api@sha256:fad2211cde7774bf53ec6ae31756bc2c8f3b7ea557ecd9d55ebff9a882c7eaf3。
  • 19 项完整发布门禁通过;第一次门禁因缺少 Playwright 默认浏览器未完成,使用已有 Edge 后完整重跑通过,没有忽略失败。
  • 原 503 snapshot_unavailable 复现请求已变为 200。平台管理员、供应商管理员与标注员返回实际 totals 和明细;初次成功热读约 159–169 ms。质检/验收账号登录及其现有只读仪表盘接口也返回 200,未把这两个角色原本只返回 audienceScope 的接口夸大为产出统计验收。
  • 首个新版本快照重建约 69.3 秒,随后自动刷新约 54.1 秒;后续健康检查观测到又一代约 54.5 秒。刷新期间四个 API 均返回同一代完整数据(约 147–210 ms),未返回空统计或 503。
  • 四实例构建版本及同代汇总一致。真实分页保持同代与总计;CSV 行数与当次筛选总数一致。生产数据持续变化,不要求跨代总数固定。
  • 标注员全部返回明细归属本人,供应商管理员全部明细归属其供应商;试图筛选他人/其他供应商返回零条。非管理员诊断 403,匿名诊断 401。
  • 11:46(Asia/Shanghai)最终复核:健康状态 healthy、可用、失败次数 0、无容量预警;来源约 31.9 MB / 127900 文档。Worker、validator、coordinator 及其他非本次目标 Deployment 的 spec 与发布前相同,ConfigMap/PVC/Service 等受保护资源通过工具复核。

本轮没有领取、保存、送检、审核决定或删除客户任务。常规登录记录与内部统计缓存写入在批准范围内。 role-login 已记录 passed;完整多供应商业务操作、标注交付、质检/终审写入、生产故障注入及视频播放验收仍如实记录为 unverified,发布状态保留 deployed_pending_acceptance。这不否定已完成的看板修复验收,也不代表所有生产业务已全量验收。

原始证据在 local-data/verification/dashboard-stability-release-20261026/,主要包括 online-before.json、online-after.json、replica-result.json、refresh-result.json、 read-contract-result.json、final-infrastructure.json 与 acceptance-evidence.json。 会话文件和凭据不得提交。

扩展边界

本轮让查询表达式和非统计过程历史不会无界拖累统计,并在保护预算前发出可观测信号;它不是无限规模的增量数据仓库。当前仍按需解释相关正式历史,来源 64 MiB / 250000 文档、单代解压 32 MiB、压缩 4 MiB、构建 90 秒等上限保留。

若持续出现 80% 预警,需要在达到硬上限前实施下一阶段的持久化增量事实与对账。不能仅按 createdAt/updatedAt 拉取新记录:迟到事件、已存在 reviewOperation 从 applying 变 completed、返工使旧完成失效、作者/供应商历史归属均可能导致漏算。那一阶段必须具备可靠变更游标、可重放、修正/删除传播、全量重建与跨代切换,并独立验证后迁移。本轮没有把未经这些验证的“增量缓存”投入使用。