droboticflow/docs/operations/acceptance-search-v2.md
2026-11-10 04:57:09 -08:00

13 KiB
Raw Permalink Blame History

验收跨项目搜索:标量候选发现与显示名称批量读取

本修订基于 7a1231c7,针对全部项目验收搜索在候选发现前反复扫描大文档,以及列表名称补充逐条读取采集记录的问题。生产尚未启用本修订;本地结果见任务证据,不能据此宣称生产容量验收通过。

查询与兼容

  • 将摘要有效性检查与候选关联 ID 收集合为一次聚合。仅投影标量索引字段,在聚合边界后应用完整原始筛选及源版本校验;最终的匹配、权限、分页与领取判断保持原路径。

  • 使用独立、可选的 poolSearch.searchText / textVersion=1。原 schema=1、text 数组和状态摘要不变。缺失或过期的新名称摘要进入旧路径,不作为“没有任务”。读取接口不补写。

  • 关联名称查询在本次请求中复用运行到采集记录的关系;根范围确定后以固定四路重叠独立读取,运行到采集仍保持先后依赖,失败会取消兄弟读取;每个关联集合使用一次覆盖扫描,在投影边界之后合并判断所有名称字段;避免多个名称字段的 OR 迫使 Mongo 回表读取大文档。

  • 超过 4096 条候选、旧记录或无法证明安全的运行目录形态回退原路径,绝不截断可见任务。多目录、缺失/空白目录保留原解析器。盲标权限表达式继续使用旧路径。

  • 列表显示名称按页去重批量读取采集记录的 id/captureId/prefix。保留原 ID 查找语义与历史缺失组织字段的记录;调用方仍先完成任务授权,名称结果不能授予任务访问权。缓存仅限本次请求,包含缺失记录,不缓存跨请求权限。

  • 已匿名化的验收记录不再读取来源批次;历史未匿名化记录按页去重批量读取来源批次。来源批次可跨项目,仍保留原匿名化条件;批量读取失败或未找到时继续原逐条回退,不漏脱敏。计数接口不读这些仅供展示使用的来源批次。

  • 计数请求在本次 HTTP 上下文中复用完全相同的名称候选读取;每池及每页仍独立执行原范围、有效性和权限检查。该读取结果不跨请求保留,领取和审查写路径不使用此缓存。

  • 每个 API 进程仅合并进行中且组织/原始范围完全一致的候选扫描。单个调用方取消不会中断其他等待者,后台读取有8秒上限;完成结果和错误立即移出合并表。用户权限、canClaim及最终任务过滤仍逐请求执行。

索引与启用顺序

完整字段见 acceptance-search-indexes-v2.json。描述函数不会在启动时调用或自动创建索引。

集合 索引 用途
humanItems pool_search_guard_cover_v2 范围、版本与源字段的标量覆盖读取
humanItems pool_search_text_v2 可选名称搜索键
runs pool_run_names_cover_v2 首个正式目录及关联 ID;仅索引首目录为字符串的记录
runs pool_run_tail_v2 多目录记录的兼容回退入口
annotationTasks pool_task_names_cover_v2 历史任务的文件名字段
captureRecords production_capture_cover_v1 复用现有生产索引,不重复创建

上线前需单独授权五个新索引的生产创建与回退删除。创建会占用磁盘、构建 CPU/IO,并增加后续写入维护成本;应逐个创建,记录前后 collStats/indexSizes、节点内存、CPU、IO、写入延迟及执行计划,异常时暂停。不能仅凭索引存在或单条 explain 快就宣布成功。

部署 API、处理器和 Worker 的同一候选,防止旧写入器丢失可选新字段。根覆盖索引缺失时直接调用已部署的旧候选发现算法,不先做无 hint 的全量根扫描;关联名称扫描的索引缺失时也使用原候选算法,避免无索引数字数组投影的不同结构;仅输出 ID 的旧兼容查询保留无 hint 的限定 ID 回退。兼容旧部署,但性能不保证达标。旧写入器导致新字段缺失时恢复旧查询,不能影响业务结果。

经单独授权后,仅补建 humanItems 的摘要:先以 pool-search-backfill --collection humanItems dry-run,核对目标环境、组织与数量,再加 --apply。工具使用全文 CAS,只更新 poolSearch,冲突留待重跑,成功后再次 dry-run 应为零;不改正文、状态、归属、任务版本或其他集合。默认不传 collection 的原五集合模式保持兼容,不应误用来扩大本次生产变更。

