SuperPlane 多实例本地开发指南：一套仓库端口映射并行运行多个开发环境

【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载导读SuperPlane 是一个一次投入、一次成型one-shot engineering的开源工厂级工程平台其本地开发环境基于 Docker Compose 编排默认将所有服务端口固定在同一组默认值上。本文讲解如何在单机上一字排开运行两套甚至五套 SuperPlane 开发实例例如superplane/与superplane2/并存通过每个仓库根目录下的.env文件覆盖端口映射与基础 URL实现互不干扰地并行调试 API、Vite 前端、Storybook、OTEL 观测与数据库工具。读完本文你将掌握多实例端口矩阵的完整配置方法、make dev.up/make dev.server的启动链路以及如何利用make db.snapshot/make db.restore让第二个实例跳过 owner 设置与 GitHub 连接直接复用已完成初始化的本地数据库。多实例方案的原理每个仓库一份 .envSuperPlane 的开发 Docker Compose 配置docker-compose.dev.yml在定义服务时大量使用${VAR:-default}形式的变量插值。Docker Compose 会自动读取仓库根目录下的.env文件参与插值因此每个克隆出来的仓库副本都可以拥有自己独立的端口映射互不影响。这正是多实例并行得以成立的基础SuperPlane 官方在仓库根目录提供了专用的模板文件 .env.multi-instance.example其中预置了 Instance A 到 Instance E 五套完整的端口方案。你不需要修改任何 Compose 文件只需要在每个仓库里把模板复制为.envcp .env.multi-instance.example .env在第一个仓库中取消Instance A区块的注释在第二个仓库中取消Instance B区块的注释第三、四、五个仓库依次对应 C、D、E像平时一样启动每个仓库例如make dev.up后执行make dev.server。启动完成后两套实例的 UI 分别位于Instance Ahttp://localhost:8000Instance Bhttp://localhost:8001说明.env不是env_file。docker-compose.dev.yml 中的注释明确指出它只参与 Compose 的变量插值只有 Compose 文件里显式引用的变量才会生效。所以多实例方案无需担心.env中的无关变量被注入容器。完整端口映射表两实例对照下表汇总了官方模板中 Instance A 与 Instance B 的端口对照C/D/E 实例以此类推每套整体偏移用途环境变量示例 A示例 B公共 APIUI 入口PUBLIC_API_PORT80008001Vite 开发服务器VITE_DEV_PORT51735174Vite 预览VITE_PREVIEW_PORT41734174StorybookSTORYBOOK_PORT60066007OTEL gRPCOTEL_GRPC_PORT43174319OTEL HTTPOTEL_HTTP_PORT43184320PgWebPGWEB_PORT80818082RabbitMQRABBITMQ_PORT56725673RabbitMQ 管理 UIRABBITMQ_MANAGEMENT_PORT1567215673pprofPPROF_PORT60606061Base URLBASE_URLhttp://localhost:8000http://localhost:8001Webhooks 基础 URLWEBHOOKS_BASE_URLhttp://localhost:8000http://localhost:8001从源码看这些端口在 docker-compose.dev.yml 中均有对应的插值引用例如app服务通过ports映射${VITE_DEV_PORT:-5173}、${VITE_PREVIEW_PORT:-4173}、${STORYBOOK_PORT:-6006}、${PUBLIC_API_PORT:-8000}、${PPROF_PORT:-6060}otel服务映射${OTEL_GRPC_PORT:-4317}与${OTEL_HTTP_PORT:-4318}pgweb服务映射${PGWEB_PORT:-8081}rabbitmq服务映射${RABBITMQ_PORT:-5672}与${RABBITMQ_MANAGEMENT_PORT:-15672}。因此.env中任一端口变量的覆盖都会直接反映到容器端口绑定上。Instance B 的 RabbitMQ 使用5673、OTEL gRPC 使用4319等都刻意与默认值错开避免宿主机端口冲突。关键变量逐项拆解PUBLIC_API_PORTUI 与 API 的统一入口PUBLIC_API_PORT是这套端口体系中最核心的变量。在 Compose 中它同时驱动app容器的端口映射以及PORT: ${PORT:-${PUBLIC_API_PORT:-8000}}API_PORT: ${API_PORT:-${PUBLIC_API_PORT:-8000}}也就是说PORT与API_PORT默认都跟随PUBLIC_API_PORT只有当 app 服务器与 Vite 代理需要刻意分离时才需要单独覆盖它们参考 .env.example 中的说明。BASE_URL 与 WEBHOOKS_BASE_URL链接与回调的来源BASE_URL默认http://localhost:8000用于浏览器内链接与外部回调地址WEBHOOKS_BASE_URLCompose 内默认http://app:8000本机开发建议覆盖为宿主机可达地址用于发给外部系统的 webhook 回调。docker-compose.dev.yml 中明确提示当通过隧道例如ngrok http 8000访问时应在.env中把WEBHOOKS_BASE_URL设置为公网隧道地址不要带尾斜杠。多实例场景下两套实例的这两个 URL 必须与各自的PUBLIC_API_PORT保持一致否则回调会打到错误的实例。此外还有一个容易遗漏的联动项ALLOWED_WS_ORIGINSCompose 默认http://localhost:8000控制 WebSocket 的跨域白名单.env.example 建议在修改PUBLIC_API_PORT时同步对齐BASE_URL、WEBHOOKS_BASE_URL与ALLOWED_WS_ORIGINS。OTEL 双端口gRPC 与 HTTP 分离SuperPlane 开发环境内置 OpenTelemetry Collectorotel/opentelemetry-collector-contrib:0.110.0dev profile同时暴露 gRPCOTEL_GRPC_PORT默认 4317与 HTTPOTEL_HTTP_PORT默认 4318两个接收端口。app 容器的 exporter 指向http://otel:4317gRPC 协议。多实例时两套 Collector 使用不同端口即可独立采集遥测数据。pprof本地性能剖析当PPROF_ENABLEDyesdev Compose 默认开启时Go 服务会在http://localhost:${PPROF_PORT}/debug/pprof/暴露 CPU、heap、goroutine、block、mutex 等剖析端点详见 .env.example 与 profiling 文档 的说明该端点无鉴权仅适合本地开发。多实例时每个实例分配独立端口如 A6060、B6061方便分别抓取剖析数据。PgWeb浏览器里的数据库管理PgWebsosedoff/pgwebdev profile通过DATABASE_URL: postgres://postgres:the-cake-is-a-liedb:5432/superplane_dev?sslmodedisable直连本 Compose 栈内的 Postgres。每套实例的PGWEB_PORT独立即可为各自实例单独打开数据库 UI。启动链路make dev.up 与 make dev.server 做了什么多实例启动与单实例完全一致只是每套仓库的.env不同。从 Makefile 可以看到完整链路make dev.up创建tmp/screenshots与 Go 缓存目录执行docker compose up -d --wait --build --pull always拉起app、db、rabbitmq等服务并在非 CI 环境额外构建本地 runner 镜像。app容器默认command: [sleep, infinity]处于空闲态。make dev.setup首次需要安装前端依赖npm install、生成 protobuf/OpenAPI 代码、下载 Go 模块并编译cmd/server/main.go、创建并迁移superplane_dev、superplane_test与broker数据库最后启动 task-broker 并注入local、e1-large-amd64等 fleet。make dev.server拉起 runner 工作进程然后执行docker-entrypoint.dev.sh该脚本docker-entrypoint.dev.sh先清理残留的air/vite进程再并行启动 Go 热重载air与 Vite 开发服务器最后通过scripts/wait-for-app等待应用就绪。细节提醒docker-compose.dev.yml 注释中提到两个并发go build例如两个 Air 实例可能因共享模块下载临时文件而互相干扰出现rename ... .tmp: no such file or directory与failed to build, error: exit status 1。为此 Compose 将GOMODCACHE/GOCACHE固定到命名卷go-pkg-cache:/go多实例各有一套命名卷天然规避该问题。五实例扩展Instance C/D/E官方模板不止支持双实例。.env.multi-instance.example 预置了直到 Instance E 的完整端口矩阵变量ABCDEPUBLIC_API_PORT80008001800280038004VITE_DEV_PORT51735174517551765177VITE_PREVIEW_PORT41734174417541764177STORYBOOK_PORT60066007600860096010OTEL_GRPC_PORT43174319432143234325OTEL_HTTP_PORT43184320432243244326PGWEB_PORT80818082808380848085RABBITMQ_PORT56725673567456755676RABBITMQ_MANAGEMENT_PORT1567215673156741567515676PPROF_PORT60606061606260636064BASE_URLhttp://localhost:8000…8001…8002…8003…8004WEBHOOKS_BASE_URLhttp://localhost:8000…8001…8002…8003…8004可以看到整套端口体系按实例整体偏移宿主机的端口冲突风险主要来自同实例内的服务例如 8000 与 8081 并不相邻只要按模板取值即可安全并行。模板也提示根据需要为你的环境调整。让第二实例跳过初始化本地数据库快照多实例的典型痛点第二套实例启动后仍要重新完成 owner 设置、组织创建与 GitHub 连接。SuperPlane 提供的解法是本地数据库快照make db.snapshot对当前 worktree 的superplane_dev执行pg_dump -Fc --no-owner --no-acl输出到.local/superplane_dev.dump该文件被 gitignore勿提交。实现见 scripts/db_snapshot.sh。make db.restore从该 dump 恢复superplane_dev并自动应用尚未执行的迁移见 scripts/db_restore.sh 与 Makefile 中的目标注释。官方流程完整说明见 Local database snapshot在第一个实例的 UI 中完成 owner、组织、GitHub 与 workspace 设置执行make db.snapshot保存基线 dump之后如果有想保留的后续设置变更再次执行make db.snapshot若新环境是另一个 worktree先把.local/superplane_dev.dump复制过去在新 worktree 中执行make db.restore若make dev.server已在运行重启它。注意事项快照/恢复必须在提供你所用 UI 的那个 worktree 中执行make db.snapshot与make db.restore使用该 worktree 的 Compose 栈其中的 Postgres 是db:5432而PUBLIC_API_PORT来自.env只是 UI 端口与数据库地址无关。恢复只替换superplane_dev不会改动superplane_testdump 只保存 Postgres 行数据不包含 blob 文件GitHub App 凭据等依然来自.env快照脚本硬性限制只对superplane_dev生效db.snapshot only runs against superplane_dev。这套机制对脚本与 Agent 自动化创建本地环境同样适用——官方文档明确建议当脚本或 Agent 创建本地环境时使用该路径。多实例的典型应用场景与排查要点并行调试前后端改动在两套仓库分别应用不同分支的改动通过 A/B 端口对照 UI 行为差异互不干扰验证外部回调接入 ngrok 等隧道时为每个实例设置独立的公网 URL并把WEBHOOKS_BASE_URL、BASE_URL与ALLOWED_WS_ORIGINS一并对齐端口冲突排查若某实例启动失败先用docker compose ps确认是否有容器未绑定到预期端口再核对.env是否只取消注释了一组实例区块模板默认全部注释资源考量每套实例都会拉起 Postgres 17.5、RabbitMQ 3.8.17、otel collector 与 app 容器五实例并行对 CPU 与内存要求较高实际并行数量请根据本机资源调整。总结SuperPlane 的多实例本地开发方案建立在每个仓库独立.env Compose 变量插值之上复制 .env.multi-instance.example 为.env、取消对应实例区块的注释即可获得一套完整且互不冲突的端口矩阵配合make db.snapshot/make db.restore快速克隆已初始化的superplane_dev第二个实例甚至不需要重复 owner 设置与 GitHub 连接。无论你是手工维护两套工作区还是让脚本与 Agent 批量创建本地环境这套方案都能让多个 SuperPlane 开发实例在同一台机器上并驾齐驱。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐Polar 多实例本地开发环境用 dev docker 并行管理多个隔离工作树Polar 多实例本地开发环境用 dev docker 并行管理多个隔离工作树 导读 Polar 是一个面向智能时代的计费billing平台其代码库横跨后端前端金融科技Cherry Studio 如何用 CS_DEV_USER_DATA_SUFFIX 并行运行多个开发实例Cherry Studio 如何用 CS_DEV_USER_DATA_SUFFIX 并行运行多个开发实例 在 Cherry Studio一个基于 Elect人工智能大模型AI 应用交互助手本地部署Taro跨端开发终极指南一套代码多端运行Taro跨端开发终极指南一套代码多端运行 Taro是一个开源的开放式跨端跨框架解决方案它让开发者能够使用React、Vue或Nerv等现代前端框架来开发微信前端小程序跨平台移动开发上一篇终极Step CLI实战指南7个真实场景教你轻松处理OAuth 2.0和OIDC下一篇Laravel LogViewer 终极使用指南快速掌握日志管理神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考