Havenask 1.2.0 常用 CLI 命令详解

目标：系统梳理 Havenask v1.2.0 单机部署形态下的三类操作入口——hape 编排命令行、sql_query.py 查询脚本、REST API（curl 直连）——覆盖状态查看、集群生命周期、表管理、配置导出、SQL 读写与全文检索全链路，全部命令附真实回显，并沉淀运行用户一致性、validate 拒绝 root、python3 跑 sql_query.py 报错等实测排障结论。全文在 Ubuntu 22.04 + Havenask v1.2.0 环境实测（实测日期 2026-10-23），部署过程见《Ubuntu 22.04 安装 Havenask 1.2.0 指南》。

一、环境信息

项目	值
操作系统	Ubuntu 22.04（宿主机）
Havenask 版本	v1.2.0（官方 Docker 镜像 `registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0`，`--net=host` 运行）
编排工具	hape（镜像内置，`/usr/bin/hape`，Python 2.6/2.7 兼容语法的 click 应用）
SQL 查询脚本	`/ha3_install/sql_query.py`（shebang 为 `#!/usr/bin/python2`）
运行环境进入方式	`havenask-120-runtime/sshme`（内部为 `docker exec --user root -it havenask-120-runtime sh -c 'cd ~ && /bin/bash'`，进入后提示符 `[root@havenask ~]#`）
集群形态	单机伪集群：ZooKeeper + havenask admin/qrs/searcher + swift admin/broker + bs admin，共 7 个容器

单机模式各组件监听端口（hape 全局配置渲染值）：

端口	组件	用途
2181	ZooKeeper	服务注册与配置存储（`zfs://127.0.1.1:2181/havenask/...`）
45700	havenask admin	HTTP：CatalogService/SchedulerService REST
45800	qrs	HTTP：SQL 查询入口 `/QrsService/searchSql`
45801	qrs	arpc 服务端口
45898	searcher	arpc 服务端口
45899	searcher	HTTP 服务端口
45900	searcher	健康检查心跳（`/HeartbeatService/heartbeat`）
45901	searcher	写入链路 gig grpc 端口
11112-11113	swift	broker/topic 端口

二、工具概览

Havenask v1.2.0 的日常操作分三个入口，定位不同：

入口	形态	适用场景	是否需要进入运行环境
hape	运行环境内 CLI	集群生命周期（start/stop/restart/delete）、表管理（create/delete table）、状态查看（gs）、配置导出与更新（get/update/customize）	需要（sshme 进入后执行）
sql_query.py	运行环境内脚本	单条 SQL 的写入/查询调试（本质是向 qrs 发 REST 请求的封装）	需要；也可从能连通 qrs 的任意环境用 python2 执行
REST API	HTTP（curl 即可）	qrs 45800 负责 SQL 执行；admin 45700 负责表结构/目录/系统状态查询；适合程序化集成与远程运维	不需要（`--net=host` 端口直接暴露在宿主机）

三者关系：hape 是唯一能管理容器拓扑与表生命周期的入口；sql_query.py 与 REST API 只操作数据面（SQL 与元数据查询），不碰容器。集群的部署与首次建表流程见安装指南第四、五节。

三、前置条件

已按安装指南完成单机集群部署并进入运行环境（./havenask-120-runtime/sshme）。
hape 必须以部署用户运行。官方 create_container.sh 以 root 部署时会把部署用户的 ssh 凭据带入环境（/root/.ssh/ 含 id_rsa/authorized_keys），hape 在 docker 模式下通过「免密 ssh 到目标机执行 docker 命令」管理容器，因此以 root 进入并执行 hape 是默认可用形态。
宿主机已配置当前部署用户免密 ssh 自登录（安装指南 2.3 节），且该用户具备 docker 命令权限。
hape 每次执行都会先渲染并打印一遍全局配置日志（Rendered hape global config: {...}），后续回显均省略该行。