回退代码不要求改写客户数据;可选新字段可保留。索引可单独删除,但删除后新版本可能退回较慢查询。禁止删除原索引或修改客户任务来达标。

验证要求

本地夹具按只读盘点构造:humanItems 26218、runs 26490、captureRecords 29767、annotationTasks 23611、humanEvents 342694、6 项目、3 供应商;运行记录互不共用,整包验收采用独立聚合批次/来源批次;包含大载荷、历史未匿名化记录和受限权限。列表带真实页面的 trace=1,覆盖空搜索整页、搜索命中/无命中、我的任务、已验收,以及全部项目/单项目的同条件计数。81 人为 60 标注、12 质检、8 验收及 1 管理员。生产客户正文与凭证不复制。

同一脚本、合成数据、Mongo 资源与压缩设置对照 7a1231c7 和候选;记录完整 API 耗时、错误、查询量、返回字节、CPU、内存与结果身份。验收全部项目命中/无命中均须 p95 ≤2秒且比基线下降至少50%,没有新增错误;较短冒烟不能替代约定的三轮持续压测。首次大规模测试曾因重复采集读取及本地 Mongo 内存耗尽失败,必须保留失败证据,修复后重测。

覆盖索引必须以真实命令的 executionStats 验证,不根据索引名称推断。参见 MongoDB 官方查询优化与聚合优化。

生产只读盘点与性能边界(2026-11-09)

生产 Mongo 为 8.0.17-r1,本机对照使用官方 Mongo 8.0.17;Mongo 缓存 0.5GiB,API GOMAXPROCS=2,未设置 Mongo 进程的硬 CPU/RSS 配额。不能把该本机对照直接当作集群容量承诺。

生产目标组织的 2552 条可领取验收根记录都有有效运行关联,26490 个运行记录均为单目录。目标组织及组织外少量记录的拟建索引字段均只读核验为标量,没有数组/对象值。该盘点只证明当前快照可建立这些标量覆盖索引;创建前仍需确认在途写入兼容性,不能代替生产变更授权。

数据库地址在集群内解析为私网地址。初步本机对照显示合并根扫描后,API 延迟下降但 Mongo 返回的标量关系字节可能增加,不能宣称所有链路流量都下降。公网 HTTP 压缩响应基本不变;报告需分别列出公网响应、私网 Mongo 字节和 CPU/RSS。

早期无 trace、仅搜索请求的结果保留为补充证据,不计入完整性能验收。修正后的三轮隔离准备对照已完成并通过本地查询专项门槛,结果如下;7a1231c7 已部署发布记录仍保持待验收,新修复尚未上线。

本地复验

运行 npm run verify:plan -- --base 7a1231c7 与 npm run verify:task -- --base 7a1231c7。任务级回归覆盖旧数据、权限、搜索分页、浏览器搜索、来源批次匿名化失败回退,以及采集显示字段的批量投影。

持续读取对照入口为 TestPollPoolReadMixLocal,仅允许本机 Mongo 和独立的 poll_pool_read_mix_ 数据库。两版必须使用相同的两个夹具文件 poll_pool_load_test.go、poll_pool_production_fixture_test.go。本次选项:POLL_POOL_LOAD=1、POLL_POOL_PRODUCTION_SHAPE=1、POLL_POOL_PAGE_SHAPE=1、POLL_POOL_READMODELS=1、POLL_POOL_SEARCH=1、POLL_POOL_AUTHORIZATION_STATE=initialized、POLL_POOL_AVAILABLE_PER_STAGE=215、POLL_POOL_RUN_PAYLOAD_KIB=80、POLL_POOL_TASK_PAYLOAD_KIB=16、POLL_POOL_AUTHOR_HISTORY=100、POLL_POOL_WARMUP_SECONDS=300、POLL_POOL_DURATION_SECONDS=1800、GOMAXPROCS=2。候选另设 POLL_POOL_SEARCH_INDEXES=1;基线为 0,两版都保留既有采集覆盖索引。URI 用 POLL_POOL_LOCAL_MONGO_URI 指定本机独立服务,输出用 POLL_POOL_OUTPUT 指定私有诊断目录。

记录 API 与 Mongo CPU/内存的绝对时间以对齐稳态区间;首次加载样本独立保存,不混入稳态 p95。逐账号、逐请求比较任务身份、计数、canClaim 和追溯信息摘要。压测不包含媒体、编辑提交、连续审查续期、入口网关、真实认证或完整页面的任务详情关联,不能据此承诺这些链路的容量。统计面板只作为读取背景负载,本轮不重新验收统计面板的生产冷加载。

