Hasura GraphQL Engine 保姆级部署教程：给数据库瞬间套上 GraphQL + REST 接口层

一、项目介绍

Hasura GraphQL Engine 是一个开源产品，官方 V2 README 对其定位是："accelerates API development by 10x by giving you GraphQL or REST APIs with built-in authorization on your data, instantly."（通过在你的数据上即时提供带内建授权的 GraphQL 或 REST API，把 API 开发速度提升 10 倍。）它是一个位于 Postgres 数据库前面的引擎，客户端发来 GraphQL 请求时，Hasura 直接把它翻译成 SQL 打到 Postgres，并把结果序列化为 JSON 返回。

官方仓库 graphql-engine 是一个大型 monorepo，包含 V2（当前稳定版）与 V3（DDN，已 GA）两套引擎代码。V2 核心 GraphQL Engine 以 Apache License 2.0 发布；V2 目录中除 server、cli、console 外的其他内容（含 docs、community）以 MIT License 发布。V3 引擎与全部 Data Connectors 均以 Apache License 2.0 发布。项目在 GitHub（hasura/graphql-engine）持续活跃维护，官方提供 Docker 镜像 hasura/graphql-engine、Hasura Cloud 托管服务与一键部署按钮（Heroku、DigitalOcean、Azure、Render）。

二、功能拆解

按官方 V2 README「Features」一节，核心功能如下：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/hasura/graphql-engine
• 官方网站：https://hasura.io/
• V2 文档：https://hasura.io/docs
• V3/DDN 文档：https://hasura.io/docs/3.0/getting-started/quickstart/
• Docker 安装清单：https://github.com/hasura/graphql-engine/tree/master/install-manifests
• V2 README：https://github.com/hasura/graphql-engine/blob/master/V2-README.md
• Discord：https://discord.gg/hasura ｜ Twitter：https://twitter.com/HasuraHQ

四、环境要求

官方 Docker 部署文档《Run Hasura GraphQL Engine Using Docker》明确前置要求：

• Docker 与 Docker Compose（Prerequisites 一节原文）。
• 端口：Hasura 引擎默认监听 8080（compose 中 ports: - "8080:8080"）。
• 元数据库：官方 compose 自带一个 postgres:15 容器用于存储 Hasura Metadata；业务数据源可在控制台中另行接入。
• 操作系统：官方未限定具体 OS，只要能运行 Docker / Docker Compose 即可。
• 硬件：官方文档未给出最低硬件指标。

五、部署步骤

步骤 1：新建目录并下载官方 docker-compose 文件

官方文档原文："The hasura/graphql-engine/install-manifests repo contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:"

curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml

逐段解释：curl 下载文件；URL 指向官方 install-manifests 仓库中的 docker-compose 清单；-o docker-compose.yml 保存到当前目录。官方文档另给 wget 等价命令：wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose/docker-compose.yaml。

预期输出参考： curl 下载进度条，文件保存成功，无报错。

步骤 2：查看 compose 文件关键内容

官方 install-manifests 中的 docker-compose.yaml 原文如下（核心节选）：

services:
  postgres:
    image: postgres:15
    restart: always
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: postgrespassword
  graphql-engine:
    image: hasura/graphql-engine:v2.51.3
    ports:
      - "8080:8080"
    restart: always
    environment:
      ## postgres database to store Hasura metadata
      HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
      ## this env var can be used to add the above postgres database to Hasura as a data source
      PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
      ## enable the console served by server
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true" # set to "false" to disable console
      ## enable debugging mode. It is recommended to disable this in production
      HASURA_GRAPHQL_DEV_MODE: "true"
      HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
      ## uncomment next line to set an admin secret
      # HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
    depends_on:
      - postgres
volumes:
  db_data:

逐段解释：postgres 服务使用 postgres:15 镜像，POSTGRES_PASSWORD: postgrespassword 设置元数据库密码，db_data 命名卷持久化数据；graphql-engine 服务使用官方镜像 hasura/graphql-engine:v2.51.3，映射 8080 端口；HASURA_GRAPHQL_METADATA_DATABASE_URL 指向元数据库连接串；PG_DATABASE_URL 用于把同一个 Postgres 注册为业务数据源；HASURA_GRAPHQL_ENABLE_CONSOLE: "true" 开启服务端控制台；HASURA_GRAPHQL_DEV_MODE: "true" 开启调试模式（官方注释建议生产环境关闭）；HASURA_GRAPHQL_ADMIN_SECRET 默认被注释，公网部署必须取消注释并设置强密钥。

步骤 3：启动 Hasura 引擎与 Postgres

docker compose up -d

逐段解释：官方文档原文："The following command will run Hasura GraphQL Engine along with a Postgres database to store its Metadata." docker compose up 依据 docker-compose.yml 创建并启动所有服务；-d 后台运行。

