droboticflow/docs/operations/query-serving.md

47 lines
8.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 后台查询读表与可选加速组件
状态:本地实现;生产保持关闭。新采用的独立查询库、原库无 CDC 时的增量标记及回退边界见 [独立查询库操作说明](query-replica.md),其规定优先于下文旧同库路径。速度与资源结论见同任务证据,未通过的门槛不能据本说明视为通过。
## 责任与兼容
Mongo 仍是任务、权限、归属、版本与正式审查记录的权威存储。独立 `query-read-builder` 只写 `queryReadModelControl`、`queryReadModelData` 及既有 `annotationOutputSnapshot*` 派生集合,不领取、退回、重置、补验或改写客户任务。读取新集合不触发构建。
后台使用租约代次隔离写者,先完整构建再发布清单。单个失败不会发布半份结果。进程重启先使旧追平证明失效,再打开变更流、核对源身份和重建;发布代次不能推进观察器追平时间。空批次不代表追平:后台每秒在私有控制记录写入一次标记,只使用对应变更事件的原始 updateDescription,不读取可能已更新的 fullDocument;滞后时证明自然过期,查询走兼容路径。此路径额外约每秒一次私有写入,计入资源对照。`--once` 也执行这条路径并有5分钟上限,退出后搜索新鲜度随心跳过期,不把遗留索引视为最新。副本集/分片集群变更流是持续搜索加速的前提,普通独立 Mongo 不支持时后台暂停,API 继续旧路径。
- 生产总览复用原事实读取与 `productionstats.Build`,保留原日期、供应商、人员和首次送检批次口径。当前配置项目集合生成一份报告;其他未预建项目组合走原路径。来源无变化且观察器新鲜时复用同一代次;有变化按原事实缓存时限停止使用旧结果。
- 人员与供应商看板复用既有分片快照和聚合器,后台无人访问也预热。Valkey 共享不可变分片及按完整范围、用户、供应商、日期、时区、代次隔离的结果;本进程已算出的结果优先,避免每次重复访问缓存服务器。已访问的个人/供应商查询登记保留4分钟,每范围最多256条,单个身份最多预热2条;新代次发布前复用原聚合器、每分片只解码一次,最多预热128条/5秒。预热不完整不缓存半份结果,失败也不阻断完整快照发布。时区规则必须与当前服务端标准规则一致,自定义时区保留原计算。
- Typesense 只存任务 ID 与名称搜索窗口,返回保守候选 ID。长词最多选取40个必要窗口约束,避免默认100次筛选运算限制;完整搜索词仍由原匹配器复核,候选不截断。用 Unicode 窗口交集保持任意子串、Capture/part 和标点语义;最终匹配、排序、分页、实时可领取及权限仍走原服务端规则。候选过大、超时、索引过期或不完整时退回原查询,不能截断候选凑性能指标。
- 派生集合对通用数据库浏览入口隐藏,防止绕过组织和个人权限。Valkey、Typesense 只允许服务端私网访问,不开放浏览器直连。
## 配置与本地验证
聚合后台现在必须显式提供独立的 `QUERY_READ_MONGO_URI` / `QUERY_READ_MONGO_DB`,并通过投影库身份检查;不再接受使用原库直接构建。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`;短测通过不代表线上容量验收。
Docker 本机规模夹具统一使用 Mongo 2 CPU/4GiB(WiredTiger 0.5GiB)、Valkey 1 CPU/256MiB、Typesense 2 CPU/1GiB;这是隔离对照的固定配置,不是生产扩容建议。1GiB Mongo 的首轮对照因旧路径 OOM 作废,不能计为优化收益。
本机 Docker 已发现服务端时钟前跳、数百毫秒即触发8秒 MaxTimeMS 的既有环境问题。性能入口持续采样 Mongo 时钟;两版任一存在超过500ms跳变或缺失采样,整轮不能通过。时钟异常记录不得重写为成功。可用官方原生 Mongo 的独立 loopback 27019/query-rs、新数据目录重测;`--native-mongo` 仅接受本任务 `local-data/query-serving-local/native/mongod.pid` 对应进程,不自动替换服务。此模式采集原生进程RSS/CPU,固定0.5GiB WiredTiger,但没有容器CPU/RSS上限,必须单列环境,不能与Docker对照拼接或作生产容量承诺。原二进制来源和SHA256保存在本机忽略目录,不安装系统服务。
两版夹具都显式安装仓库已有 `PoolSearchReadIndexes` 与 `PlatformReadIndexes`,报告记录身份。准备阶段合成写入使用w=1,正式计时重新连接默认写关注,包括后台派生发布写入。生产预检须只读核对这些既有索引;缺失时另列成本与授权方案,不能因本地具备而假定现网具备。该优化不在API启动创建业务索引。
## 运行与清理
名称构建失败按5~60秒退避,统计失败按30~300秒退避;组件失联时先清理普通不可达载荷,保留远端集合清理意图,恢复后再完成删除,避免垃圾载荷因搜索不可用而一直滞留。
后台单进程生成、跨副本租约;Valkey 不持久化,清空后仅损失速度。Typesense 索引可重建。清理只删除当前数据库登记、已不可达且超过保留期的派生代次,当前清单和其他部署不在清理范围。固定构建预算和载荷预算超限时保留旧路径,不改任务准入。
显式 `query-read-builder --ensure-indexes` 只为派生行创建 `query_model_rows_v1`;API 启动不建索引。生产新增组件、该索引及派生数据构建会产生数据库读取和索引维护开销,需另列具体部署、资源和授权计划。不上线时不向公司集群安装或写入这些数据。
修改生产统计或名称匹配的语义时必须递增 `queryModelSchema`(当前v3),防止新代码复用旧口径的派生代次。API 与后台应发布同一已核验源码版本。
## 发布与回退条件
先核对 Mongo 拓扑与权限、私网连接及组件资源,再在隔离环境验收完整任务链和查询结果。比较搜索 p95、冷/暖看板延迟、错误、结果/权限等价、后台业务写入为零、Mongo 读取字节与命令、Go/三组件 CPU 和内存。未达到搜索p95≤2秒、暖面板p95≤500ms、预热首访≤2秒,或三轮持续资源恶化未解释时保持待验收。
上线采用独立开关,先预热后逐步启用读取。回退关闭 API 的 `QUERY_SERVING_READS` 并停后台,恢复原读取;不改写客户记录,不要求删除新派生集合。组件失联仅是性能降级,不改变标注、切片、送检、质检和验收准入,也不恢复严格源校验。
追平语义依据:[MongoDB变更流规范](https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.md)中的 postBatchResumeToken 表示已扫描的位置,不等于客户端当前时间;[update事件说明](https://www.mongodb.com/docs/manual/reference/change-events/update/)明确 updateLookup 可能读到后续版本。因此不解码内部token、不以空批次当前时间或后续全文伪造追平。v3派生键隔离旧协议;滚动混用或旧后台占有租约时只走原读取。