12 KiB
独立查询库操作与验收
状态:本地实现,默认关闭;无生产数据、索引或集群变更。实现决策见 ADR 0014。现有 查询读表与缓存 在此模式下只作用于查询库。
数据路径
业务命令 → 原 Mongo(原权限/CAS + 同文档同步标记)
↓ 限速增量投影 / 断点历史复制
独立查询 Mongo(多数事务、薄事实)
↓ 查询库自己的 CDC
query-read-builder → 读表 / Valkey
计数/看板/作业记录 → 查询库或共享结果
任务列表 → 查询库选候选 → 按 ID 核对原库当前状态 → 原服务端授权
领取/保存/切片/送检/质检/最终验收 → 原 Mongo(不改读异步副本)
原库当前入口已用只读探测验证不支持 CDC(40573),并非 API 总资源不足。独立查询库必须是另一 Mongo 部署,不能只改原服务器上的数据库名。投影器核对 hello 身份,拒绝相同进程/副本集;查询端必须支持事务。聚合器还检查投影库私有身份,不接受直接对原库构建。
默认关闭的配置
凭证只通过既有 loader 私有覆盖文件或 Secret 注入,不写入仓库或证据。投影器、API 与聚合器必须使用相同且按环境隔离的 QUERY_SERVING_NAMESPACE;查询库控制表绑定来源数据库名与命名空间,拒绝不同来源配置的投影器接管。它是逻辑环境绑定,不替代物理拓扑核验;同名副本/灾备切换仍需专门恢复计划。
| 配置 | 角色与含义 |
|---|---|
QUERY_SOURCE_TRACKING=1 |
API、切片处理器、校验器、Worker、协调器及写维护工具;启用同文档标记 |
QUERY_READ_MONGO_URI / QUERY_READ_MONGO_DB |
独立查询库;不得与权威部署相同 |
QUERY_REPLICA_REPORTS=1 |
API:计数/生产与人员看板/作业统计的目标读取;默认关闭 |
QUERY_REPLICA_POOLS=1 |
API:任务池候选、计数及管理员标注池;报告模式可用后另启用 |
QUERY_SERVING_READS=1 / QUERY_SERVING_NAMESPACE |
查询库派生结果、不可变快照及缓存,namespace 必须隔离环境 |
QUERY_VALKEY_URL |
可选共享缓存。失联只回到查询库 |
QUERY_TYPESENSE_URL / QUERY_TYPESENSE_API_KEY |
可选搜索候选,后续独立验收;本批不要求启用 |
源校验 advisory/cutoff 等现行业务配置不因查询迁移改变。查询聚合器与 API 保持同一口径配置。聚合器不需要原库凭证,不能运行业务调度器。
投影进程:query-replica --writers-covered --bootstrap --interval=1s。--writers-covered 是完成写者盘点后的操作声明,不会自动升级旧作业。每集合每次最多200条、连接池4,投影/确认可重放;查询库租约代次使旧进程不能继续发布。历史复制是一次性、可恢复的读取;每6小时对每集合启动一轮限速摘要对账,每次只处理一个批次。
新代码只保存白名单字段,维持原 productionstats、workforcestats、名称匹配和历史回退。保留原标注和正式意见;作业记录正文按选中的正式记录 ID 回原库读取。不能安全复制的 URL/名称不作为“成功迁移”忽略,须先处理兼容项,或保持该路径开关关闭。
原库索引与写入成本
不会在 API 启动创建索引。query-replica --ensure-source-indexes 是明确的原库写操作,生产必须另列计划并授权:
- 当前22个白名单集合,各新增
query_sync_dirty_v1(_querySync.dirty,_id,只索引 dirty=true)及query_sync_delete_claim_v1(稀疏 deleteClaim)。 - 私有删除意图集合新增 phase/lease、collection/phase/audit 及 expireAt TTL 三个索引。已确认意图保留7天,未完成意图不自动过期。
- 合计47个索引;即便初始为空,构建仍需扫描集合。先只读盘点各集合体积、已有等价索引和磁盘余量,逐集合限速构建,记录 CPU/IO 和停止阈值。不得把索引收益忽略掉持续维护成本。
- 标记与业务写同次提交;只有相关变化需要一次小的确认更新。草稿正文、日志等不做持续投影。删除另外增加意图/标记写入,必须计入真实作业对照。
- 对账只做元数据 CAS,保留业务版本、状态、归属及标注;不得用老快照回写正文。
查询库显式运行 EnsureTargetIndexes,复用 PoolSearchReadIndexes / PlatformReadIndexes,另加精简事实关联索引。不能用与原实现不同的同名索引蒙混对照。查询库计数选择小文档索引,不强制扫描原库为大文档设计的覆盖路径。
权限、缓存与故障
计数缓存只保存候选事实,权限仍由每个请求的原服务端谓词计算。查询库事实代次在投影事务中递增,缓存按组织/筛选/代次隔离。内存预算64MiB、最多32份;合并最多16个并发构建,单构建8秒,取消互不影响。超容量改用查询库流式读取,不能截断结果。Valkey 使用压缩 BSON 保留私有权限元数据,单值仍受4MiB上限,TTL两秒。
原库待同步标记屏障使用小索引;最多1000条变更,越界显示暂不可用,不扫描全量权威历史。未同步任务覆盖旧候选,未同步批次策略读原库。物理删除尚未确认时不伪造零计数。列表继续批量核对当前任务,服务器计算 canClaim,实际领取/提交仍用原版本与权限校验。
查询副本追平证明30秒过期;失联不集中回源。有效查询连接在冷启动时保留,每秒最多一次、支持取消的拓扑/绑定核验,恢复后自动继续;不替换运行中的读者指针,也不要求手动重启 API。统计失败不返回伪造零数据;API 核心作业仍使用权威库。缓存丢失只影响响应耗时。旧代码或维护工具漏报的变化可由限速对账恢复,但持续旧写者、数据库浏览器 DDL 或人工直接写入不属于实时保证,切读前必须盘点并升级/暂停。
本地验证与验收证据
功能环境是独立 standalone 源库27119、query-read-rs 查询库27129;只允许专用合成数据库,测试结束清理各自随机库,不使用共享快照或客户记录。专用 native 数据目录位于本 worktree 的 local-data/query-replica-local/。native 只有固定 WiredTiger 配置,没有 CPU/RSS 配额,只能作为功能与读取路径证据。
本批专项入口:
QUERY_REPLICA_LOCAL_TEST=1 go test -race ./internal/store ./internal/api -run '^TestQueryReplica|^TestQuerySync' -count=1 -v
QUERY_REPLICA_LOCAL_TEST=1 QUERY_REPLICA_SCALE_LOCAL=1 go test ./internal/store -run '^TestQueryReplicaScaleLocal$' -count=1 -v
对照固定26218条合成任务;两侧安装相同既有读取索引。81/200/500并发分别测试单项目与全部项目,记录结果、p95、原库命令/响应字节及原生进程 CPU,包含同步标记确认与实时屏障。这仍是短时读取路径对照;原库回复字节不是公网 EIP 流量。
生产准备前仍须完成:
- 包含真实规模历史、多供应商、受限权限和冷缓存的完整业务链;开启标记后的保存/送检/恢复与既有基线对照。
- 固定源库4CPU的资源对照,查询侧明确 CPU/RSS/PV/IOPS;81→200→500用户逐级长稳态,三轮、冷启动、集中进入、积压、缓存丢失、查询库重启。观察原库 CPU、扫描量、读取字节与写放大,而不只看页面响应。
- 普通看板/计数暖态p95≤500ms、任务池包括冷查询p95≤2s;无新增业务错误、结果/权限等价;资源持续恶化须解释和处理。native 无配额不能替代上述容量门槛。
- 查询副本集多数提交、跨节点调度、PV备份恢复与审计;单节点本地副本集不能证明生产高可用。
项目 verify:plan/quick/task 与正式发布门禁另行保留证据;跳过、超时、已有失败和新增失败分开记录。
发布顺序与回退
本地验证达标后才准备具体公司变更计划,不在此文执行:
- 只读盘点写者、旧作业、原库索引/负载、查询库私网与 PV;查询库3副本建议每副本4CPU/8GiB,投影与聚合进程各1–2CPU/2–4GiB,Valkey 主备各1CPU/2GiB,仅为起步测试预算。
- 按单独批准计划建设源索引、新查询服务;所有源写者先升级同一核验版本并开启标记。旧维护脚本不再绕过适配器。保留原作业入口。
- 限速复制、持续增量,影子对照;先报告/计数,再任务池。基础管理员执行概览仍保留现有有界执行摘要/配置读取,不宣称其全部来源已迁走。
- 在不同时扩原库/改带宽的条件下比较总资源。原库确实减负、结果和速度达标后才准备正式切换。
- 回退先关
QUERY_REPLICA_POOLS/QUERY_REPLICA_REPORTS,再停后台和QUERY_SOURCE_TRACKING。保留原有读取、标注和正式记录;私有标记可保留。源索引可在评估后单独批准删除,不以回退为名清理客户数据。
源码必须先并入、核验并同步 dev,再按 scripts/release.py 准备,不能直接发布未合并工作树。推送、PR、集群变更、原库索引和数据写入均需要各自的明确授权。
本批验证记录(2026-11-12)
- 原 Mongo 入口 CDC 探测为不支持拓扑(40573);不把连接失败或权限失败当作此结论。
- 专项真实 Mongo/Valkey、竞态检测与旧合同回归通过;包括启动配置选择独立薄事实、错误配置不回源、筛选/盲标计数叠加待同步任务、删除恢复、失权、原标注保留及替换写入的 SDK 多选项语义。
- 工作可用性四阶段门禁通过,现有切片/返工/管理员任务池/搜索/看板浏览器及统计稳定性回归通过。Python 兼容检查37通过、4项物化夹具缺失仍跳过,不能记为全通过。
- 最终 Go 基线门禁68项既有失败、0项新增;初次曾出现 Worker 双实例并发用例额外失败,20次定向运行也曾失败,完整复跑通过,原始基线在竞态检测下也复现同一失败。初次记录不删除,不将该既有调度问题归为已解决;调度并发仍需独立确认。
- 固定26218条任务的 Docker 短时全部项目计数:81/200/500并发,最终新路径p95为203/328/528ms,均无错误。旧路径对应有39/83/187次超时,因此整项对照测试失败,原始结果保留;不能用旧路径失败后的残缺结果宣称严格等价对照通过。此测试仅是存储计数访问器,不包含完整HTTP授权和视频。
- 源容器配额4CPU/4GiB,查询容器4CPU/8GiB,但本机Docker虚拟机实际仅4CPU、约6GiB,两个Mongo共享主机;目标8GiB不是可兑现的独立物理预算。短时减少的源库命令/读取字节和CPU只证明该查询路径的减负,不能承诺生产总CPU降幅或公网带宽降幅。
- 完整任务级检查仍记录有失败、跳过和外部用例映射缺口;后续修正夹具的领取库存、作业追溯、索引迁移和供应商转换已定向通过。持续写入/删除积压、完整HTTP及后台写放大/CPU/RSS/IO、三轮长稳态、重启和高可用恢复尚未完成。
详细命令、原始失败及源码身份记录在该工作树的 .scratch/mongo-cpu/verification.md 和忽略目录 local-data/diagnostics/mongo-cpu/。本批保持所有生产开关与数据不变,不具备生产容量验收或发布资格。
本批只读存储盘点:当前注册的 StorageClass 为静态 csi-bos,现有80Gi本地卷和200Gi BOS卷均已占用,未做修改。隔离验收仍需独立SSD持久卷,不能将现有BOS挂载视为已满足数据库文件系统要求。MongoDB要求目录fsync等文件系统语义,并推荐WiredTiger使用XFS,参见官方生产说明。节点allocatable不等于空闲资源;尚未创建Pod、PV、StorageClass或Secret。
定稿性能复测中,单项目500并发曾有70次就绪检查失败。已将重复的水位读取合并为仅在途共享(无跨请求TTL、无权限缓存),以真实Mongo命令监控证明100个同时检查只读一次;相同夹具复测新路径所有档位均零错误。旧路径仍有超时,因此组合对照仍标为失败,而非性能验收通过。最终全部项目500并发p95528ms仍高于暖态500ms目标;81/200档通过的只是存储计数访问器,完整HTTP/业务授权及长稳态仍待验收。