Ubuntu 22.04 安装 Hasura GraphQL Engine 指南

目标：在 Ubuntu 服务器上从零完成 Hasura GraphQL Engine（v2.51.1）的安装、Postgres 依赖部署、systemd 托管与验证，并给出 Docker Compose 备用方案、升级降级、常见问题与卸载清理。已在 Ubuntu 22.04.5 LTS 与 Ubuntu 24.04.5 LTS 双环境实测通过（引擎 v2.51.1 + PostgreSQL 14.24 / 16.15 + Docker 29.1.3 + Compose v2.40.3）。

一、环境信息

本章列出本文实测所用的服务器环境与各组件版本，读者可据此判断自己的环境是否与实测基线一致。

• 操作系统 A：Ubuntu 22.04.5 LTS（x86_64，GLIBC 2.35）
• 操作系统 B：Ubuntu 24.04.5 LTS（x86_64，GLIBC 2.39）
• Hasura GraphQL Engine：v2.51.1（官方最新稳定版，GitHub Releases 2026-10-20 发布，2026-10-22 查询）
• hasura CLI：v2.51.1（cli/v2.51.1 标签，2026-10-19 发布，2026-10-22 查询）
• PostgreSQL：14.24（Ubuntu 22.04 apt 默认源）/ 16.15（Ubuntu 24.04 apt 默认源）
• Docker Engine：29.1.3（Ubuntu 22.04 docker.io 仓库版，仅方案 B 需要）
• Docker Compose：v2.40.3（Ubuntu 22.04 docker-compose-v2 仓库版，仅方案 B 需要）
• 引擎监听端口：8080（HTTP API 与 Console）；Console CLI 端口 9695 / 迁移 API 端口 9693（见 D1 命令篇）
• 元数据库：hasura_metadata；业务数据源：hasuradb（均在原生 PostgreSQL 实例中）

二、前置条件

安装前确认服务器满足以下条件，避免中途卡在依赖与环境上。

• 一台 Ubuntu 22.04（或 24.04）x86_64 服务器，具备 sudo 权限的账号（本文以 root 演示）；
• 服务器可访问外网（下载官方二进制与 apt 软件包；国内网络建议为 apt/curl 配置代理）；
• 端口 8080 未被占用（引擎默认 HTTP 端口），可用 ss -ltn | grep 8080 预先检查，无输出即空闲；
• 基础工具：curl、wget（Ubuntu 默认自带，缺失时 apt-get install -y curl wget）；
• 对 GraphQL 与 Hasura 的基本认知可参阅 《Hasura v2.51.1 介绍与选型指南》。

验证基础环境（Ubuntu 22.04.5 实测回显）：

cat /etc/os-release | grep PRETTY && ldd --version | head -1 && ss -ltn | grep 8080 || echo "8080 空闲"

PRETTY_NAME="Ubuntu 22.04.5 LTS"
ldd (Ubuntu GLIBC 2.35-0ubuntu3.11) 2.35
8080 空闲

💡 技术拓展：GLIBC（GNU C 库）版本决定了二进制程序能否在发行版上运行。Hasura 官方 Linux 二进制自近期的 v2 线起在 GLIBC 2.38 环境编译（下文实测验证），对发行版有硬性下限，主流发行版对照——

发行版	GLIBC 版本	能否运行 v2.51.1 官方二进制
Ubuntu 22.04	2.35	否（实测 GLIBC_2.38 not found）
Ubuntu 24.04	2.39	是（实测 version 正常输出）
Debian 12	2.36	否
Debian 13	2.41	是

本文因目标系统为 Ubuntu 22.04，主线给出官方二进制的完整标准流程与 glibc 排障实录，并在方案 B 提供 22.04 上完整可用的 Docker Compose 部署路径；两者选型见"六、方案对比与选择建议"。

三、版本选型说明

Hasura 有三类官方分发渠道，版本节奏各不相同，安装前先对齐。以下信息于 2026-10-22 实查 GitHub Releases 与官方 CDN。

关键差异与选型：需要固定/回退历史版本只能走官方镜像（方案 B）；官方 CDN 二进制永远只给最新稳定版。CLI 二进制则始终可从 GitHub Releases 按版本下载。hasura CLI 的历史独立仓库 hasura/cli 已不再发布 Release（其 releases 接口返回 Not Found，2026-10-22 实查），CLI 现统一在 graphql-engine 仓库以 cli/vX.Y.Z 标签发布。

