droboticflow/docs/internal-test-lane.md

14 KiB
Raw Permalink Blame History

内部测试环境操作指南

本指南对应 ADR-0004 和实施基线。受控命令只在本地验证六份已批准材料、生成环境清单和批次计划;它不会访问客户数据库、BOS 或集群,也不会部署、创建账号或证明业务验收。实际样本读取与复制、集群资源创建和部署须分别取得具体授权。部署前再次核对 kubeconfig 的集群、namespace 和资源额度;不要从配置默认值推断线上状态。

离线准备

配置样例见 scripts/internal_test_lane/config.example.json;其中全零摘要和示例域名仅用于填写参考,不能作为已验证镜像部署。使用仓库内的 local-data/internal-test-lane/ 作为私有根目录。它被 Git 忽略,导入的原始模板和批次记录不能加入提交。一次批次的配置为 JSON:schemaVersion: 1、独立测试 batchId 和 hostname、生产入口列表 productionOrigins、以 SHA256 固定的 image 与 mongoImage、完整 buildCommit、workspaceGi、mongoGi,以及 API、processor、Mongo 各自的 CPU/内存 requests 和 limits;还需要 TLS Secret 名、镜像拉取 Secret 名和入口控制器 namespace。verify-config 会拒绝已知生产入口、IP 主机名、其他 namespace、非固定镜像及越界资源值。资源值和外部入口、存储类能力仍需获准只读盘点后确认。

素材包 bundle.json 的 schemaVersion 为 droboticflow.internal-test-seed/v1。它含 dictionaries、六个 samples 和 assets 清单。BLF-data、SL-data 各三条完整 part,样本键使用小写字母、数字和连字符;至少各有一种 scratch 与 snapshot 模板。每个样本包含 source.captureId、正数 durationSeconds 和 media 中的双目视频、双目 PTS、IMU 路径;可额外含 sourceManifest。所有路径相对素材包目录,位于 templates/<sample-key>/。assets 为每个引用文件列出相同路径、字节数和 SHA256。快照还需明确阶段、切片和动作;舍弃切片的原因必须存在于所属项目的舍弃原因字典快照中。字典和快照使用获准样本的真实内容,不能伪造已有审查或交付结果。导入前另行审查六个来源 ID/版本、文件清单与总大小。

以下命令仅处理本地文件;示例路径由操作者替换为已审查文件:

python3 scripts/internal_test_lane.py verify-config --config local-data/internal-test-lane/inputs/batch-config.json
python3 scripts/internal_test_lane.py import-bundle --bundle local-data/internal-test-lane/inputs/bundle.json
python3 scripts/internal_test_lane.py prepare --batch <batch-id> --import-id <import-sha256> --config local-data/internal-test-lane/inputs/batch-config.json
python3 scripts/internal_test_lane.py status
python3 scripts/internal_test_lane.py credentials --config local-data/internal-test-lane/inputs/batch-config.json --out local-data/internal-test-lane/batches/<batch-id>/credentials

import-bundle 校验目录与文件均非符号链接、文件大小和 SHA256,然后将原件复制到私有 imports/<import-id>/;再次使用同一包会验证现有导入,不覆盖。prepare 在批次唯一且上批已归档时生成 environment.json、initializer.json、config.json、seed-plan.json 和 batch.json。前两个是供审查的 Kubernetes 资源清单和临时初始化 Pod 清单;本地 seed plan 只用于预览身份、素材和目标,不可直接用于集群初始化。batch.json 绑定源码提交、镜像、配置、导入版本和清单摘要,状态仅为 prepared,远端状态为 unknown。未完成的目录必须人工调查,工具不将其当作成功。

credentials 在新的私有目录中生成 0600 的 secret.json、accounts.json 和 mongo-uri.txt,标准输出仅返回路径。secret.json 含测试 Mongo root/app 凭证及 API token;accounts.json 含平台管理员、test 供应商管理员、标注员、质检员和终审员五个独立账号。不要打印、提交或转存这些内容到工单。账号使用者由审批清单指定。数据库 URI 指向本批次 Mongo 服务的完整集群 DNS 名和独立数据库;运行服务只应持有该测试权限。

经另行批准后的集群顺序

