Nhost CLI 实战指南：用 Docker 一键搭建本地 GraphQL 全栈开发环境

Nhost CLI 实战指南用 Docker 一键搭建本地 GraphQL 全栈开发环境【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost CLI 是 Nhost 开源项目The Open Source Firebase Alternative with GraphQL官方提供的命令行工具核心职责是在本地用 Docker 拉起一套完整的后端开发环境并自动追踪数据库迁移migrations与 Hasura metadata。本文以仓库 cli/README.md 为主线结合 cli/main.go、cli/cmd/dev/up.go、cli/cmd/project/init.go 等源码完整讲解安装、初始化、启动、配置管理与 MCP Server 的实战用法读完后你可以在自己的机器上从零跑通 Nhost 本地开发环境并理解其底层工作机制。一、Nhost CLI 是什么Nhost 是一个开源的 Firebase 替代品基于 GraphQL 构建。Nhost CLI 用于搭建本地开发环境它会自动追踪数据库迁移和 Hasura metadata让后端配置nhost/目录可以像代码一样纳入版本控制。官方推荐的协作方式是本地开发 云端部署双轨并行使用 Nhost CLI 在本地开发再结合 Nhost GitHub Integration通过类似 Netlify 与 Vercel 的 git-based 工作流将变更自动部署到生产环境。也就是说本地nhost/目录中的配置、迁移与 metadata 即是基础设施即代码的唯一事实来源。CLI 提供的服务组件nhost up一次性启动的本地服务栈对应 cli/cmd/dev/up.go 输出的服务列表服务说明Nhost Dashboard本地可视化控制台默认nhost/dashboard:3.5.3镜像Postgres Database数据库服务本地默认连接串为postgres://postgres:postgreslocalhost:5432/localGraphQL EngineHasura GraphQL 引擎同时暴露/v1/graphql与 Hasura 管理接口Auth认证服务处理注册、登录、JWT 签发等Storage文件存储服务Nhost Serverless Functions无服务函数运行时本地默认版本2.2.0Minio S3对象存储S3 兼容供 Storage 底层使用Mailhog本地邮件捕获服务用于测试邮件发送流程二、安装 Nhost CLI原文档提供了四种官方安装途径覆盖 macOS、Linux含 Nix以及通过 Node 包管理器固定版本等场景。HomebrewmacOS / Linuxbrew install nhost/tap/nhostNix若已启用 flakes直接安装nix profile install github:nhost/nhost#cli或临时运行、不写入 profilenix run github:nhost/nhost#clinpm / pnpm / Yarn / Bun在项目内以开发依赖安装可将 CLI 版本固定给整个团队适合与package.json一起提交npm install -D nhost/cli pnpm add -D nhost/cli yarn add -D nhost/cli bun add -d nhost/cli不安装、直接运行npx nhost/clilatest --version pnpm dlx nhost/clilatest --version yarn dlx nhost/clilatest --version bunx nhost/clilatest --version快速安装脚本Linux / macOScurl -sSL https://raw.githubusercontent.com/nhost/nhost/main/cli/get.sh | bash或指定版本安装示例为 1.38.0curl -sSL https://raw.githubusercontent.com/nhost/nhost/main/cli/get.sh | bash -s 1.38.0仓库内对应的安装脚本为 cli/get.sh。从源码结构看CLI 主体由 cli/main.go 构成内部通过 urfave/cli v3 注册全部子命令config、dev、mcp、project、run、schema、secrets、deployments、software、user等安装后即可在终端使用nhost命令。三、快速开始从登录到启动下面的步骤是快速参考仓库内 cli/README.md 也强调这是一份速查逐字引导式教程以官方 CLI Quickstart 为准。1. 认证nhost login仅当需要从已有的 Nhost Cloud 项目拉取配置或部署时才需要登录纯本地开发可以跳过。nhost login该命令对应 cli/cmd/user/login.go实际执行 cli/clienv/wf_login.go 中的Login流程支持两种认证方式OAuth2 PKCE默认本地起一个临时回调服务器监听127.0.0.1随机端口打开浏览器跳转授权页回调时校验state参数与授权码再换取含offline_accessscope 的 refresh token 并持久化到本地凭据文件PATPersonal Access Token若设置了pat直接调用 Auth 服务的 PAT 登录接口换取会话凭据。登录凭据会被保存见saveCredentials写入 CLI 的 auth 文件供nhost init --remote、nhost config pull、部署等云端操作复用。2. 初始化项目nhost initnhost init该命令会脚手架出两个目录并纳入 Git 版本控制nhost/后端配置目录包含config.yaml、secrets、migrations/default、metadata、seeds、emails等functions/Serverless 函数目录。实现见 cli/cmd/project/init.goinitFolders会创建.nhost、functions、nhost/migrations/default、nhost/metadata、nhost/seeds、nhost/emails目录init.go随后把内嵌模板与认证邮件模板写入项目writeFS两次调用分别写入templates/init与services/auth/email-templates。也可以从已有的 Nhost Cloud 项目起步nhost init --remote--remote标志环境变量NHOST_REMOTE触发 InitRemote先解析云端项目、config pull拉取配置再通过 Hasura CLI 包装器创建初始 Postgres migrationmigrate create init --from-server并导出 metadata 到本地实现云端现状的完整本地化。3. 启动开发环境nhost upnhost up该命令使用 Docker 拉起完整技术栈Postgres、GraphQL、Auth、Storage、Functions并打印各服务的本地访问地址。本地 Dashboard 地址为https://local.dashboard.local.nhost.run停止环境用nhost down跟踪日志用nhost logs。下图是 CLI 启动本地环境的终端输出示例可以看到各服务端点Functions、GraphQL、Auth、Storage、Hasura UI的打印结果nhost up的启动流程从 cli/cmd/dev/up.go 的up函数可以还原出完整启动流水线前置校验检查nhost.toml与 secrets 文件是否存在不存在则提示先执行nhost init或nhost config pullup.go解析配置与 secrets解析 secrets要求值带引号、调用config.Validate校验配置生成 compose 文件由dockercompose.ComposeFileFromConfig动态生成docker-compose.yaml并写入工作目录启动容器dc.Start拉起全部服务并等待健康应用迁移与元数据migrations函数依次应用nhost/migrations/defaultApplyMigrations、nhost/metadata/version.yamlApplyMetadata若.nhost目录不存在或指定--apply-seeds则再应用nhost/seeds/defaultup.go重启并导出 metadata重启 storage/auth/ai/functions 等服务使 metadata 生效随后调用 Hasura CLI 包装器执行metadata export把最新 metadata 回写本地目录最后ReloadMetadata收尾。nhost up还支持大量可调参数均可在 cli/cmd/dev/up.go 中找到定义并支持同名环境变量覆盖Flag默认值说明--http-port443HTTP 监听端口NHOST_HTTP_PORT--disable-tlsfalse禁用 TLSNHOST_DISABLE_TLS--postgres-port5432Postgres 对外端口NHOST_POSTGRES_PORT--apply-seedsfalse显式应用 seedsNHOST_APPLY_SEEDS--auth-port/--storage-port/--functions-port/--hasura-port/--hasura-console-port0不暴露将对应服务额外暴露到宿主机端口源码注释明确标注Not recommended即默认不建议直接暴露--dashboard-versionnhost/dashboard:3.5.3Dashboard 镜像版本NHOST_DASHBOARD_VERSION--functions-version2.2.0Functions 运行时版本NHOST_FUNCTIONS_VERSION--run-service空追加 run service 到开发环境可多次传递格式/path/to/run-service.toml[:overlay_name]NHOST_RUN_SERVICE--run-service-volume空把本地目录挂载进 run service 容器格式service-name/local/path:/container/pathNHOST_RUN_SERVICE_VOLUME--ca-certificates空覆盖容器内 CA 证书路径NHOST_CA_CERTIFICATES四、配置管理nhost config命令族本地环境的全部后端行为由nhost/目录下的配置驱动。CLI 在 cli/cmd/config/config.go 中注册了完整的config子命令族nhost config default输出默认配置nhost config example输出一份完整示例配置见 cli/cmd/config/example.go覆盖 Global、AI、GraphQL、Hasura、Functions、Auth、Postgres、Provider、Storage、Observability、Experimental 等全部区块nhost config pull从云端项目拉取配置到本地nhost config apply应用配置变更nhost config show查看当前配置nhost config validate校验配置合法性nhost config edit编辑配置。默认配置骨架nhost init生成的默认配置定义在 cli/project/config.goHasura 的admin_secret、webhook_secret与 RS256 JWT 公钥/私钥均通过{{ secrets.XXX }}模板变量引用由 secrets 文件提供真实值同时预置 Postgres 存储容量与 Grafana 可观测性配置最终经 schema 填充与校验后落盘。配置与 secrets 的分工启动时 cli/cmd/dev/up.go 会同时解析 secrets 与配置secrets 文件中存放HASURA_GRAPHQL_ADMIN_SECRET、NHOST_WEBHOOK_SECRET、NHOST_JWT_PUBLIC_KEY、NHOST_JWT_PRIVATE_KEY、NHOST_JWT_KID、GRAFANA_ADMIN_PASSWORD等敏感值解析失败时提示确保 secret 值用引号包裹配置文件中则以模板变量引用它们实现配置与密钥分离、密钥不入库的安全实践。五、内置 MCP Server让 AI 助手安全操作你的项目Nhost CLI 内置了一个 MCPModel Context Protocol服务器允许 AI 助手通过标准协议与你的 Nhost 项目交互。核心价值在于安全、可控的访问提供对 GraphQL 数据、项目配置和文档的访问通过细粒度权限精确指定 LLM 可以执行哪些查询queries与变更mutations开发场景下支持 AI 辅助的 schema 管理、metadata 变更、迁移以及直接读取 GraphQL schema 用于智能查询构建。MCP 子命令入口在 cli/cmd/mcp/mcp.go全局 flag--config-file或环境变量NHOST_MCP_CONFIG_FILE指定配置文件路径默认是$NHOST_DOT_NHOST_FOLDER/mcp-nhost.toml。包含三个子命令nhost mcp config交互式向导生成并保存配置文件支持--confirm跳过确认子命令nhost mcp config dump把配置打印到 stdout 供检查cli/cmd/mcp/config/config.gonhost mcp start以 stdio 方式启动 MCP 服务器cli/cmd/mcp/start/start.gonhost mcp gen生成 Nhost Cloud 的 GraphQL schema默认仅允许organizations、organization、app、apps、config等查询--with-mutations时才额外允许updateConfig变更见 cli/cmd/mcp/gen/gen.go。MCP 权限配置示例配置模型定义在 cli/mcp/config/config.go顶层包含[cloud]管理云端项目enable_mutations控制是否允许变更类操作与[[projects]]本地或云端项目的访问授权列表。每个 project 的关键字段字段说明subdomain/region项目的子域名与区域用于拼接端点 URL见 cli/clienv/urls.go 中https://subdomain.service.region.nhost.run的构造规则description项目描述会注入 MCP 服务器的指令文本admin_secret/pat二选一管理密钥或属于该项目的 PAT用于认证manage_metadata是否允许管理项目 metadata表、关系、权限等allow_queries允许执行的查询白名单[*]表示全部允许空列表则禁止所有查询allow_mutations允许执行的变更白名单规则同上graphql_url/auth_url/hasura_url可选覆盖默认拼接的端点 URL仓库 cli/cmd/mcp/testdata/sample.toml 给出了一个完整示例同时配置了本地项目、云端 staging 与 production 三个环境并演示了最小权限实践——production 项目只放行getComments查询与insertComment、updateComment、deleteComment变更[cloud] enable_mutations true [[projects]] subdomain local region local description Local development project running via the Nhost CLI admin_secret nhost-admin-secret manage_metadata true allow_queries [*] allow_mutations [*] [[projects]] subdomain asdasdasdasdasd region eu-central-1 description Staging project for my awesome app manage_metadata false admin_secret your-admin-secret-1 allow_queries [*] allow_mutations [*] [[projects]] subdomain qweqweqweqweqwe region us-east-1 description Production project for my awesome app manage_metadata false pat pat-for-qweqweqweqweqwe allow_queries [getComments] allow_mutations [insertComment, updateComment, deleteComment]MCP 服务器在 cli/cmd/mcp/start/start.go 的BuildServer中组装先注入服务指令含cfg.Projects.Instructions()生成的项目清单与使用须知再按配置注册资源resources、云端工具cloud tools受enable_mutations控制、项目工具与 schema 工具。若配置文件不存在启动时会回退到 DefaultConfig——一个仅含本地项目local/localmanage_metadatatruequeries 与 mutations 全放行的最小安全配置。六、从源码构建与本地 TLS 证书仓库源码以 Go 编写要求 Go 1.18 或更高版本。在仓库内构建并安装go build -o /usr/local/bin/nhost构建产物即终端可用的nhost命令。源码目录内附带一张用于测试的自签名证书对于配置了 AWS 访问权限的 Nhost workers可以使用 cli/cert.sh 脚本从 Lets Encrypt 生成真实证书。重新生成本地 TLS 证书证书脚本当前要求显式指定 Kubernetes 目标对之前无参运行的操作者而言是刻意的破坏性变更。从仓库根目录进入 CLI 开发 shell 后执行nix develop .#cli cd cli ./cert.sh namespace deployment运行环境需要 Certbot 及其 Route53 插件、kubectl、jq、digshellcheck仅用于脚本 lint 而非运行时依赖。操作者需要具备有效的 AWS 凭据用于 Route53 证书签发以及活跃的 Kubernetes 上下文对 Deployment 具备get、patch及 rollout 状态/等待权限。脚本永远不会选择或切换 kubectl context。几个关键安全与运维细节原文档明确说明需严格注意通配符认证 hook 通过修改 Deployment 中现有的ACME_CHALLENGE_*环境变量来发布挑战九个受支持变量每个都必须在某个容器中作为唯一的、直接的、非空的value恰好出现一次——重复变量、valueFrom或 Deployment 布局变更都会导致 fail-closed安全失败挑战快速发布可能引发中间态 rollout 抖动只有最终被调用的 hook 才会等待最终 generation 与 DNS 就绪挑战值会有意保留。若 Certbot 完全复用了所有缓存的授权则不会调用任何 hook此时发布是合法的空操作若仅部分缓存命中最终 hook 仍会校验所有保留值超时参数rollout 超时、全局 DNS 超时、DNS 轮询间隔默认分别为 300s、300s、2s可通过环境变量ACME_ROLLOUT_TIMEOUT_SECONDS、ACME_DNS_TIMEOUT_SECONDS、ACME_DNS_POLL_INTERVAL_SECONDS覆盖最坏情况约在快速 patch 之后十分钟内完成DNS 默认使用系统解析器可通过ACME_DNS_SERVER指定标准 53 端口的主机名或 IPv4 解析器当递归负缓存延迟了新的 TXT 记录时优先使用权威或合适的公共解析器不要对同一 Deployment 并发执行证书请求每个服务每种值只能存一份rollout 期间的 UID 或 generation 变化也会中止运行校验值属于公开 DNS 数据kubectl set env必然会把当前值暴露在该进程的参数列表中hook 会抑制含值的命令输出且不创建 token 状态文件但操作者仍应限制本机进程检查与命令追踪Route53 证书、证书复制目的地与最终清理逻辑保持不变务必从cli/目录运行该命令以保证其既有的相对输出路径可以正确解析。七、依赖与支持平台nhost up依赖以下本机软件均为原文档列出的硬性依赖Docker安装说明Docker ComposecurlGit支持平台macOSLinuxWindows WSL2八、小结Nhost CLI 把Firebase 替代品的整套后端Postgres、Hasura GraphQL、Auth、Storage、Serverless Functions压缩进几条命令nhost init脚手架项目、nhost up一键拉起本地栈并自动应用迁移与 metadata、nhost config系列管理配置、内置 MCP Server 让 AI 助手在细粒度权限下参与开发。配合 git-based 的云端部署工作流本地nhost/目录即可成为团队后端配置的唯一事实来源。若想深入源码建议从 cli/main.go 的命令注册表出发沿 cli/cmd/dev/up.go 的启动流水线、cli/cmd/project/init.go 的脚手架逻辑以及 cli/mcp/config/config.go 的权限模型逐层阅读。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考