Hasura GraphQL Engine Docker镜像文档

重要提示

2022年12月7日上午10:00（太平洋标准时间），Hasura从本仓库中移除了受安全漏洞影响的部分镜像，以防止其在生产环境中运行。建议受影响用户立即更新至修复版本。

更多详情请参见安全公告：[***]

镜像概述

Hasura GraphQL Engine 是一款极速的GraphQL服务器，可在Postgres数据库上提供即时、实时的GraphQL API，支持通过数据库事件触发Webhook，并通过远程模式实现业务逻辑集成。其核心优势在于细粒度访问控制，帮助用户快速构建基于Postgres的GraphQL应用，或为现有Postgres应用增量迁移至GraphQL架构。

!Hasura logo

核心功能与特性

• 即时GraphQL API：无需手动编写 resolver，自动为Postgres数据库生成GraphQL API
• 实时数据推送：支持通过GraphQL订阅（Subscriptions）实现数据实时更新
• 数据库事件触发器：通过Webhook响应数据库事件（插入、更新、删除）
• 远程模式集成：合并多个GraphQL服务，统一API入口
• 细粒度访问控制：基于角色的权限系统，控制数据访问范围
• 多架构支持：兼容amd64和arm64架构

支持的标签

• <version>：指定版本（如v2.15.2），latest对应最新稳定版
• 迁移工具集成版：<version>.cli-migrations-v2、latest.cli-migrations-v2、<version>.cli-migrations-v3、latest.cli-migrations-v3（包含CLI迁移工具）

快速参考

• 获取帮助：Hasura ***社区 或 Stack Overflow（标签hasura）
• 提交Issue：GitHub仓库
• 支持架构：amd64、arm64
• 官方文档：[***]

使用场景

• 快速构建基于Postgres的GraphQL后端服务
• 为现有Postgres应用提供GraphQL接口，实现增量迁移
• 需要实时数据推送的应用（如仪表盘、协作工具）
• 多服务API聚合（通过远程模式合并多个GraphQL服务）

使用方法

Hasura依赖Postgres数据库运行，Postgres部署说明参见官方镜像。

启动Hasura实例

docker run -d -p 8080:8080 \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://用户名:密码@主机名:端口/数据库名 \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

Hasura控制台将在 http://localhost:8080 可用。

HASURA_GRAPHQL_DATABASE_URL 示例：

• postgres://admin:password@localhost:5432/my-db（带密码）
• postgres://admin:@localhost:5432/my-db（无密码）

网络配置

若Postgres实例运行在本地主机，需调整Docker网络配置以允许容器访问主机服务：

Linux系统

添加 --net=host 标志共享主机网络命名空间：

docker run -d --net=host \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://用户名:密码@localhost:端口/数据库名 \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

Docker Desktop（Mac/Windows）

使用 host.docker.internal 作为主机名访问宿主机服务：

docker run -d -p 8080:8080 \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://用户名:密码@host.docker.internal:端口/数据库名 \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

使用docker-compose部署

以下为Hasura与Postgres的docker-compose.yaml示例：

version: '3.6'
services:
  postgres:
    image: postgres
    restart: always
    volumes:
    - db_data:/var/lib/postgresql/data  # 持久化Postgres数据
  graphql-engine:
    image: hasura/graphql-engine:v1.0.0-beta.6  # 指定Hasura版本
    ports:
    - "8080:8080"  # 映射控制台端口
    depends_on:
    - "postgres"  # 依赖Postgres服务
    restart: always
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:@postgres:5432/postgres  # 连接Postgres（服务名作为主机名）
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"  # 启用控制台（设为"false"禁用）
      ## 取消注释以设置管理员密钥
      # HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
volumes:
  db_data:  # 定义数据卷

执行 docker-compose up，待初始化完成后访问 http://localhost:8080 打开Hasura控制台。

环境变量配置

注意事项

• 密码特殊字符：若密码包含#、%、$、@等特殊字符，需URL编码（如@编码为%40）。
• 日志检查：通过容器日志确认数据库连接状态（docker logs <容器ID>）。
• Postgres权限：Hasura需要Postgres数据库的特定权限，详见官方文档。
• 匿名遥测：Hasura默认收集匿名使用数据，详情及退出方法见遥测说明。

许可信息

hasura/graphql-engine 镜像包含开源和专有组件：

• 开源部分：基于 Apache License 2.0 许可。
• 专有组件：包含Hasura企业版功能，需通过Hasura提供的许可密钥启用。

如需仅含开源组件的镜像，使用标签以 -ce 结尾的社区版（如 hasura/graphql-engine:<VERSION>-ce）。

与所有Docker镜像一样，本镜像可能包含基础系统（如Bash等）及依赖组件，其许可可能不同。

注：文档中提及的外部链接（如event-triggers.md）请参考官方文档获取完整内容。