以下是操作顺序,不是当前授权,也不是自动发布脚本。集群写入前须有该次部署的明确批准,并立即核对目标集群和 droboticflow-internal-test namespace;样本读取、测试存储写入和凭证处理分别遵循已批准范围。先核实 namespace、网络策略、配额、Ingress/TLS、存储类与节点可用资源。空间不足时保持暂停,不缩减生产资源。

  1. 审查 environment.json、initializer.json、私有 Secret 清单及 source/inventory 记录。环境清单建立独立 namespace、配额与网络策略、数据库和工作区 PVC;Mongo 目标副本为 1,API 与 processor 初始副本为 0。不要提前打开业务入口。测试 PVC 和数据库按批次独立,旧版本不能自动指向新批次迁移后的数据库。internal-test-quota 是整个测试 namespace 的固定名称配额,新批次清单会更新它;更新前人工核对现有 PVC、已用存储和运行工作负载,并确认新额度覆盖保留批次与新批次,且不低于当前实际占用。若此前部署过旧版按批次命名的 quota,应在单独审查和获准的远端清单中处理;旧对象不会因本地清单变化自动消失。
  2. 在获准测试 namespace 创建清单与私有 Secret,等待独立 Mongo 就绪。只在隔离工作区准备临时 initializer Pod,上传已复制并核验的模板文件、规范化 manifest.json、匹配源码版本的 Linux seed 可执行文件及必要的私有账号/URI 文件。临时 Pod 不是长期服务;测试 API、processor 不带客户读取凭证。
  3. 在 initializer 内对 /workspace 的文件重新运行 internal-test-seed plan --manifest <manifest> --assets-root /workspace --workspace-root /workspace --batch <batch-id> --out <new-plan>。本地预览计划绑定的是本地导入路径,不能跨机器复用。核对新计划的六个样本、两项目、五账号、目标数据库和摘要后,以同一 manifest、素材根目录与计划摘要运行 internal-test-seed apply --plan <new-plan> --manifest <manifest> --assets-root /workspace --accounts-file <private-accounts> --mongo-uri-file <private-uri> --confirm <new-plan-sha256>。该命令只接受专用测试 URI 和空数据库;若中途失败,保持停机并调查部分写入,不绕过拒绝检查。
  4. 核实 seed 完成标记及素材路径/哈希,删除 initializer Pod 和暂存的私有文件,然后才将 API 与 processor 调至各 1 个副本。处理器切片并发为 1。确认入口明确标为测试、五角色登录和越权拒绝,再通过原业务界面完成领取、切片、标注、送检、质检和终审,并核验测试工作区内的受审媒体及 JSON。标准交付打包的未覆盖边界见下文;输出不进入客户出口。

snapshot 模板保留经审查的切片/动作内容,但 seed 不伪造送检、质检结论或切片生成产物。尤其是 quality_review 快照的切片媒体与正式审核证据必须通过真实业务提交和处理流程生成并核验;不能仅凭 requestedStage 字段宣称已进入质检。正常、退回和恢复路径的结果及未验证项应写入批次验收记录。测试通过不等于获准发布生产。

归档与清理

换版本前停止新测试并等待在途处理结束,在集群中确认服务停用、相关处理和工作区已从旧批次分离;保留结果及对应提交、镜像和配置。然后用本地证据 JSON(仅 batchId、tasksComplete: true、environmentStopped: true、detached: true、reviewer)归档:

python3 scripts/internal_test_lane.py archive --batch <batch-id> --evidence local-data/internal-test-lane/inputs/<batch-id>-archive.json
python3 scripts/internal_test_lane.py status

这是操作者陈述的记录,工具无法从本地证明远端已经停止或验收完成。固定模板和最新三个已归档批次保留;更旧批次先预览再确认:

python3 scripts/internal_test_lane.py cleanup-plan --batch <old-batch-id>
python3 scripts/internal_test_lane.py clean --batch <old-batch-id> --confirm <confirmSha256-from-plan>

clean 重新校验预览中文件的路径、大小和 SHA256,只删除该批次拥有的本地目录;导入模板不被清理。远端 PVC、数据库、Secret、Ingress 或工作区没有自动清理,不得因本地 clean 成功声称集群资源已删除。远端清理由内部管理员另拟精确清单、备份/保留判断及授权后实施;不删除或修改客户数据。

导入实际执行与业务验证证据

prepare 后的 prepared 仅证明本地文件已生成。操作员取得 seed apply 的 JSON 结果后,使用 record-evidence 导入 seeded 证据;随后取得真实 HTTP 流程的结果 JSON,再导入 business-verified 证据。该命令只读本地报告和计划,不查询 Mongo、HTTP、BOS 或集群。状态显示的是操作员提供的报告已导入,不等于工具实测远端,也不代表六条样本全部业务验收通过。无结果、失败或中断时保持原状态与 unknown,不得填造成功报告。