预期输出参考（官方文档原文）：

[+] Running 3/3
 ⠿ Network default_default     Created
 ⠿ Container default-postgres-1        Started
 ⠿ Container default-graphql-engine-1  Started

步骤 4：确认容器运行状态

docker ps

逐段解释：列出正在运行的容器。

预期输出参考（官方文档原文）：

CONTAINER ID  IMAGE                      ...  STATUS   PORTS
097f58433a2b  hasura/graphql-engine      ...  Up 1m    8080->8080/tcp
b0b1aac0508d  postgres                  ...  Up 1m    5432/tcp

六、配置参数详解

1. 官方 compose 中的核心环境变量：

2. Admin Secret 配置（官方文档「Securing the GraphQL endpoint」一节）：

官方文档原文："To make sure that your GraphQL endpoint and the Hasura Console are not publicly accessible, you need to configure an admin secret key." 在 compose 的 graphql-engine.environment 中加入：

      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey

官方警告："The HASURA_GRAPHQL_ADMIN_SECRET should never be passed from the client to the Hasura GraphQL Engine as it would give the client full admin rights to your Hasura instance."（Admin Secret 绝不应下发到客户端，否则客户端即获得全部管理员权限。）

七、启动与运维

• 启动： docker compose up -d（官方原命令）。
• 停止： docker compose down。
• 查看状态： docker ps（官方原命令）。
• 查看日志： 官方文档原文："You can check the logs of the Hasura GraphQL Engine deployed using Docker by checking the logs of the GraphQL Engine container:"

docker logs 097f58433a2b

逐段解释：把 097f58433a2b 换成 docker ps 中 graphql-engine 容器的实际 ID 或容器名。预期输出参考（官方文档原文）：

{"timestamp":"2018-10-09T11:20:32.054+0000","level":"info","type":"http-log","detail":{"status":200,"url":"/v1/graphql","method":"POST",...}}

• 开机自启： 官方 compose 中两个服务都带 restart: always，即官方提供的自启方式——容器异常退出或 Docker 重启后自动拉起。
• 修改端口： 编辑 compose 中 graphql-engine.ports，如 "9000:8080"，宿主端口改为 9000，容器内仍 8080，然后 docker compose up -d 重建。
• 数据持久化： 官方 compose 用命名卷 db_data:/var/lib/postgresql/data 持久化元数据库。

八、实操验证

1. 浏览器访问 http://服务器IP:8080，应看到 Hasura Console 控制台界面（因 HASURA_GRAPHQL_ENABLE_CONSOLE: "true"）。
2. 在 Console 左侧 DATA 页签中，官方 compose 已通过 PG_DATABASE_URL 把 Postgres 注册为数据源；点击公开（Public）一个 schema，Hasura 会自动追踪数据库表结构。
3. 在 DATA 页签中新建一张表（如 profile，含 id serial primary key、name text）。
4. 转到 GRAPHQL 页签，在左侧 docs 面板展开 insert_profile_one mutation，发送一条 mutation：

mutation {
  insert_profile_one(object: {name: "hello"}) {
    id
    name
  }
}

逐段解释：mutation 写操作；insert_profile_one 是 Hasura 根据表结构自动生成的插入 mutation；object 参数传入字段值；{id name} 指定返回字段。预期输出参考： 返回 {"data":{"insert_profile_one":{"id":1,"name":"hello"}}}。
5. 再发一条查询：

query {
  profile {
    id
    name
  }
}

应返回刚才插入的记录，即验证 Hasura 已为数据库自动生成 GraphQL API。

登录与安全（重要）

• 官方默认账号密码：无独立账号密码体系。 Hasura 没有出厂用户；控制台与 GraphQL 端点的访问控制由 HASURA_GRAPHQL_ADMIN_SECRET 这一共享密钥承担。
• Admin Secret（管理员密钥）： 默认 compose 中该变量被注释（无密钥），即任何人都能访问控制台与 GraphQL 端点——仅限本地测试。官方文档「Securing the GraphQL endpoint」一节明确要求公网部署必须设置。
• 设置方法： 在 compose 的 graphql-engine.environment 中取消注释 HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey，把值改成自己的强随机字符串，docker compose up -d 重建。
• 登录控制台： 设置 Admin Secret 后，浏览器访问 http://服务器IP:8080 会弹出密码输入框，输入 Admin Secret 即可进入。
• GraphQL 客户端传参： 在 HTTP Header 中加 x-hasura-admin-secret: 你的密钥；应用侧应通过 webhook / JWT 给终端用户发细粒度 token，而非把 Admin Secret 下发到前端。
• 密钥存放位置： compose 文件的 environment 段；生产环境建议改用 Docker secrets 或环境变量注入，勿把密钥提交到 git。
• 安全提醒：部署到公网前必须设置 HASURA_GRAPHQL_ADMIN_SECRET，并关闭 HASURA_GRAPHQL_DEV_MODE；官方 README 另提示 Hasura 默认收集匿名遥测，opt-out 见官方遥测文档。

