droboticflow/docs/local-dev-guide.zh-CN.md
d-robotics 8369b7e951 Restore local dev toolkit (recovered after working copy loss)
- scripts/local/env-local.sh + run-operator.sh (verified working again)
- local-samples for json_to_csv + video_slice
- docs/local-dev-guide.zh-CN.md + docs/release-checklist.zh-CN.md
2026-09-17 19:17:54 +08:00

9.4 KiB
Raw Blame History

本地开发调试指南(macOS / 隔离环境)

本指南描述如何在不接触公司集群的前提下,在本机完成单功能开发与调试。环境搭建背景见仓库根目录 README.md,业务概念见 docs/platform-usage-manual.zh-CN.md。

0. 隔离边界(先读这个)

事项 规则
MongoDB 只用本机容器 fanyu-mongo(127.0.0.1:27017),绝不指向公司实例
Kubernetes 不导出 KUBECONFIG、不使用 fanyu.conf;发布走 docs/release-checklist.zh-CN.md 且须同事确认
BOS / AI 本地全部留空禁用;数据源一律用本地路径(local-samples/)
镜像仓库 本地构建演练不登录、不推送;推送发布见发布清单

1. 环境准备(已完成则跳过)

# 工具链(一次性)
brew install go colima docker docker-buildx ffmpeg mongosh
colima start --cpu 4 --memory 6 --vm-type vz --vz-rosetta

# 本地 MongoDB(只绑 127.0.0.1;--restart 保证 colima/VM 重启后自动跟随启动)
docker run -d --name fanyu-mongo --restart unless-stopped -p '127.0.0.1:27017:27017' -v fanyu-mongo-data:/data/db mongo:7

# Python 算子依赖(公司网络下 pip 默认源不可用,用阿里镜像)
python3 -m venv .venv
.venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r requirements-dev.txt

# Go 模块代理(公司网络下 proxy.golang.org 不可用)
go env -w GOPROXY=https://goproxy.cn,direct

# 前端依赖
npm install

注意事项(踩过的坑):

  • Go 进程不读取 .env.local:仓库没有 godotenv,MONGO_URI 等变量必须 shell 导出。
  • colima VM 内 DNS 可能失效(systemd-resolved 未安装导致 resolv.conf 指向不存在的 stub)。症状:docker pull 报 lookup ... on [::1]:53: connection refused。修复:colima ssh -- sudo sh -c 'printf "nameserver 202.4.130.100\nnameserver 202.4.130.101\n" > /etc/resolv.conf'。
  • Docker Hub 直连超时:改走国内镜像 docker pull docker.m.daocloud.io/library/mongo:7 再 docker tag 回 mongo:7。
  • colima 每次重建 VM 后要重配两样:VM 内 DNS(见上文修复命令)和 docker daemon 的 registry mirror(colima ssh -- sudo sh -c 'printf ... > /etc/docker/daemon.json && systemctl restart docker')。建议保持 --vm-type vz --vz-rosetta 参数启动。
  • 日常启停:colima start / colima stop。Mongo 容器已设 --restart unless-stopped,会随 docker daemon 自动跟随启动;只有 colima VM 被删除重建(colima delete)后容器才会丢,需要按上面命令重建。
  • API 报 server selection timeout ... connection refused = 27017 没人监听:docker start fanyu-mongo(先确认 colima status 是 running)。API 进程本身不会死,Mongo 恢复后立即自愈,无需重启 npm run dev。

2. 启动本地平台(API + 前端)

source scripts/local/env-local.sh   # 每个新 shell 都要先 source
npm run dev                          # API :3001 + Vite :5173
  • 浏览器打开 http://127.0.0.1:5173,首次用「创建超管账号」入口建一个本地管理员(如 admin@local.dev)。
  • 已验证可用:登录/会话、CSRF 双提交写保护、算子目录(111 个)、存储连接、项目、工作流(含节点)全套 CRUD。
  • 预期边界:不启动 worker(npm run dev:full 本地起不来——worker 启动必须有 kubeconfig)。页面上点"运行"后 Run 会停在 queued,这是轻量层的正常行为。如需本地端到端,需另行搭建本地迷你 K8s(kind/colima-k8s),属于后续升级项。

写接口的 curl 调试需带 CSRF(与线上一致):

curl -c /tmp/c.txt -X POST http://127.0.0.1:3001/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@local.dev","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/projects \
  -H 'Content-Type: application/json' -H "X-Droboticflow-CSRF-Token: $csrf" \
  -d '{"name":"...","storageConnectionId":"<id>","storageBucket":"..."}'

3. 单算子一键调试(核心工作流)

scripts/local/run-operator.sh <slug> [输入artifact列表JSON文件]
  • <slug> 是 operator-repos/builtin/ 下的目录名;脚本自动读取 operator.json / runtime_contract.json 的 handler,用与 worker 在 K8S Job 里完全相同的方式调用 backend/operator-runner/main.py。
  • 产物固定写入 local-runs/<slug>/<时间戳>/(已 .gitignore):outputs/、result.json、stage-manifest.json。
  • 默认输入:local-samples/<slug>/input.json(存在时)。
  • 附加超参:OPERATOR_EXTRA_HYPERPARAMS='[{"key":"SEGMENT_DURATION_SECONDS","value":"4"}]'。
  • 已内置样例:json_to_csv(3 行 JSON→CSV)与 video_slice(本地 10 秒测试视频→3 段虚拟切片)。

