Manticore Search 29.9.0 配置参数详解

Manticore Search 29.9.0 配置参数详解：逐项实测 searchd 段核心参数（listen/log/rt_flush_period/net_workers/max_threads_per_query 等）、表级参数、环境变量覆盖机制，给出默认值、修改方式、重启生效与验证命令及废弃参数排障。

Manticore SearchManticore Search配置参数详解数据库2026/10/25

Manticore Search 29.9.0 配置参数详解

目标：把 Manticore Search 29.9.0 的配置拆成「searchd 服务段」「表级参数」「环境变量覆盖」三类，逐项给出默认值、作用、修改方式与验证命令。文中所有回显均为本机实测（Ubuntu 24.04、Docker 29.9.2、Compose v5.6.1、Manticore Search 29.9.0），取材日期 2026-10-25；部署流程见《Manticore Search 29.9.0 Docker Compose 部署指南》，产品定位见《Manticore Search 29.9.0 介绍与选型指南》。

一、环境信息

  • 应用版本：Manticore Search 29.9.0，内核 C++，Buddy v4.4.3
  • 对外端口：9306（SphinxQL）、9308（HTTP JSON）、9312（二进制 API）
  • 配置入口：/etc/manticoresearch/manticore.conf（searchd 段）、建表语句中的表级参数、searchd_* 前缀环境变量
  • 生效方式：配置文件改动需重启 searchd；表级参数在建表/改表时生效；环境变量在启动时注入
  • 实测基线：单实例、RT 表 products（含 title text、price float、category int）、数据目录 /var/lib/manticore

本文每个参数都按「改值 → 重启 → 用状态/查询回显验证」的方式实测。

二、配置体系总览

Manticore Search 的配置分成三层，职责不同：

层位置管什么生效时机
服务段配置manticore.conf 的 searchd {} 段监听端口、日志路径、线程模型、网络参数、刷新周期searchd 启动时读取；改完需重启
表级参数建表语句中的字段类型与 table_options字段是否索引/存储、分词器、列存、KNN 参数建表/ALTER TABLE 时生效
环境变量searchd_* 前缀的环境变量覆盖 searchd 段同名键启动时由官方启动脚本注入

💡 技术拓展：为什么 Manticore 用配置文件 + SQL 双入口？ 传统 Sphinx 全部配置写在 sphinx.conf（表结构、数据源、服务参数全在一起），改表结构要重启。Manticore 把表结构移到 SQL（CREATE TABLE），配置文件只管服务级参数，改表无需重启。这是 Manticore 相对 Sphinx 的关键改进之一。

三、searchd 段核心参数

3.1 listen（监听端口）

默认值：无默认值，必填。至少声明一个监听端口。

格式：listen = [IP:]端口[:协议]，协议可选 mysql41（SphinxQL）、http、sphinx（二进制 API）、replication（集群复制）。

实测配置：

listen = 9306:mysql41
listen = 9308:http
listen = 9312:sphinx

验证：启动后查看端口监听与状态：

ss -ltn | grep -E ':9306|:9308|:9312'

实测回显：

LISTEN 0      4096         0.0.0.0:9306       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:9308       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:9312       0.0.0.0:*

结论：三个端口按声明的协议监听。不写 IP 默认监听所有接口（0.0.0.0）。

3.2 log / query_log（日志路径）

默认值：log 无默认值（不写则输出到 stderr）；query_log 默认不记录查询。

实测配置：

log = /var/log/manticore/searchd.log
query_log = /var/log/manticore/query.log

验证：执行一条查询后查看 query.log：

curl -s "http://127.0.0.1:9308/sql" --data-urlencode "query=SELECT id FROM products WHERE MATCH('search')" > /dev/null
cat /var/log/manticore/query.log | tail -1

实测回显：

/* Sun Oct 25 12:07:56.465 2026 conn 576 (10.89.60.1:40348) real 0.000 wall 0.000 found 6 */ SELECT id FROM products WHERE MATCH('search');

结论：query_log 记录每条查询的连接来源、耗时（real/wall）、匹配文档数与原始 SQL，是慢查询分析的主要依据。

3.3 mysql_version_string（SphinxQL 协议版本号）

默认值：5.6.30。

作用：向 MySQL 客户端报告的服务器版本号。部分 MySQL 客户端（尤其是 8.x）会校验服务器版本，版本过低会拒绝连接。

实测配置：

mysql_version_string = 8.0.30

验证：

curl -s "http://127.0.0.1:9308/cli" -d "SHOW STATUS LIKE 'mysql_version'"

实测回显：

+---------------+--------+
| Counter       | Value  |
+---------------+--------+
| mysql_version | 8.0.30 |
+---------------+--------+

结论：设为 8.0.30 后，新版 MySQL 客户端可正常连接。旧版本客户端连接失败时，优先检查此参数。

3.4 rt_flush_period（RT 表刷盘周期）

默认值：10（秒）。

