【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载SuperPlane 本地开发环境在首次启动时需要在 Web UI 中完成 owner 初始化、组织创建、GitHub 连接等一系列一次性设置。本文介绍基于 Postgres dump 的本地数据库快照方案完成一次 UI 配置后通过make db.snapshot把superplane_dev数据库的整体状态保存为本地 dump 文件之后在任何新 worktree 中用make db.restore秒级恢复出可直接使用的开发环境无需重复任何配置步骤。读完本文你将掌握该机制的工作原理、完整操作流程、底层命令细节、边界限制以及如何在多实例并行开发场景中组合使用。为什么需要数据库快照SuperPlane 的本地开发环境由 docker-compose.dev.yml 定义的 Compose 栈驱动其中 Postgrespostgres:17.5以服务名db、端口5432对外提供服务应用默认连接的数据库名为superplane_dev。一个全新的本地环境要进入可用状态必须在 UI 中依次完成owner 设置installation admin 初始化对应迁移db/migrations/20260324120000_add-installation-admin-to-accounts.up.sql组织创建organization 记录及相关角色、策略初始化GitHub 连接GitHub App / OAuth 授权凭据通过环境变量注入不落库工作区与首屏相关配置。这些步骤一旦在 UI 里做过其最终状态全部沉淀在superplane_dev这张数据库里。本地数据库快照的思路就是把做完配置后的数据库整体打包成 dump之后用 dump 重建数据库从而让脚本或 AI Agent 创建本地环境时完全不碰 UI 配置流程——这正是 docs/contributing/local-database-snapshot.md 所定位的适用路径。快照机制的调用链与核心原理make db.snapshot与make db.restore两个目标定义在仓库根目录的 MakefileL386-L399它们通过 Compose 栈在app容器内执行对应的 Shell 脚本# Local only. Writes this worktrees superplane_dev to # .local/superplane_dev.dump so a later restore can skip owner setup # and GitHub connection. Postgres in this stack is db:5432. # The dump is gitignored. db.snapshot: $(COMPOSE) exec app ./scripts/db_snapshot.sh superplane_dev # Local only. Replaces this worktrees superplane_dev from # .local/superplane_dev.dump, then applies pending migrations. Use this # to create a new local environment without owner setup or GitHub # connection. It does not touch superplane_test. Restart make # dev.server after restore if it is already running. db.restore: $(COMPOSE) exec app ./scripts/db_restore.sh superplane_dev两个目标都只作用于superplane_dev且都运行在当前 worktree 自己的 Compose 栈上。整条链路可以概括为make db.snapshot └─ docker compose exec app scripts/db_snapshot.sh superplane_dev └─ pg_dump -Fc --no-owner --no-acl → .local/superplane_dev.dump make db.restore └─ docker compose exec app scripts/db_restore.sh superplane_dev ├─ pg_terminate_backend 断开活动连接 ├─ dropdb createdb 重建 superplane_dev ├─ pg_restore 载入 dump └─ scripts/db_migrate.sh 补齐 pending 迁移关键设计点dump 采用pg_dump的自定义压缩格式-Fc恢复用pg_restore两者都带--no-owner --no-acl意味着 dump 中不固化 owner 与 ACL 信息恢复后所有对象归属当前恢复连接的用户postgres保证跨机器、跨容器恢复的一致性。保存快照一次配置随时复用操作步骤在 Web UI 中完成 owner、organization、GitHub、workspace 的全部初始化配置首次环境必需。执行make db.snapshotSuperPlane 会把当前superplane_dev写入.local/superplane_dev.dump。后续如果又做了想保留的配置变更比如新增了一个组织、换了一个 GitHub App再次执行make db.snapshot覆盖旧 dump 即可。不要提交.local/目录——dump 是纯本地产物且 .gitignore 第 28 行已经忽略了.local/请保持该规则不被破坏。底层实现细节快照由 scripts/db_snapshot.sh 完成核心命令如下DUMP_PATH${DUMP_PATH:-.local/superplane_dev.dump} DB_NAME${1:-superplane_dev} if [[ $DB_NAME ! superplane_dev ]]; then echo db.snapshot only runs against superplane_dev. 2 exit 1 fi export PGPASSWORDthe-cake-is-a-lie mkdir -p $(dirname $DUMP_PATH) pg_dump -Fc --no-owner --no-acl \ -h db -p 5432 -U postgres -d $DB_NAME \ -f $DUMP_PATH if [[ -n ${PUBLIC_API_PORT:-} ]]; then echo Wrote ${DUMP_PATH} from the database for http://localhost:${PUBLIC_API_PORT}. else echo Wrote ${DUMP_PATH}. fi值得注意的实现细节硬性数据库名校验脚本第一道防线就是拒绝非superplane_dev的库名防止误把测试库或其他库打进去连接参数固定-h db -p 5432 -U postgres对应 Compose 栈内的 Postgres 服务与默认超级用户密码来自docker-compose.dev.yml中POSTGRES_PASSWORD: the-cake-is-a-lie的环境注入仅本地开发使用-Fc自定义格式压缩存储、体积小、恢复时可按需选择性加载是pg_restore的标准搭档--no-owner --no-acl剥离对象属主与权限使 dump 在任意环境恢复时不会因用户/角色差异失败DUMP_PATH可通过环境变量覆盖脚本读取DUMP_PATH环境变量默认值.local/superplane_dev.dump恰好与 Makefile 的预期路径一致输出提示关联 UI 端口若.env中配置了PUBLIC_API_PORT脚本会在结束时提示 dump 对应的 UI 地址http://localhost:${PUBLIC_API_PORT}方便确认快照取自哪个实例。恢复快照新环境秒级就绪操作步骤如果新环境位于不同的 worktree先把.local/superplane_dev.dump拷贝到该 worktree 的.local/目录下docker-compose.dev.yml将仓库根目录 bind mount 为容器的/app脚本路径解析基于当前 worktree。执行make db.restoreSuperPlane 会用 dump 重建superplane_dev并自动应用所有 pending 迁移。如果make dev.server已经在运行重启它让后端与前端进程重新连接新的数据库状态。恢复操作只替换superplane_dev不影响superplane_test——测试库的独立性被刻意保留避免本地快照干扰测试数据。底层实现细节恢复由 scripts/db_restore.sh 完成其执行顺序很讲究值得逐段理解DUMP_PATH${DUMP_PATH:-.local/superplane_dev.dump} DB_NAME${1:-superplane_dev} if [[ $DB_NAME ! superplane_dev ]]; then echo db.restore only runs against superplane_dev. 2 exit 1 fi if [[ ! -f $DUMP_PATH ]]; then echo Dump file ${DUMP_PATH} is missing. 2 echo Set up the UI, then run make db.snapshot. 2 exit 1 fi第一步缺失防护。脚本在动数据库之前先确认 dump 文件存在不存在时直接提示“先在 UI 里完成配置再执行make db.snapshot”避免在无快照的情况下盲目重建出一个空库。psql -h db -p 5432 -U postgres -d postgres -q -v ON_ERROR_STOP1 \ -c SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname ${DB_NAME} AND pid pg_backend_pid(); dropdb -h db -p 5432 -U postgres --if-exists --force $DB_NAME createdb -h db -p 5432 -U postgres $DB_NAME第二步安全重建。先用pg_terminate_backend强制断开superplane_dev上除自身外的所有活动连接否则 dropdb 会因连接占用失败再dropdb --if-exists --force删除旧库最后createdb重建空库。pg_restore --no-owner --no-acl \ -h db -p 5432 -U postgres -d $DB_NAME \ $DUMP_PATH ./scripts/db_migrate.sh $DB_NAME第三步恢复 迁移。pg_restore把 dump 数据灌入新库随后调用 scripts/db_migrate.sh 以golang-migrate风格执行db/migrations与db/data_migrations两套迁移目录的up并重新生成db/structure.sql作为结构基准。这一步保证了即使 dump 创建于较早的迁移版本恢复后数据库 schema 也能自动对齐当前仓库的最新迁移状态——这正是“恢复后立刻可用”的底层保障。脚本末尾同样会根据PUBLIC_API_PORT提示对应的 UI 地址并提醒“迁移后如需刷新快照再跑一次make db.snapshot”。边界与限制快照不覆盖什么理解限制才能避免误用。依据 docs/contributing/local-database-snapshot.md 与 Compose 配置快照方案存在以下明确边界边界说明只含 Postgres 行数据dump 记录的是superplane_dev的表数据不包含 blob 文件blob 存储独立于库开发环境默认BLOB_STORAGE_PROVIDERfilesystemblob 落在 Docker 卷blob-data:/var/lib/superplane/blobs见 docker-compose.dev.yml恢复数据库不会带回这些文件GitHub App 凭据不入库GitHub 相关凭据通过SUPERPLANE_GITHUB_APP_*、GITHUB_CLIENT_ID等环境变量注入见 docker-compose.dev.yml L84-L85、L110-L115它们留在.env/ 容器环境里不属于 dump 范围恢复后无需重新授权即可复用同一套凭据只动superplane_devsuperplane_test不受影响快照不会破坏测试数据不清理 Docker 卷恢复只替换数据库不会 wipe 任何 Docker volumes也不会动 RabbitMQ、blob 卷等基础设施纯本地产物.local/已被 .gitignore 忽略严禁提交一个典型的误用场景提醒如果你关心 blob如上传的附件、制品仅靠数据库快照是不够的需要另行备份blob-data卷本文方案的设计意图是跳过 UI 配置流程而非整体数据灾备。多实例并行开发快照 端口隔离当需要并行运行两个 SuperPlane 实例例如同时维护superplane/和superplane2/两个 worktree时快照方案与端口隔离组合使用效果最佳详见 docs/contributing/multi-instance-dev.md每个仓库根目录各自维护.env从.env.multi-instance.example复制模板并启用不同端口块实例 A 用8000、实例 B 用8001在服务 UI 的那个 worktree里执行make db.snapshot与make db.restore新 worktree 先拷贝 dump 再make db.restore即可跳过 owner 设置与 GitHub 连接直接得到一个已配置好的第二实例。可覆盖的关键端口变量包括PUBLIC_API_PORTUI/API 端口、VITE_DEV_PORT、STORYBOOK_PORT、OTEL_GRPC_PORT、RABBITMQ_PORT、PPROF_PORT以及BASE_URL/WEBHOOKS_BASE_URL等完整映射见 docs/contributing/multi-instance-dev.md。由于快照脚本会读取PUBLIC_API_PORT并体现在输出提示中多实例下务必区分清楚dump 取自哪个端口实例、恢复到哪个端口实例——原则是快照与恢复都围绕“你正在使用的那个 UI 对应的 worktree”执行。常见问题排查make db.restore报 Dump file ... is missing说明该 worktree 的.local/下没有 dump。先在已完成配置的实例上跑make db.snapshot再把.local/superplane_dev.dump拷过来跨 worktree 场景必须手动拷贝因为.local/不随 git 传输。恢复后 UI 行为异常如果make dev.server在恢复前就已经在跑进程可能仍持有旧连接或旧内存状态先重启make dev.server。想回退到更早状态快照是单文件覆盖式每次make db.snapshot都会覆盖.local/superplane_dev.dump。若需要保留多个历史状态可在执行前自行把 dump 文件复制一份另存脚本支持通过DUMP_PATH环境变量指定输出路径。误操作测试库脚本对非superplane_dev的库名直接拒绝执行不要手动绕过该校验superplane_test应始终保持独立。小结本地数据库快照把“UI 一次性配置”与“环境创建”解耦make db.snapshot用pg_dump -Fc把配置完成的superplane_dev固化为.local/superplane_dev.dumpmake db.restore则通过“断开连接 → 重建库 →pg_restore→ 自动迁移”四步把它还原成可用的新环境。这套机制对脚本化、Agent 化创建本地开发环境尤其有价值同时清楚界定了边界blob 文件与 GitHub App 凭据不在 dump 范围内superplane_test永不被触碰。配合 docs/contributing/multi-instance-dev.md 的端口隔离方案即可在多个 worktree 间快速复制出完全一致的开发体验。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐Super-Linter开发者指南devcontainer Make开发环境快速上手从克隆到跑通测试套件Super Linter开发者指南devcontainer Make开发环境快速上手从克隆到跑通测试套件 这是一份面向新贡献者的 Super Linte代码质量CI/CDRhit如何用 1 秒读完百万行 Nginx 日志的完整指南Rhit如何用 1 秒读完百万行 Nginx 日志的完整指南 凌晨三点access.log 五十 MB你不想再靠 grep 硬扛 半夜用户报障你只想马上约700欧完整指南把乱撞的廉价割草机改造成RTK GPS智能割草机器人约700欧完整指南把乱撞的廉价割草机改造成RTK GPS智能割草机器人 升级完成的那天看着它一行接一行地割、精准地绕开花坛你大概会忘了它曾经像个喝醉的陀螺机器人嵌入式智能硬件硬件开发自动驾驶上一篇突破物理内存限制OBMM单节点内存扩展方案在大数据库中的应用下一篇5分钟上手libcdma从安装到实现异步内存传输的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考