改算子源码的调试循环(不需要任何镜像构建):

# 1. 直接改 operator-repos/builtin/<slug>/src/operator.py
# 2. run-operator.sh 默认通过 DROBOTICFLOW_OPERATOR_SOURCE 直指这份源码,立即验证
scripts/local/run-operator.sh <slug>
# 3. 验证通过后,同步镜像副本(否则 operators:manifests:check 会挂):
npm run operators:repos

4. 分层测试命令

层 命令 说明
单算子 scripts/local/run-operator.sh <slug> 真实执行,秒级
单算子单测 .venv/bin/python -m pytest backend/operator-runner -k <关键词> 或 tests/backend/<某算子>_test.py
Go 全量 npm test(= go test ./...) 不需要 Mongo/集群
Python 全量 npm run test:python 用系统 python3;建议先 source .venv/bin/activate
前端 npm run test:frontend node --test,无需浏览器
总闸门 npm run verify:local lint + 全部测试 + 构建 + k8s 清单 dry-run

5. 算子发布链本地演练(无 docker)

内置算子的正式发布流程是"改码 → 生成仓库清单 → 构建镜像 → digest 钉版 → 目录同步 → reconcile"。本地可以演练全部不碰 docker 的环节:

npm run operators:repos                # 同步 operator-repos 与 backend 镜像副本
python3 scripts/update_operator_release_manifests.py --slug <slug> \
  --image <registry/ref:tag> --image-id <registry/ref@sha256:digest>   # 钉版(digest 来自实际构建)
npm run operators:images               # 重新生成算子目录/镜像契约
npm run operators:images:check         # 一致性闸门,必须通过

6. 镜像构建演练(本地、不推送)

公司网络下四个拦路虎及解法:

  1. 基础镜像拉不下来(Docker Hub 直连超时):先 docker pull docker.m.daocloud.io/library/<镜像> 再 docker tag 回标准名(golang:1.24-bookworm、node:22-alpine、debian:bookworm-slim、python:3.11-slim 都需要)。
  2. 构建时 go mod download 超时:Dockerfile 里默认 GOPROXY=proxy.golang.org 被墙,构建时必须传 --build-arg GOPROXY=https://goproxy.cn,direct。
  3. apt/pip 下载超时(operator-runner 镜像重灾区):用本机代理 127.0.0.1:7890。colima 容器里访问宿主机代理要用 VM 网关地址(colima ssh -- ip route | grep default,当前为 192.168.5.2),以 --build-arg http_proxy=http://192.168.5.2:7890 注入(docker 的 http_proxy/https_proxy build-arg 无需 Dockerfile 声明即自动生效)。
  4. QEMU 交叉编译 Go 会段错误:colima 需用 --vm-type vz --vz-rosetta 启动(Rosetta 模拟 amd64 接近原生速度)。

因此公司网络内的本地构建演练用 docker 原生命令(scripts/build-and-push-images.sh 未透传 GOPROXY/代理,直接跑会卡在 go mod download 或 pip):

PROXY=http://192.168.5.2:7890   # colima VM 看到的宿主机代理地址

docker build -f Dockerfile.worker --platform linux/amd64 \
  --build-arg GOPROXY=https://goproxy.cn,direct -t droboticflow-worker:localtest .
docker build -f Dockerfile.drosync-coordinator --platform linux/amd64 \
  --build-arg GOPROXY=https://goproxy.cn,direct -t drosync-coordinator:localtest .
docker build -f Dockerfile.api --platform linux/amd64 \
  --build-arg GOPROXY=https://goproxy.cn,direct \
  --build-arg http_proxy=$PROXY --build-arg https_proxy=$PROXY \
  -t droboticflow-api:localtest .
docker build -f Dockerfile.operator-runner --platform linux/amd64 \
  --build-arg http_proxy=$PROXY --build-arg https_proxy=$PROXY \
  -t droboticflow-operator-runner:localtest .

# 验证产物架构
docker image inspect droboticflow-operator-runner:localtest --format '{{.Os}}/{{.Architecture}}'

注:真正推送发布时走 scripts/build-and-push-images.sh(见发布清单)——如果届时也卡在 go mod download / pip,可先与同事确认是否把代理 build-arg 透传进脚本,或临时在本机代理开着的状态下用上面的原生命令构建后手动 docker push。

7. 常见问题

  • go run 卡在下载依赖:确认 go env GOPROXY 是 https://goproxy.cn,direct。
  • pytest 报 numpy/cv2 缺失:用 .venv/bin/python -m pytest 而不是裸 pytest。
  • 算子报"无法获取真实输入文件":检查 input.json 里 items[].path(文件级 path 是算子找源的入口,不是 artifact 顶层 path)。
  • API 起不来报 Mongo 连接失败:docker start fanyu-mongo,确认 mongosh --host 127.0.0.1 能 ping。