Nhost 全栈本地复现指南用 Docker Compose 一键拉起 Auth / GraphQL / Storage / Functions 演示环境【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost本篇技术指南基于仓库中 examples/docker-compose/README.md 展开讲解如何用 Docker Compose 在本地复现一套接近完整的 Nhost 开源后端栈PostgreSQL Hasura GraphQL Auth Storage Serverless Functions Dashboard并逐个验证各服务的真实运行结果。读完本文你将掌握该示例的架构组成、.env配置要点、启动流程以及针对每个服务的 curl 实测方法与生产化改造方向。Nhost 栈的核心组成前端经单一域名访问 GraphQL、Auth、Storage、Functions 四类 API底层由 Hasura、PostgreSQL 与 S3 兼容对象存储支撑架构图来自仓库 assets/nhost-diagram.png。一、示例概览一个接近完整的 Nhost 栈该示例的定位在其 README 中表述得很清楚用于演示如何用 Docker Compose 复现 Nhost 技术栈它基于 Nhost CLI 的实现思路仓库中的 cli/dockercompose/compose.go 即 CLI 侧生成 compose 配置的实现为探索 Nhost 能力提供一个大部分完整的演示环境。需要特别强调的是README 在开头就给出了重要提示IMPORTANT此示例仅用于演示目的。虽然它大体上完整呈现了 Nhost 栈但包含了一些面向开发友好的特性不适合直接用于生产环境。同时自托管声明也值得留意官方不提供无支持协议的免费自托管支持正式支持需要购买 support agreement除对本示例的修复与更新外其余支持由社区提供由于仪表盘以非云模式运行NEXT_PUBLIC_NHOST_PLATFORM: false部分与 Nhost Cloud 服务相关CI 集成、配置管理等的选项会被置灰。也就是说这是一个功能演示 / 本地开发学习环境而非生产部署模板。1.1 十个服务与镜像版本从 docker-compose.yaml 可以看到完整的服务编排共 10 个容器服务镜像职责postgrespostgres:16主数据库挂载 initdb.d 初始化脚本数据持久化到pgdata卷graphqlnhost/graphql-engine:v2.46.0-ceHasura GraphQL 引擎将 PostgreSQL 自动转为 GraphQL APIconsolenhost/graphql-engine:v2.46.0-ce.cli-migrations-v3Hasura Console以 hasura-cli 模式运行用于管理 schema 与迁移authnhost/auth:0.40.2认证服务处理注册、登录、JWT、MFA、邮件验证等storagenhost/storage:0.7.2文件存储服务后端对接 MinIOS3 兼容miniominio/minio:RELEASE.2025-02-28T09-55-16ZS3 兼容对象存储作为 Storage 的底层文件后端functionsnhost/functions:22-1.4.0Serverless 函数运行时Node 22绑定挂载当前目录dashboardnhost/dashboard:2.34.0Nhost 管理面板Next.js 应用mailhogjcalonso/mailhog:v1.0.1开发用邮件测试工具SMTP 假邮箱traefiktraefik:v3.1反向代理网关按 Host 规则把流量路由到各服务依赖关系上也做了健康检查编排auth与storage都depends_onGraphQL 与 Postgres 的service_healthy条件graphql依赖postgres健康postgres使用pg_isready探活graphql使用curl /healthz探活auth使用wget /healthz探活。README 中展示的启动日志也印证了这一点postgres与graphql率先达到Healthy其余服务随后启动。二、架构与流量入口单一网关、多域名路由整套编排以Traefik 作为统一入口监听宿主 80 端口每个服务通过traefik.*标签声明路由规则以Host(...)区分服务。核心配置摘录如下traefik: image: traefik:v3.1 command: - --api.insecuretrue - --providers.dockertrue - --providers.file.directory/opt/traefik - --providers.file.watchtrue - --providers.docker.exposedbydefaultfalse - --entrypoints.web.address:80 ports: - target: 80 published: 80--providers.docker.exposedbydefaultfalse只有显式打了traefik.enable: true标签的容器才会被路由各服务通过extra_hosts把local.*.local.nhost.run等域名映射到host-gateway保证容器内外都能按域名访问GraphQL 路由还使用了replacepathregex中间件把/v1/...路径重写为/v1/graphql...Functions 路由则将/v1(/|$)(.*)重写为/$2剥离前缀。启动完成后以下端点全部可用来自 README 的端点表服务URL说明Authhttp://local.auth.local.nhost.run认证服务Dashboardhttp://local.dashboard.local.nhost.runNhost 管理面板Databasepostgres://local.db.local.nhost.runPostgreSQL 数据库Functionshttp://local.functions.local.nhost.runServerless 函数Hasura Consolehttp://local.graphql.local.nhost.run/consoleGraphQL API 管理GraphQLhttp://local.graphql.local.nhost.runGraphQL 服务Mailhoghttp://local.mailhog.local.nhost.run邮件测试工具仅开发Storagehttp://local.storage.local.nhost.run文件存储服务这些域名由 .env.example 中的AUTH_URL、DASHBOARD_URL、DB_URL、FUNCTIONS_URL、GRAPHQL_URL、MAILHOG_URL、STORAGE_URL变量统一定义Traefik 标签与容器内环境变量都引用这些变量做到一处修改、全局生效。三、环境变量与安全配置从 .env.example 开始环境配置集中在 .env.example复制的第一步就是cp .env.example .env。其关键变量可分为四组1. 服务 URL域名AUTH_URLlocal.auth.local.nhost.run DASHBOARD_URLlocal.dashboard.local.nhost.run DB_URLlocal.db.local.nhost.run FUNCTIONS_URLlocal.functions.local.nhost.run GRAPHQL_URLlocal.graphql.local.nhost.run MAILHOG_URLlocal.mailhog.local.nhost.run STORAGE_URLlocal.storage.local.nhost.run2. 安全密钥README 明确警告生产环境必须修改GRAPHQL_ADMIN_SECRETchange-me POSTGRES_PASSWORDpostgresGRAPHQL_ADMIN_SECRET会贯穿注入到 graphql、auth、storage、functions、console、dashboard 全部服务作为 Hasura 管理密钥POSTGRES_PASSWORD则用于postgres://postgres:${POSTGRES_PASSWORD}postgres:5432/postgres这条全栈共享的数据库连接串。3. JWT 密钥JSON 格式HS256# Format: {type:HS256,key:your-secret-key} # You can generate a new key with openssl rand -base10 32 JWT_SECRET{type:HS256,key:0f987876650b4a085e64594fae9219e7781b17506bec02489ad061fba8cb22db}该密钥同时被 graphqlHASURA_GRAPHQL_JWT_SECRET、authHASURA_GRAPHQL_JWT_SECRET与 functions 引用保证三者签发的 JWT 互通互认——这正是认证链路能打通的关键。4. 存储与认证开关STORAGE_ACCESS_KEYminioaccesskey123 STORAGE_SECRET_KEYminiosecretkey123 AUTH_EMAIL_SIGNIN_EMAIL_VERIFIED_REQUIREDfalse存储密钥直接作为 MinIO 的MINIO_ROOT_USER/MINIO_ROOT_PASSWORDAUTH_EMAIL_SIGNIN_EMAIL_VERIFIED_REQUIRED控制邮箱验证后才能登录示例默认关闭以降低演示门槛。3.1 Auth 服务的完整可调参数docker-compose.yaml 中 auth 服务暴露了完整的AUTH_*环境变量体系这是理解 Nhost Auth 配置面的最佳入口主要包括访问控制AUTH_ACCESS_CONTROL_ALLOWED_EMAILS/ALLOWED_EMAIL_DOMAINS/BLOCKED_EMAILS/BLOCKED_EMAIL_DOMAINS默认均留空、AUTH_ACCESS_CONTROL_ALLOWED_REDIRECT_URLS令牌时效AUTH_ACCESS_TOKEN_EXPIRES_IN900秒即 15 分钟、AUTH_REFRESH_TOKEN_EXPIRES_IN259200030 天功能开关AUTH_ANONYMOUS_USERS_ENABLED、AUTH_DISABLE_SIGNUP、AUTH_DISABLE_NEW_USERS、AUTH_EMAIL_PASSWORDLESS_ENABLED、AUTH_MFA_ENABLED、AUTH_OTP_EMAIL_ENABLED、AUTH_PASSWORD_HIBP_ENABLEDHIBP 泄露密码库检查密码策略AUTH_PASSWORD_MIN_LENGTH9限流策略AUTH_RATE_LIMIT_ENABLEtrue含全局GLOBAL_BURST100/1m、暴力破解BRUTE_FORCE_BURST10/5m、注册SIGNUPS_BURST10/5m、邮件EMAIL_BURST10/1hEMAIL_IS_GLOBALtrue、短信SMS_BURST10/1h多维度限流SMTP 邮件AUTH_SMTP_HOSTmailhog、AUTH_SMTP_PORT1025、AUTH_SMTP_SECUREfalse、AUTH_SMTP_SENDERauthexample.com—— 开发环境直接把邮件发往 Mailhog角色体系AUTH_USER_DEFAULT_ROLEuser、AUTH_USER_DEFAULT_ALLOWED_ROLESuser,me。此外 auth 服务把宿主目录 nhost/emails 以 bind 方式挂载到/app/email-templates该目录按bg/cs/en/es/fr等语言维护了 email-confirm-change、email-verify、password-reset、signin-otp、signin-passwordless、signin-passwordless-sms 六类邮件模板并有 generator 目录以 React TSX 方式维护模板源文件说明邮件模板支持多语言与按需定制。四、从零启动四条命令拉起全部服务按 README 的 Demo 章节启动步骤如下$ git clone https://gitcode.com/GitHub_Trending/nh/nhost $ cd nhost/examples/docker-compose $ cp .env.example .env $ docker compose up -d [] Running 10/10 ✔ Container docker-compose-mailhog-1 Started 10.6s ✔ Container docker-compose-traefik-1 Started 10.6s ✔ Container docker-compose-dashboard-1 Started 10.6s ✔ Container docker-compose-functions-1 Started 10.6s ✔ Container docker-compose-storage-1 Started 21.8s ✔ Container docker-compose-auth-1 Started 21.9s ✔ Container docker-compose-graphql-1 Healthy 21.6s ✔ Container docker-compose-minio-1 Started 10.5s ✔ Container docker-compose-postgres-1 Healthy 6.5s ✔ Container docker-compose-console-1 Started 11.5s启动顺序可以观察到两个规律一是健康检查驱动的依赖启动postgres 6.5s 先健康、graphql 21.6s 健康storage/auth 等待其健康后才完成启动二是functions 容器健康检查的start_period长达 600s——因为函数服务需要安装依赖functions_node_modules/root_node_modules卷用于缓存 node_modules避免宿主与容器权限/路径冲突。另外仓库中 test/docker-compose.test.ts 提供了基于 Vitest 的 e2e 测试骨架package.json中e2e: vitest run可作为后续自动化验证服务连通性的扩展点。五、逐服务实测从 curl 到 GraphQL 查询README 为每个核心服务都给出了可复制的验证命令下面逐一展开并补充说明。5.1 Postgres直连数据库$ psql postgres://postgres:postgreslocal.db.local.nhost.run -c SELECT VERSION(); version --------------------------------------------------------------------------------------------------------------------------- PostgreSQL 16.8 (Debian 16.8-1.pgdg1201) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit (1 row)数据库在 5432 端口对宿主暴露见 compose 中 postgres 的ports配置。值得注意的是 initdb.d/0001-create-schema.sql 会在首次初始化时自动创建auth、storage两个 schema并安装pgcrypto、citext扩展同时定义set_current_timestamp_updated_at触发器函数——这是 auth/storage 服务建表迁移的前提也是镜像 nhost/postgres 初始化逻辑的复刻。5.2 Auth版本探测与邮箱密码注册$ curl http://local.auth.local.nhost.run/v1/version {version:0.37.1}说明上述输出是 README 录制示例时的运行版本当前 compose 文件固定的镜像为nhost/auth:0.40.2见 docker-compose.yaml实际启动后以镜像内版本为准。注册接口的完整请求与响应如下JWT claims 已展开为可读结构$ curl -X POST http://local.auth.local.nhost.run/v1/signup/email-password \ -H Content-Type: application/json \ -d {email: emailacme.test, password:s3cur3p4ssw0rd!} { session: { accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..., accessTokenExpiresIn: 900, refreshToken: 5743ea5b-9561-46f6-a9a4-b0cbc3c13dd2, refreshTokenId: 44a66ddf-a099-4a1d-bdb4-4c4d6e3d10ac, user: { avatarUrl: https://www.gravatar.com/avatar/1de09cde1ce545d06c9381280237c224?dblankrg, createdAt: 2025-03-27T14:40:31.046694975Z, defaultRole: user, displayName: emailacme.test, email: emailacme.test, emailVerified: false, id: f4603524-448d-4a96-b6d6-d4cf476796a8, isAnonymous: false, locale: en, metadata: null, phoneNumberVerified: false, roles: [ user, me ] } } }这段响应反映了几个关键设计accessTokenExpiresIn: 900与AUTH_ACCESS_TOKEN_EXPIRES_IN900完全对应JWT 中携带https://hasura.io/jwt/claims自定义 claimsx-hasura-allowed-roles、x-hasura-default-role、x-hasura-user-id这是 Hasura 做行级/角色级权限控制的凭证基础avatarUrl使用 Gravatar 默认图对应AUTH_GRAVATAR_ENABLEDtrue与AUTH_GRAVATAR_DEFAULTblank。5.3 Storage版本探测与文件上传$ curl http://local.storage.local.nhost.run/v1/version {buildVersion:0.7.1} $ curl -X POST http://local.storage.local.nhost.run/v1/files \ -H X-Hasura-Admin-Secret: change-me \ -H Content-Type: multipart/form-data \ -F fileREADME.md { id: ed8d72f4-34da-446a-aac7-150fd909bfd8, name: README.md, size: 6567, bucketId: default, etag: \19dba20946122f4a2f0aa41a12288270\, createdAt: 2025-03-27T14:43:42.08104700:00, updatedAt: 2025-03-27T14:43:42.08613700:00, isUploaded: true, mimeType: text/plain; charsetutf-8, uploadedByUserId: , metadata: null }上传需要携带X-Hasura-Admin-Secret值即.env中的GRAPHQL_ADMIN_SECRET。文件先进入 Storage 服务nhost/storage底层由 S3 兼容的 MinIO 承接S3_ENDPOINThttp://minio:9000、S3_BUCKETnhost元数据写入 PostgreSQLPOSTGRES_MIGRATIONS1时自动建表迁移。返回中的etag即对象存储的校验和bucketId: default为默认桶。5.4 GraphQL元数据查询与业务查询$ curl http://local.graphql.local.nhost.run/v1/version {server_type:ce,version:v2.36.9-ce} $ curl -X POST http://local.graphql.local.nhost.run/v1/graphql \ -H Content-Type: application/json \ -H X-Hasura-Admin-Secret: change-me \ -d {query:query { users { id email } }} { data: { users: [ { id: f4603524-448d-4a96-b6d6-d4cf476796a8, email: emailacme.test } ] } }这个查询直接复用了上一步注册的用户数据——Auth 写入 PostgreSQL 的 users 表Hasura 自动暴露为users查询两条命令即可验证注册即查询的全链路打通。GraphQL 引擎的HASURA_GRAPHQL_DATABASE_URL指向同一个 postgres 实例HASURA_GRAPHQL_UNAUTHORIZED_ROLEpublic、HASURA_GRAPHQL_DEV_MODEtrue等参数表明这是一个开发模式引擎。5.5 Functions调用 Serverless 函数$ curl http://local.functions.local.nhost.run/v1/echo { headers: { host: local.functions.local.nhost.run, user-agent: curl/8.7.1, accept: */*, x-forwarded-for: 172.19.0.1, x-forwarded-host: local.functions.local.nhost.run, x-forwarded-port: 80, x-forwarded-proto: http, x-forwarded-server: 941746efd09a, x-replaced-path: /v1/echo, accept-encoding: gzip }, query: {}, node: v22.13.0, arch: arm64 }/v1/echo对应的实现位于 functions/echo.ts一个标准的 Express 风格处理器回显请求头、查询参数、Node 版本与架构。注意响应中的x-replaced-path: /v1/echo——这正是 Traefik 中间件把/v1/echo重写为/echo后的结果验证了网关路径重写链路。同目录的 functions/hello.ts 则演示了参数化问候export default (req, res) { res.status(200).send(Hullo, ${req.query.name}!) }functions 容器将当前项目根目录 bind 到/opt/project因此新增.ts函数文件即可实时生效非常适合本地迭代。六、管理面板Dashboard 与 Hasura ConsoleDashboardhttp://local.dashboard.local.nhost.runNhost 管理面板通过NEXT_PUBLIC_NHOST_AUTH_URL、NEXT_PUBLIC_NHOST_GRAPHQL_URL、NEXT_PUBLIC_NHOST_STORAGE_URL、NEXT_PUBLIC_NHOST_FUNCTIONS_URL、NEXT_PUBLIC_NHOST_HASURA_CONSOLE_URL等环境变量指向本地各服务NEXT_PUBLIC_NHOST_PLATFORM: false使其以非云平台模式运行因此 README 提到与云服务相关的选项CI 集成、配置管理等会置灰不可用。Hasura Consolehttp://local.graphql.local.nhost.run/console由console服务提供镜像为带cli-migrations-v3的版本以hasura-cli console --no-browser模式运行把 nhost 目录 bind 挂载为工作目录。这里有一个值得注意的细节nhost目录下只有 config.yamlversion: 3没有 migrations/metadata 子目录说明示例让 Hasura 以连接即用的方式直接由数据库 schema 生成 GraphQL API同时把 migrations 管理能力留给开发者通过 Console 逐步建立。七、生产化注意事项README 明确建议README 在 Production Considerations 中明确列出本示例包含仅用于开发的组件——Mailhog邮件测试与Hasura Consoleschema 管理面向生产部署时应移除仅用于开发的组件Mailhog、Hasura Console配置正确的认证密钥.env中的GRAPHQL_ADMIN_SECRET、POSTGRES_PASSWORD、JWT_SECRET均需替换为强随机值设置合理的数据库凭据与访问控制实现正确的 SSL/TLS 终止示例中 Traefik 均为tls: false纯 HTTP 入口仅适合本地配置适当的资源限制制定并实施备份策略。此外docker-compose.yaml中AUTH_SMTP_HOSTmailhog、HASURA_GRAPHQL_DEV_MODEtrue、HASURA_GRAPHQL_ENABLE_TELEMETRYfalse、HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORStrue等均为开发向配置生产部署时同样需要逐一评估收敛。八、与 Nhost CLI 的关系与延伸阅读README 明确说明本示例基于 Nhost CLI 的实现。对应地仓库中 cli/dockercompose 目录下的 compose.go 及其测试如 compose_test.go、postgres.go正是 CLI 内部生成 Docker Compose 编排的逻辑感兴趣的话可以将二者对照阅读理解CLI 一键nhost dev背后实际生成的容器拓扑。示例中涉及的 auth、storage、functions 服务源码也分别位于 services/auth、services/storage、services/functions可作为深入理解各服务内部实现的入口。小结examples/docker-compose是一个麻雀虽小、五脏俱全的 Nhost 全栈复现示例Traefik 统一网关 PostgreSQL/Hasura 数据层 Auth 认证 Storage/MinIO 存储 Functions 无服务器函数 Dashboard 管理面板 Mailhog 邮件调试10 个容器一条命令即可拉起且 README 为每个服务都准备了可复制的验证命令。它最适合作为本地学习 Nhost 各组件协作方式、验证业务集成方案的演示环境若需生产级自托管则应在此基础上按第七节要点进行安全与稳定性加固。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考