droboticflow/docs/local-dev-guide.zh-CN.md

11 KiB
Raw Blame History

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

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

0. 隔离边界与本地环境分工(先读这个)

事项 规则
MongoDB(双库并存) 27017 空库(fanyu-mongo,env-local.sh):用于空库初始化、合成测试及基础工作流 CRUD 调试;
27018 快照库(fanyu-mongo-restore,env-local-snapshot.sh):承载公司生产数据结构副本,用于标注/质检/验收工作台与接口真实结构复刻(详见 docs/HANDOFF.md);
两者均为本机容器,绝不把本地开发 API 指向公司生产 Mongo 实例
Kubernetes 日常本地开发不导出 KUBECONFIG;线上只读排查或 Fanyu 正式发布统一按 docs/release/README.md 与 python3 scripts/release.py 执行(scripts/deploy-k8s.sh 已拦截 Fanyu),任何集群写操作须用户明确授权
BOS / AI 轻量空库模式(env-local.sh)默认留空禁用,数据源用本地路径(local-samples/);快照库复刻模式通过 WORKSPACE_MOUNT_PATH 挂载已下载至 local-data/workspace 的本地 Capture(见 docs/HANDOFF.md §4),公司 BOS 桶默认只读
镜像仓库 本地构建演练不登录、不推送;Fanyu 候选镜像构建与发布见 docs/release/README.md(使用 scripts/release-build-api-image.sh 注入构建 commit 与时间戳)

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. 分层测试命令

日常改动优先按 docs/agents/verification.md 使用 npm run verify:plan -- --base <起点>、npm run verify:quick 与 npm run verify:task。全量与专项命令如下:

层 命令 说明
分层快检 / 任务级 npm run verify:quick -- --base <ref> / npm run verify:task -- --base <ref> 按改动范围自动选择受影响单元与业务回归
单算子 scripts/local/run-operator.sh <slug> 真实执行,秒级
单算子单测 .venv/bin/python -m pytest backend/operator-runner -k <关键词> 或 tests/backend/<某算子>_test.py
Go 基线门禁 npm run test:go:gate 对照 tests/known-failures.json 仅在新增失败时报红(跑前先停本地 3001 API)
Python 全量 npm run test:python 用系统 python3;建议先 source .venv/bin/activate
前端基线门禁 npm run test:frontend:gate 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}}'

注:Fanyu 正式发布镜像必须使用 GOPROXY=https://goproxy.cn,direct scripts/release-build-api-image.sh 构建(自动注入 DROBOTICFLOW_BUILD_COMMIT 与 DROBOTICFLOW_BUILD_TIME 并输出不可变 digest),完整流程见 docs/release/README.md。非 Fanyu 环境才使用 scripts/build-and-push-images.sh。

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。