15 KiB
标注模块本地全流程部署方案(对齐集群线上环境)
技术栈说明:本项目是 Go (API+worker) + React/Vite (前端) + Python (算子 runner) + MongoDB + Kubernetes。 你本地 Mac 已由前几轮搭建完成全部基础环境(Go/colima/docker/venv/npm 依赖/本地 Mongo),本文在此基础上输出可照做的完整方案。 每一步末尾的
✅ 校验就是成功的明确标识,没过就停下排查,不带病前进。
第一步:前置环境校验清单
逐条执行,全部通过再继续(预计 2 分钟):
# 1. Go 工具链(≥1.24)
go version
# ✅ 校验:输出 go1.24 或更高
# 2. Node(≥20.19)与依赖已装
node --version && ls node_modules/.package-lock.json
# ✅ 校验:v2x.x 且文件存在
# 3. colima 虚拟机运行中
colima status
# ✅ 校验:输出 "colima is running"
# 4. 快照数据库容器(上一步恢复的 8/31 全库快照)
docker ps --format '{{.Names}} {{.Status}}' | grep fanyu-mongo-restore
# ✅ 校验:显示 Up
# 5. ffmpeg(本地切片物化需要——物化在 API 进程内执行,不走 K8s)
ffmpeg -version | head -1
# ✅ 校验:输出版本号
# 6. Python venv(算子调试用)
.venv/bin/python -c "import bcrypt; print('bcrypt ok')"
# ✅ 校验:输出 bcrypt ok(没有就 .venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com bcrypt)
第二步:进入最新工作树并检查基线(分支/依赖/新鲜度)
# 默认在统一开发工作树或按 docs/agents/branch-workflow.md 创建的独立任务 worktree 中执行
# (严禁在主工作区 ~/Desktop/fanyu/droboticflow 直接切分支或盲目 git add -A / rebase)
cd ~/Desktop/fanyu/droboticflow/local-data/worktrees/recent-integration
# 1. 检查当前工作区状态与分支新鲜度(只读)
git status -sb
bash scripts/local/branch-freshness.sh
# ✅ 校验:确认当前工作树包含 origin/dev 及线上运行版本;若需新独立分支,按 docs/agents/branch-workflow.md 从 origin/dev 创建 worktree
# 2. 依赖(一般无新增,必要时确认)
npm install
# ✅ 校验:无 error 退出
第三步:标注模块轻量化快速启动(不等全量部署)
原理:标注模块的数据查询/任务领取/提交/审核流转全部走 API + MongoDB(读快照库);视频切片物化在 API 进程内用本地 ffmpeg 完成,不依赖 worker 和 K8s。只有"新建 Run 跑自动算子"需要 worker,标注测试不需要。 所以:API + 前端 + 快照库 = 可以直接测标注。
cd ~/Desktop/fanyu/droboticflow
# 1. 确保快照库在跑(第一次需要先执行拉取脚本)
docker ps | grep fanyu-mongo-restore || scripts/local/fetch-mongo-snapshot.sh
# ✅ 校验:容器 Up,脚本末尾输出 "集合数: 57"
# 2. 一次性操作:给快照里的泛宇全流程测试账号组重置本地密码(只改本地 27018 副本,线上无关)
# 在 bash 中隐藏输入,仅设置本地测试密码;不要提交或粘贴密码到文档中。
read -r -s -p 'Local test password: ' LOCAL_TEST_PASSWORD; printf '\n'
export LOCAL_TEST_PASSWORD
HASH=$(.venv/bin/python -c 'import bcrypt, os; print(bcrypt.hashpw(os.environ["LOCAL_TEST_PASSWORD"].encode(), bcrypt.gensalt()).decode())')
docker exec fanyu-mongo-restore mongosh --quiet 127.0.0.1:27017/drobodata-fanyu --eval "
const hash = '$HASH';
const emails = ['fanyu-admin@droboticflow.local','fanyu-full-annotator@droboticflow.local','fanyu-full-qc@droboticflow.local','fanyu-full-acceptance@droboticflow.local'];
print('重置: ' + db.users.updateMany({email: {\$in: emails}}, {\$set: {passwordHash: hash}}).modifiedCount + ' 个账号');
"
# ✅ 校验:输出 "重置: 4 个账号"
unset LOCAL_TEST_PASSWORD HASH
# 3. 启动(一个终端:API 连快照库;另一个终端:前端)
source scripts/local/env-local-snapshot.sh && npm run dev:api
# ✅ 校验:curl -s http://127.0.0.1:3001/api/health 返回 {"status":"ok"...}
# ✅ 校验:curl -o /dev/null -w '%{http_code}' http://127.0.0.1:3001/api/auth/me 返回 401(匿名不再回落默认账号——这是与线上的关键对齐项,env-local-snapshot.sh 已内置 DROBOTICFLOW_REQUIRE_SESSION_AUTH=true)
npx vite --port 5173 --strictPort
# ✅ 校验:curl -o /dev/null -w '%{http_code}' http://127.0.0.1:5173/ 返回 200
# 4. 浏览器打开 http://127.0.0.1:5173 登录
# 标注员: fanyu-full-annotator@droboticflow.local / 本地自行设置的密码
# 质检员: fanyu-full-qc@droboticflow.local / 本地自行设置的密码
# 验收员: fanyu-full-acceptance@droboticflow.local / 本地自行设置的密码
# 管理员: fanyu-admin@droboticflow.local / 本地自行设置的密码
# ✅ 校验:登录后能看到快照里的真实项目/工作流/20 个标注批次
第四步:全量服务部署(含 worker 与算子执行)
本地全量 = API + 前端 + worker + 本地迷你 K8s(算子 Job 执行)。worker 需要 kubeconfig 才能启动,算子执行需要真实集群资源。
# 1. 启动本地迷你 K8s(colima 内置 k3s)
colima start --kubernetes --cpu 4 --memory 6 --vm-type vz --vz-rosetta --dns 202.4.130.100
# ✅ 校验:kubectl get nodes 显示 Ready
# 2. 准备本地工作区 PVC + 镜像(算子 runner 用昨天构建的 localtest 镜像)
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: droboticflow-workspace, namespace: default}
spec: {accessModes: [ReadWriteMany], resources: {requests: {storage: 10Gi}}}
EOF
# ✅ 校验:kubectl get pvc droboticflow-workspace 显示 Bound
docker tag droboticflow-operator-runner:localtest localhost:5000/droboticflow-operator-runner:local
docker run -d -p 127.0.0.1:5000:5000 --restart always registry:2 # 本地 registry(镜像走本地不碰公司仓库)
docker push localhost:5000/droboticflow-operator-runner:local
# ✅ 校验:curl -s http://127.0.0.1:5000/v2/_catalog 输出包含 droboticflow-operator-runner
# 3. 启动 worker(连快照库 + 本地 K8s)
source scripts/local/env-local-snapshot.sh
OPERATOR_RUNNER_IMAGE=localhost:5000/droboticflow-operator-runner:local \
WORKSPACE_PVC_NAME=droboticflow-workspace K8S_NAMESPACE=default \
MONGO_URI=mongodb://127.0.0.1:27018/drobodata-fanyu npm run dev:worker
# ✅ 校验:curl -s http://127.0.0.1:3002/worker-api/ready 返回 ready:true
# ✅ 校验(端到端):平台上发起一条简单工作流 Run → 状态从 queued 变 running,算子 Job 在本地 k3s 创建并完成
# 4. 全量验证闸门
npm run verify:local
# ✅ 校验:lint/构建/k8s:validate 段全过;Go/Python/前端测试段见第七步说明(上游测试债,非部署问题)
第五步:标注模块与集群对齐配置
1:1 对齐声明(哪些天然对齐、哪些有差异必须知道):
| 维度 | 对齐方式 |
|---|---|
| 标注流程代码 | 本地代码 ⊇ 线上(dev 分支比线上 6eb21ada 多 3 个标注修复提交)。对齐技巧:要严格复刻线上行为就 git checkout 6eb21ada 跑;要测最新就留在 dev HEAD。差异仅这 3 个提交,都是标注任务领取/恢复类 bugfix,向前兼容 |
| 数据同步规则 | 快照是 8/31 只读副本,本地改动永不回传线上(无任何反向通道,天然单向隔离)。要新快照就重跑 fetch-mongo-snapshot.sh(会在覆盖前重建 27018 容器) |
| 接口地址映射 | 前端经 Vite 代理 /api → 127.0.0.1:3001,与线上浏览器 → 公网 LB 的路径结构完全一致(同一份前端代码、同一路由)。无 hardcoded 地址 |
| 权限配置对齐 | 快照自带线上真实账号体系(9 用户/3 组织/供应商/项目成员),角色判断逻辑走同一份 Go 代码——权限行为 1:1。CSRF 双提交 cookie 机制一致 |
| 视频预览/物化 | 线上从 BOS 桶读视频;本地无 BOS 凭据注入 → 快照里 bos:// 引用的实体视频打不开(元数据、时间轴、PTS 数据可见)。这步的差异见下方"替代兼容方案" |
| worker/算子 | 线上用 CCR digest 镜像+GPU 节点;本地用自构建镜像+本地 k3s。对标注测试无影响(人工节点不占算子资源),只影响自动算子 Run |
替代兼容方案(本地无法模拟的场景):
- 场景 A:标注工作台打不开真实视频。方案:
local-samples/video_slice/sample-video.mp4先测 UI 交互;完整验证走第六步"数据集类"索要(1-2 个 Capture 的 BOS 原始目录下载到本地,用real_source算子SOURCE_PATH指本地路径跑)。 - 场景 B:Qwen 预标注无结果(AI key 未配)。方案:快照里已含历史预标注结果(headposeArtifacts/handPrelabel 等字段),查看/编辑链路可测;生成新结果才需要真 key——索要见第六步。
- 场景 C:HeadPose/WiLoR sidecar 拉不起来(GPU 镜像)。方案:本地跳过 pose 证据分支,只测人工环节;集群侧由同事在真环境跑(他的 91 个 v56 Job 就是干这个的)。
第六步:向同事索要的资源清单
代码依赖类
| 资源 | 用途 | 对接人 |
|---|---|---|
| Gitea 账号 + longtao.wu/droboticflow 写权限 | 推送修复分支、参与评审 | 仓库 owner (longtao.wu / eust-w) |
| dev 分支的发布节奏说明(哪天 deploy) | 避免本地基线落后太多 | 同上 |
数据集类(最关键缺口)
| 资源 | 用途 | 对接人 |
|---|---|---|
| 1-2 个完整 Capture 的 BOS 原始目录(左右目视频+PTS+IMU+标定,几 GB) | 本地跑通"目录读取→物化→标注工作台看真视频"全链路 | longtao.wu(桶 owner) |
| 对应这些 Capture 的最新库快照(现在的 8/31 快照里 34 条 Capture 记录对应的桶路径列表我可导出给他勾选) | 数据与库记录配套 | 同上 |
配置密钥类
| 资源 | 用途 | 对接人 |
|---|---|---|
| AI 生成服务 key(或确认禁用) | Qwen 工作流/算子生成本地可测 | longtao.wu(secret owner) |
| 测试账号在线上的密码(如需在线上测试时用) | 只读浏览线上标注页面对照 | 同上 |
集群同步类
| 资源 | 用途 | 对接人 |
|---|---|---|
| 独立测试项目或 namespace 的授权 | 最终在真集群验收(避免混入他 v56 正式测试) | 同上 |
| 发布窗口约定(避开 v56 批处理时段) | 你将来自己 deploy 时不撞车 | 同上 |
第七步:标注模块完整测试用例参考
登录标注员(fanyu-full-annotator / 本地自行设置的密码)逐条执行:
| # | 用例 | 操作 | 通过标识 |
|---|---|---|---|
| T1 | 登录与会话 | 上述账号登录 | 进入首页,用户名"泛宇全流程测试标注员" |
| T2 | 标注批次列表 | 进入标注中心/批次页 | 能看到 20 个批次(含 4 个 pending_annotation 态任务) |
| T3 | 任务池浏览 | 打开"可领取"任务 | 列表与详情一致,无报错 |
| T4 | 领取任务 | 点"领取"某 pending 任务 | 原子变为"我的任务"(409 冲突若被并发占用属正常) |
| T5 | 工作台打开 | 进入标注工作台 | 双目时间轴/切片列表渲染(无视频画面=场景A已知边界,UI/交互/批注应正常) |
| T6 | 切片批注 | 添加/修改描述批注 | 保存后重开页面批注保留(这正是 dev 分支 3 个修复提交的场景,重点测!) |
| T7 | 提交送检 | 完成切片+语义标注后提交 | 状态转 pending_quality,质检员账号可见 |
| T8 | 质检打回 | 质检员登录,打回并填原因+问题切片 | 标注员重新领取后看到打回意见(dev 修复点之一) |
| T9 | 质检通过 | 质检员通过 | 触发抽样决策(快照数据完整可观察) |
| T10 | 最终验收 | 验收员登录处理抽中条目 | HeadPose/HandPose include/exclude 决定可提交,交付包状态更新 |
| T11 | 审计追溯 | 管理员登录查看历史/审计页 | 打回-返工链路全程可追溯 |
| T12 | 回归对比 | git checkout 6eb21ada 重跑 T6/T8 |
线上行为基线对照,确认差异只在已知 3 个修复 |
API 级补充用例(curl 直测,不依赖页面):
# 会话+CSRF 通路(任何写操作的通道)
# 在当前 bash 中输入已设置的本地密码;通过 stdin 传给 curl,避免出现在命令参数中。
read -r -s -p 'Local test password: ' LOCAL_TEST_PASSWORD; printf '\n'
export LOCAL_TEST_PASSWORD
python3 -c 'import json, os; print(json.dumps({"email": "fanyu-full-annotator@droboticflow.local", "password": os.environ["LOCAL_TEST_PASSWORD"]}))' | \
curl -c /tmp/c.txt -X POST http://127.0.0.1:3001/api/auth/login -H 'Content-Type: application/json' --data-binary @-
unset LOCAL_TEST_PASSWORD
CSRF=$(grep droboticflow_csrf /tmp/c.txt | awk '{print $NF}')
curl -b /tmp/c.txt -X POST http://127.0.0.1:3001/api/human-items/<id>/claim \
-H "X-Droboticflow-CSRF-Token: $CSRF"
# ✅ 校验:返回任务详情 JSON,且 GET /api/human-items 的 assignee 变为该用户
停止与重启: Ctrl+C 停 API/前端即可;快照库容器 --restart unless-stopped 常驻。绝对不要对 27018 库之外的任何公司资源做写操作——这条红线下,本方案所有操作与公司集群零冲突。
附录:真实数据标注链路(同事已放行下载 Capture)
线上的产物路径已被清理(桶里只剩 FYLX_B/ 原始数据和回收站),所以"看真视频"的路径是从原始数据接入:
# 1. 下载一个完整 Capture(约 235MB,左右目视频+PTS+IMU+标定)
scripts/local/download-capture.sh # 默认 FYLX_B01_AZER764007R_19700101_001838
# ✅ 校验:~/Desktop/fanyu/droboticflow/local-data/captures/ 下 10 个文件,ffprobe 能解析左目视频
# 2. 接进快照库的标注任务(改本地 27018 库里的 artifact path + 任务归属)
scripts/local/wire-local-capture.sh
# ✅ 校验:curl 登录后 GET /api/human-items/<id>/subject-content 返回 200 video/mp4
# 3. 浏览器进标注工作台
# fanyu-full-annotator@droboticflow.local 登录 → 领取的任务里双目视频真实可播、可拖进度条
原理(为什么这能通):API 的 serveResolvedRunArtifactContent 对本地路径的 artifact(path 不含 :// 且文件存在)直接走本地文件流式输出,含 Range 支持;对 bos:// 才去连 BOS。所以把快照库里的 artifact path 换成本地文件路径,标注工作台的视频播放就完全本地化了,且权限体系(角色/成员/供应商隔离)原样生效——这已实测验证(质检员访问标注员的任务正确返回 403)。
远程验收脚本的凭据配置
远程验收脚本不再内置账号密码。仅在已经获得公司环境写入授权后运行;本次文档清理并不授权执行远程验收。
- 三个
*-workflow-acceptance.sh脚本(holobrain-full-training、poc-operator、wilor-operator)必须设置DROBOTICFLOW_ACCEPTANCE_PASSWORD。 scripts/execute_remote_poc_test.py还必须设置FANYU_ANNOTATOR_PASSWORD、FANYU_QUALITY_PASSWORD、FANYU_ACCEPTANCE_PASSWORD。- 从环境负责人或未跟踪的本地凭据文件获取实际值,不在命令行参数、文档或提交中记录密码。缺少必需值时脚本直接停止。
- 旧版本曾包含固定密码;删除源码中的明文不会使旧密码失效,也不会删除已有 Git 历史。环境负责人应核对这些旧账号并轮换仍有效的密码。