forked from longtao.wu/droboticflow
- 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
9.4 KiB
9.4 KiB
本地开发调试指南(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. 镜像构建演练(本地、不推送)
公司网络下四个拦路虎及解法:
- 基础镜像拉不下来(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 都需要)。 - 构建时
go mod download超时:Dockerfile 里默认GOPROXY=proxy.golang.org被墙,构建时必须传--build-arg GOPROXY=https://goproxy.cn,direct。 - 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 声明即自动生效)。 - 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。