作用：RT 表的内存段（RAM chunk）定期刷到磁盘的间隔。值越小，崩溃时丢失的写入越少，但 IO 开销越大。

实测配置：

rt_flush_period = 10

验证：

curl -s "http://127.0.0.1:9308/cli" -d "SHOW STATUS LIKE 'uptime'"

实测回显：

+---------+-------+
| Counter | Value |
+---------+-------+
| uptime  | 82    |
+---------+-------+

说明：rt_flush_period 本身不出现在 SHOW STATUS 中，其效果通过 query_log 中的写入耗时与崩溃恢复行为体现。默认 10 秒在大多数场景下是性能与持久性的平衡。

3.5 net_workers（网络工作线程数）

默认值：auto（通常等于 CPU 核数）。

作用：处理网络连接与查询请求的工作线程数。

实测配置：

net_workers = 4

验证：

curl -s "http://127.0.0.1:9308/cli" -d "SHOW STATUS LIKE 'workers%'"

实测回显：

+-----------------------+-------+
| Counter               | Value |
+-------+-------+
| workers_total         | 6     |
| workers_active        | 4     |
| workers_clients       | 2     |
| workers_clients_vip   | 0     |
| workers_clients_buddy | 1     |
+-----------------------+-------+

结论：workers_active 为 4，与 net_workers = 4 一致。workers_total 为 6 是因为 Buddy 也占用了线程。

3.6 max_threads_per_query（单查询最大线程数）

默认值：0（不限制）。

作用：单个查询可使用的最大并行线程数，替代旧版的 dist_threads。

实测配置：

max_threads_per_query = 4

⚠️ 旧参数 dist_threads 在 29.9.0 中已废弃，启动日志会出现 WARNING: key 'dist_threads' is deprecated; use 'max_threads_per_query' instead。必须改用 max_threads_per_query。

3.7 max_matches（最大匹配数）

默认值：已从配置文件移除。

作用：限制查询返回的最大文档数。29.9.0 起不再支持在 searchd 段配置，改为通过查询语句的 OPTION 子句动态设置。

⚠️ 在配置文件中写 max_matches = 1000 会触发 WARNING: key 'max_matches' was permanently removed from configuration。

正确用法：在查询中用 OPTION：

curl -s "http://127.0.0.1:9308/sql" --data-urlencode "query=SELECT id FROM products WHERE MATCH('search') OPTION max_matches=5000"

实测回显：

{"took":0,"timed_out":false,"hits":{"total":6,"total_relation":"eq","hits":[{"_id":2,"_score":1379,"_source":{}},...]}}

也可用 SET 语句设置会话级默认值：

curl -s "http://127.0.0.1:9308/cli" -d "SET max_matches=5000"

实测回显：

Query OK, 0 rows affected (0.003 sec)

3.8 thread_stack（线程栈大小）

默认值：256K。

作用：每个工作线程的栈大小。复杂查询或深度嵌套的过滤器可能需要更大的栈。

实测配置：

thread_stack = 1M

说明：此参数不在 SHOW STATUS 中暴露，其效果通过是否出现 stack overflow 错误判断。默认 256K 对大多数查询足够，遇到栈溢出错误时再调大。

3.9 max_packet_size（最大数据包大小）

默认值：8M。

作用：单次请求的最大字节数，影响批量写入（BULK INSERT）的单批大小。

实测配置：

max_packet_size = 128M

说明：此参数不在 SHOW STATUS 中暴露。批量写入时若遇到 packet too large 错误，需调大此值。

3.10 pseudo_sharding（伪分片）

默认值：1（开启）。

作用：把单表查询拆成多个子查询并行执行，充分利用多核 CPU。数据量大时效果明显。

实测配置：

pseudo_sharding = 1

说明：此参数不在 SHOW STATUS 中暴露。对小表伪分片可能反而增加开销，可通过 OPTION pseudo_sharding=0 在单条查询中关闭。

3.11 persistent_connections_limit（持久连接上限）

默认值：0（不限制）。

作用：持久连接（keep-alive）的最大数量。

实测配置：

persistent_connections_limit = 100

说明：此参数不在 SHOW STATUS 中暴露。高并发短连接场景下设为合理值可避免连接耗尽。

3.12 binlog_path（binlog 路径）

默认值：无默认值，建议显式设置。

作用：RT 表写入日志目录，保证写入持久性。进程崩溃后自动重放 binlog 恢复未刷盘的数据。

实测配置：

binlog_path = /var/lib/manticore/binlog

验证：

ls -la /var/lib/manticore/binlog/

实测回显：

total 20
drwxrwxrwx 2 root root 4096 Oct 25 12:00 .
drwxrwxrwx 4 root root 4096 Oct 25 12:02 ..
-rw------- 1 999  999     0 Oct 25 12:00 binlog.001
-rw------- 1 999  999     0 Oct 25 12:00 binlog.lock

⚠️ 关键：binlog_path 指定的目录必须在启动前存在，否则 searchd 启动时 FATAL 退出（failed to open '.../binlog/binlog.lock': No such file or directory）。