每次导入需要一份元数据 JSON,字段恰为 schemaVersion: 1、batchId、stage(seeded 或 business-verified)、reviewer、带时区的 observedAt、target、buildCommit、image、configSha256、approvedExecutionPlanSha256、resultSha256。target 的本地形式为 { "kind": "local", "databaseName": "...", "hostname": "127.0.0.1", "namespace": "local" };集群形式还须有 clusterContext,hostname 和 namespace 必须与本批配置相符。三个版本字段直接取已准备的 batch.json;resultSha256 为结果 JSON 的文件字节摘要。approvedExecutionPlanSha256 取真正执行的 plan 内 sha256,不取本地预览文件的 seedPlanSha256。集群上传素材后重新生成的计划通常有新的身份与摘要。工具核对实际计划与预览计划的样本、素材哈希、manifest 摘要及目标库一致,并核对报告与实际计划一致。

python3 scripts/internal_test_lane.py record-evidence --batch <batch-id> \
  --evidence local-data/internal-test-lane/inputs/<batch-id>-seeded-evidence.json \
  --plan local-data/internal-test-lane/inputs/<approved-execution-plan>.json \
  --result local-data/internal-test-lane/inputs/<go-apply-result>.json
python3 scripts/internal_test_lane.py record-evidence --batch <batch-id> \
  --evidence local-data/internal-test-lane/inputs/<batch-id>-business-evidence.json \
  --plan local-data/internal-test-lane/inputs/<approved-execution-plan>.json \
  --result local-data/internal-test-lane/inputs/<http-workflow-result>.json
python3 scripts/internal_test_lane.py status

Seed 结果必须是 Go apply 成功返回的纯 JSON,包含同一数据库、planSha256、created 布尔值及 2 项目、6 样本、5 账号计数。HTTP 验证器的进度日志不能直接充当结果文件;保存其最终 JSON 对象后再计算文件摘要。该对象至少包含同一批次、样本键、该计划中的任务和 item ID、最终验收 item ID 与 status: "accepted";若带 checks,每项都须为 status: "passed"。目前这只覆盖报告中的单条样本完整流程,状态里的 scope 会明确写为 single-sample-http-workflow。原始报告可能包含敏感信息,应留在私有本地目录;批次状态只保存摘要、目标、审查者和报告范围。

本地合成流程复测

本轮使用全新 Mongo 端口 27019 和 API 3019,没有复用已有 27017/27018 数据库。素材由 tests/internal_test_lane/make_synthetic_bundle.py 的 ffmpeg 测试画面生成。tests/internal_test_lane/verify_local.py 是针对这套本地验收夹具的脚本,固定读取 local-data/internal-test-lane/verification-final/local-plan.json、credentials/accounts.json 和 workspace;它不是集群验收脚本,也不会自动创建数据库或启动服务。

准备新的本地合成目录、通过本工具生成和应用计划、以该测试库的独立 readWrite 凭证启动 API/processor 后,可执行:

python3 tests/internal_test_lane/verify_local.py --project SL-data --confirm <local-plan-sha256> --output local-data/internal-test-lane/verification-final/sl-result.json
python3 tests/internal_test_lane/verify_local.py --sample-key blf-2 --confirm <local-plan-sha256> --output local-data/internal-test-lane/verification-final/snapshot-result.json
python3 tests/internal_test_lane/verify_local.py --sample-key blf-3 --stop-at-quality-review --confirm <local-plan-sha256> --output local-data/internal-test-lane/verification-final/quality-snapshot-result.json

最后一条仅接受 manifest 中阶段为 quality_review 的快照,先重建真实媒体并保留动作,再停在质检阶段供复现;不会伪造质检证据。测试脚本会真实领取、送检、审核计划内任务,不能对同一份已完成任务无条件重复运行;应重新准备新批次。报告拒绝覆盖旧文件。实际样本键以自己的计划为准。

标准交付打包的覆盖边界

当前首版没有启用工作流 worker,也没有复制客户的打包工作流。真实业务可到终审通过,并生成供审查的双目视频、PTS、IMU 和动作 JSON,但这不等于产品标准 delivery package 已经产出。终审后的 release partition 仍需 worker 处理;空测试工作流不能直接承担该步骤。不得将自制导出包或单纯终审成功当作标准交付验收。

若需要验收原产品的打包和交付界面,应补独立测试 worker、仅测试 namespace 的 Job 权限及有资源上限的打包工作流,然后另行验证。其部署与真实素材使用仍须具体授权;不能给现有测试身份追加生产权限来绕过隔离。