droboticflow/docs/operations/query-serving.md

5.0 KiB
Raw Blame History

后台查询读表与可选加速组件

状态:本地实现;生产保持关闭。速度与资源结论见同任务证据,未通过的门槛不能据本说明视为通过。

责任与兼容

Mongo 仍是任务、权限、归属、版本与正式审查记录的权威存储。独立 query-read-builder 只写 queryReadModelControl、queryReadModelData 及既有 annotationOutputSnapshot* 派生集合,不领取、退回、重置、补验或改写客户任务。读取新集合不触发构建。

后台使用租约代次隔离写者,先完整构建再发布清单。单个失败不会发布半份结果。进程重启先打开变更流,再核对源身份和重建;不把遗留索引视为最新。副本集/分片集群变更流是持续搜索加速的前提,普通独立 Mongo 不支持时后台暂停,API 继续旧路径。

  • 生产总览复用原事实读取与 productionstats.Build,保留原日期、供应商、人员和首次送检批次口径。当前配置项目集合生成一份报告;其他未预建项目组合走原路径。来源无变化且观察器新鲜时复用同一代次;有变化按原事实缓存时限停止使用旧结果。
  • 人员与供应商看板复用既有分片快照和聚合器,后台无人访问也预热。Valkey 共享不可变分片及按完整范围、用户、供应商、日期、时区、代次隔离的结果;本进程已算出的结果优先,避免每次重复访问缓存服务器。
  • Typesense 只存任务 ID 与名称搜索窗口,返回保守候选 ID。用 Unicode 窗口交集保持任意子串、Capture/part 和标点语义;最终匹配、排序、分页、实时可领取及权限仍走原服务端规则。候选过大、超时、索引过期或不完整时退回原查询,不能截断候选凑性能指标。
  • 派生集合对通用数据库浏览入口隐藏,防止绕过组织和个人权限。Valkey、Typesense 只允许服务端私网访问,不开放浏览器直连。

配置与本地验证

API、后台分别显式设置 QUERY_SERVING_READS=1 与唯一 QUERY_SERVING_NAMESPACE,默认关闭。可选 QUERY_VALKEY_URL、QUERY_TYPESENSE_URL、QUERY_TYPESENSE_API_KEY 均通过现有私有环境配置提供;凭证不提交。不同集群即便数据库同名也必须使用不同 namespace。缓存连接异步建立,启动不可用不会阻止 API;缓存请求有短时限和退避。

本机合成依赖:python3 scripts/test_query_serving.py --start。仅暴露 loopback 27019/16379/18108;随机测试密钥在忽略目录,Mongo 使用独立 query-rs 和独立数据卷。--down 只停这一项目,保留卷;不停止共享快照库和其他项目。Mongo 文件句柄上限显式设为65536,避免多轮隔离测试建索引触发默认低限制。

功能与故障回归使用真实本机三组件,--race 检查并发。规模对照入口为 python3 scripts/test_query_serving_performance.py --production-shape,使用同一合成数据、索引、资源及固定压缩设置;可通过 --database 复用脚本生成的专用数据库。完整稳态验收另设 --rounds 3 --warmup 300 --duration 1800;短测通过不代表线上容量验收。

本机规模夹具统一使用 Mongo 2 CPU/4GiB(WiredTiger 0.5GiB)、Valkey 1 CPU/256MiB、Typesense 2 CPU/1GiB;这是隔离对照的固定配置,不是生产扩容建议。1GiB Mongo 的首轮对照因旧路径 OOM 作废,不能计为优化收益。

运行与清理

后台单进程生成、跨副本租约;Valkey 不持久化,清空后仅损失速度。Typesense 索引可重建。清理只删除当前数据库登记、已不可达且超过保留期的派生代次,当前清单和其他部署不在清理范围。固定构建预算和载荷预算超限时保留旧路径,不改任务准入。

显式 query-read-builder --ensure-indexes 只为派生行创建 query_model_rows_v1;API 启动不建索引。生产新增组件、该索引及派生数据构建会产生数据库读取和索引维护开销,需另列具体部署、资源和授权计划。不上线时不向公司集群安装或写入这些数据。

修改生产统计或名称匹配的语义时必须递增 queryModelSchema,防止新代码复用旧口径的派生代次。API 与后台应发布同一已核验源码版本。

发布与回退条件

先核对 Mongo 拓扑与权限、私网连接及组件资源,再在隔离环境验收完整任务链和查询结果。比较搜索 p95、冷/暖看板延迟、错误、结果/权限等价、后台业务写入为零、Mongo 读取字节与命令、Go/三组件 CPU 和内存。未达到搜索p95≤2秒、暖面板p95≤500ms、预热首访≤2秒,或三轮持续资源恶化未解释时保持待验收。

上线采用独立开关,先预热后逐步启用读取。回退关闭 API 的 QUERY_SERVING_READS 并停后台,恢复原读取;不改写客户记录,不要求删除新派生集合。组件失联仅是性能降级,不改变标注、切片、送检、质检和验收准入,也不恢复严格源校验。