本文引擎版本基准为 v2.51.1（OSS v2 线最新稳定版）；v3（Hasura DDN）为新一代云原生架构，不在本篇范围。

四、方案 A：官方二进制安装（原生部署主线）

本方案走官方原生路径：apt 安装 Postgres 依赖 → 下载官方二进制 → 创建专用账号与环境文件 → systemd 托管 → 验证。全流程在 Ubuntu 22.04.5 上实测，其中引擎二进制的版本验证步骤暴露了 GLIBC 硬边界（排障实录见 4.3），完整的"安装成功"回显取自 Ubuntu 24.04.5 复测。

4.1 方案说明

官方 Linux 二进制是引擎的官方非托管安装形态：单个约 100.6 MB 的可执行文件，内置迁移与元数据管理能力，配合 systemd 可做成开机自启的标准服务。它的官方分发点是 hasura CDN 的 server/latest/linux-amd64（GCS 存储，Content-Type application/octet-stream）。该方案要求宿主 GLIBC ≥ 2.38（4.3 实测结论），且官方 CDN 只提供 latest 通道，无法按版本号下载历史版本。

4.2 部署 Postgres 依赖（Ubuntu 22.04 实测）

Hasura 需要一个 PostgreSQL 实例存储元数据（catalog），同时通常把业务库作为数据源接入。Ubuntu 22.04 默认源带 PostgreSQL 14，直接 apt 安装：

apt-get update && apt-get install -y postgresql postgresql-contrib

Setting up postgresql-14 (14.24-0ubuntu0.22.04.1) ...
Processing triggers for man-db (2.10.2-1) ...

启动并设置开机自启，随后为 postgres 管理账号设置密码、创建元数据库与业务库（示例密码统一用 q1w2e3r4，生产请更换）：

systemctl enable postgresql && systemctl start postgresql && systemctl is-active postgresql

Executing: /lib/systemd/systemd-sysv-install enable postgresql
active

su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'q1w2e3r4';\""
su postgres -c 'createdb hasura_metadata'
su postgres -c 'createdb hasuradb'

ALTER ROLE

验证库已创建（实测回显）：

su postgres -c "psql -c '\l'" | grep hasura

 hasura_metadata | postgres | UTF8     | C.UTF-8 | C.UTF-8 |           |           |
 hasuradb        | postgres | UTF8     | libc    | C.UTF-8 | C.UTF-8 |            |           |

💡 技术拓展：PostgreSQL 的客户端认证由 pg_hba.conf 控制，常见方法对比——| 方法 | 说明 | 适用 | |---|---|---| | peer | 用 OS 用户名匹配数据库用户 | 本机 postgres 管理员（Ubuntu 默认 local all postgres peer） | | scram-sha-256 | 口令质询认证（PG 14+ 默认） | 本机/内网 TCP 连接（Ubuntu 默认 127.0.0.1/32 scram-sha-256） | | md5 | 旧口令认证 | 兼容老客户端 | | trust | 免密，仅调试 | 不建议生产 |

本文引擎通过 127.0.0.1:5432 以 scram-sha-256 口令认证连接，无需改 pg_hba.conf。

在业务库中建一张示例表并写入数据，供后续验证 GraphQL API（实测回显）：

su postgres -c "psql -d hasuradb -c \"CREATE TABLE products(id serial primary key, name text not null, price numeric(10,2) not null, created_at timestamptz default now());\""
su postgres -c "psql -d hasuradb -c \"INSERT INTO products(name,price) VALUES ('Keyboard',199.00),('Mouse',89.50),('Monitor',1299.00);\""

CREATE TABLE
INSERT 0 3

4.3 下载官方二进制与依赖排障实录

先把二进制下载到 /usr/local/bin 并赋执行权限。CDN 文件大小约 100.6 MB（实测 105428024 字节）：

curl -L https://graphql-engine-cdn.hasura.io/server/latest/linux-amd64 -o /usr/local/bin/graphql-engine
chmod +x /usr/local/bin/graphql-engine
ls -la /usr/local/bin/graphql-engine

-rwxr-xr-x 1 root root 105428024 Oct 22 11:26 /usr/local/bin/graphql-engine

校验下载完整性（实测 sha256）：

sha256sum /usr/local/bin/graphql-engine

1f34ad4264df07b3a5c0171c1f87b8405e5a2459f4c8f3d1824dec6904999a67  /usr/local/bin/graphql-engine

执行版本命令时，Ubuntu 22.04 会先后报出两个缺失依赖，实测排障过程如下。

第一次执行报共享库缺失：

graphql-engine version