⚠️ 以非部署用户（如环境内的 admin 用户）执行 hape 的行为差异见常见问题 8.2——gs/validate/restart 会因 ssh 免密链路不可达而失败或误报，实测不要这样用。

四、hape 命令详解

4.1 命令体系总览

hape --help 实测回显：

Usage: hape [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  create     Create table in havenask cluster
  customize  Customize hape config by case
  delete     Delete cluster, will stop processors, and then clean zk &
             database runtime files

  get        get hape config
  gs         Get status of havenask cluster
  prepare    Prepare hape necessary resources
  restart    Restart cluster, will recover service from zookeeper
  start      Start cluster
  stop       Stop cluster. Will only stop containers and not clean zookeeper
             and database files

  update     Update some hape config
  validate   Validate hape env and domain conf

二级子命令速查（均经 --help 实测）：

一级	二级	作用
create	table	建表（指定表名/schema/分区数）
gs	havenask / swift / bs / table	查看检索集群/swift/构建服务/单表状态
start / restart	havenask / swift	启动或重启对应集群
stop	havenask / swift / build / container	停止集群或指定容器（不清理 zk 与数据）
delete	table / havenask / swift / all	删表或删集群（停进程并清理 zk 与数据文件）
get	default-hippo-config	按 role 导出 hippo 进程模板 JSON
update	candidate / hippo-config / load-strategy / offline-table-index / table-schema / template	更新候选机、资源模板、加载策略、离线索引、表结构、hape 模板
customize	—（直接参数）	按模板渲染自定义 hape 配置
prepare	—（直接参数）	准备 hape 所需资源
validate	—（直接参数）	校验环境与域名配置（单机 Docker 形态实测不可用，见 8.3）

4.2 状态查看：gs

hape gs havenask（集群总状态）实测回显（关键字段）：

{
    "hint": "",
    "leaderAddress": "http://127.0.1.1:45700",
    "serviceZk": "zfs://127.0.1.1:2181/havenask/havenask-sql-local/appmaster",
    "hippoZk": "zfs://127.0.1.1:2181/havenask/havenask-sql-local/hippo",
    "clusterStatus": "READY",
    "sqlClusterInfo": {
        "admin": [
            {
                "containerName": "havenask-sql-local_appmaster",
                "containerStatus": "RUNNING",
                "ip": "127.0.1.1",
                "processorName": "suez_admin_worker",
                "role": "admin",
                "processorStatus": "RUNNING"
            }
        ],
        "qrs": { "qrs_partition_0": [ { "...": "processorName: ha_sql, workerStatus: WS_READY" } ] },
        "database": { "database_partition_0": [ { "...": "processorName: ha_sql, workerStatus: WS_READY" } ] }
    }
}

clusterStatus: READY 且各 role 的 processorStatus 为 RUNNING、workerStatus 为 WS_READY 即集群健康。启动后若显示 NOT_READY，hint 字段会给出原因（如建表前 Group database Role database_partition_0 has unready containers... 属正常等待，约 1 分钟内转 READY）。

hape gs swift 实测回显（processors 数组节选）：

{
    "leaderAddress": "http://127.0.1.1:59582",
    "serviceZk": "zfs://127.0.1.1:2181/havenask/havenask-swift-local/appmaster",
    "processors": [
        { "containerName": "havenask-swift-local_appmaster", "processorName": "swift_admin", "role": "admin", "processorStatus": "RUNNING" },
        { "containerName": "havenask_container_root_havenask-swift-local_0", "processorName": "swift_broker", "role": "default##broker_0_0", "processorStatus": "RUNNING" }
    ],
    "hippoZk": "zfs://127.0.1.1:2181/havenask/havenask-swift-local/hippo"
}

hape gs bs 回显结构同上，processors 中是 bs_admin_worker（构建服务 admin，离线全量构建场景使用，直连表不依赖它）。

hape gs table -t in0（单表状态）以部署用户 root 执行，实测 2.4 秒返回：

$ time hape gs table -t in0
{
    "in0": {
        "status": "READY"
    }
}

real    0m2.43s

4.3 表管理：create / delete table

建表 hape create table 帮助与参数（实测）：

Usage: hape create table [OPTIONS]

Options:
  -c, --config TEXT        Path of hape config. Will use default if not specified
  -v, --verbose            Enable debug level logging
  -t, --table TEXT         Table name  [required]
  -p, --partition INTEGER  Partition count of table
  -s, --schema TEXT        Schema file path of table  [required]
  -f, --full TEXT          Full data path for offline table (not needed by direct table)

schema 文件的索引字段结构使用 snake_case（index_type/index_config/index_fields/field_name），与 REST API 回显的 camelCase（indexType/indexConfig）不同；写成 camelCase 会触发 KeyError: 'index_type'/KeyError: 'index_config'。完整建表过程与 schema 实例见安装指南 5.1 节。

删表 hape delete table -t in1 实测回显（节选）：

[2026-10-23 19:16:47,590] [INFO] [catalog_service.py:__init__:15]: Visit catalog service in address http://127.0.1.1:45700
[2026-10-23 19:16:47,769] [INFO] [domain.py:delete_table:184]: Succeed to delete table
[2026-10-23 19:16:47,770] [INFO] [domain.py:delete_table:185]: Before continue to read & write tables, please confirm havenask cluster ready by using gs havenask subcommand

删表后经 admin REST 复核，CatalogService/listTable 的 tableNames 由 ["in0","in1"] 变回 ["in0"]。注意 --keeptopic 选项可保留 swift topic；默认会把该表的 swift topic 一并删除（hape delete all 回显中可见 Delete swift topic in0 字样）。

hape update table-schema 用于更新已建表结构（离线表场景，要求提供全量数据路径与消费时间戳）：

Usage: hape update table-schema [OPTIONS]

Options:
  -t, --table TEXT         Table name  [required]
  -p, --partition INTEGER  Partition count of table
  -s, --schema TEXT        Schema file path of table  [required]
  -f, --full TEXT          Full data path for offline table  [required]
  --timestamp INTEGER      After full index loaded, havenask will consume this
                           realtime message from this timestamp  [required]

4.4 配置导出与更新：get / update

hape get default-hippo-config -r searcher 导出 searcher 角色的 hippo 进程模板（共 294 行 JSON），关键结构实测节选：

{
    "role_desc": {
        "count": 1,
        "healthCheckerConfig": {
            "args": [
                { "value": "45900", "key": "PORT" },
                { "value": "/HeartbeatService/heartbeat", "key": "CHECK_PATH" }
            ],
            "name": "adv_lv7"
        },
        "containerConfigs": [
            "BIND_MOUNTS=(/home/admin/${appName}_${roleName}:/home/admin)",
            "WORKING_DIRS=(ha_sql:/home/admin/)"
        ],
        "processInfos": [
            {
                "cmd": "ha_sql",
                "args": [
                    { "value": "/ha3_install", "key": "-r" },
                    { "value": "arpc:45898", "key": "--port" },
                    { "value": "http:45899", "key": "--port" },
                    { "value": "httpPort=45900", "key": "..." }
                ]
            }
        ]
    }
}

该输出即进程级配置的「当前生效值」来源：健康检查端口/路径、容器挂载、ha_sql 启动参数（arpc 45898、http 45899、心跳 45900）一目了然，-r qrs 可导出 qrs 角色模板做对照。修改方法与资源参数逐项含义见《Havenask 1.2.0 配置参数详解》5.3 节。

hape update hippo-config（把改过的模板推回集群）参数实测：

Options:
  -p, --hippo_config_path TEXT  hippo config file for role  [required]
  -r, --role_type TEXT          role type, [searcher|qrs]  [required]

update 家族其余子命令（candidate/load-strategy/offline-table-index/template）参数详见各自 --help，其中 update candidate 维护 workerCandidateMap 候选机列表，update template 会重启 havenask admin 使模板生效。

4.5 集群生命周期：start / stop / restart / delete

命令	行为（官方 --help 描述 + 实测）
`hape start havenask` / `hape start swift`	拉起对应集群的 appmaster 与 worker 容器
`hape stop havenask` / `hape stop swift`	只停容器，不清理 ZooKeeper 与数据文件（重新 start 即恢复）
`hape stop build -t <表> -g <generation>`	停止指定代的离线构建
`hape stop container -i <ip> -n <name>`	停止指定容器（单容器粒度运维）
`hape restart havenask` / `hape restart swift`	基于 ZooKeeper 中的注册信息恢复服务；以部署用户执行实测可用（回显见安装指南 8.1 节），swift 卡死时的修复用法见安装指南 9.3 节
`hape delete table -t <表>`	删表并删除 swift topic（见 4.3）
`hape delete havenask` / `hape delete swift`	删除对应集群：停进程并清理 zk 与运行时数据文件
`hape delete all`	一次性删除全部（havenask + swift + bs）

hape delete all 完整实测回显（省略配置渲染行，按时间顺序停掉全部 6 个兄弟容器）：

[2026-10-23 19:24:37,307] [INFO] [domain.py:stop:84]: Delete swift topic in0
[2026-10-23 19:24:37,482] [INFO] [docker_appmaster.py:stop:61]: Starts to stop appmaster
[2026-10-23 19:24:37,483] [INFO] [docker_util.py:stop_container:124]: Stop container havenask-sql-local_appmaster in 127.0.1.1
[2026-10-23 19:24:37,875] [INFO] [docker_appmaster.py:stop:66]: Starts to stop worker
[2026-10-23 19:24:37,880] [INFO] [docker_util.py:stop_container:124]: Stop container havenask_container_havenask-sql-local_0 in 127.0.1.1
[2026-10-23 19:24:38,327] [INFO] [docker_util.py:stop_container:124]: Stop container havenask_container_havenask-sql-local_1 in 127.0.1.1
[2026-10-23 19:24:38,841] [INFO] [docker_appmaster.py:stop:61]: Starts to stop appmaster
[2026-10-23 19:24:38,842] [INFO] [docker_util.py:stop_container:124]: Stop container havenask-bs-local_appmaster in 127.0.1.1
[2026-10-23 19:24:39,243] [INFO] [docker_appmaster.py:stop:66]: Starts to stop worker
[2026-10-23 19:24:39,276] [INFO] [docker_appmaster.py:stop:61]: Starts to stop appmaster
[2026-10-23 19:24:39,276] [INFO] [docker_util.py:stop_container:124]: Stop container havenask-swift-local_appmaster in 127.0.1.1
[2026-10-23 19:24:39,693] [INFO] [docker_appmaster.py:stop:66]: Starts to stop worker
[2026-10-23 19:24:39,701] [INFO] [docker_util.py:stop_container:124]: Stop container havenask_container_root_havenask-swift-local_0 in 127.0.1.1

执行后 docker ps 实测仅剩运行环境本体容器（havenask-120-runtime）。彻底卸载还需执行运行环境目录下的 stopContainer.sh 并按需删除镜像，完整序列见安装指南第十节。

4.6 环境校验与其他：validate / prepare / customize

hape validate：校验环境与域名配置。单机 Docker 形态实测不可用：以 root 运行被拒绝（RuntimeError: account:root is not supported, please use anothor acount），以 admin 等其他用户运行则卡在 ssh 免密检查报 Permission denied (publickey,password)（两者回显见 8.3）。环境健康以 hape gs havenask 与实际读写验证为准。
hape prepare -c <配置路径>：按配置准备 hape 所需资源（默认配置可不带 -c）。
hape customize -t <模板路径> -i <镜像>：以指定模板与镜像渲染出自定义 hape 配置，用于多机/自定义镜像场景。

五、sql_query.py 详解

5.1 用法与默认行为

sql_query.py --help 实测回显：

Usage: sql_query.py [OPTIONS]

Options:
  --address TEXT  address of qrs (http://ip:port)
  --query TEXT    sql query  [required]
  --help          Show this message and exit.

默认 qrs 地址 http://127.0.0.1:45800。当 query 中不含 kvpair 时，脚本自动追加 &&kvpair=databaseName:database;formatType:string（源码逻辑，实测回显中的 Request address 行可见拼接结果）。

查询实测：

$ /ha3_install/sql_query.py --query "select id,hits from in0 where id=4"
Request address:[http://127.0.0.1:45800/QrsService/searchSql] query:[select id,hits from in0 where id=4&&kvpair=databaseName:database;formatType:string]
USE_TIME: 11.594ms, ROW_COUNT: 1, HAS_SOFT_FAILURE: 0, SOFT_FAILURE_CODES: [], COVERAGE: 1

------------------------------- TABLE INFO ---------------------------
total:1, rows:[0, 1), cols:2
                 id (uint32) |               hits (uint32) |
                           4 |                           2 |

显式指定地址（跨机或非默认端口时）实测可用：

$ /ha3_install/sql_query.py --address http://127.0.1.1:45800 --query "select count(*) from in0"
Request address:[http://127.0.1.1:45800/QrsService/searchSql] query:[select count(*) from in0&&kvpair=databaseName:database;formatType:string]
USE_TIME: 2.437ms, ROW_COUNT: 1, HAS_SOFT_FAILURE: 0, SOFT_FAILURE_CODES: [], COVERAGE: 1

5.2 必须直接执行：python3 调用会报错

脚本 shebang 为 #!/usr/bin/python2。若显式用 python3 执行，会在 requests 内部 JSON 序列化阶段报错（实测回显）：

$ python3 /ha3_install/sql_query.py --query "select id,hits from in0 where id=4"
TypeError: Object of type 'bytes' is not JSON serializable

原因（源码定位）：脚本先把 query encode("utf-8") 成 bytes，再以 requests.post(address, json=data) 发送；Python 2 中 str 即 bytes 可正常序列化，Python 3 的 json 不接受 bytes，因此报 TypeError。结论：直接 /ha3_install/sql_query.py --query "..." 执行（走 shebang 的 python2），不要用 python3 调用。

5.3 SQL 方言要点

写入：insert into in0 (createtime,hits,id,title,subject)values(1,2,4,'test','test')，返回 ROW_COUNT: 1 即成功（实测回显见安装指南 5.2 节）。
全文检索：全文条件使用 query('default','词')，例如 select id,hits from in0 where query('default','test')；match() 函数在该版本报语法错误。default 是 schema 中 PACK 组合索引名，标题/正文的 boost 权重在 schema 中定义。
TEXT 列在 SQL 字符串结果中显示 null（展示层行为，全文命中不受影响），ATTRIBUTE 列正常返回——实测结论与规避见安装指南 9.4 节。
列数必须与值数一致，否则报错（实测）：Number of INSERT target columns (4) does not equal number of source items (5)。

六、REST API 详解

--net=host 形态下 REST 端口直接暴露在宿主机，curl 即可完成数据面全链路操作，无需进入运行环境。

6.1 qrs：SQL 执行（45800）

统一入口 POST http://127.0.1.1:45800/QrsService/searchSql，body 为 <SQL>&&kvpair=databaseName:database;formatType:string|json。

写入（实测）：

$ curl -s -X POST http://127.0.1.1:45800/QrsService/searchSql \
    -H 'Content-Type: application/json' \
    -d "insert into in0 (id,title,subject,hits,createtime) values (100,'rest-doc','via-curl-rest',3,20261023)&&kvpair=databaseName:database;formatType:string|json"
USE_TIME: 38.691ms, ROW_COUNT: 1, HAS_SOFT_FAILURE: 0, SOFT_FAILURE_CODES: [], COVERAGE: 1
BUILD_WATERMARK: in0:1792753842940411;

------------------------------- TABLE INFO ---------------------------
total:1, rows:[0, 1), cols:1
            ROWCOUNT (int64) |
                           1 |

查询（formatType:string|json，实测）：

$ curl -s -X POST http://127.0.1.1:45800/QrsService/searchSql \
    -H 'Content-Type: application/json' \
    -d "select id,title,subject,hits from in0 where id=100&&kvpair=databaseName:database;formatType:string|json"
USE_TIME: 54.632ms, ROW_COUNT: 1, HAS_SOFT_FAILURE: 0, SOFT_FAILURE_CODES: [], COVERAGE: 1

------------------------------- TABLE INFO ---------------------------
total:1, rows:[0, 1), cols:4
                 id (uint32) |          title (multi_char) |        subject (multi_char) |               hits (uint32) |
                         100 |                        null |                        null |                           3 |

查询（省略 formatType 默认返回 JSON，适合程序解析，实测）：

$ curl -s -X POST http://127.0.1.1:45800/QrsService/searchSql \
    -H 'Content-Type: application/json' \
    -d "select id,hits from in0 where id=100&&kvpair=databaseName:database"
{"total_time":17.754,"has_soft_failure":false,"soft_failure_codes":[],"covered_percent":1.0,
 "row_count":1,"format_type":"json","search_info":{},"rpc_info":"","table_leader_info":{},
 "table_build_watermark":{},
 "sql_query":"select id,hits from in0 where id=100&&kvpair=databaseName:database",
 "iquan_plan":{"error_code":0,"error_message":"","result":{"rel_plan_version":"","rel_plan":[],"exec_params":{}}},
 "navi_graph":"","trace":[],
 "sql_result":"{\"data\":[[100,3]],\"column_name\":[\"id\",\"hits\"],\"column_type\":[\"uint32\",\"uint32\"]}",
 "error_info":"{\n\"errorCode\": 0,\n\"errorMsg\": ERROR_NONE\n}\n"}

结果数据在 sql_result 字段内（JSON 字符串，二次解析即可拿到 data/column_name/column_type）。

全文检索（实测，2.2 万微秒级响应）：

$ curl -s -X POST http://127.0.1.1:45800/QrsService/searchSql \
    -H 'Content-Type: application/json' \
    -d "select id,hits from in0 where query('default','test')&&kvpair=databaseName:database;formatType:string|json"
USE_TIME: 18.704ms, ROW_COUNT: 1, ...
                 id (uint32) |               hits (uint32) |
                           4 |                           2 |

实测提示：实时写入后立即查询可能返回 0 行（构建链路尚在处理），等待数秒重查即可见（实测 4 秒后可见）。

6.2 admin：目录与表结构（45700）

CatalogService 系列端点均为 POST + JSON body，实测可用端点：

端点	请求体	返回关键字段
`/CatalogService/listCatalog`	`{}`	`catalogNames`（实测 `["catalog"]`）
`/CatalogService/listTable`	`{"catalogName":"catalog","databaseName":"database"}`	`tableNames`（实测 `["in0"]`）
`/CatalogService/getTable`	`{"catalogName":"catalog","databaseName":"database","tableName":"in0"}`	`table.tableStructure`：columns（含 type/analyzer）与 indexes（五类索引全结构）
`/CatalogService/getDatabase`	`{"catalogName":"catalog","databaseName":"database"}`	database 对象：version/status/tables 内嵌各表结构

getTable 回显节选（与建表 schema 对应，注意 REST 侧是 camelCase）：

"columns":[{"name":"title","type":"TEXT","analyzer":"simple_analyzer"},
           {"name":"subject","type":"TEXT","analyzer":"simple_analyzer"},
           {"name":"id","type":"UINT32"},{"name":"hits","type":"UINT32"},
           {"name":"createtime","type":"UINT64"}],
"indexes":[{"name":"id","indexType":"PRIMARY_KEY64",...},
           {"name":"id","indexType":"ATTRIBUTE",...},
           {"name":"title","indexType":"TEXT",...},
           {"name":"default","indexType":"PACK","indexConfig":{"indexFields":[{"fieldName":"title","boost":100},{"fieldName":"subject","boost":200}]}},
           {"name":"summary","indexType":"SUMMARY",...}]

关于建表/删表的 REST 化（实测结论）：

/CatalogService/createTable 端点存在（缺参数时返回 {"status":{"code":"INVALID_ARGUMENTS","message":"catalog_name is not specified"}}），但其请求体是 hape 内部拼装的 protobuf JSON（含 swift 数据源描述、模板 md5 等），手工构造不现实——建表走 hape CLI 是官方支持路径。
/CatalogService/deleteTable 无此端点（实测返回 service or method not found for /CatalogService/deleteTable）——删表只能走 hape delete table。

6.3 admin：系统状态（45700）

POST /SchedulerService/getSystemInfo（body {}）返回 systemInfoStr 字符串，内容为各 role 分区的实例健康状态（healthStatus: HT_ALIVE、ip、实例角色等），可用于监控集成：

{"systemInfoStr":"{\n\"database\":\n  {\n  \"groupStatus\":\n    0,\n  \"roleStatuses\":\n    {\n    \"database_partition_0\":\n      {\n      \"adjustedCount\":\n        0,\n      ...\"healthStatus\":\n              \"HT_ALIVE\",\n            \"ip\":\n              \"127.0.1.1\",...}

七、注意事项

运行用户一致性：hape 的 gs/validate/restart/delete all 等命令依赖「当前用户免密 ssh 到目标机执行 docker 命令」，必须以 create_container.sh 的部署用户（实测环境为 root，凭据已随初始化带入环境）执行；换用户执行会产生 8.2 节的各种误报。表级操作（create/delete table）与 REST 不受用户影响。
delete 不可逆：hape delete table/all 会清理 ZooKeeper 注册信息与运行时数据文件并删除 swift topic，执行前确认数据已持久化（实时写入未构建全量索引的数据会丢失，见安装指南 8.1 节结论）。
stop 与 delete 的区别：stop 只停容器保留 zk 与数据（可 start 恢复）；delete 连数据文件一起清理。
每条 hape 命令都会先打印配置渲染日志（Rendered hape global config: {...}，数十行），解析输出时按 [INFO] 行过滤即可。
sql_query.py 与 REST 的 kvpair 中 databaseName:database 对应默认库名；自建多库场景需对应调整。
端口规划与宿主机占用检查（ss 命令）见安装指南 5.4 节。

八、常见问题（排障实录）

8.1 python3 执行 sql_query.py 报 `Object of type 'bytes' is not JSON serializable`

现象：python3 /ha3_install/sql_query.py --query "..." 报 TypeError。定位：脚本 shebang 为 python2，且源码中 query 被 encode 成 bytes 后传入 requests.post(json=...)，Python 3 的 json 不支持 bytes。解决：直接 /ha3_install/sql_query.py --query "..." 执行；或自写 python3 脚本直接调 REST（query 保持 str 不 encode）。

8.2 以 admin 用户执行 hape 出现 NOT_READY / Permission denied

现象（三类，均实测）：

hape gs havenask 输出 clusterStatus: NOT_READY，hint 为 Group database Role database_partition_0 has no containers, maybe lack of candidate nodes，各 role 数组为空；
hape gs table -t in0 长时间挂起（实测 4m14s）后输出 "in0": {"status": "NOT_READY"}，-v 日志可见重试：Check [qrs achieve target replicas] not succeed by now, retry 8/50, wait up to 250 seconds，且每次伴随 admin@127.0.1.1: Permission denied (publickey,password)；
hape restart havenask 直接抛 RuntimeError: Cannot execute ssh command in ip 127.0.1.1 ... Permission denied (publickey,password)。

定位：hape 的 docker 模式通过「当前用户免密 ssh 目标机执行 docker 命令」获取容器视图与执行容器操作；admin 用户无宿主机免密凭据，容器视图被判定为空，进而误报 NOT_READY（数据面此时完全正常，SQL 读写实测不受影响）。解决：以部署用户（root）重新进入环境执行（sshme 脚本本身即 --user root）。验证：root 下 hape gs havenask 立即返回 READY，hape gs table -t in0 实测 2.4 秒输出 READY，restart/delete all 均正常。

8.3 hape validate 在单机 Docker 形态不可用

现象：以 root 运行报 RuntimeError: account:root is not supported, please use anothor acount（validate 显式拒绝 root）；以 admin 等其他用户运行则在 docker 模式容器检查步骤报 Cannot execute ssh command in ip 127.0.1.1 ... Permission denied。结论：validate 面向的是具备非 root 部署用户且 ssh 免密链路完整的场景；官方 create_container.sh 单机流程中该命令实际不可用，环境校验以 hape gs havenask（READY）加一次 insert/select 冒烟为准。

8.4 REST insert 报 `Number of INSERT target columns (4) does not equal number of source items (5)`

现象：insert 的列清单与 values 个数不一致时，返回 ROW_COUNT: 0 并附上述错误（实测 4 列 5 值触发）。解决：列数与值数一一对齐；TEXT 值用单引号。

8.5 实时写入后马上查询查不到

现象：insert 返回 ROW_COUNT: 1 后立即 select 该行返回 0 行（实测 in1 表复现）。结论：实时数据经 swift→searcher 构建链路可见性有秒级延迟，等待数秒重查即可；应用侧建议写入后轮询而非同步读。

九、参考链接

官方仓库：https://github.com/alibaba/havenask（v1.2.0，2026-10-23 查询）
官方快速上手（README Quick Start）：https://github.com/alibaba/havenask#quick-start
站内同族文档：《Ubuntu 22.04 安装 Havenask 1.2.0 指南》（部署全流程与安装侧排障）、《Havenask 1.2.0 配置参数详解》（参数级配置与资源模板）、《Havenask 介绍与选型指南》（选型定位与同类对比）
同类引擎站内参考：《Elasticsearch 9.5.5 介绍与选型指南》《OpenSearch 3.9 介绍与选型指南》

Havenask 1.2.0 常用 CLI 命令详解

Havenask 1.2.0 常用 CLI 命令详解

一、环境信息

二、工具概览

三、前置条件

四、hape 命令详解

4.1 命令体系总览

4.2 状态查看：gs

4.3 表管理：create / delete table

4.4 配置导出与更新：get / update

4.5 集群生命周期：start / stop / restart / delete

4.6 环境校验与其他：validate / prepare / customize

五、sql_query.py 详解

5.1 用法与默认行为

5.2 必须直接执行：python3 调用会报错

5.3 SQL 方言要点

六、REST API 详解

6.1 qrs：SQL 执行（45800）

6.2 admin：目录与表结构（45700）

6.3 admin：系统状态（45700）

七、注意事项

八、常见问题（排障实录）

8.1 python3 执行 sql_query.py 报 Object of type 'bytes' is not JSON serializable

8.2 以 admin 用户执行 hape 出现 NOT_READY / Permission denied

8.3 hape validate 在单机 Docker 形态不可用

8.4 REST insert 报 Number of INSERT target columns (4) does not equal number of source items (5)

8.5 实时写入后马上查询查不到

九、参考链接

8.1 python3 执行 sql_query.py 报 `Object of type 'bytes' is not JSON serializable`

8.4 REST insert 报 `Number of INSERT target columns (4) does not equal number of source items (5)`