四、表级参数

表级参数在建表语句中指定，无需重启服务。Manticore 的字段类型决定了它参与全文检索还是仅用于过滤：

CREATE TABLE products (
    title text indexed stored,
    price float,
    category uint
)
类型/属性作用实测回显（DESCRIBE）
text indexed参与全文分词与检索title text indexed stored
text stored可返回原值，不参与检索同上
int/uint/bigint整型属性，用于过滤/排序/分组category uint
float/double浮点属性，用于过滤/排序price float
timestamp时间戳属性—
string字符串属性（不过滤，可返回）—

验证：

curl -s "http://127.0.0.1:9308/cli" -d "DESCRIBE products"

实测回显：

+----------+--------+----------------+
| Field    | Type   | Properties     |
+----------+--------+----------------+
| id       | bigint |                |
| title    | text   | indexed stored |
| price    | float  |                |
| category | uint   |                |
+----------+--------+----------------+

💡 技术拓展：全文索引 vs 列存属性。

类型存储方式用途代价
text indexed倒排索引全文检索占用索引空间，写入慢
attribute（列存）列存文件过滤/排序/分组不参与全文，扫描快

Manticore 29.9.0 默认对属性启用列存（access_columnar_attrs='mmap'），列存数据按需 mmap 加载，内存占用远低于 Elasticsearch 的 doc_values。

五、环境变量覆盖机制

官方启动脚本支持用 searchd_ 前缀的环境变量覆盖 searchd 段同名键。例如，把 listen 改为 9306:mysql41|9308:http：

export searchd_listen='9306:mysql41|9308:http'

启动脚本会解析该变量并注入到配置文件中。这个机制适合在不修改配置文件的情况下调整参数，尤其在编排系统中通过 environment: 注入。

等价编排写法：

services:
  manticore:
    environment:
      - searchd_listen=9306:mysql41|9308:http|9312:sphinx
      - searchd_rt_flush_period=5

注意：环境变量只在启动脚本中处理，直接运行 searchd 二进制不会读取这些变量。

六、生产配置模板

以下模板适用于 4 核 8GB 内存、NVMe SSD、日增量百万文档的搜索场景：

searchd {
    listen = 9306:mysql41
    listen = 9308:http
    listen = 9312:sphinx

    log = /var/log/manticore/searchd.log
    query_log = /var/log/manticore/query.log
    pid_file = /var/run/manticore/searchd.pid
    data_dir = /var/lib/manticore
    binlog_path = /var/lib/manticore/binlog

    mysql_version_string = 8.0.30

    rt_flush_period = 10
    net_workers = 4
    max_threads_per_query = 4
    pseudo_sharding = 1
    thread_stack = 1M
    max_packet_size = 128M
    persistent_connections_limit = 1000

    # 崩溃恢复时重放 binlog 的超时（秒）
    # binlog_flush_period = 0  # 0 表示每次写入都刷盘，最安全但最慢
}

模板说明：

  • rt_flush_period = 10：平衡持久性与 IO，10 秒内的写入崩溃可能丢。
  • net_workers = 4：与 CPU 核数一致，避免线程过多切换。
  • max_threads_per_query = 4：单查询最多用 4 线程，复杂查询不阻塞其他查询。
  • max_packet_size = 128M：支持大批量写入。
  • persistent_connections_limit = 1000：支持高并发持久连接。

七、参数查看与修改方式

7.1 查看运行时状态

curl -s "http://127.0.0.1:9308/cli" -d "SHOW STATUS"

返回全部运行时计数器，包括 uptime、connections、workers_*、各命令统计、性能百分位（search_stats_ms_pct95 等）。

7.2 查看表结构

curl -s "http://127.0.0.1:9308/cli" -d "DESCRIBE products"

7.3 修改配置

  1. 编辑 manticore.conf；
  2. 重启服务：docker compose restart manticore；
  3. 查看日志确认无 WARNING/FATAL：docker compose logs manticore --since 2m | grep -iE 'warning|fatal|error'。

八、常见问题

Q1：配置文件中写了 max_matches，启动报 WARNING: key 'max_matches' was permanently removed

解决：从配置文件删除该行，改用查询级 OPTION max_matches=N 或会话级 SET max_matches=N。

Q2：配置文件中写了 dist_threads，启动报 WARNING: key 'dist_threads' is deprecated

解决：把 dist_threads = N 改为 max_threads_per_query = N。

Q3：启动报 FATAL: failed to open '.../binlog/binlog.lock': No such file or directory

解决：binlog_path 指定的目录不存在，手动创建并赋予写权限：mkdir -p /var/lib/manticore/binlog && chmod 777 /var/lib/manticore/binlog。

Q4：修改配置后重启，参数似乎没生效

排查：检查配置文件路径是否正确挂载，查看启动日志中 using config file '...' (N chars) 的字符数是否与预期一致；配置文件挂载加了 :ro 会导致启动脚本 chown 失败。

九、参考链接