graphql-engine: error while loading shared libraries: libodbc.so.2: cannot open shared object file: No such file or directory

定位：引擎为支持 SQL Server 数据源链接了 unixODBC。解决：安装 unixodbc：

apt-get install -y unixodbc

Processing triggers for libc-bin (2.35-0ubuntu3.14) ...

第二次执行暴露 GLIBC 边界：

graphql-engine version

graphql-engine: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by graphql-engine)

定位：用 ldd --version 确认 Ubuntu 22.04 的 GLIBC 为 2.35，而官方二进制要求 2.38（对二进制做符号解析可见其引用了 GLIBC_2.32/2.33/2.34/2.38）。结论：v2.51.1 官方 Linux 二进制要求 GLIBC ≥ 2.38，Ubuntu 22.04 无法原生运行该二进制，且 Ubuntu 官方源不提供更高版本 glibc。

⚠️ 注意：这一限制是官方二进制自身的编译边界，不是安装步骤错误。Ubuntu 22.04 上要让 Hasura 运行起来，请使用"五、方案 B：Docker Compose 部署"；若坚持原生二进制路径，请使用 Ubuntu 24.04 及以上（GLIBC 2.39）服务器，以下步骤在 Ubuntu 24.04.5 上实测继续。

在 Ubuntu 24.04.5（GLIBC 2.39）上重复 4.2–4.3 后，版本验证通过。除 unixodbc 外，24.04 还需补 libpq5（PostgreSQL 客户端库），同样以共享库报错形式暴露：

apt-get install -y unixodbc libpq5
graphql-engine version

Hasura GraphQL Engine: v2.51.1

引擎运行期动态依赖清单（ldd /usr/local/bin/graphql-engine 实测，供离线服务器备料）：libodbc.so.2、libpq.so.5、libssl.so.3、libcrypto.so.3、libgmp.so.10、libgnutls.so.30、libldap.so.2、libsasl2.so.2、libffi.so.8、libstdc++.so.6 等，均由 unixodbc、libpq5 与系统基础包覆盖。

4.4 创建运行账号与环境文件

为引擎创建无登录权限的系统账号（实测回显）：

useradd -r -s /usr/sbin/nologin hasura
id hasura

uid=997(hasura) gid=997(hasura) groups=997(hasura)

创建配置目录与环境变量文件 /etc/hasura/env（Engine 的全部配置均以 HASURA_GRAPHQL_* 环境变量传入，逐项详解见 《Hasura 配置参数详解》对应的 C1 篇）：

mkdir -p /etc/hasura
cat > /etc/hasura/env <<'EOF'
## 元数据存储库
HASURA_GRAPHQL_METADATA_DATABASE_URL=postgres://postgres:q1w2e3r4@127.0.0.1:5432/hasura_metadata
## 默认数据源（首次启动自动接入）
HASURA_GRAPHQL_DATABASE_URL=postgres://postgres:q1w2e3r4@127.0.0.1:5432/hasuradb
## 管理密钥
HASURA_GRAPHQL_ADMIN_SECRET=q1w2e3r4
## 服务端托管 Console
HASURA_GRAPHQL_ENABLE_CONSOLE=true
## 开发模式（生产应关闭）
HASURA_GRAPHQL_DEV_MODE=true
## HTTP 监听端口
HASURA_GRAPHQL_SERVER_PORT=8080
EOF

关键项说明：

• HASURA_GRAPHQL_METADATA_DATABASE_URL：元数据库连接串，首次启动时引擎自动建表（catalog 版本 48，v2.51.1 实测）；
• HASURA_GRAPHQL_DATABASE_URL：默认数据源连接串，首次启动自动以 default 名称接入；
• HASURA_GRAPHQL_ADMIN_SECRET：管理密钥，设置后所有请求必须携带 X-Hasura-Admin-Secret 头；
• HASURA_GRAPHQL_ENABLE_CONSOLE：是否由服务端托管 Web Console；
• HASURA_GRAPHQL_DEV_MODE：开发模式，生产应改 false；
• HASURA_GRAPHQL_SERVER_PORT：HTTP 监听端口，默认 8080。

4.5 systemd 托管

写入服务单元 /etc/systemd/system/hasura.service：

cat > /etc/systemd/system/hasura.service <<'EOF'
[Unit]
Description=Hasura GraphQL Engine
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=hasura
Group=hasura
EnvironmentFile=/etc/hasura/env
ExecStart=/usr/local/bin/graphql-engine serve
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

