Nhost基于 GraphQL 的开源 Firebase 替代方案——架构拆解与本地开发实战指南【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost 是一个完全开源的 Firebase 替代品核心特性是开箱即用的 GraphQL API围绕 PostgreSQL 数据库、Hasura GraphQL 引擎、内置认证、文件存储与 Node.js Serverless Functions 构建了一整套后端即服务BaaS能力。本文将以本仓库的 README.md 为主线结合 CLI 源码、Nhost CLI 配置示例 与 Docker Compose 自托管示例完整讲解 Nhost 的架构组成、三种上手路径托管平台 / 本地 CLI / 自托管以及如何用nhost/nhost-js客户端在任意前端框架中完成登录认证与 GraphQL 数据请求。一、Nhost 是什么四项设计原则根据 README.md 的开篇定义Nhost 是一个开源 Firebase 替代品且以 GraphQL 为核心整个项目围绕以下四点构建Open Source开源包括 CLI、Auth、Storage、GraphQL 等在内的核心组件全部开源仓库整体采用 MIT 许可证见 LICENSE并允许用户完整自托管整个技术栈。GraphQL所有数据访问都通过自动生成的 GraphQL API 完成无需手写 REST 端点。SQL底层数据库为标准 PostgreSQL数据模型、迁移、种子数据都由 SQL 驱动天然支持复杂查询与事务。Great Developer Experience卓越的开发体验通过 Nhost CLI 实现一键启动本地开发环境、迁移管理与云端部署将后端基础设施的复杂度降到最低。Nhost 由若干开源软件组合而成各组件在仓库中均有对应实现目录能力技术选型仓库位置数据库PostgreSQLservices/postgres即时 GraphQL APIHasura由 services/constellation 与 CLI 集成管理认证Nhost Authservices/auth文件存储Nhost Storageservices/storageServerless FunctionsNode.jsJavaScript / TypeScriptservices/functions本地开发工具Nhost CLIcli前端 SDKnhost/nhost-jspackages/nhost-js二、Nhost 架构组成从 assets/nhost-diagram.png 架构图可以看出Nhost 采用以 PostgreSQL 为底座、以 GraphQL 引擎为中枢的分层架构PostgreSQL 数据库所有业务数据的唯一事实来源同时承载 Auth、Storage 等服务的元数据。Hasura GraphQL 引擎直接读取 PostgreSQL 表结构自动生成即时可用的 GraphQL Schema并提供权限系统、事件触发器、远程 Schema 等能力。仓库中 examples/docker-compose/docker-compose.yaml 的graphql与console两个服务即分别对应 Hasura 引擎与 Hasura CLI 控制台。Nhost Auth提供邮箱密码、短信密码无感登录、OAuthGitHub、Google、Apple 等、WebAuthn、TOTP 多因素认证等全套认证能力签发 JWT 供 GraphQL 请求鉴权完整配置项见下文nhost.toml的[auth]段。Nhost Storage基于 MinIO/S3 协议的文件存储服务负责文件上传、下载与访问控制。Serverless FunctionsNode.js 运行时的无服务器函数与 GraphQL 引擎、认证体系深度打通。Dashboard 与 CLI图形化控制台与命令行工具是日常开发与运维的入口。从源码结构看CLI 的入口 cli/main.go 注册了config、dev、deployments、dockercredentials、mcp、project、run、schema、secrets、software、user、docs等子命令并支持 shell 自动补全可以推断出 CLI 覆盖了本地开发、配置管理、部署、密钥管理、文档检索、MCP 服务等完整工作流。三、三种上手路径托管平台 / 本地 CLI / 自托管README.md 提供了三条上手路线开发者可以根据场景选择Option 1托管平台最快路径无需安装任何东西登录云端控制台创建应用即可。Option 2本地 CLI本地开发首选能跟踪数据库迁移与 Hasura 元数据实现代码即基础设施。Option 3自托管完全掌控部署适合对数据主权有要求的场景。3.1 Option 1Nhost 托管平台官方托管平台的流程仅三步登录 Nhost 云端控制台app.nhost.io。创建一个 Nhost 应用。完成——应用创建后会提供 subdomain 与 region供客户端 SDK 接入。托管模式的优势在于免运维数据库备份、GraphQL 引擎升级、函数部署、监控告警均由平台托管开发者只需关注业务代码。3.2 Option 2本地开发Nhost CLINhost CLI 是本地开发最核心的工具它会在你的机器上拉起一整套与云端一致的后端环境并且自动跟踪数据库迁移migrations与 Hasura 元数据metadata让本地与云端的 Schema 保持同步。安装 CLI四种方式任选其一# macOS / LinuxHomebrew 或官方安装脚本 brew install nhost/tap/nhost # 或 curl -sSL https://raw.githubusercontent.com/nhost/nhost/main/cli/get.sh | bash # Nix nix profile install github:nhost/nhost#cli # npm / pnpm / Yarn / Bun推荐作为项目开发依赖安装 npm install -D nhost/cli pnpm add -D nhost/cli yarn add -D nhost/cli bun add -d nhost/cli开始构建——经典三连nhost login nhost init nhost up下面结合源码逐一说明这三个命令在底层做了什么帮助你理解 CLI 的工作机制。nhost login登录 Nhost 账号该命令用于登录 Nhost 账号并保存会话凭证。查看实现 cli/cmd/user/login.go它调用clienv.Login完成认证流程登录态持久化在cli/clienv/wf_login.go、wf_session.go等文件中管理。登录后nhost init与nhost up才能关联到你的云端项目。nhost init初始化 Nhost 项目该命令在工作目录下创建标准的 Nhost 项目结构。源码 cli/cmd/project/init.go 展示了完整流程若当前目录已存在nhost文件夹命令直接报错退出nhost folder already exists避免覆盖已有项目创建nhost目录并生成初始配置与密钥config.InitConfigAndSecrets若带--remote或环境变量NHOST_REMOTE标志则会先从云端关联项目拉取配置、迁移与元数据InitRemote内部调用config.Pull并用 Hasura CLI 生成初始 migration 与导出 metadata否则走本地初始化initInit。本地初始化cli/cmd/project/init.go会创建如下目录骨架project-root/ ├── .nhost/ # CLI 内部状态如 app id ├── functions/ # Serverless Functions 代码目录 └── nhost/ ├── migrations/default/ # PostgreSQL 迁移文件 ├── metadata/ # Hasura 元数据含 version.yaml ├── seeds/ # 种子数据 ├── emails/ # 认证邮件模板内嵌模板自动写入 └── config.yaml # 配置文件内容为 version: 3生成的模板文件通过 Go 的embed.FS内嵌在 cli/cmd/project/templates 中邮件模板则直接复用 services/auth/email-templates。初始化成功后CLI 会提示运行nhost up启动开发环境。nhost up一键启动本地后端这是 CLI 的核心命令源码见 cli/cmd/dev/up.go执行流程如下前置校验检查nhost/nhost.toml与.nhost密钥文件是否存在不存在则提示先运行nhost init或nhost config pull配置校验解析并校验nhost.tomlconfig.Validate生成 docker-compose.yaml根据配置动态生成docker-compose.yamldockercompose.ComposeFileFromConfig拉起 PostgreSQL、Hasura、Auth、Storage、Functions、Dashboard、Mailhog、Config Server 等容器应用迁移与元数据执行migrations、metadata、seeds的应用逻辑cli/cmd/dev/up.go目录不存在时给出警告导出元数据并重启服务通过 Hasura CLI 导出 metadata 到本地nhost/metadata随后重启 Auth/Storage/Functions 等服务以应用最新配置输出访问地址启动完成后打印全部服务 URL 与 SDK 配置信息见 printInfo。nhost up还提供了大量可调参数全部支持环境变量覆盖常用如下参数环境变量默认值说明--http-portNHOST_HTTP_PORT443HTTP 监听端口--postgres-portNHOST_POSTGRES_PORT5432PostgreSQL 对外端口--disable-tlsNHOST_DISABLE_TLSfalse是否禁用 TLS--apply-seedsNHOST_APPLY_SEEDSfalse是否应用种子数据.nhost目录不存在时强制应用--dashboard-versionNHOST_DASHBOARD_VERSIONnhost/dashboard:3.5.3Dashboard 镜像版本--functions-versionNHOST_FUNCTIONS_VERSION2.2.0Functions 运行时版本--run-serviceNHOST_RUN_SERVICE—向开发环境附加自定义 Run Service格式/path/to/run-service.toml[:overlay_name]可多次传入--run-service-volumeNHOST_RUN_SERVICE_VOLUME—将本地目录挂载进 Run Service 容器格式service-name/local/path:/container/path便捷运维nhost down停止开发环境nhost logs查看日志对应 cli/cmd/dev/down.go 与 cli/cmd/dev/logs.go。启动成功后CLI 会打印类似如下的地址表源自 printInfo 与 examples/docker-compose/README.md服务本地地址默认 443 端口说明Postgrespostgres://postgres:postgreslocalhost:5432/local数据库直连Hasurahttps://local.hasura.local.nhost.runHasura 管理 APIGraphQLhttps://local.graphql.local.nhost.runGraphQL 端点Authhttps://local.auth.local.nhost.run认证服务/v1前缀Storagehttps://local.storage.local.nhost.run文件存储/v1前缀Functionshttps://local.functions.local.nhost.runServerless Functions/v1前缀Dashboardhttps://local.dashboard.local.nhost.run图形化控制台Mailhoghttps://local.mailhog.local.nhost.run开发环境邮件测试工具同时 CLI 会提示 SDK 配置参数Subdomain: local、Region: local即本地环境与托管环境使用同一套 SDK 接入方式切换环境只改配置不改代码。3.3 Option 2 进阶nhost.toml配置文件详解nhost init生成的nhost/nhost.toml是整个本地环境与云端项目配置的单一事实来源。仓库提供了完整示例 cli/examples/myproject/nhost/nhost.toml下面拆解核心配置段全局环境变量与密钥引用[global] [[global.environment]] name GREET value Sayonara [[global.environment]] name STRIPE_SECRET_KEY value {{ secrets.STRIPE_SECRET_KEY }}环境变量可以硬编码也可以通过{{ secrets.XXX }}模板语法引用.nhost中的密钥文件敏感信息不会写入版本库。Hasura 配置版本、Admin Secret、JWT[hasura] version v2.48.10-ce adminSecret {{ secrets.HASURA_GRAPHQL_ADMIN_SECRET }} webhookSecret {{ secrets.NHOST_WEBHOOK_SECRET }} [[hasura.jwtSecrets]] type RS256 key {{ secrets.JWT_PUBLIC_KEY }} signingKey {{ secrets.JWT_PRIVATE_KEY }} kid bskhwtelkajsd [hasura.settings] corsDomain [https://local.dashboard.local.nhost.run, http://localhost:3000] enableRemoteSchemaPermissions false liveQueriesMultiplexedRefetchInterval 3000Serverless Functions 与 Auth 认证[functions] [functions.node] version 22 [auth] version 0.50.1 [auth.redirections] clientUrl http://localhost:3000 [auth.signUp] enabled true [auth.user.roles] default user allowed [user, me] [auth.session.accessToken] expiresIn 900 [[auth.session.accessToken.customClaims]] key spirit-animal value animals[0].id default 00000000-0000-0000-0000-000000000000 [auth.session.refreshToken] expiresIn 2592000 [auth.method.emailPassword] hibpEnabled false emailVerificationRequired false passwordMinLength 9可以看出 Auth 配置覆盖了注册开关、默认角色user/me、access token900 秒与 refresh token2592000 秒 ≈ 30 天过期时间、自定义 JWT claims支持从数据库字段取值、密码最小长度9 位以及 HIBP 泄露密码检查。此外[auth.method.oauth]下内置了 Apple、AzureAD、Bitbucket、Discord、Facebook、GitHub、GitLab、Google、LinkedIn、Spotify、Strava、Twitch、Twitter、Windows Live、WorkOS 等全部主流 OAuth 提供方的开关[auth.method.webauthn]与[auth.totp]则对应无密码 WebAuthn 与 TOTP 多因素认证。数据库、存储与 AI[postgres] version 14.20-20251217-1 [storage] version 0.14.0 [ai] version 0.8.1 webhookSecret {{ secrets.GRAPHITE_WEBHOOK_SECRET }} [ai.openai] apiKey {{ secrets.OPENAI_API_KEY }} [ai.autoEmbeddings] synchPeriodMinutes 5 [observability.grafana] adminPassword {{ secrets.GRAFANA_ADMIN_PASSWORD }}值得关注的是 Nhost 已内置 AI 能力Graphite/GraphRAG 相关配置、自动向量嵌入每 5 分钟同步与 Grafana 可观测性配置[experimental.constellation]段对应新的 Constellation 运行时services/constellation。3.4 Option 3自托管Docker Compose由于 Nhost 100% 开源你可以用 examples/docker-compose 中的 Docker Compose 文件在任意支持 Docker 的主机上复现整套 Nhost 栈。该示例基于 CLI 的实现构建是一个完整的演示环境。启动方式见 examples/docker-compose/README.mdgit clone https://gitcode.com/GitHub_Trending/nh/nhost cd nhost/examples/docker-compose cp .env.example .env docker compose up -ddocker compose up -d会依次启动 docker-compose.yaml 中定义的 10 个服务服务镜像职责postgrespostgres:16主数据库暴露 5432 端口graphqlnhost/graphql-engine:v2.46.0-ceHasura GraphQL 引擎consolenhost/graphql-engine:...cli-migrations-v3Hasura CLI 控制台迁移/元数据管理authnhost/auth:0.40.2认证服务storagenhost/storage:0.7.2文件存储服务miniominio/minioS3 兼容对象存储底座functionsnhost/functions:22-1.4.0Serverless Functionsdashboardnhost/dashboard:2.34.0Nhost 图形化 Dashboardmailhogjcalonso/mailhog:v1.0.1开发用邮件测试工具traefiktraefik:v3.1反向代理按域名路由到各服务该示例的 auth 服务通过环境变量暴露了完整的认证行为配置AUTH_SIGNUP_ENABLED、AUTH_ACCESS_TOKEN_EXPIRES_IN900、AUTH_REFRESH_TOKEN_EXPIRES_IN2592000、AUTH_PASSWORD_MIN_LENGTH9、限流参数等与nhost.toml的[auth]段一一对应可作为深度定制时的参考。自托管需要注意该示例面向演示用途包含 Mailhog、Hasura Console 等开发友好特性README 明确提示生产环境应仔细审查.env与 Compose 中的安全设置考虑移除仅开发用的服务并说明官方对无支持协议的自托管仅提供社区级支持。四、接入认证与发起 GraphQL 请求nhost/nhost-js本地环境跑起来或云端应用创建好之后就可以用官方 JavaScript/TypeScript SDK 构建应用了。安装 packages/nhost-jsnpm install nhost/nhost-jsREADME.md 给出了最小可运行示例——先签名登录再发起 GraphQL 查询import { createClient } from nhost/nhost-js const nhost createClient({ subdomain: your-project, region: eu-central-1 }) await nhost.auth.signInEmailPassword({ email: userexample.com, password: password }) await nhost.graphql.request({ query: query GetUsers { users { id displayName email } } })该示例完整展示了 Nhost 的认证 GraphQL核心链路nhost.auth.signInEmailPassword完成登录并拿到会话nhost.graphql.request自动携带 JWT 访问由 Hasura 生成的users查询。深入源码可以了解 SDK 的内部机制统一客户端packages/nhost-js/src/nhost.ts 中的createClient聚合了auth、storage、graphql、functions四个子客户端与sessionStorage会话存储一个实例即可访问全部服务。URL 生成规则packages/nhost-js/src/index.ts 的generateServiceUrl将服务地址规范化为https://{subdomain}.{service}.{region}.nhost.run/v1当subdomain/region缺失时回退到本地开发地址https://local.{service}.local.nhost.run/v1——这正是 CLI 本地环境所用的域名体系所以同一套代码无需改动即可在本地与云端切换。会话中间件链packages/nhost-js/src/nhost.ts 提供两套内置配置withClientSideSessionMiddleware客户端场景包含会话自动刷新、会话持久化、自动附加 access token与withServerSideSessionMiddleware服务端场景为避免竞态不做自动刷新。Admin 客户端withAdminSession可以为 storage/graphql/functions 附加管理员会话绕过权限并支持角色切换但源码注释明确警告admin secret 拥有数据库全部权限严禁在客户端代码中使用packages/nhost-js/src/nhost.ts。五、前端框架无关一套后端全端通用Nhost 是**前端框架无关frontend agnostic**的GraphQL JWT 的标准协议意味着任何能发 HTTP 请求的框架都能接入。仓库为以下主流框架提供了 Logo 素材与 Quickstart 示例Next.jsassets/nextjs.svg示例见 examples/quickstarts/nextjsNuxt.jsassets/nuxtjs.svgReactassets/react.svg示例见 examples/quickstarts/reactReact Nativeassets/react-native.svg示例见 examples/quickstarts/reactnativeSvelteassets/svelte.svg示例见 examples/quickstarts/svelteVueassets/vuejs.svg示例见 examples/quickstarts/vue除 JavaScript/TypeScript 外Nhost 还提供 Dart/Flutter 客户端nhost-dart服务端开发者同样可以基于 services/auth 的 REST API 与 Hasura 的 JWT 校验机制自行接入任意语言。六、仓库内更多资源Dashboard 应用dashboard——Nhost 图形化管理控制台Next.js GraphQL 客户端实现含 e2e 测试。官方文档站docs——基于 Astro 构建的完整文档站含 200 篇 mdx 技术文档与 CLI 参考。CLI 完整参考cli 与 CLI CHANGELOGCLI 内置gen-docs命令可生成 Markdown 格式的 CLI 参考文档见 cli/main.go。自托管 Compose 示例examples/docker-compose。端到端示例examples 下的demos、guides、quickstarts、tutorials目录覆盖了 React、Next.js、React Native、Svelte、Vue 的完整教程工程。SDK 源码packages/nhost-js含认证、存储、GraphQL、Functions 四类客户端实现与测试。贡献指南CONTRIBUTING.md、CODE_OF_CONDUCT.md。总结Nhost 以开源 GraphQL SQL 开发体验为设计基石将 PostgreSQL、Hasura、认证、存储、Serverless Functions 组合成可本地可云端、可托管可自托管的完整 BaaS 方案。通过nhost login nhost init nhost up三行命令即可获得与生产一致的本地后端借助nhost/nhost-js的统一客户端与前端框架无关的接入方式开发者可以专注于业务本身把后端基础设施交给这套开源技术栈。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考