droboticflow-new/docs/operations/query-build-lifecycle.md

12 KiB
Raw Blame History

查询库首次构建与日常刷新

范围与状态

仅独立周期查询库的构建器采用持久任务。权威Mongo、标注/切片/送检/审核/验收、权限目录和版本竞争路径不改。生产查询入口仍未切换。本地通过、代码部署、Pod就绪分别不代表影子验收或分流降载验收。

上一轮e4影子构建已完成:复用125,186条,补写14,820条;事实写入阶段约101秒,后续观察到至少两轮完整刷新。原维护窗口在2026-11-15 14:38:42 UTC到期,两影子作业按约定暂停到0副本并保留断点。本文不延长该窗口。

执行与持久性

参数 计划值 说明
首次构建单轮调度 60秒 正常让出,不是全程完成期限
变化刷新单轮调度 30秒 延续既有3分钟周期、15分钟展示年龄
原生输入单次逻辑读取 5秒 最多3次瞬时重试,每次服务端1.5秒
持久事务 15秒 多数提交及journal;游标与数据共同确认
累计无确认进展 5分钟有效执行时间 不含停机;真正无进展持久记录后停止
内部写入限速 512KiB/s 暂不调整;不能以延长超时取代限速核对
应用批次 最多200逻辑行,约64KiB写入 单条较大的合法事实仍完整写入
容量/Pod/底层IO 保持现有配置 25Gi、现有内存/CPU/IO边界不变

正常阶段:捕获输入→保存完整计划→应用事实→清理未匹配的未来版本→核对→事务发布。新一代完整之前,读者继续使用原完整代次及原权限校验;超出既有展示年龄仍按原错误/成品回退契约处理,不无限伪装新鲜或集中回源。

queryBuildJobs记录组织、输入代次、快照、阶段、事实应用游标、清理游标及分项失败;queryBuildParts保存带校验和的压缩输入和计划。均为私有集合,禁止从通用数据管理API读写。维护清理只回收不再被当前任务/输入引用的派生分段,绝不清客户标注或同步事实。

无变化日常刷新只有在观察器追平证明新鲜且组织、范围、逻辑版本及业务修订相同的情况下,才直接重新确认原完整事实和统计结果。否则新建输入代次并按上述流程计算。变更刷新可以读取查询库必要输入;不会重新启动原Mongo历史回填。

暂停、恢复与限制

  • 轮次预算耗尽:保留pending状态和游标,下轮正常续建,不增加失败退避,不因此降为0副本。
  • 进程退出/部署/调用方取消:已确认批次保留;新持有者以新租约恢复,旧持有者不能提交。
  • 数据库/权限/租约/持久化/容量异常:记录阶段、类别及Mongo代码;停止构建,保持旧完整结果,不自动清库重试。
  • 维护截止:按已批准观察器策略停影子作业,保存累计同步预算和断点。启动必须有新的有效窗口。
  • 已封存输入:原快照历史过期不影响应用恢复。未封存输入若历史已丢失,停止并保留分段,需单列恢复方案,不能混入新时间点。
  • 算法/字段语义变更必须更新构建逻辑schema并审核旧任务迁移;封存计划指纹不符时禁止继续混写。

待确认的实际启用方案

  1. 通过本任务检查和正式发布门禁,提交候选来源、镜像摘要及最终可执行清单。新代码尚未获得推送/上传或部署确认。
  2. 核对新的维护窗口、当前同步断点/预算、源健康、查询库容量/IO、原有镜像及运行身份;旧窗口不能复用。
  3. 仅为查询库构建器授权私有两集合的必要读写,在查询库queryWorkforceFacts增加workforce_fact_key_v1:organizationId,key,fromEpoch,toEpoch。不在原Mongo建索引。本地14万事实需记录新增索引体积,生产DDL仍列入最终计划。
  4. 构建器保持0副本更新镜像;同步沿原有效授权运行并取得新鲜追平证明后,再启用构建器1副本。保留所有e4确认事实,不能调用旧版restoreWorkforceStage清除新任务的未来版本。
  5. 核验首次完整发布、两轮正常刷新、权限/供应商/日期等价、Valkey丢失回退和查询库重启;生产查询入口继续关闭。原Mongo降载需后续经确认切入口后独立验收。