九、故障排查

案例 1：容器启动后 8080 端口访问不到，日志报数据库连接失败

• 报错原文（常见形式，日志中出现）：error: connection to server at "postgres" (172.x.x.x), port 5432 failed: Connection refused
• 报错原因：graphql-engine 在 Postgres 尚未就绪时启动；或 compose 中 HASURA_GRAPHQL_METADATA_DATABASE_URL 的主机名/密码与 postgres 服务不一致。
• 分步解决：① 检查 compose 中 postgres.environment.POSTGRES_PASSWORD 与 HASURA_GRAPHQL_METADATA_DATABASE_URL 中的密码一致（默认均为 postgrespassword）；② 等待 Postgres 容器 healthy 后 docker compose restart graphql-engine；③ 官方 compose 已用 depends_on: postgres 声明启动顺序，不要随意删除。

案例 2：公网部署后控制台未授权即可访问

• 报错现象：未输入任何密码即可打开 http://服务器IP:8080 并执行 mutation。
• 报错原因：compose 中 HASURA_GRAPHQL_ADMIN_SECRET 仍被注释（官方默认示例即注释状态）。
• 分步解决：① 编辑 docker-compose.yml，取消 HASURA_GRAPHQL_ADMIN_SECRET 行注释并改为强密钥；② docker compose up -d 重建 graphql-engine 容器；③ 刷新浏览器，应提示输入密码。

案例 3：降级到旧版本后 Metadata 不兼容

• 报错原文（常见形式）：inconsistent metadata 或 catalog version mismatch。
• 报错原因：官方文档原文警告："If you are downgrading to an older version of the GraphQL Engine you might need to downgrade your Metadata catalogue version as described in Downgrading Hasura GraphQL Engine."
• 分步解决：① 升级前先 docker compose down 备份 db_data 卷；② 按官方《Downgrading Hasura GraphQL Engine》文档执行 metadata catalog 降级；③ 再把 compose 中镜像 tag 改回旧版本号。

案例 4：Hasura 容器内访问不到宿主机或其他容器的 webhook API

• 报错原因：官方文档「Docker networking」一节专门说明不同网络场景下的连接地址。
• 分步解决：① 若 API 在宿主机上：Linux 用 --net=host 或 docker bridge IP（172.17.0.1），macOS/Windows 用 host.docker.internal；② 若 API 在同一 compose 文件中：直接用服务名（如 api:3000）；③ 若两个容器分别 docker run：用 docker inspect 查容器内部 IP。

十、升级、回滚与卸载

升级（官方文档《Updating Hasura GraphQL Engine》一节）：

# Step 1: 查看最新 release 版本号
#   访问 https://github.com/hasura/graphql-engine/releases
# Step 2: 编辑 docker-compose.yml，把 image tag 改为最新版本，例如：
#   image: hasura/graphql-engine:v2.51.3
docker compose up -d

逐段解释：官方文档原文："In the docker compose command that you're running, update the image tag to this latest version." 修改 image 标签后 docker compose up -d 自动用新镜像重建 graphql-engine 容器，postgres 数据卷保留。

回滚： 官方未提供专门回滚命令；基于镜像标签机制，把 compose 中 image: hasura/graphql-engine:<版本> 改回旧版本号后 docker compose up -d。注意：降级前须按官方《Downgrading Hasura GraphQL Engine》文档处理 metadata catalog。

卸载： ① docker compose down 停止并删除容器；② 如需彻底删除元数据库，删除命名卷：docker volume rm default_db_data（卷名以 docker volume ls 实际输出为准）；③ 删除镜像：docker rmi hasura/graphql-engine:v2.51.3 postgres:15。

十一、商用许可合规说明

• 许可证：V2 核心 GraphQL Engine 为 Apache License 2.0；V2 目录中除 server、cli、console 外的内容（含 docs、community）为 MIT License；V3 引擎与全部 Data Connectors 为 Apache License 2.0（官方根 README「Licenses」一节明确）。
• Apache-2.0 与 MIT 均允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，Apache-2.0 还要求标注修改并附带 NOTICE（如有）。
• 官方 compose 中 HASURA_GRAPHQL_ENABLE_CONSOLE: "true" 与 HASURA_GRAPHQL_DEV_MODE: "true" 仅用于开发；生产环境应按官方注释关闭 dev mode 并设置 admin secret。
• Hasura 同时提供 Hasura Cloud 商业托管与企业版功能，属可选项，不影响自开源引擎的商用部署。