Nhost Dashboard 完全指南环境配置、本地联调、CSP 自托管与测试体系【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost Dashboard 是 Nhost 开源项目Open Source Firebase Alternative with GraphQL中的核心 Web 管理控制台用于在浏览器中管理 Nhost 项目Auth、GraphQL、Storage、Hasura 等。本指南以 dashboard/README.md 为骨架围绕如何把 Dashboard 跑起来、如何连接本地/自托管后端、如何用环境变量控制运行时行为、如何配置 CSP 并接入测试体系展开并辅以仓库源码package.json、next.config.js、playwright.config.ts 等进行印证。读完你既能在一台干净机器上从零启动 Dashboard 并指向本地 Nhost 后端也能理解其构建、安全与测试的底层设计。一、项目定位与前置条件从 dashboard/README.md 的定义看Nhost Dashboard 是一个管理 Nhost 项目的 Web 应用。它本身不提供后端能力而是面向 Auth、GraphQL、Storage、Hasura 等 Nhost 服务的管理界面。运行它需要先有一个 Nhost 项目云端项目在 app.nhost.io 创建本地项目则通过 Nhost CLI 的nhost up启动它是一个基于Next.js的单体应用见 dashboard/package.json 中的next、react19 依赖通过环境变量决定连接哪个后端仓库采用 pnpm workspace 管理Dashboard 依赖工作区内的nhost/nhost-js等包nhost/nhost-js: workspace:^因此首次构建前需要先构建工作区内的依赖包。前置工具清单工具用途依据pnpm包管理器package.json 中preinstall通过only-allow pnpm强制使用dashboard/package.jsonNode.js运行 Next.js 构建与开发服务器dashboard/package.jsonNhost CLI可选本地启动 Nhost 后端nhost upcli/README.md二、从零启动安装、构建依赖包与运行开发服务器原文给出了三步启动流程这是本地体验 Dashboard 的标准路径。2.1 安装依赖pnpm install由于preinstall钩子执行npx only-allow pnpm使用 npm 或 yarn 安装会被直接拦截必须使用 pnpm。2.2 构建工作区依赖包pnpm -w buildDashboard 引用了工作区内的nhost/nhost-js等包dashboard/package.json且 dashboard/package.json 中outputFileTracingRoot指向仓库根目录。pnpm -w build会构建整个 workspace 中被 Dashboard 依赖的包避免运行时报找不到模块错误。2.3 启动开发服务器pnpm dev对应 dashboard/package.json 中的dev: next dev启动后访问 http://localhost:3000。三、环境变量体系按目标环境分层配置原文强调按目标环境选择.env.target_environment.local文件。这是 Next.js 环境变量加载规则的实践文件何时生效优先级.env.development运行nhost upCLI 启动本地后端时注入低.env.development.local运行pnpm dev高覆盖.env.local.env.production.local运行pnpm build高覆盖.env.local.env.localpnpm dev或pnpm build均生效基准这些.local文件已被加入.gitignore不会提交到仓库因此修改环境变量必须落在.local后缀文件里否则改动可能被他人/CI 的默认值覆盖。仓库提供了模板 dashboard/.env.example可直接复制为.env.development.local使用。3.1 三个最基础的开关变量取值含义NEXT_PUBLIC_ENVdev/staging/prod标识当前运行环境多数场景设为devNEXT_PUBLIC_NHOST_PLATFORMfalse默认/truefalse连接本地或自托管后端true连接 Nhost 云平台NEXT_PUBLIC_NHOST_ADMIN_SECRET字符串默认nhost-admin-secretHasura 的 Admin Secret其中NEXT_PUBLIC_NHOST_PLATFORM是行为分水岭为true时 Dashboard 会启用 Stripe 计费、GitHub App 安装、Analytics、Bragi 消息通道等云平台能力见下文其他环境变量为false时这些能力被关闭只保留针对后端服务的核心管理功能。四、连接本地 Nhost 后端Local Development这是原文最具实操价值的部分让 Dashboard 直接管理nhost up启动的本地后端。4.1 第一步启动本地后端cd your_nhost_project nhost upnhost up会拉起 Auth、GraphQL、Storage、Hasura、Configserver、日志等全套本地服务并为每个服务暴露*.local.nhost.run域名。这些域名的生成规则实现在 cli/dockercompose/compose.go 中——CLI 在生成 Dashboard 容器环境时正是通过URL(...)/WebsocketURL(...)等辅助函数拼接出NEXT_PUBLIC_NHOST_AUTH_URL、NEXT_PUBLIC_NHOST_GRAPHQL_URL、NEXT_PUBLIC_NHOST_HASURA_API_URL等值并统一设置NEXT_PUBLIC_NHOST_PLATFORMfalse。也就是说本地联调时的这些 URL 就是 CLI 注入给 Dashboard 的标准地址手工配置时照抄即可。4.2 第二步在.env.development.local中写入服务地址NEXT_PUBLIC_ENVdev NEXT_PUBLIC_NHOST_PLATFORMfalse NEXT_PUBLIC_NHOST_AUTH_URLhttps://local.auth.local.nhost.run/v1 NEXT_PUBLIC_NHOST_FUNCTIONS_URLhttps://local.functions.local.nhost.run/v1 NEXT_PUBLIC_NHOST_GRAPHQL_URLhttps://local.graphql.local.nhost.run/v1 NEXT_PUBLIC_NHOST_STORAGE_URLhttps://local.storage.local.nhost.run/v1 NEXT_PUBLIC_NHOST_HASURA_CONSOLE_URLhttps://local.hasura.local.nhost.run NEXT_PUBLIC_NHOST_HASURA_MIGRATIONS_API_URLhttps://local.hasura.local.nhost.run/v1/migrations NEXT_PUBLIC_NHOST_HASURA_API_URLhttps://local.hasura.local.nhost.run写入后重启pnpm devDashboard 即指向本地后端。更完整的模板见 dashboard/.env.example其中还包含 Configserver GraphQLNEXT_PUBLIC_NHOST_CONFIGSERVER_URL、日志 GraphQL 与 WebSocketNEXT_PUBLIC_NHOST_LOGS_GRAPHQL_URL/NEXT_PUBLIC_NHOST_LOGS_WEBSOCKET等变量分别对应 cli/dockercompose/configserver.go 与 cli/dockercompose/dockerlogs.go 启动的本地服务需要完整日志/配置面板时一并配置。4.3 各服务地址变量速查变量指向的服务本地联调时的地址CLI 生成NEXT_PUBLIC_NHOST_AUTH_URLAuth 认证服务https://local.auth.local.nhost.run/v1NEXT_PUBLIC_NHOST_FUNCTIONS_URLServerless Functionshttps://local.functions.local.nhost.run/v1NEXT_PUBLIC_NHOST_GRAPHQL_URLGraphQL APIhttps://local.graphql.local.nhost.run/v1NEXT_PUBLIC_NHOST_STORAGE_URLStorage 存储服务https://local.storage.local.nhost.run/v1NEXT_PUBLIC_NHOST_HASURA_CONSOLE_URLHasura Consolehttps://local.hasura.local.nhost.runNEXT_PUBLIC_NHOST_HASURA_MIGRATIONS_API_URLHasura Migrations APIhttps://local.hasura.local.nhost.run/v1/migrationsNEXT_PUBLIC_NHOST_HASURA_API_URLHasura Schema/Metadata APIhttps://local.hasura.local.nhost.run自托管场景下将这些地址改为你自托管各服务的真实地址即可语义完全一致见 dashboard/README.md。五、构建期 CSP 配置让自托管域名可用原文特别强调了build-time CSPContent Security Policy配置这是自托管部署到自定义域名时的关键环节。默认的 Nhost Cloud CSP 会限制脚本、连接等资源来源自定义域名往往不在白名单内导致页面资源被浏览器拦截。5.1 两个 CSP 变量变量取值说明CSP_MODEnhost默认/disabled/customnhost使用 Nhost Cloud 默认 CSPdisabled完全不输出 CSP 头custom使用CSP_HEADER提供的自定义策略CSP_HEADER完整的 CSP 字符串仅在CSP_MODEcustom时生效例如default-src self; script-src self unsafe-eval; ...自托管到自定义域名时将CSP_MODE设为disabled或custom。5.2 源码级实现CSP 的构建期逻辑在 dashboard/next.config.js 的getCspHeader()中CSP_MODEdisabled→ 返回nullasync headers()直接返回空数组不输出任何 CSP 头next.config.jsCSP_MODEcustom→ 原样使用CSP_HEADER的值其他情况含默认nhost→ 输出一份硬编码的 Nhost Cloud CSP覆盖default-src、script-src、connect-src、style-src、img-src、font-src、frame-src等指令允许*.nhost.run、Stripe、Segment、Cloudflare 等云依赖。最终通过 Next.js 的headers()钩子为所有路径/:path*附加Content-Security-Policy与X-Frame-Options: DENY两个响应头dashboard/next.config.js。Nix 打包环境也印证了这一点——dashboard/project.nix 中导出CSP_MODEdisabled作为自托管构建的默认值。六、云平台专属环境变量Platform-only以下变量仅在NEXT_PUBLIC_NHOST_PLATFORMtrue即连接 Nhost 云时才会被使用变量用途NEXT_PUBLIC_STRIPE_PKStripe 公钥用于计费与订阅界面NEXT_PUBLIC_GITHUB_APP_INSTALL_URLGitHub App 安装 URL用于关联 GitHub 仓库部署NEXT_PUBLIC_ANALYTICS_WRITE_KEY产品分析Segment写入密钥NEXT_PUBLIC_NHOST_BRAGI_WEBSOCKETBragi 消息通道 WebSocket 地址NEXT_PUBLIC_前缀意味着这些变量在构建期被内联进客户端 bundle修改后必须重新pnpm build或pnpm dev才会生效。更多云平台配置项如 Segment CDN、Zendesk OAuth、Turnstile 站点密钥可参考 dashboard/.env.example。七、代码质量与规范Biome 规则项目使用 Biomedashboard/README.md 列出了一组关键规则及级别。部分规则默认关闭是因为代码库中确有合理使用场景规则级别说明useOptionalChainerror强制使用可选链user?.name而非user user.nameuseThrowOnlyErrorerror只允许抛出Error对象noUselessElseerror禁止return之后的无意义elsenoParameterAssignerror禁止重赋值函数参数useBlockStatementserror所有控制流强制使用花括号noConsoleerror仅允许console.error/warn/infonoExplicitAnyerror禁止显式anynoUnusedImportserror未使用导入自动修复noImportCycleserror防止循环依赖noShadowerror禁止变量遮蔽外层作用域useLiteralKeys、noBannedTypes、noNonNullAssertion、noExtraNonNullAssertion、noAccumulatingSpread等off按需关闭允许特定写法pnpm lint即执行biome check见 dashboard/package.json。这套规则保证了 Dashboard 数千个 TS/TSX 文件主要位于 dashboard/src/features/orgs 与 dashboard/src/components在大型代码库中的一致性与可维护性。八、测试体系Vitest 单元测试与 Playwright E2E8.1 单元测试Vitest单元测试基于 Vitest配置见 dashboard/vitest.config.mts执行pnpm testpnpm test实际串联了类型检查、lint、Vitest 与坏链接检查dashboard/package.jsontest: pnpm test:typecheck pnpm lint pnpm test:vitest pnpm test:broken-links测试覆盖了 Dashboard 的绝大多数核心交互例如权限编辑器的可视化规则VisualRuleEditor.test.tsx、数据库 CIDR 设置DatabaseAllowedCIDRs.test.tsx、备份的按时间点恢复PointInTimeTabsContent.test.tsx等。8.2 端到端测试PlaywrightE2E 测试针对真实环境运行需要一个 Nhost 测试账号和一个可用项目可在 app.nhost.io 注册创建然后在dashboard目录下创建.env.test文件NHOST_TEST_DASHBOARD_URLtest_dashboard_url NHOST_TEST_USER_EMAILtest_user_email NHOST_TEST_USER_PASSWORDtest_user_password NHOST_TEST_ORGANIZATION_NAMEtest_organization_name NHOST_TEST_ORGANIZATION_SLUGtest_organization_slug NHOST_TEST_PERSONAL_ORG_SLUGtest_personal_org_slug NHOST_TEST_PROJECT_NAMEtest_project_name NHOST_TEST_PROJECT_SUBDOMAINtest_project_subdomain NHOST_TEST_PROJECT_ADMIN_SECRETtest_project_admin_secret其中必需变量说明组织/项目信息需从 Nhost Dashboard 复制变量含义NHOST_TEST_DASHBOARD_URL测试目标地址如http://localhost:3000或 staging 地址NHOST_TEST_USER_EMAIL/NHOST_TEST_USER_PASSWORD拥有测试项目的账号凭证NHOST_TEST_ORGANIZATION_NAME/NHOST_TEST_ORGANIZATION_SLUG测试项目所在组织的名称与 slugNHOST_TEST_PERSONAL_ORG_SLUG个人组织 slugNHOST_TEST_PROJECT_NAME/NHOST_TEST_PROJECT_SUBDOMAIN测试项目名称与子域名NHOST_TEST_PROJECT_ADMIN_SECRET测试项目的 Hasura Admin Secret此外 dashboard/e2e/env.ts 还读取NHOST_TEST_REMOTE_SCHEMA_NAME、NHOST_TEST_STAGING_SUBDOMAIN、NHOST_TEST_STAGING_REGION等变量供远程 Schema、staging 等专项测试使用。执行方式pnpm e2epnpm e2e会先串行运行main项目单 worker再并行运行main-parallelizable项目两个 worker见 dashboard/package.json。Playwright 配置在 dashboard/playwright.config.ts其中定义了完整的测试编排setup 项目auth.setup.ts登录并保存登录态到e2e/.auth/user.json、database.setup.ts、refresh-metadata.setup.ts按依赖顺序执行main依赖 setup使用保存的登录态排除 onboarding 与 CLI 本地 Dashboard 用例main-parallelizable仅运行 dashboard/e2e/auth、dashboard/e2e/account、dashboard/e2e/run、dashboard/e2e/serverless-functions 等目录下可并行用例local运行 cli-local-dashboard.test.ts针对本地 Dashboard 地址onboarding运行 onboarding.test.ts。E2E 用例按业务域组织在 dashboard/e2e 下覆盖 Auth用户增删改查、封禁、数据库表/函数/视图/权限、事件Cron、事件触发器、GraphQL 元数据、远程 Schema、Run 服务等完整功能面。九、Docker 部署的运行时配置补充除构建期环境变量外Dashboard 也支持容器化运行时注入。入口脚本 dashboard/docker-entrypoint.sh 在容器启动时读取环境变量带默认值并通过sed将构建产物中的占位符如__NEXT_PUBLIC_NHOST_AUTH_URL__替换为真实地址变量默认值NEXT_PUBLIC_NHOST_ADMIN_SECRETnhost-admin-secretNEXT_PUBLIC_NHOST_AUTH_URLhttp://localhost:1337/v1/authNEXT_PUBLIC_NHOST_FUNCTIONS_URLhttp://localhost:1337/v1/functionsNEXT_PUBLIC_NHOST_GRAPHQL_URLhttp://localhost:1337/v1/graphqlNEXT_PUBLIC_NHOST_STORAGE_URLhttp://localhost:1337/v1/storageNEXT_PUBLIC_NHOST_HASURA_CONSOLE_URLhttp://localhost:9695NEXT_PUBLIC_NHOST_HASURA_MIGRATIONS_API_URLhttp://localhost:9693NEXT_PUBLIC_NHOST_HASURA_API_URLhttp://localhost:8080这也是nhost up本地链路中 Dashboard 容器获得服务地址的机制之一CLI 侧见 cli/dockercompose/compose.go与源码方式pnpm dev.env.*.local互为补充。十、常见问题排查清单pnpm dev报模块缺失确认先执行了pnpm install与pnpm -w build工作区依赖如nhost/nhost-js未构建是常见原因。Dashboard 连不上本地后端确认nhost up正常运行且.env.development.local中的NEXT_PUBLIC_NHOST_PLATFORMfalse及各服务地址与 CLI 生成的一致修改环境变量后需重启pnpm dev。自托管域名页面资源被拦截检查是否设置CSP_MODEdisabled或custom 自定义CSP_HEADER后重新pnpm buildCSP 是构建期决定的。E2E 用例登录失败核对.env.test中的账号、组织、项目信息是否与 Nhost Dashboard 中一致E2E 需要真实可用的测试项目。lint 报noConsole/noExplicitAny按 dashboard/biome.json 规则修正或确认该处是否属于规则明确关闭的合理场景。延伸阅读Dashboard 开发约定与命令总览dashboard/CLAUDE.md环境变量完整模板dashboard/.env.example构建与 CSP 实现dashboard/next.config.jsE2E 编排dashboard/playwright.config.ts本地后端各服务 URL 生成逻辑cli/dockercompose/compose.go运行时占位符替换dashboard/docker-entrypoint.shDashboard 所依赖的 JS SDKpackages/nhost-js/README.md【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