回退:先暂停构建器,保留任务/分段/事实、头和同步断点。e4旧构建器不能直接接手尚未完成的新生命周期任务,否则其旧恢复逻辑可能删除未来版本;无损回退优先停构建器并继续读上一完整版本。只有独立核实不存在未完成新任务、已发布完整头可用后,才能另行确认恢复旧镜像。不删表、不回滚客户标注、不重置预算、不降低持久性。

验证证据

证据集中写入本工作树忽略目录local-data/test-results/query-build-*,包含读取次数、批次、耗时、数据/索引占用及配置。不得复制客户原文或凭证。正式结果待验证完成后更新,不用短时成功代替完整验收。

2026-11-15 本地同规模结果

固定35,000条合成事件、140,000条事实,查询Mongo为1核/1GiB、WiredTiger 256MiB;生产影子库仍为4核/8GiB,不把本地结果当作生产容量验收。写入限速一直为512KiB/s,持久化一直为majority+journal。

场景 结果
保留e4的125,186条确认事实、补14,814条 76.33秒,跨2轮
同夹具遍历无变化事实作为算法对照 42.53秒
复用已证明无变化的完整结果,两次刷新 194.75ms、181.10ms
从零写入140,000条事实 318.71秒,跨6轮及进程对象重建
从零完成后的两次刷新 163.63ms、153.75ms
以上构建与刷新对原Mongo的读取 0

从零构建确认写入148,610,000 BSON字节,限速理论下界约283秒,实际约319秒;不需要通过增加全程超时或削弱持久性才能完成。采样查询容器CPU最高37.41%,无OOM;Docker VM的IO full avg10最高0.91%,该值不是单库IO等待。新增键索引在14万事实时约14.44MB。内存包含Mongo文件缓存压力,本地1GiB测试不能替代生产8GiB长时验证。

快速检查通过。首次全任务执行的浏览器、统计稳定性、权限和共享缓存检查通过;隔离副本组在总编排900秒耗尽后被停止,原报告verify-1794758125279658000保留为incomplete,不能写成通过。后续对失败落盘分支完成故障注入后,集中补跑受影响的隔离组;已通过且输入未变的浏览器证据保留。

最终功能补验与容量边界

  • 故障注入已复现并修复:结果/失败原因落盘失败不能丢失停止标记;恢复时断点库不可用也必须停止。红绿证据为query-build-outcome-red-confirmed.log及query-build-outcome-green.log。
  • 长期复用的旧完整载荷在切换后增加15分钟退休宽限期,随新头在同一事务确认;跨无变化刷新保留,到期回收,避免在途读取被清理。红绿证据为query-build-retirement-red.log、query-build-retirement-green.log。
  • 真实本机Mongo中途重启验证通过:同一容器、同一卷、1核1Gi、实际构建游标0/79恢复,408条事实完整发布,重复原生输入读取为0。命令:QUERY_REPLICA_LOCAL_TEST=1 QUERY_BUILD_PHYSICAL_RESTART=1 go test ./internal/store -run '^TestQueryBuildPhysicalMongoRestartMidApplyLocal$' -count=1 -race -v。该用例需要独占本机实验库,不放进普通并行任务;证据query-build-physical-restart.log。
  • 完整注册功能用例110项在6批中全部通过,missing=[]、skipped=false、sourceChanged=false;6次同卷重启的majority+journal断点校验均通过。证据query-build-batched-final.log,原始完整日志check-6dddc83cc2f54acbba24785a686e1a4f.log。
  • 单进程连续执行完整套用例曾两次导致1Gi实验Mongo OOM(exit137),原始失败保留,不能改写为容量通过。Docker VM总内存约5.8Gi并运行其他开发任务,未增加限制或停止其他容器。--bounded-query功能验证改为每批最多20项,批间验证没有其他客户端、原卷及资源不变后重启;不跳过用例,不在单个用例途中释放资源,不降低持久性。此模式不证明连续1Gi或生产8Gi容量。