单元说明：EnvironmentFile 指向 4.4 的环境文件；After/Wants postgresql.service 保证依赖库先起；Restart=on-failure 异常退出自动拉起；LimitNOFILE=65536 抬高文件句柄上限适配连接池。启动并设置开机自启（实测回显）：

systemctl daemon-reload
systemctl enable hasura
systemctl start hasura
systemctl is-active hasura

Created symlink /etc/systemd/system/multi-user.target.wants/hasura.service → /etc/systemd/system/hasura.service.
active

查看服务状态（systemctl status hasura 实测节选）：

● hasura.service - Hasura GraphQL Engine
     Loaded: loaded (/etc/systemd/system/hasura.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-22 11:34:26 UTC; 13s ago
   Main PID: 3473 (graphql-engine)
      Tasks: 34 (limit: 94371)
     Memory: 41.3M (peak: 42.5M)
        CPU: 141ms
     CGroup: /system.slice/system.slice/hasura.service
             └─3473 /usr/local/bin/graphql-engine serve

4.6 验证运行

第一层：健康检查与版本（实测回显）：

curl -s http://127.0.0.1:8080/healthz && echo
curl -s http://127.0.0.1:8080/v1/version

OK
{"server_type":"ce","version":"v2.51.1"}

第二层：启动日志关键行（journalctl -u hasura 实测节选）：

{"detail":{"info":{"database_url":"postgres://postgres:...@127.0.0.1:5432/hasura_metadata","retries":1},"kind":"postgres_connection"},"level":"info",...}
{"detail":{"info":"Successfully initialized the catalog (at version 48).","kind":"catalog_migrate"},"level":"info",...}
{"detail":{"info":{"message":"Starting API server","time_taken":0.126531726},"kind":"server"},"level":"info",...}

Successfully initialized the catalog (at version 48) 表示元数据库初始化完成，Starting API server 表示 HTTP 服务已就绪。

第三层：鉴权行为（实测回显）——不带密钥的请求被拒绝：

curl -s -X POST http://127.0.0.1:8080/v1/graphql -H 'Content-Type: application/json' -d '{"query":"{ products { id } }"}'

{"errors":[{"message":"\"x-hasura-admin-secret\" required, but not found","extensions":{"path":"$","code":"access-denied"}}]}

第四层：GraphQL 取数闭环。先用 Metadata API 把示例表纳入跟踪（返回 {"message":"success"}），再发查询（实测回显）：

curl -s -X POST http://127.0.0.1:8080/v1/metadata -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"type":"pg_track_table","args":{"source":"default","table":{"schema":"public","name":"products"}}}'
curl -s -X POST http://127.0.0.1:8080/v1/graphql -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"query":"{ products { id name price } }"}'

{"message":"success"}
{"data":{"products":[{"id":1,"name":"Keyboard","price":199.00}, {"id":2,"name":"Mouse","price":89.50}, {"id":3,"name":"Monitor","price":1299.00}]}}

第五层：Console 可访问（HASURA_GRAPHQL_ENABLE_CONSOLE=true 时）：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/console

200

五层全部通过即部署完成。命令行的项目化管理（hasura CLI）见 《Hasura 常用命令与工具详解》对应的 D1 篇。

五、方案 B：Docker Compose 部署（备用方案，Ubuntu 22.04 可用主线）

本方案用官方镜像编排「Postgres + 引擎」双服务，是 Ubuntu 22.04 上完整可用的部署路径（规避了方案 A 的 GLIBC 边界），也是官方快速上手的标准形态：元数据库与引擎各一个服务，数据落在命名卷持久化。以下全程在 Ubuntu 22.04.5 实测。

5.1 前置：安装 Docker Engine 与 Compose

Ubuntu 22.04 官方源提供 Docker Engine 29.1.3 与 Compose v2 插件（实测版本），直接 apt 安装并启动：

apt-get install -y --no-install-recommends docker.io docker-compose-v2
systemctl start docker && systemctl is-active docker
docker --version && docker compose version

active
Docker version 29.1.3, build 29.1.3-0ubuntu3~22.04.2
Docker Compose version 2.40.3+ds1-0ubuntu1~22.04.1

5.2 编写 Compose 编排文件

建项目目录并写入 docker-compose.yaml（基于官方 install-manifests 模板，镜像固定 v2.51.1）：

mkdir -p /opt/hasura && cd /opt/hasura
cat > docker-compose.yaml <<'EOF'
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.1
    ports:
      - "8080:8080"
    restart: always
    environment:
      ## 元数据库连接（存储 Hasura 元数据）
      HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
      ## 把同一个 Postgres 作为数据源接入
      PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
      ## 服务端托管 Console
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      ## 开发模式（生产关闭）
      HASURA_GRAPHQL_DEV_MODE: "true"
      HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
    depends_on:
      - postgres

volumes:
  db_data:
EOF

配置说明：postgres 服务用官方 postgres:15 镜像，口令 postgrespassword，数据持久化在命名卷 db_data；graphql-engine 服务固定 v2.51.1 镜像并把 8080 映射到宿主机同名端口；HASURA_GRAPHQL_METADATA_DATABASE_URL 指向同编排内的 postgres 服务（Compose 内置 DNS 按服务名解析）；PG_DATABASE_URL 把同一库作为数据源接入；depends_on 保证先起数据库。与方案 A 不同，此处把元数据库与业务数据源合并为同一个 Postgres 库，这是官方快速上手的默认形态；生产中建议拆分（见六、对比表）。

5.3 启动与验证

cd /opt/hasura && docker compose up -d
docker compose ps

实测回显：

 Container hasura-compose-postgres-1  Started
 Container hasura-compose-graphql-engine-1  Starting
 Container hasura-compose-graphql-engine-1  Started
NAME                              IMAGE                           COMMAND                   SERVICE          CREATED         STATUS         PORTS
hasura-compose-graphql-engine-1   hasura/graphql-engine:v2.51.1   "/bin/sh -c '\"${HGE_…\""   graphql-engine   9 seconds ago   Up 7 seconds   0.0.0.0:8080->8080/tcp
hasura-compose-postgres-1         postgres:15                     "docker-entrypoint.s…"    postgres         10 seconds ago  Up 8 seconds   5432/tcp

引擎启动日志关键行（docker compose logs graphql-engine 实测节选）：

{"detail":{"info":"Successfully initialized the catalog (at version 48).","kind":"catalog_migrate"},"level":"info",...}
{"detail":{"info":{"message":"Starting API server","time_taken":0.274959518},"kind":"server"},"level":"info",...}

API 验证（实测回显，与方案 A 完全一致）：

curl -s -w '|%{http_code}\n' http://localhost:8080/healthz
curl -s http://localhost:8080/v1/version
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/console

OK|200
{"server_type":"ce","version":"v2.51.1"}
200

该方案的表跟踪与 GraphQL 验证命令与 4.6 完全相同（引擎 API 一致），此处不再重复。日常运维命令：docker compose stop/start/restart、docker compose logs -f graphql-engine、docker compose down（加 -v 连数据卷一起删除，慎用）。

六、方案对比与选择建议

两种方案的实测对照如下：

选择建议：Ubuntu 22.04 服务器直接选方案 B；24.04 及以上且要求原生进程、与存量 PostgreSQL 实例统一管理的环境选方案 A。两种方案的引擎配置体系完全相同（HASURA_GRAPHQL_* 环境变量），后续配置调优可无缝切换。

七、配置说明

两种方案的配置载体都是环境变量：方案 A 在 /etc/hasura/env（systemd EnvironmentFile 加载），方案 B 在 docker-compose.yaml 的 environment: 段。常用项速查：

⚠️ 注意：systemd 的 EnvironmentFile 会按 shell 规则剥引号，给 HASURA_GRAPHQL_JWT_SECRET 这类含双引号的 JSON 值必须整体用单引号包裹，否则引擎会报 Invalid JWK: Could not decode PEM 拒绝启动（实测排障实录见 《Hasura 配置参数详解》）。

配置的完整参数表、逐项实测验证方法与生产模板见 《Hasura 配置参数详解》。

八、升级、降级与多版本管理

升级（方案 A）：CDN 只有 latest 通道，升级即重新下载替换并重启，升级前后用 /v1/version 确认版本变化：

systemctl stop hasura
curl -L https://graphql-engine-cdn.hasura.io/server/latest/linux-amd64 -o /usr/local/bin/graphql-engine
chmod +x /usr/local/bin/graphql-engine
systemctl start hasura && sleep 3 && systemctl is-active hasura && curl -s http://127.0.0.1:8080/v1/version

升级（方案 B）：把 docker-compose.yaml 中的镜像 tag 改为目标版本（如 v2.51.1 → 更新版本），然后 docker compose up -d，Compose 会重建引擎服务。引擎启动时会自动执行元数据 catalog 迁移，升级前建议先备份元数据库（pg_dump hasura_metadata）。

降级与多版本管理：官方 CDN 二进制无历史版本可下，方案 A 无法降级；方案 B 可把 tag 固定到任意历史版本实现降级。多版本并存可在同一台服务器上用不同端口跑多个 Compose 项目（每个项目独立编排文件与端口映射），或用不同 tag 的镜像按项目隔离。降级前同样必须先备份元数据库——高版本 catalog 迁移通常不可逆。

九、常见问题（FAQ）

Q1：graphql-engine version 报 libodbc.so.2: cannot open shared object file？ 缺少 unixODBC 运行库（SQL Server 数据源依赖）。执行 apt-get install -y unixodbc 后重试（4.3 实测）。

Q2：报 version 'GLIBC_2.38' not found (required by graphql-engine)？ 官方二进制要求 GLIBC ≥ 2.38，Ubuntu 22.04（2.35）/Debian 12（2.36）不满足。改用 Ubuntu 24.04+（方案 A）或本机 Docker Compose（方案 B），不要尝试替换系统 glibc。

Q3：报 libpq.so.5: cannot open shared object file？ 缺 PostgreSQL 客户端库，执行 apt-get install -y libpq5（4.3 实测，Ubuntu 24.04 验证）。

Q4：启动失败，日志出现 FATAL: password authentication failed for user "postgres"？ /etc/hasura/env 里的连接串口令与数据库实际口令不一致。用 su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'q1w2e3r4';\"" 重设口令，或改正连接串后 systemctl restart hasura。

Q5：systemctl start hasura 后服务反复重启（activating）？ journalctl -u hasura -n 30 查看启动期 Fatal Error。实测中最常见的两类：环境变量 JSON 值被 systemd 剥引号导致解析失败（用单引号整体包裹）；HASURA_GRAPHQL_JWT_SECRET 的 key 字段填了私钥——该字段要求公钥 PEM（openssl rsa -in 私钥 -pubout 导出）。

Q6：带 X-Hasura-Admin-Secret 头查询仍报 field 'products' not found in type: 'query_root'？ 表尚未被 Hasura 跟踪。执行 4.6 的 pg_track_table Metadata 调用，或用 hasura metadata apply 应用项目元数据。

Q7：方案 B 拉取镜像慢或超时？ 为 Docker 守护进程配置 HTTP 代理（systemd drop-in 写入 Environment="HTTPS_PROXY=..." 后 systemctl daemon-reload && systemctl restart docker），或为 docker compose pull 阶段单独配置。

Q8：Console 打不开（404）？ 确认 HASURA_GRAPHQL_ENABLE_CONSOLE=true 且已重启生效；CLI 版 Console（9695 端口）与服务端托管 Console（8080 端口 /console）是两条路径，勿混淆。

十、卸载与清理

方案 A 卸载（Ubuntu 24.04.5 实测回显）：停服并取消自启、删除二进制/单元/环境文件/运行账号、删除元数据库与业务库。

systemctl stop hasura && systemctl disable hasura
rm -f /usr/local/bin/graphql-engine /etc/systemd/system/hasura.service
rm -rf /etc/hasura
userdel hasura
systemctl daemon-reload

Removed "/etc/systemd/system/multi-user.target.wants/hasura.service".

验证清理结果（实测回显）：

which graphql-engine || echo "graphql-engine removed"
systemctl status hasura --no-pager 2>&1 | head -3 | tail -1

graphql-engine removed
Unit hasura.service could not be found.

删除数据库（按需，实测回显）：

su postgres -c 'dropdb hasura_metadata && dropdb hasuradb'
su postgres -c "psql -tAc \"SELECT datname FROM pg_database WHERE datname LIKE 'hasura%'\""

（无输出，库已清除）

方案 B 卸载：docker compose down 删除服务与网络，加 -v 同时删除 db_data 数据卷；如不再使用 Docker，再卸载 docker.io 与 docker-compose-v2 软件包。

十一、参考链接

• 官方仓库：https://github.com/hasura/graphql-engine
• 引擎二进制官方 CDN：https://graphql-engine-cdn.hasura.io/server/latest/linux-amd64
• CLI 发布页（cli/v2.51.1）：https://github.com/hasura/graphql-engine/releases/tag/cli%2Fv2.51.1
• 官方 Docker Compose 安装清单：https://github.com/hasura/graphql-engine/blob/stable/install-manifests/docker-compose/docker-compose.yaml
• 官方文档（v2 环境变量参考）：https://hasura.io/docs/2.x/deployment/config-variable-reference/
• 站内关联：《Hasura v2.51.1 介绍与选型指南》