Hasura GraphQL Engine CLI 完整指南：安装、项目初始化与 Console 开发工作流
【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine
本指南以 cli/README.md 为骨架，结合 cli 目录下的 Go 源码（命令定义、执行上下文、构建脚本）展开，系统讲解 Hasura GraphQL Engine CLI（hasura命令）的四种安装方式、hasura init/hasura console的完整用法与底层实现、项目目录结构与config.yaml配置项，以及 CLI 与 Server 的版本兼容机制。读完本文，你将能够独立完成 CLI 的安装、构建、项目初始化，并理解每次命令执行背后的初始化流程。
一、Hasura CLI 是什么
Hasura GraphQL Engine CLI 是一个用 Go 编写的命令行工具，用于在本地管理与 Hasura GraphQL Engine 相关的项目：初始化项目目录、管理迁移（migrations）、元数据（metadata）与种子数据（seeds）、启动本地 Console 等。
从源码结构看，CLI 基于spf13/cobra构建命令树：
- 程序入口在 cli/cmd/hasura/hasura.go，
main函数调用commands.Execute()； - 根命令定义在 cli/commands/root.go，
init()中注册了init、console、metadata、migrate、seed、deploy、actions、plugins、version、scripts、docs、completion、update-cli等子命令； - 所有子命令共享同一个
ExecutionContext（见 cli/cli.go），其中保存了 Logger、Spinner、配置、HTTP 客户端、遥测数据等单例上下文。
hasura console命令实际上会启动两个本地 HTTP 服务：一个服务于 Console 前端页面（默认端口9695），另一个服务于迁移等内部 API（默认端口9693），详见下文第四节。
二、安装 Hasura CLI
cli/README.md 提供了四种安装方式，下面逐一展开。
2.1 一键脚本安装（Linux/macOS）
Linux 与 macOS 下最简单的方式是执行仓库自带的安装脚本：
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash脚本会把hasura二进制安装到/usr/local/bin。如果该目录没有写权限，脚本会提示输入sudo密码（具体逻辑见下文）。
自定义安装路径：通过INSTALL_PATH环境变量指定：
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | INSTALL_PATH=$HOME/bin bash安装指定版本：通过VERSION环境变量指定版本号（需带v前缀）：
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | VERSION=v2.50.1 bash从安装脚本源码 cli/get.sh 可以看到它的完整行为：
- 版本选择：
VERSION未设置时默认取v2.50.1（脚本中硬编码的当前默认版本）；脚本注释中保留了通过releases.hasura.io自动获取最新版本的 TODO 逻辑，因该站点未更新到 2.x 系列，暂以硬编码版本为准； - 平台与架构探测：通过
uname判断平台（linux/darwin），通过uname -m判断架构（x86_64→amd64，arm64/aarch64→arm64），其他架构会提示改用源码构建； - 下载与安装：从 GitHub Releases 下载对应
cli-hasura-<platform>-<arch>二进制到/tmp，chmod +x后移动到目标目录；若目标目录无写权限，脚本会询问是否使用sudo执行移动； - 已有安装检测：若
hasura已在 PATH 中，脚本会等待 3 秒（可Ctrl+C取消）后重新下载覆盖； - 收尾验证：安装完成后自动运行
hasura version --skip-update-check验证，若INSTALL_PATH不在$PATH中会给出提示。
2.2 Windows 安装
Windows 用户从 GitHub Releases 页面的 Assets 中下载cli-hasura-windows-amd64.exe二进制，即可直接使用。
2.3 通过 go get 安装
如果本机已安装 Go 工具链，也可以直接通过 Go 模块方式获取：
go get github.com/hasura/graphql-engine/cli/cmd/hasura该命令会拉取 cli/cmd/hasura 这个入口包，编译并安装可执行文件。
2.4 从源码构建
从源码构建需要 Go 与 GNU Make（可选）。完整流程如下：
git clone https://github.com/hasura/graphql-engine cd graphql-engine/cli make deps make build-cli-ext copy-cli-ext make build # binaries will be in _output directory各步骤含义（对应 cli/Makefile）：
make deps：执行go mod download下载 Go 依赖；make build-cli-ext：进入 cli-ext（Node.js 编写的 CLI 扩展，负责 actions codegen、SDL 处理等）执行依赖安装与构建；make copy-cli-ext：将不同平台的 cli-ext 二进制复制到 cli/internal/cliext/static-bin 下，供cli-ext子命令调用；make build：通过gox进行交叉编译，输出linux/amd64、darwin/amd64、windows/amd64、linux/arm64、darwin/arm64五个平台的静态二进制到_output/<VERSION>/目录，同时通过-ldflags注入构建版本号（version.BuildVersion）与插件分支引用（plugins.IndexBranchRef）。
构建出的二进制会以cli-hasura-<os>-<arch>命名。构建环境建议参考 cli/CONTRIBUTING.md：需要 Docker、Docker Compose（用于本地起 graphql-engine 服务）、Go >= 1.16、Node.js >= 10.19.0 与 npm >= 6.14.4。
三、快速开始：init + console
安装完成后，cli/README.md 给出的最小工作流是：
hasura init --directory <my-project> --endpoint <graphql-endpoint> --admin-secret <admin-secret> cd <my-project> hasura console第一条命令在当前目录下创建名为<my-project>的 Hasura 项目目录，并把 GraphQL Engine 的端点与管理员密钥写入项目配置；第二条命令进入项目目录启动本地 Console。
3.1 hasura init 详解
hasura init是新建项目时运行的第一个命令，其参数定义见 cli/commands/init.go：
| 参数 | 说明 |
|---|---|
[directory-name] | 项目目录名（位置参数），缺省时交互式提示输入，默认值hasura |
--directory | 已废弃的目录参数，改用位置参数 |
--endpoint | GraphQL Engine 的 HTTP(S) 根端点，如https://my-graphql-engine.com。注意：这是根端点，不是/v1/graphql |
--admin-secret | 管理员密钥（x-hasura-admin-secret请求头所需的密钥） |
--access-key | 已废弃，用--admin-secret代替 |
--version | 配置版本，默认3（即config v3），配置 v1 已被标记为弃用 |
hasura init会在项目目录中生成以下结构与文件：
config.yaml：CLI 配置文件（详见 3.3 节）；migrations/：迁移文件目录；metadata/：元数据目录（配置版本 >= 2 时创建），内含version.yaml、query_collections.yaml、allow_list.yaml、remote_schemas.yaml、actions.yaml、cron_triggers.yaml、sources.yaml等初始元数据文件，各文件由 cli/internal/metadataobject 下的对应模块生成；seeds/：种子数据目录。
若在--endpoint已给出的前提下以交互模式运行，CLI 会询问是否从该端点初始化元数据与迁移（等价于hasura metadata export+hasura migrate create --from-server）；非终端环境（如 CI）下该行为默认开启。初始化流程本身实现为一个有限状态机（FSM）：创建项目目录 → 校验端点 → 导出元数据 → 创建初始迁移，状态定义同样位于 cli/commands/init.go 中。
--endpoint指向的服务器必须是健康的（CLI 会先请求版本端点探测服务器状态），且不能是 GraphQL API 子路径；如果连接失败，cli/cli.go 的Validate()会给出排查提示（端点写错、服务器未启动、admin secret 不正确等）。
3.2 hasura console 详解
在项目目录内执行hasura console会启动一个本地 Web 服务器来提供 Hasura Console 前端，用于管理数据库、构建查询、调试 API。相关实现见 cli/commands/console.go：
| 参数 | 默认值 | 说明 |
|---|---|---|
--console-port | 9695 | Console 页面监听端口 |
--api-port | 9693 | 迁移等内部 API 监听端口 |
--address | localhost | 服务绑定地址，如0.0.0.0可对外访问 |
--api-host | http://localhost | （预览功能）提供迁移 API 的主机地址 |
--no-browser | false | 启动后不自动打开浏览器 |
--browser | 空 | 指定用哪个浏览器打开 Console |
--console-hge-endpoint | 空 | Console 前端访问 GraphQL Engine 时使用的端点（如容器场景下 CLI 与 HGE 各自在容器内，需传入http://0.0.0.0:8080之类的网络端点） |
--use-server-assets | false | 渲染 Console 时使用 HGE Server 提供的静态资源（而非 CDN） |
--static-dir | 空 | 提供 Console HTML 模板中静态资源文件的本地目录 |
--endpoint/--admin-secret | 来自config.yaml | 覆盖配置文件中的端点与密钥 |
--insecure-skip-tls-verify | false | 跳过 TLS 证书校验 |
--certificate-authority | 空 | 指定 CA 证书文件路径 |
从源码看，console命令会：读取版本 API 判断服务器类型（社区版 / EE / Cloud），据此选择对应的 Console 模板提供器（cli/pkg/console 下的NewDefaultTemplateProvider、NewEETemplateProvider、NewCloudTemplateProvider），渲染console.gohtml模板后启动两个 HTTP 服务。
一个典型的容器内使用示例（CLI 与 HGE 都跑在容器中）：
hasura console --endpoint http://host.docker.internal:8080 --no-browser --address 0.0.0.0 --console-hge-endpoint http://0.0.0.0:80803.3 项目配置文件 config.yaml
hasura init生成的config.yaml是 CLI 与服务器通信及定位项目目录的枢纽，对应 Go 结构体Config/ServerConfig（见 cli/cli.go）。一份典型的config v3配置如下：
version: 3 endpoint: http://localhost:8080 metadata_directory: metadata migrations_directory: migrations seeds_directory: seeds actions: kind: synchronous handler_webhook_baseurl: http://localhost:3000关键配置项说明（默认值来自 cli/cli.go 的readConfig()）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
version | 1 | 配置版本，当前推荐3；v3 仅支持元数据版本 >= 3 的服务器（即 Hasura v2.0.0 及以上） |
endpoint | http://localhost:8080 | GraphQL Engine 根端点 |
admin_secret | 空 | 管理员密钥；也可用access_key（已弃用） |
admin_secrets | 空 | 多管理员密钥列表，格式为["secret1", "secret2"]，与服务器端HASURA_GRAPHQL_ADMIN_SECRETS环境变量对应；设置时优先取第一个作为请求头 |
metadata_directory | metadata | 元数据目录 |
migrations_directory | migrations | 迁移目录 |
seeds_directory | seeds | 种子数据目录 |
metadata_file | 空 | 若设置，元数据以单个.json/.yaml文件维护而非目录 |
api_paths | v1/query、v2/query、v1/metadata、v1/graphql、v1alpha1/config、v1alpha1/pg_dump、v1/version | 自定义服务器 API 路径，用于对接非默认路由部署 |
insecure_skip_tls_verify | false | 跳过 TLS 校验 |
certificate_authority | 空 | CA 证书文件路径 |
actions.kind | synchronous | Action 执行模式 |
actions.handler_webhook_baseurl | http://localhost:3000 | Action 回调 webhook 的基础 URL |
配置文件支持环境变量覆盖（通过 Viper，前缀HASURA_GRAPHQL_），例如HASURA_GRAPHQL_ENDPOINT、HASURA_GRAPHQL_ADMIN_SECRET等。CLI 启动时会读取项目根目录下的.env文件（可用--envfile指定文件名，默认.env）加载环境变量。
四、每次执行命令时发生了什么
无论执行哪个子命令，CLI 都会经过 cli/cli.go 中ExecutionContext.Prepare()与Validate()两个阶段：
- Prepare：设置命令名、日志器、Spinner、版本对象；初始化全局配置目录（
~/.hasura，存放config.json、插件、上次更新检查时间等）；生成一次执行的唯一 ID； - Validate：校验执行目录、加载
.env、读取config.yaml；基于certificate_authority/insecure_skip_tls_verify构造带 TLS 配置的 HTTP 客户端；探测服务器版本端点确认服务器可达；检查 CLI 与服务器版本兼容性；获取服务器特性开关；创建migrations/、seeds/、metadata/目录（如缺失）；导出元数据判断服务器是否为元数据 v3（决定后续命令走 v2 还是 v3 元数据 API）； - 之后命令才真正执行，并通过 cli/telemetry 上报匿名使用统计（可用全局配置关闭）。
另外，根命令还注册了若干全局 flag（见 cli/commands/root.go）：
--log-level INFO|DEBUG|WARN|ERROR|FATAL # 日志级别，默认 INFO --project <dir> # 指定命令执行的项目目录（默认当前目录） --skip-update-check # 跳过执行前的自动更新检查 --no-color # 输出不带颜色 --envfile <path> # .env 文件名，默认 .env五、版本兼容性检查
CLI 每次连接服务器都会做一次版本兼容性检查，逻辑在 cli/version/compatibility.go 的CheckCLIServerCompatibility()中。规则可以概括为：
- 开发版（
dev）CLI 视为兼容； - 空 CLI 版本视为构建异常，判为不兼容；
- 服务器无版本号时按预发布构建处理；
- 主要版本号（Major）小于服务器时，提示“CLI 版本过旧，请升级”；
- 主要版本号大于服务器时，判为版本不匹配；
- 主版本相同但次版本不同，提示版本不匹配但仍视为兼容。
不兼容时 CLI 会打印警告而非中断执行（例如[cli: x] [server: y] version mismatch: ...）。通过 cli/version/compatibility_test.go 可以看到这些分支的测试用例。
六、贡献与测试
如果你希望在本地开发 CLI 或运行测试，cli/CONTRIBUTING.md 提供了完整指引，要点如下：
- 前置依赖：Docker、Docker Compose、Go >= 1.16、Node.js >= 10.19.0 与 npm >= 6.14.4、GNU Make（可选）；
- 本地启动 graphql-engine 服务器：在仓库根目录运行
cd install-manifests/docker-compose && docker compose up -d，GraphQL 端点为http://localhost:8080/v1/graphql，Console 位于http://localhost:8080/console； - 运行测试：先设置
HASURA_TEST_CLI_HGE_DOCKER_IMAGE（例如hasura/graphql-engine:v2.1.0），e2e 测试需要hasura在 PATH 中或设置HASURA_TEST_CLI_PATH，然后执行make test-all。Makefile 中test、integration_tests_config_v2、integration_tests_config_v3分别对应单元测试与两套配置版本的集成测试（cli/integration_test 下的v2/、v3/目录存放对应测试数据）。
七、小结
Hasura GraphQL Engine CLI 提供了从安装（一键脚本 / go get / 源码构建）到项目初始化（hasura init）、本地开发（hasura console）再到迁移、元数据、种子数据管理的完整工具链。理解config.yaml的配置项、命令执行前的Prepare/Validate流程，以及 CLI 与服务器的版本兼容规则，是顺畅使用 CLI 进行 Hasura 项目开发的基础。相关源码可进一步阅读：
- 入口与命令树：cli/cmd/hasura/hasura.go、cli/commands/root.go
- 执行上下文与配置：cli/cli.go
- 安装与构建脚本：cli/get.sh、cli/Makefile
- 命令实现：cli/commands/init.go、cli/commands/console.go
- 版本兼容：cli/version/compatibility.go
【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