源码、Go夹具、依赖和数据库资源未变的浏览器/统计/缓存证据继续复用;工具单元测试的诊断枚举断言另行补验。正式发布仍须绑定同步dev的最终源码与不可变镜像。

加急影子试运行建议(尚未批准执行)

不再以首次构建5分钟、1Gi实验库连续全套运行、全部查询500ms或200/500人长时压测阻塞影子部署。先更新影子构建器,在有效新窗口中追平同步,确认一个完整发布及关键生产对账,再灰度接入少量看板/作业记录。保留现有3分钟后台刷新、15分钟最大展示年龄;首轮以首屏约2–3秒、无超时、结果和权限正确为目标。全量入口和长期容量须后续独立验收,不能把分批功能通过换算成容量承诺。

不可放宽项:majority+journal、权限/供应商隔离、版本竞争、客户标注保护、完整代次原子发布、硬故障停止与回退。客户现有标注、切片、送检、质检和验收继续使用现有生产链路,不等待新查询链路完成。原运行窗口已结束,新的启动截止、镜像及目标仍须按项目规则确认。

2026-11-16:未封存快照恢复与发布保护修复(本地,尚未启用)

SnapshotTooOld(Mongo 239)仅在 production_plan / workforce_plan 的未封存输入阶段自动恢复:先以原持久性记录失败,正常让出;下轮在同一构建租约保护下选择新快照、新输入/计划代次,只重建该组织未完成的派生统计。原同步事实、源同步断点、累计预算、已发布头、事实内容及权限不变。前一代捕获页和未发布生产块在替代代次完成前保留,之后由原有有界清理回收;故障来源以 snapshotRecoveries 保存。

不能把不同快照的捕获页混用,因此未封存部分可能重新读取查询库中的当前组织输入;这不等于重新扫描/回填原Mongo。已经封存的计划照旧从应用游标续建,指纹一致的事实不重写。连续三次仍无法封存输入才报告无进展;不增加读取/事务超时、不调整512KiB/s或majority+journal。

网络/读取超时保留冷却重试。租约、权限、数据损坏、写入/持久化失败和真实无进展不自动清掉;清理临时故障标记也必须取得当前构建租约并使用majority+j事务,不重置进展时间或累计无进展值。普通单轮预算到期仍只让出。

evening-query-cutover.py 的写操作须提供已审查JSON计划、完整SHA256确认及授权消息引用。计划绑定集群context/API server摘要、namespace UID、对象UID、不可变镜像、有限累计预算/速率及明确有效期。JSON Patch通过stdin发送,核对原读取的resourceVersion;暂停/缩放同样用UID/RV CAS。不再停用观察器来强行启动;沿用有效的维护期CPU观察策略及其他硬故障保护。未获生产切换授权时不得启用生产入口。

verify-parity 不再把Ready/非空当结果一致:实际切换还须携带绑定当前已发布头与事实代次的新旧结果摘要、组织/供应商权限范围摘要及授权/拒绝结果,覆盖五角色、计数/看板/作业记录、正常/旧数据/日期边界/删除/返工/撤权/跨供应商/跨组织。合成证据仅用于本地验证,不能充当线上对照。后台首次准备和结果就绪只表示各自阶段,不代表已经分流或源库降载。

用户本轮仅授权本地修复和隔离验证,不启动生产同步,不建生产索引,不切查询入口。新维护窗口、镜像和具体回退仍在完整发布门禁后列入最终计划确认。