Supabase Studio 深度解析从本地开发到 Docker 自托管的 Dashboard 部署全链路【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabaseSupabase Studio 是 Supabase 仓库中用于管理数据库的可视化 Dashboard既服务于自托管部署Docker Compose / CLI也直接支撑官方托管平台的 Web 控制台。本文以 apps/studio/README.md 为核心骨架结合仓库中的package.json、Dockerfile、docker-compose.yml与源码实现完整覆盖功能边界、开发环境搭建、自托管运行配置以及平台/自托管双模式隔离机制读完即可在本地跑起 Studio 开发服务器并在 Docker 环境中完成一次可复制的自托管接入。一、定位与功能边界Studio 不是什么README 首先明确了 Studio 的定位它与既有部署方式配合工作本地 Docker Compose 环境或 Supabase CLI 拉起的 stack而不承担部署与项目管理的职责。这一定位直接决定了它对外暴露的功能范围Table SQL editors表编辑器与 SQL 编辑器注意Saved queries保存的查询在自托管模式下不可用Database management数据库管理覆盖 Policies行级安全策略、Roles角色、Extensions扩展、Replication复制API documentationAPI 文档。一个关键的设计原则是项目设置Project Settings在 Dashboard 之外管理。README 原文明确指出——如果你用 docker compose 部署就应该在 docker-compose 文件里管理配置如果自托管到自有云环境则应把密钥与环境变量放入 vault 或 secrets manager。换句话说Studio 是一个只读消费配置 管理数据库的控制台而不是配置的产生者。这个边界在源码中有清晰的体现apps/studio/proxy.ts 在 Next 运行时拦截/api/:function*请求当IS_PLATFORM为真即托管平台模式且路径不在托管白名单lib/hosted-api-allowlist.ts内时直接返回 404 Endpoint not supported on hosted——自托管专用的 API 在平台模式下被整体屏蔽apps/studio/start.ts 中 TanStack 运行时通过全局请求中间件复用同一份白名单实现相同语义。从源码结构看Studio 通过运行时白名单 IS_PLATFORM开关在同一份代码库中同时承载了自托管 Dashboard 与托管平台控制台两种形态这正是 README 第一句A dashboard for managing your self-hosted Supabase project, and used on our hosted platform的工程含义。二、技术栈与双运行时架构README 声明 Studio 使用Next.js Tailwind构建。进一步查看 apps/studio/package.json 可以发现当前代码库正处于一次框架双轨迁移之中这一点在 apps/studio/AGENTS.md 与 apps/studio/TANSTACK_MIGRATION.md 中有详细说明Next.js pages routerpages/**与 TanStack Startroutes/**并行运行环境变量STUDIO_FRAMEWORK决定pnpm dev/pnpm build走哪条运行时默认next解析逻辑位于 apps/studio/scripts/dispatch.js。该脚本读取.env/.env.local中的STUDIO_FRAMEWORK把dev、build、start分发到对应的dev:next/dev:tanstack等脚本package.json中的核心脚本映射如下dev/build/start→node scripts/dispatch.js target框架分发入口dev:next→next dev -p ${STUDIO_PORT:-8082}dev:tanstack→vite dev --port ${STUDIO_PORT:-8082}Node 堆上限 8192MBtest→vitest --run --coveragetest:watch→vitest watch。迁移文档 apps/studio/TANSTACK_MIGRATION.md 强调了一条纪律迁移期间绝不删除任何pages/...文件因为多数routes/**文件只是对pages/**默认导出的薄封装Next 文件对两个运行时都是承重结构正文搬移与文件删除统一留到最终清理阶段。依赖方面package.json还能印证其数据库管理能力的底层依赖supabase/pg-meta元数据 APIworkspace 依赖、libpg-queryPostgres SQL 解析的 WASM 实现供 SQL 编辑器做解析/格式化、monaco-editor代码编辑内核、sql-formatter以及openapi-fetchapi-types生成的类型化 API 客户端。三、开发者快速上手继承 README QuickstartREADME 的 Developer Quickstart 要求Node v22apps/studio/Dockerfile 的 base 镜像node:22-slim与之呼应在apps/studio目录下执行# 外部贡献者 pnpm install # 安装依赖 pnpm run dev # 启动开发服务器 # 运行测试 pnpm run test # 单次运行带 coverage pnpm run test -- --watch # watch 模式需要注意两点与 README 字面命令相关的仓库细节包管理器锁定 pnpmpackage.json中preinstall脚本为npx only-allow pnpm用 npm/yarn 安装会直接被拦截README 自托管章节里的npm install属于旧式写法实际仓库约定是 pnpm开发服务器端口为 8082dev:next与dev:tanstack均监听STUDIO_PORT默认 8082AGENTS.md也确认本地开发入口为http://localhost:8082。README 还给出了贡献规范值得完整保留从master分支拉出工作分支命名结构为{type}/{branch_name}type取值chore | fix | feature分支名自由但需概括工作内容向master提交 PR 时会自动标记前端团队成员进行审查需先阅读根目录贡献指南了解测试要求Dashboard 处于活跃开发状态应频繁git pull保持同步。README 特别提示Supabase 内部员工若要连同后端服务一起本地开发 Studio需使用内部infrastructure仓库mise studio与mise infra配合外部贡献者按上面的 pnpm 流程即可。四、在自托管环境中运行 StudioREADME 给出的自托管运行流程分三步以下逐条展开并结合仓库真实配置补全细节。1. 拉起本地 Docker stack按自托管指南Docker Compose 方式启动服务。README 给出的最小命令cd .. cd docker docker compose -f docker-compose.yml -f ./dev/docker-compose.dev.yml up其中 docker/docker-compose.yml 定义了整个 stackdocker/docker-compose.dev.yml 是开发叠加层。主 compose 文件中的studio服务是理解 Studio 自托管运行的最佳样本其关键环境配置为environment: HOSTNAME: 0.0.0.0 # 监听所有 IPv4 接口 STUDIO_PG_META_URL: http://meta:8080 # pg-meta 元数据服务地址 POSTGRES_PORT: ${POSTGRES_PORT} POSTGRES_HOST: ${POSTGRES_HOST} POSTGRES_DB: ${POSTGRES_DB} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_USER_READ_WRITE: postgres # 数据库连接角色 PG_META_CRYPTO_KEY: ${PG_META_CRYPTO_KEY} PGRST_DB_SCHEMAS: ${PGRST_DB_SCHEMAS} # 通过 PostgREST 暴露的 schema PGRST_DB_MAX_ROWS: ${PGRST_DB_MAX_ROWS:-1000} PGRST_DB_EXTRA_SEARCH_PATH: ${PGRST_DB_EXTRA_SEARCH_PATH:-public} DEFAULT_ORGANIZATION_NAME: ${STUDIO_DEFAULT_ORGANIZATION} DEFAULT_PROJECT_NAME: ${STUDIO_DEFAULT_PROJECT} SUPABASE_URL: http://api-gw:8000 SUPABASE_PUBLIC_URL: ${SUPABASE_PUBLIC_URL} SUPABASE_ANON_KEY: ${ANON_KEY} SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY} AUTH_JWT_SECRET: ${JWT_SECRET} volumes: - ./volumes/snippets:/app/snippets:z - ./volumes/functions:/app/edge-functions:ro,z2. 配置 studio 目录下的.env按 READMEstack 启动后在 studio 文件夹的.env中填入对应值POSTGRES_PASSWORD SUPABASE_ANON_KEY SUPABASE_SERVICE_KEY这三个变量在容器化运行时同样受支持且支持 Docker secrets 语义apps/studio/docker-entrypoint.sh 中的file_env函数会优先读取POSTGRES_PASSWORD_FILE/SUPABASE_ANON_KEY_FILE/SUPABASE_SERVICE_KEY_FILE指向的文件内容二者同时设置则报错退出从而允许用 Docker 的--secret机制注入机密。3. 安装依赖并启动README 给出的命令为npm install npm run dev对应当前仓库的等价操作是pnpm installpnpm run dev由scripts/dispatch.js按STUDIO_FRAMEWORK分发到 Next 或 TanStack 运行时。4. 可选自定义默认组织与项目名README 指出如需为 Default Organization 和 Default Project 设置不同默认值在 studio 的.env中更新DEFAULT_ORGANIZATION_NAME DEFAULT_PROJECT_NAME这两个变量正是 docker/docker-compose.yml 中DEFAULT_ORGANIZATION_NAME: ${STUDIO_DEFAULT_ORGANIZATION}与DEFAULT_PROJECT_NAME: ${STUDIO_DEFAULT_PROJECT}消费的运行时默认值用于在自托管模式下给 Dashboard 预置首个组织/项目入口。源码层面的自托管常量apps/studio/lib/api/self-hosted/constants.ts 定义了自托管环境的兜底常量可作为排查.env是否生效的参照export const DEFAULT_EXPOSED_SCHEMAS process.env.PGRST_DB_SCHEMAS ?? public,graphql_public export const POSTGRES_PORT parseInt(process.env.POSTGRES_PORT || 5432, 10) export const POSTGRES_HOST process.env.POSTGRES_HOST || db export const POSTGRES_DATABASE process.env.POSTGRES_DB || postgres export const POSTGRES_PASSWORD process.env.POSTGRES_PASSWORD || postgres export const POSTGRES_USER_READ_WRITE process.env.POSTGRES_USER_READ_WRITE || supabase_admin // AUTH_JWT_SECRET 未提供时的兜底值与 supabase/cli 的默认值保持一致 export const DEFAULT_AUTH_JWT_SECRET super-secret-jwt-token-with-at-least-32-characters-long从源码结构看POSTGRES_HOST默认值db即 docker compose 中 Postgres 服务的网络别名——如果 Studio 报连接失败优先核对POSTGRES_HOST/POSTGRES_PORT/POSTGRES_PASSWORD三元组是否与 compose 中 Postgres 服务一致。五、容器化构建与健康检查apps/studio/Dockerfile 展示了 Studio 的生产镜像如何构建也是 README self-hosted 场景的完整落地框架选择发生在镜像构建期ARG STUDIO_FRAMEWORKnext--target production时 BuildKit 只会构建被选中的分支build-next或build-tanstack因为两个运行时的构建产物与依赖树不同。构建 TanStack 版本等价于加--build-arg STUDIO_FRAMEWORKtanstack多阶段瘦身turbo prune studio --docker修剪无关 workspace 依赖 →pnpm install --frozen-lockfile→ 框架编译 → 组装/srv运行时树Next 走.next/standalone自包含输出TanStack 走pnpm deploy --prod裁剪树并附dist/构建期冒烟测试TanStack 构建完成后立即运行node scripts/smoke-server.mjs启动服务端 bundle让模块级崩溃在构建期失败而不是容器运行期 500统一入口与健康检查production阶段固定PORT3000、EXPOSE 3000健康检查探测http://localhost:3000/api/platform/profile返回非 200 即判不健康。该检查与 docker/docker-compose.yml 中studio服务定义的 healthcheck 完全一致5 秒间隔、3 次重试、20 秒启动宽限。六、配置归属与常见问题速查综合 README 与仓库配置自托管接入 Studio 时的配置归属可以归纳为配置项归属位置说明POSTGRES_PASSWORD/SUPABASE_ANON_KEY/SUPABASE_SERVICE_KEYstudio 的.env或 Docker secrets 的*_FILE变量连接与鉴权三要素见 docker-entrypoint.shDEFAULT_ORGANIZATION_NAME/DEFAULT_PROJECT_NAMEstudio 的.env自托管默认组织/项目展示名对应 compose 中STUDIO_DEFAULT_ORGANIZATION/STUDIO_DEFAULT_PROJECTSTUDIO_FRAMEWORK.env/.env.local/ shell / Docker build-arg选择next默认或tanstack运行时STUDIO_PG_META_URLdocker-compose 环境变量pg-meta 服务地址默认指向http://meta:8080PGRST_DB_SCHEMAS等 PostgREST 相关变量docker-compose 环境变量控制 Data API 暴露的 schema、行数上限等端口开发 8082STUDIO_PORT容器 3000PORT开发服务器与生产容器端口不同健康检查针对 3000排查顺序建议先用pnpm run testvitest组件测试基于 MSW 且未处理网络请求会直接失败确认本地代码层无回归再核对.env三要素与 compose 中 Postgres 网络别名默认db最后对照容器健康检查端点/api/platform/profile判断服务是否真正就绪。小结apps/studio/README.md用简短篇幅划定了 Supabase Studio 的职责边界——管理数据库、不管理部署配置在 Dashboard 之外docker compose 或 secrets manager完成。结合仓库源码可以看到这一声明的完整落地scripts/dispatch.js实现 Next/TanStack 双运行时切换docker-entrypoint.sh支持文件型密钥注入lib/api/self-hosted/constants.ts提供自托管连接兜底常量Dockerfile与docker-compose.yml共同保证容器化部署的健康检查与配置注入闭环。掌握以上内容即可独立完成 Studio 的本地开发、测试与自托管接入。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考