Havenask 1.2.0 配置参数详解

Havenask v1.2.0 配置参数逐项详解：hape 全局配置/端口拓扑/资源配额/表 schema 五类索引/分词器/向量索引/表处理链/swift 与 ZooKeeper，附实测内存 RSS 与 16GB 单机生产模板。

Havenask搜索引擎数据库2026/10/23

Havenask 1.2.0 配置参数详解

目标：系统讲解 Havenask v1.2.0 单机部署形态下的全部关键配置参数——hape 全局配置、集群拓扑与端口、进程资源配额、表 schema 与索引、分词器、向量索引、表处理链、swift/ZooKeeper 参数——每类参数给出配置文件位置、逐项含义、默认值与修改方法，并附实测资源占用对照与生产推荐模板。全部内容在 Ubuntu 22.04 + Havenask v1.2.0 单机集群实测（实测日期 2026-10-23）。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Havenask 版本：v1.2.0（官方最新稳定版）
  • 部署形态：官方 ha3_runtime 镜像 + hape 单机伪集群（部署过程见《Ubuntu 22.04 安装 Havenask 1.2.0 指南》）
  • 配置根目录：/ha3_install/hape_conf/default/
  • 数据存储根：/root/havenask/havenask_data_store/
  • 实测内存占用（进程级 RSS）：searcher 1545MB、QRS 1094MB、swift_broker 15MB、ZooKeeper 250MB（限制堆 512MB 后）

二、前置条件

按官方脚本完成部署并确认集群 READY（若尚未部署，先完成安装篇第四、五章）：

/ha3_install/hape gs havenask | grep clusterStatus
ss -ltn | grep -E ':(2181|45700|45800|45801|4589[89]|45900|45901)\b' | head -5

实测回显：

    "clusterStatus": "READY",
LISTEN 0      256          0.0.0.0:45700      0.0.0.0:*
LISTEN 0      256          0.0.0.0:45800      0.0.0.0:*
LISTEN 0      256          0.0.0.0:45900      0.0.0.0:*
LISTEN 0      256          0.0.0.0:45898      0.0.0.0:*
LISTEN 0      50                 *:2181             *:*

三、参数查看与修改方式

Havenask 开源版的配置分三层，先分清层再谈参数：