第一轮带追溯的 30 分钟持续对照(每版42150次读取)证明旧候选尚未达相对门槛:命中搜索742.7→406.7ms(45.2%),命中计数749.7→562.9ms(24.9%)。零错误/写入,身份一致;结果保留,不能按短测77%收益替代。后续合并关联扫描及请求内重复名称读取后重新验证。为排除跨轮 Mongo 分配器与索引构建内存残留,后续各版都重启本任务拥有的本机27019实例,保持同版本、0.5GiB缓存和其他配置一致,不重启共享27018环境。

只读256条可领取验收记录的补充抽样:根记录BSON中位数11826字节、p95为31953字节;运行记录中位数88927字节、p95为147435字节,来源数量均为1。该抽样按UUID排序选取,不是随机全量统计。现有合成活动根载荷偏大,并保留较多旧验收阶段以覆盖兼容压力;因此记录数量相近不等于复制生产分布,生产容量仍需上线后单独核验。

后续资源验证进一步分离准备和测量:单独进程构造数据/索引,校验夹具配置摘要;随后仅重启本任务Mongo实例保留合成库,并启动全新的API读取进程。测量进程不构造数据、不重建索引。显式库名仅允许本机 poll_pool_read_mix_ 前缀;复用须摘要及集合数量完全一致。复用配置不匹配和准备目标已存在时均拒绝,且不会删除该库;哨兵保留测试已通过。

此前同进程准备的数据对照保留为查询证据,内存不再用于资源验收:原版预热时也有大量空闲malloc区与压缩页残留。分离后短测的候选物理占用约749MiB,基线约1.2GiB;该读数仍属于本机观测,不是生产硬内存限制验证。各版均保持相同Mongo版本、缓存、API GOMAXPROCS与请求脚本。

最终三轮对照结果

最终采用独立准备进程、重启保留数据的 Mongo、全新 API 读取进程的协议。每版每轮预热5分钟、稳态30分钟;共6次运行、252900次稳态读取。全部请求零HTTP/Mongo错误、零业务写入;逐账号、逐接口的任务、计数、canClaim及追溯摘要完全一致。全部任务池接口p95不超过2秒,以下四个目标每轮均超过50%的相对改善门槛。

轮次 命中搜索p95,ms 无命中搜索p95,ms 命中计数p95,ms 无命中计数p95,ms
1 1131.7 → 417.0 876.0 → 189.3 1142.1 → 453.4 906.6 → 270.3
2 1076.1 → 244.9 1002.5 → 173.4 1102.2 → 343.4 1018.6 → 231.0
3 1043.9 → 258.5 1131.8 → 210.5 1023.1 → 361.2 1149.3 → 356.5

目标搜索及计数下降60%~83%。合计API进程CPU时间下降约10.3%,Mongo命令数下降20.5%,Mongo响应字节下降2.8%。API进程包含压测和压缩工作,因此该CPU读数不是独立服务容器容量结论。公网gzip响应为基线的1.0008倍,基本不变,本次不宣称公网带宽下降。

各轮API回收后堆内存约为基线的1.01倍。Mongo稳态RSS中位数分别为964→724、855→923、859→611MiB,峰值分别为1543→1652、1537→1394、1572→1500MiB;没有三轮持续恶化超过10%,但也不能宣称Mongo内存始终下降。未验证生产硬资源限制、入口网关、媒体和写入混合负载。

最终任务门禁 verify-1794271033888668000 通过,无未映射文件;包括项目Go基线门禁、权限/旧数据/分页/匿名化/覆盖索引及浏览器搜索回归。进行中读取合并的竞态测试通过。六次执行的夹具摘要和候选代码补丁摘要一致。复用未改变源码和配置的验证证据,不以短测替代持续对照。

私有证据位于本工作树 local-data/diagnostics/acceptance-search/:final-acceptance-summary.json、mongo8-isolated-formal-comparison.json、六份 mongo8-isolated-formal-{baseline|candidate}-r{1,2,3}.json 及执行/资源日志。证据包含本地环境信息,不提交到Git。

结论:本地查询专项通过,可准备生产变更方案。新建五个索引、humanItems摘要CAS补建、API/处理器/Worker同版更新均仍需对应授权;本轮没有执行这些生产操作,也没有推送或更新PR。生产只读复测和容量验收仍待完成。