层位置生效方式
hape 全局配置/ha3_install/hape_conf/default/global.confhape start 启动时渲染生效
角色 hippo 模板/ha3_install/hape_conf/default/cluster_templates/hippo/*.json集群启动/重启时按模板拉起进程
表级配置schema JSON（建表时传入）+ cluster_templates/direct_table/ 表模板hape create table 时下发

三种查看途径（均已实测）：

  1. 看渲染后的生效配置：hape start havenask 日志第一段会打印 Rendered hape global config: {...}，这是唯一包含全部变量替换后实值的视图；
  2. 看集群运行状态：hape gs havenask / hape gs swift / hape gs table -t <表名>；
  3. 看原始模板：cat /ha3_install/hape_conf/default/global.conf 等（模板内 {{ 变量 }} 占位符未渲染）。

修改方式与生效规则（--help 实测回显）：

$ /ha3_install/hape update --help
Commands:
  candidate            Update hape candidate iplist
  hippo-config         Update hippo config
  load-strategy        Update load config
  offline-table-index  Update offline table index
  table-schema         Update table schema
  template             Update hape template, will restart havenask admin
  • 改 global.conf（服务名/镜像/dataStoreRoot/资源默认值）：改完需重建集群（hape delete all → hape start havenask）；
  • 改角色资源/进程参数：hape update hippo-config -r <searcher|qrs> -p <模板文件>，然后重启对应集群；
  • 改表 schema：hape update table-schema -t <表名> -s <schema 文件>（结构变更走 catalog 版本化发布）；
  • 建表时的 schema：建表即生效，改表结构用 update table-schema 或删表重建。

四、参数总览

分类配置文件核心参数默认值（实测）
hape 全局global.confbinaryPath / dataStoreRoot / serviceName / image / adminCpu / adminMem/ha3_install、~/havenask/havenask_data_store、havenask-sql-local、ha3_runtime:1.2.0、100、5124
拓扑与端口global.conf + hippo 模板qrsHttpPort / adminHttpPort / searcherReplicaCount / qrsReplicaCount / searcher 端口组45800 / 45700 / 1 / 1 / 45898-45901
资源配额hippo 模板searcher/qrs cpu / mem、adminCpu / adminMem200(=2核) / 10240(=10GB)、100 / 5124
表 schema建表 schema JSONcolumns.type、indexes.index_type（5 类）官方 normal 示例
分词器analyzer.jsonsimple_analyzer / singlews_analyzer / jieba_analyzersimple_analyzer（空格分词）
向量索引schema JSONaitheta2_indexer / Qc / dimension / distance_type维度 128、SquaredEuclidean
表处理链default_table.jsonprocessor_queue_size / processor_thread_num / use_v2_index2000 / 10 / true
swiftswift.confbroker_count / admin_count / bind_port1 / 1 / 11112、11113
ZooKeeperstart.shjava 堆参数未设置（默认宿主内存 1/4）

五、核心参数分类详解

5.1 hape 全局参数（global.conf）

文件位置：/ha3_install/hape_conf/default/global.conf，实测原文：

[common]
binaryPath=/ha3_install
# domainZkRoot=zfs://${default_variables.local_host}:2181/havenask
dataStoreRoot={{ default_variables.user_home }}/havenask/havenask_data_store

[swift]
serviceName=havenask-swift-local
image=registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0
adminCpu=100
adminMem=5124

[havenask]
serviceName=havenask-sql-local
image=registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0
adminCpu=100
adminMem=5124

[bs]
serviceName=havenask-bs-local
image=registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0
adminCpu=100
adminMem=5124

逐项说明：

参数含义默认值修改影响
binaryPath引擎安装根目录，进程以它为 -r 根/ha3_install一般不改；自定义安装位置时同步改
dataStoreRoot索引/元数据/部署配置的存储根~/havenask/havenask_data_store改这里可把数据盘指到大容量分区；多版本共存时按版本隔离
serviceName各子集群在 ZooKeeper 上的服务名havenask-sql-local / havenask-swift-local / havenask-bs-local单机多套集群并存时改名隔离
imageworker 进程使用的镜像ha3_runtime:1.2.0升级版本即改此值
adminCpuadmin 进程 CPU 配额（单位：百分之一核）100（=1 核）admin 为控制面，一般无需调大
adminMemadmin 进程内存配额（MB）5124表多/分区多时适当上调

启动时渲染后的完整生效配置（hape start havenask 日志节选，关键字段注释为笔者实测说明）：

Rendered hape global config: {'default_variables': ..., 'havenask': {
  'qrsHttpPort': 45800,                       # QRS SQL 查询 HTTP 端口
  'searcherIpList': ['127.0.1.1'],            # searcher 候选机列表（单机=本机回环）
  'adminIpList': ['127.0.1.1'],               # admin 候选机列表
  'qrsIpList': ['127.0.1.1'],                 # qrs 候选机列表
  'adminCpu': '100', 'adminMem': '5124',
  'image': 'registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0',
  'serviceZkAddr': 'zfs://127.0.1.1:2181/havenask/havenask-sql-local',
  'suezClusterStoreRoot': '/root/havenask/havenask_data_store/suez_cluster_store',
  'serviceName': 'havenask-sql-local',
  'searcherReplicaCount': 1,                  # searcher 副本数
  'adminHttpPort': 45700,                     # admin 管理面 HTTP 端口
  'qrsReplicaCount': 1,                       # qrs 副本数 },
 'swift': { 'brokerCount': 1, ... },
 'common': { 'domainZkRoot': 'zfs://127.0.1.1:2181/havenask',
  'processorMode': 'docker',                  # worker 进程以独立容器进程形态运行
  'javaHome': '/opt/taobao/java',             # 内置 JDK（bs/离线链路使用）
  'binaryPath': '/ha3_install',
  'catalogName': 'catalog', ... },
 'bs': { 'serviceName': 'havenask-bs-local', ... }}

5.2 集群拓扑与端口参数

参数位置默认值说明（实测）
qrsHttpPortglobal.conf [havenask]45800SQL 查询唯一入口（/QrsService/searchSql），对业务暴露
adminHttpPortglobal.conf45700管理面（CatalogService/SchedulerService REST）
searcher 端口组searcher_hippo.jsonarpc 45898 / http 45899 / 心跳 45900 / 写入 45901心跳健康检查路径固定 /HeartbeatService/heartbeat
searcherIpList / qrsIpList / adminIpListglobal.conf127.0.1.1候选机列表；分布式部署时改为真实节点 IP 列表
searcherReplicaCount / qrsReplicaCountglobal.conf1 / 1副本数；-p 1 建表的分区数决定 database_partition 数量
ZooKeeperstart.sh 参数2181hape 测试实例；生产可自建 zk 并填 domainZkRoot

💡 技术拓展：搜索引擎的“分区 × 副本”两层拓扑在各产品中叫法不同。Havenask 中，-p N 把一张表切成 N 个 database_partition（数据分片，各分片承载全量数据的一个哈希区间，实测 schema 中默认区间 0_65535）；searcherReplicaCount 是每个分片的副本数（查询容灾与吞吐扩展）。这与 Elasticsearch 的 shard/replica、Manticore 的局部/全局表概念对应：分片扩查询与存储上限，副本扩读可用性。

5.3 资源参数（hippo 角色模板）

文件位置：/ha3_install/hape_conf/default/cluster_templates/hippo/searcher_hippo.json 与 qrs_hippo.json。两者资源段一致，实测：

"resources": [
    {
        "resources": [
            { "amount": 200,   "name": "cpu", "type": "SCALAR" },
            { "amount": 10240, "name": "mem", "type": "SCALAR" },
            { "amount": 0,     "name": "searcher", "type": "TEXT" },
            { "amount": 0,     "name": "havenask-sql-local:searcher", "type": "EXCLUSIVE" }
        ]
    }
]

逐项说明：

参数默认值含义
cpu amount200配额单位是“百分之一核”，200 = 2 核
mem amount10240单位 MB，10GB；这是调度配额上限，不是预分配
TEXT 资源位0角色标签资源，用于集群内资源记账
EXCLUSIVE 资源服务名:角色独占标记，防止同角色进程挤同机（分布式场景生效）

健康检查参数（searcher/qrs 一致）：

"healthCheckerConfig": {
    "args": [ { "key": "PORT", "value": "45900" },
              { "key": "CHECK_PATH", "value": "/HeartbeatService/heartbeat" } ],
    "name": "adv_lv7"
}

实测进程内存对照（单机空载+1 表 2 行数据的真实 RSS）：

进程hippo 配额实测 RSS
searcher（ha_sql）2 核 / 10GB1545MB
QRS（ha_sql）2 核 / 10GB1094MB
swift_broker—15MB
ZooKeeper（java）—250MB（堆限 512MB 后）

结论：单机最小可跑内存约 3GB（含 admin），配额默认值面向生产余量设计；内存紧张的小规格机器可把 mem 降到 4096，但需保证索引全部加载后的峰值（hape gs 不再转 READY 即是配额不足的信号）。

修改方式（实测 --help）：

$ /ha3_install/hape update hippo-config --help
Options:
  -p, --hippo_config_path TEXT  hippo config file for role  [required]
  -r, --role_type TEXT          role type, [searcher|qrs]  [required]

即：先改 searcher_hippo.json 中的 resources 段，再执行 hape update hippo-config -r searcher -p /ha3_install/hape_conf/default/cluster_templates/hippo/searcher_hippo.json，随后重启集群生效。

5.4 表 schema 参数（columns + indexes）

schema 以 JSON 文件随 hape create table -s <文件> 传入。官方 normal 示例 /ha3_install/example/cases/normal/in0_schema.json 结构分两段：columns（字段）与 indexes（索引）。

columns 字段类型（实测可用取值）：

类型示例字段说明
TEXTtitle、subject全文检索字段，必须搭配 analyzer 与 TEXT/PACK 索引；SQL 投影中显示 null（实测）
UINT32id、hits无符号整型，可作 ATTRIBUTE 过滤/排序
UINT64createtime时间戳常用类型
STRINGurl、pk（llm/vector 示例）变长字符串
RAWDUP_vector、DUP_pk原样存储列（配合 DupFieldProcessor 做字段复制）

字段级可选参数：analyzer（TEXT 字段指定分词器名，默认 simple_analyzer）。

indexes 索引类型（5 类，实测默认示例全部包含）：

index_type示例中的用途要点
PRIMARY_KEY64id主键索引，64 位主键，支持按主键实时增删改
ATTRIBUTEid、hits、createtime属性索引，正排列存，SQL where/order by 的执行基础
TEXTtitle、subject单字段全文索引
PACKdefault打包复合索引，把 title(boost 100)+subject(boost 200) 打进一个 default 索引，全文检索 query('default','词') 的对象；boost 决定字段权重
SUMMARYsummary摘要索引，定义 select * 能回原的字段集合

PACK 索引原文（节选）：

{
    "name": "default",
    "index_type": "PACK",
    "index_config": {
        "index_fields": [
            { "field_name": "title",   "boost": 100 },
            { "field_name": "subject", "boost": 200 }
        ]
    }
}

分区数：建表命令 -p <N> 指定 database_partition 数（实测 -p 1 时 gs 中角色名为 database_partition_0，主键区间 0_65535）。分区数决定单表水平扩展度，建表后不可直接修改，需重建表。

5.5 分词器参数（analyzer.json）

文件位置：/ha3_install/hape_conf/default/cluster_templates/direct_table/analyzer.json（建表模板内置三个分词器，实测原文节选）：

{
    "analyzers": {
        "simple_analyzer":  { "tokenizer_configs": { "tokenizer_type": "simple", "delimiter": " " } },
        "singlews_analyzer": { "tokenizer_configs": { "tokenizer_type": "singlews" } },
        "jieba_analyzer":   { "tokenizer_name": "jieba_analyzer" }
    },
    "tokenizer_config": {
        "modules": [ { "module_name": "analyzer_plugin", "module_path": "libjieba_analyzer.so" } ],
        "tokenizers": [
            {
                "tokenizer_name": "jieba_analyzer",
                "tokenizer_type": "jieba",
                "module_name": "analyzer_plugin",
                "parameters": {
                    "dict_path": "{{ common.binaryPath }}/usr/local/share/jieba_dict/jieba.dict.utf8",
                    "hmm_path": "{{ common.binaryPath }}/usr/local/share/jieba_dict/hmm_model.utf8",
                    "user_dict_path": "{{ common.binaryPath }}/usr/local/share/jieba_dict/user.dict.utf8",
                    "idf_path": "{{ common.binaryPath }}/usr/local/share/jieba_dict/idf.utf8",
                    "stop_word_path": "{{ common.binaryPath }}/usr/local/share/jieba_dict/stop_words.utf8"
                }
            }
        ]
    }
}
分词器原理适用
simple_analyzer按分隔符（默认空格）切分，默认值英文/已分词文本
singlews_analyzer单字切分精确子串召回、调试
jieba_analyzer结巴中文分词（内置词典+HMM 模型+用户词典+IDF+停用词五个词典文件）中文正文检索

💡 技术拓展：中文分词器的常见选择——单字切分（召回最全、精度低）、词典最大匹配（快、歧义处理弱）、统计模型分词（如 jieba 的 HMM，歧义好、依赖词典）、深度学习分词（效果最好、成本高）。Havenask 内置 jieba 插件并把词典路径全部参数化，替换自训练词典只需改 user_dict_path 等五个路径参数。本篇实测环境使用默认 simple_analyzer（官方示例口径），中文业务建议显式指定 jieba_analyzer。

中文分词用法（官方 custom_analyzer 示例 schema，实测存在）：

{
    "name": "title",
    "type": "TEXT",
    "analyzer": "jieba_analyzer"
}

5.6 向量索引参数（vector 示例 schema）

官方 /ha3_install/example/cases/vector/in0_schema.json 展示了向量索引的完整参数（实测原文关键字段）：

{
    "name": "vector",
    "index_type": "VECTOR",
    "index_config": {
        "index_fields": [ { "boost": 1, "field_name": "DUP_vector" } ],
        "index_params": {
            "indexer": "aitheta2_indexer",
            "parameters": "{
                \"enable_rt_build\":\"true\",
                \"vector_index_type\":\"Qc\",
                \"builder_name\":\"QcBuilder\",
                \"searcher_name\":\"QcSearcher\",
                \"distance_type\":\"SquaredEuclidean\",
                \"dimension\":\"128\",
                \"embedding_delimiter\":\",\",
                \"min_scan_doc_cnt\":\"20000\",
                \"linear_build_threshold\":\"5000\",
                \"enable_recall_report\":\"true\",
                \"is_embedding_saved\":\"true\",
                \"search_index_params\":\"{\\\"proxima.qc.searcher.scan_ratio\\\":0.01}\",
                \"build_index_params\":\"{\\\"proxima.qc.builder.quantizer_class\\\":\\\"Int8QuantizerConverter\\\", ...}\"
            }"
        }
    }
}

逐项说明：

参数默认值含义
indexeraitheta2_indexer向量索引引擎（阿里 Proxima 系列）
vector_index_type / builder / searcherQc / QcBuilder / QcSearcherQc 量化聚类索引：内存省、召回略降
distance_typeSquaredEuclidean距离度量（平方欧氏距离）
dimension128向量维度，必须与写入数据一致
embedding_delimiter,STRING 字段中向量分量的分隔符
enable_rt_buildtrue实时构建（配合 direct table 实时写）
linear_build_threshold5000数据量低于该值退化为暴力线性检索（精度 100%）
min_scan_doc_cnt / scan_ratio20000 / 0.01检索扫描下限与扫描比例（召回-性能旋钮）

配合 llm 示例 schema（example/cases/llm/in0_schema.json，pk/embedding/content/source_id/url 字段 + DUP_ 原样列），即可搭建 RAG 向量召回库。

5.7 表处理链参数（default_table.json）

文件位置：/ha3_install/hape_conf/default/cluster_templates/direct_table/data_tables/default_table.json，实测原文关键字段：

{
    "control_config": { "use_v2_index": true },
    "processor_config": {
        "processor_queue_size": 2000,
        "processor_thread_num": 10
    },
    "processor_rule_config": {
        "parallel_num": 1,
        "partition_count": 1
    },
    "processor_chain_config": [
        {
            "document_processor_chain": [
                { "class_name": "DupFieldProcessor", "parameters": { "DUP_id": "id", "DUP_vector": "vector" } },
                { "class_name": "TokenizeDocumentProcessor", "parameters": {} }
            ]
        }
    ]
}
参数默认值含义
use_v2_indextrue使用 v2 索引格式
processor_queue_size2000文档处理队列长度，写入突增报队列满时调大
processor_thread_num10文档处理线程数
parallel_num / partition_count1 / 1处理链并行度与分片数
DupFieldProcessorDUP_<列>=<源列>字段复制（如把 vector 复制到 RAW 列 DUP_vector 供向量索引引用）
TokenizeDocumentProcessor—分词处理（TEXT 字段的必经环节）

5.8 SQL 输出与写入参数（biz_config/sql.json）

文件位置：/ha3_install/hape_conf/default/cluster_templates/direct_table/biz_config/sql.json，实测原文：

{
    "output_format": "json",
    "table_writer_config": { "zone_names": $zones }
}
参数默认值含义
output_formatjsonQRS SQL 结果默认输出格式；查询时可被 kvpair 中 formatType:string/json 覆盖（两种格式均已实测）
table_writer_config.zone_names渲染为实际 zone实时写入链路面向的 zone（searcher）

5.9 swift 与 ZooKeeper 参数

swift 消息队列（实时写链路的缓冲层）配置：/ha3_install/hape_conf/default/cluster_templates/swift/config/swift.conf，实测原文：

[common]
user_name={{ default_variables.user }}
service_name = {{ swift.serviceName }}
hippo_root = {{ swift.serviceHippoZkAddr }}
zookeeper_root = {{ swift.serviceMasterZkAddr }}
broker_count = {{ swift.brokerCount }}
admin_count = 1

[admin]
bad_broker_dispatch_delay_ms=20
dispatch_interval_ms=1000
bind_port = 11112

[broker]
data_root_path={{ swift.swiftDataStoreRoot }}
bind_port = 11113
参数默认值含义
broker_count1（global.conf [swift] 渲染）broker 数量，实时写入吞吐不足时增加
admin_count1swift admin 数量（单机固定 1）
bind_portadmin 11112 / broker 11113swift 自身端口
data_root_pathhavenask_data_store 下 swift_data_rootswift 数据落盘位置
dispatch_interval_ms1000admin 调度间隔

ZooKeeper：hape 默认自建测试实例（端口 2181，数据目录 /ha3_install/usr/local/share/zookeeper/var/）。生产建议自建 zk 集群并把 global.conf 中 domainZkRoot（默认注释行 # domainZkRoot=zfs://...）改为真实 zk 地址。ZooKeeper 的 JVM 堆限制方法与实测验证见安装篇 8.3（实测 -Xms256m -Xmx512m 生效回显）。

六、生产配置模板（16GB 内存单机，中小规模直接检索场景）

适用：16GB 内存 / 8 核 / NVMe SSD / 文档量千万级以内、以实时写入+SQL 查询为主的单机场景。

# /ha3_install/hape_conf/default/global.conf 关键项
[common]
binaryPath=/ha3_install
dataStoreRoot=/data/havenask/havenask_data_store   # 数据指向独立数据盘

[havenask]
serviceName=havenask-sql-local
image=registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:1.2.0
adminCpu=100
adminMem=5124

// searcher_hippo.json 资源段（qrs 同理）
"resources": [{ "resources": [
    { "amount": 400,   "name": "cpu", "type": "SCALAR" },
    { "amount": 6144,  "name": "mem", "type": "SCALAR" }
]}]

// 业务表 schema 关键项（中文场景）
"columns": [ { "name": "title", "type": "TEXT", "analyzer": "jieba_analyzer" }, ... ]

# ZooKeeper 堆限制（start.sh 第 34 行）
nohup java -Xms256m -Xmx512m ... org.apache.zookeeper.server.quorum.QuorumPeerMain ...

模板解读：数据盘独立（dataStoreRoot 指向 /data）；searcher/qrs 各 4 核 6GB（16GB 机器扣除 admin 5GB 配额后的均衡值，配额非预分配，实际按 5.3 节实测 RSS 预留约 3GB + 索引增长余量）；中文场景显式 jieba；zk 堆锁 512MB。

七、常见问题

Q1：改了 global.conf 不生效？ hape 配置在集群启动时渲染。改完必须 hape delete all 后重新 hape start havenask（或最小化：delete 对应集群再 start）。仅 hape restart 不会重读 global.conf。

Q2：内存配额改小后集群一直 NOT_READY？ worker 进程按 hippo 配额申请资源启动，配额低于进程实际需求会导致健康检查不过。恢复默认 10240 或按 5.3 节实测 RSS 留足余量后 hape restart havenask。

Q3：TEXT 字段能加 ATTRIBUTE 索引吗？ 不能直接混用：TEXT 走全文索引（TEXT/PACK），过滤/排序需求落在独立数值/字符串列上（如示例用 id/hits/createtime 做 ATTRIBUTE）。实测 TEXT 列在 SQL 投影中显示 null，业务需要回显正文时依赖 SUMMARY 索引定义的回原字段集合。

Q4：中文分词为什么查不到？ 默认示例是 simple_analyzer（空格分词），中文整句会被当成一个 term。建表时在 TEXT 字段显式指定 "analyzer": "jieba_analyzer"（5.5 节），改分词器需重建表（分词在写入期生效，改历史数据需重灌）。

Q5：向量维度与写入数据不一致？ dimension 与实际向量长度必须一致，写入即校验报错；embedding_delimiter 默认逗号，自定格式需同步修改。

八、参考链接

  1. 官方仓库与 README：https://github.com/alibaba/havenask（查询日期 2026-10-23）
  2. 官方文档站：https://havenask.net
  3. 站内关联文档：《Ubuntu 22.04 安装 Havenask 1.2.0 指南》、《Havenask 介绍与选型指南》