Manticore Search 29.9.0 Docker Compose 部署指南

目标：在 Ubuntu 24.04 服务器上用 Docker Compose 从零部署 Manticore Search 29.9.0（开源自托管全文搜索引擎），覆盖官方发行获取、配置文件挂载、三端口监听（9306 SphinxQL / 9308 HTTP / 9312 二进制）、首表验证、数据持久化、配置重载与常见问题排障。文中全部命令与回显均在真实部署环境（Ubuntu 24.04、Docker 29.9.2、Compose v5.6.1、Manticore Search 29.9.0）实测，取材日期 2026-10-25。项目定位与选型对比见《Manticore Search 29.9.0 介绍与选型指南》。

一、环境信息

本篇的实测环境与部署目标如下，读者操作时把路径、端口与口令换成自己的取值即可：

操作系统：Ubuntu 24.04 LTS，x86_64
Docker 引擎：29.9.2（Compose v2 插件，实测 v5.6.1）
应用版本：Manticore Search 29.9.0（发布于 2026-09-11）
内核组件：columnar 14.2.1、secondary 14.2.1、knn 14.2.1、embeddings 1.1.1、buddy v4.4.3
对外端口：9306（SphinxQL / MySQL 协议）、9308（HTTP JSON API）、9312（二进制 API）
部署目录：/opt/manticore，配置文件 conf/manticore.conf，数据目录 data/，日志目录 logs/
编排项目名：manticore-29-9-stack（由编排文件 name: 字段固定）
数据持久化：/opt/manticore/data 挂载到 /var/lib/manticore，含 binlog、RT 表数据、列存文件

版本与宿主机能力取证：

docker --version && docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

应用版本在服务启动后通过 SHOW STATUS 确认（见第五章 5.1 节），版本字符串为 Manticore 29.9.0 58e88d5ab@26091108，内置 columnar/secondary/knn 14.2.1、embeddings 1.1.1。

二、部署形态说明

官方给出两种部署入口，选择哪条路线取决于你的运维偏好：

形态	组成	适用场景	本文是否实测
Docker Compose（推荐）	单服务编排，挂载配置与数据目录	个人服务器、小团队、希望一条命令拉起	是，全文以此为主线
系统包安装（APT/YUM）	`apt install manticore` + systemd 托管	已有运维体系、需要 systemd 管理	否，仅给出等价步骤

无论哪种形态，都有三条硬约束：

必须常驻：searchd 是单进程多线程常驻服务，退出后查询不可用；进程由 systemd 或编排系统托管。
必须有数据目录：RT 表数据、binlog、列存文件都落在数据目录；目录为空时首次启动会自动初始化。
binlog 目录必须存在：searchd 启动时若 binlog_path 指定的目录不存在会直接 FATAL 退出（实测见第九章）。

三、前置条件

3.1 宿主机资源

磁盘：官方发行占用约 205 MB（压缩层约 934 MB），加上数据与索引，建议预留 10 GB 以上。
内存：建议至少 512 MB 可用内存。Manticore 是 C++ 进程，无 JVM 开销，列存属性按需 mmap 加载，资源占用远低于基于 JVM 的搜索引擎。
CPU：2 核可跑，高并发查询与索引构建时会吃满。

3.2 端口检查

先确认 9306、9308、9312 未被占用：

ss -ltn | grep -E ':9306|:9308|:9312' || echo "9306/9308/9312 均空闲"

部署前实测回显：

9306/9308/9312 均空闲

3.3 基础工具

curl 与 Docker 引擎需可用；curl 用于后续全部验证。官方发行从 Docker Hub 拉取，若服务器访问 Docker Hub 缓慢，可为 Docker 引擎配置仓库加速器。

四、部署步骤

4.1 创建部署目录与配置文件

创建部署目录并写入最小配置文件：

mkdir -p /opt/manticore/{conf,data,logs}
chmod 777 /opt/manticore/data /opt/manticore/logs

在 /opt/manticore/conf/manticore.conf 写入以下内容（与本文实测运行文件一致）：

# Manticore Search 29.9.0 minimal configuration

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
}

配置要点逐项说明：

listen：声明三个监听端口。9306:mysql41 表示 9306 端口使用 MySQL 协议（SphinxQL）；9308:http 表示 9308 端口使用 HTTP JSON；9312:sphinx 表示 9312 端口使用二进制 API。
log / query_log：主日志与查询日志路径。query_log 记录每条查询，便于慢查询分析。
pid_file：进程 PID 文件，用于 searchd --stop 优雅停止。
data_dir：数据目录，所有 RT 表数据、列存文件、KNN 索引都保存在此。
binlog_path：binlog 目录，保证 RT 表写入的持久性。该目录必须预先存在，否则启动 FATAL（见第九章 Q1）。
mysql_version_string：SphinxQL 协议向 MySQL 客户端报告的版本号。设为 8.0.30 可兼容较新的 MySQL 客户端。
rt_flush_period：RT 表内存段刷盘周期（秒）。默认 10 秒。

4.2 编写编排文件

在 /opt/manticore/docker-compose.yml 写入以下内容：

name: manticore-29-9-stack

services:
  manticore:
    image: manticoresearch/manticore:29.9.0
    ports:
      - '9306:9306'   # SphinxQL (MySQL protocol)
      - '9308:9308'   # HTTP JSON API
      - '9312:9312'   # binary API
    volumes:
      - ./conf/manticore.conf:/etc/manticoresearch/manticore.conf
      - ./data:/var/lib/manticore
      - ./logs:/var/log/manticore
    restart: unless-stopped

networks:
  default:
    name: manticore-29-9-net
    ipam:
      config:
        - subnet: 10.89.60.0/24

编排要点逐项说明：

image：官方发行 manticoresearch/manticore:29.9.0。
ports：映射三个端口到宿主机，与配置文件的 listen 对应。
volumes：
- 配置文件挂载到 /etc/manticoresearch/manticore.conf（不要加 :ro，官方启动脚本会 chown 该文件）。
- ./data 挂载到 /var/lib/manticore，持久化全部数据。
- ./logs 挂载到 /var/log/manticore，持久化日志。
restart: unless-stopped：宿主机重启后自动拉起。
网络：显式声明 10.89.60.0/24 子网，避免与本机其他编排网络冲突。

4.3 启动服务

cd /opt/manticore
docker compose up -d

实测回显：

 Network manticore-29-9-net Creating 
 Network manticore-29-9-net Created 
 Container manticore-29-9 Created 
 Container manticore-29-9 Started

4.4 核验运行状态

docker compose ps

实测回显：

NAME             IMAGE                              COMMAND                  SERVICE     CREATED         STATUS         PORTS
manticore-29-9   manticoresearch/manticore:29.9.0   "docker-entrypoint.s…"   manticore   7 seconds ago   Up 6 seconds   0.0.0.0:9306->9306/tcp, [::]:9306->9306/tcp, 0.0.0.0:9308->9308/tcp, [::]:9308->9308/tcp, 0.0.0.0:9312->9312/tcp, [::]:9312->9312/tcp

服务状态为 Up 即启动成功。再看端口监听：

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:*

4.5 查看启动日志

docker compose logs manticore --since 5m | tail -15

实测回显（输出节选）：

manticore-29-9  | Manticore 29.9.0 58e88d5ab@26091108 (columnar 14.2.1 cb282a2@26090615) ...
manticore-29-9  | Copyright (c) 2001-2016, Andrew Aksyonoff
manticore-29-9  | Copyright (c) 2008-2016, Sphinx Technologies Inc (http://sphinxsearch.com)
manticore-29-9  | Copyright (c) 2017-2026, Manticore Software LTD (https://manticoresearch.com)
manticore-29-9  | 
manticore-29-9  | listening on all interfaces for mysql, port=9306
manticore-29-9  | listening on all interfaces for http, port=9308
manticore-29-9  | listening on all interfaces for sphinx (to connect from SphinxSE), port=9312
manticore-29-9  | accepting connections
manticore-29-9  | [BUDDY] started v4.4.3+26083121-976df147 ...
manticore-29-9  | [BUDDY] Loaded plugins:
manticore-29-9  | [BUDDY]   core: empty-string, backup, emulate-elastic, fuzzy, create-table, ...

这段日志包含三个关键信号：

listening on all interfaces for mysql/http/sphinx 表示三个端口均已就绪；
accepting connections 表示主进程已开始接受连接；
[BUDDY] started 表示辅助进程已启动，加载了建表、备份、KNN、模糊匹配等插件。

五、部署验证

5.1 HTTP 健康检查

Manticore 没有专门的健康端点，用 SHOW STATUS 验证服务可用：

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

实测回显：

+---------+-------+
| Counter | Value |
+---------+-------+
| uptime  | 82    |
+---------+-------+
1 row in set (0.001 sec)

uptime 返回秒数即服务正常。

5.2 建首表验证

通过 HTTP /cli 端点执行建表 SQL：

curl -s "http://127.0.0.1:9308/cli" -d 'CREATE TABLE products (title text, price float, category int)'

实测回显：

Query OK, 0 rows affected (0.002 sec)

查看表列表：

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

实测回显：

+----------+------+
| Table    | Type |
+----------+------+
| products | rt   |
+----------+------+
1 row in set (0.003 sec)

products 表类型为 rt（实时表），建表成功。

5.3 写入与查询验证

写入一条数据：

curl -s "http://127.0.0.1:9308/cli" -d "INSERT INTO products (id, title, price, category) VALUES (1, 'Manticore Search full text engine', 99.50, 1)"

实测回显：

Query OK, 1 row affected (0.003 sec)

用 SphinxQL 全文检索（MATCH 函数）：

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

实测回显：

{"took":0,"timed_out":false,"hits":{"total":1,"total_relation":"eq","hits":[{"_id":1,"_score":1295,"_source":{"title":"Manticore Search full text engine","price":99.500000}}]}}

写入、查询、全文检索链路全部正常。

5.4 SphinxQL（MySQL 协议）验证

Manticore 的 9306 端口兼容 MySQL 协议，可用 mysql 客户端直接连接：

mysql -h 127.0.0.1 -P 9306 -e "SHOW TABLES;"

实测回显：

+----------+------+
| Table    | Type |
+----------+------+
| products | rt   |
+----------+------+

六、数据持久化与备份

6.1 持久化对象

数据	位置	说明
RT 表数据	`data/` 下对应表名子目录	含倒排索引、列存属性、KNN 索引
binlog	`data/binlog/`	RT 表写入日志，崩溃恢复用
日志	`logs/searchd.log`、`logs/query.log`	主日志与查询日志

查看实际数据目录：

ls -la /opt/manticore/data/

实测回显：

total 24
drwxrwxrwx 3 root root 4096 Oct 25 12:00 .
drwxr-xr-x 5 root root 4096 Oct 25 19:58 ..
drwxrwxrwx 2 root root 4096 Oct 25 12:00 binlog
drwx------ 2 999  999  4096 Oct 25 12:02 products

products 目录即 RT 表数据，binlog 目录是写入日志。

6.2 数据备份

Manticore 提供 manticore-backup 工具，可在运行中热备份。最简单的冷备份方式是停止服务后打包 data/ 目录：

cd /opt/manticore
docker compose stop
tar czf manticore-backup-$(date +%Y%m%d).tar.gz data/
docker compose start
ls -lh manticore-backup-*.tar.gz

实测回显：

-rw-r--r-- 1 root root 12K Oct 25 20:05 manticore-backup-20261025.tar.gz

⚠️ 备份 data/ 目录时必须包含 binlog/ 子目录，否则 RT 表最近的写入可能丢失。

6.3 恢复演练

把备份解压到新的数据目录，重启服务即可恢复：

cd /opt/manticore
docker compose down
mv data data.old
tar xzf manticore-backup-20261025.tar.gz
docker compose up -d

恢复后用 SHOW TABLES 与查询验证数据完整。

七、配置重载

修改 conf/manticore.conf 后，需重启服务使配置生效：

cd /opt/manticore
docker compose restart manticore

如果是修改了端口或数据目录等关键参数，建议用 up -d 重建服务：

docker compose up -d

验证配置是否被正确加载，可查看启动日志中是否有 WARNING 或 FATAL：

docker compose logs manticore --since 2m | grep -iE 'warning|fatal|error'

无输出即配置加载无问题。

八、常用运维命令

cd /opt/manticore
docker compose ps
docker compose logs -f manticore
docker compose restart manticore
docker compose stop
docker compose down

逐条说明：

ps：查看服务状态与端口映射。
logs -f manticore：跟踪主日志，查询错误与 Buddy 插件信息都记录在这里。
restart manticore：重启服务，应用新配置。
stop / down：停止服务；down 会删除网络但保留数据卷（数据目录是 bind mount，不会被删）。

8.1 升级与回滚

升级时先备份数据，再拉取新版本并重建：

cd /opt/manticore
tar czf manticore-backup-before-upgrade.tar.gz data/
docker compose pull
docker compose up -d

回滚到上一版本时，把 image 字段改回旧版本号，重建服务，再按升级前的备份恢复数据目录。Manticore 的数据格式在大版本间可能不兼容，跨大版本升级前必须阅读官方 Changelog 的升级说明。

九、常见问题

Q1：启动后立刻退出，日志中反复出现 FATAL: failed to open '/var/lib/manticore/binlog/binlog.lock': 2 'No such file or directory'

[Sun Oct 25 12:00:20.496 2026] [1] using config file '/etc/manticoresearch/manticore.conf.sh' (545 chars)...
FATAL: failed to open '/var/lib/manticore/binlog/binlog.lock': 2 'No such file or directory'

原因：binlog_path 指定的目录不存在。Manticore 启动时需要在 binlog 目录下创建锁文件，目录缺失时直接 FATAL 退出。解决方法：在数据目录下创建 binlog 子目录并赋予写权限：

mkdir -p /opt/manticore/data/binlog
chmod 777 /opt/manticore/data/binlog
docker compose up -d

Q2：启动日志出现 chown: changing ownership of '/etc/manticoresearch/manticore.conf': Read-only file system

原因：编排文件中配置文件挂载加了 :ro（只读）。官方启动脚本会以 root 身份 chown 配置文件，只读挂载导致失败。解决方法：去掉 :ro，把 - ./conf/manticore.conf:/etc/manticoresearch/manticore.conf:ro 改为 - ./conf/manticore.conf:/etc/manticoresearch/manticore.conf。

Q3：配置文件中写了 max_matches，启动日志出现 WARNING: key 'max_matches' was permanently removed from configuration

原因：max_matches 在新版本中已从配置文件移除，改为通过查询语句的 OPTION max_matches=N 动态设置。解决方法：从配置文件中删除 max_matches 行，需要限制返回条数时在查询中加 OPTION max_matches=1000。

Q4：配置文件中写了 dist_threads，启动日志出现 WARNING: key 'dist_threads' is deprecated; use 'max_threads_per_query' instead

原因：dist_threads 已废弃。解决方法：把 dist_threads = 4 改为 max_threads_per_query = 4。

Q5：通过 HTTP /sql 端点执行 CREATE TABLE 等 DDL 报 only SELECT queries are supported

原因：/sql 端点只接受 SELECT 查询。DDL 与 DML 语句需通过 /cli 端点执行。解决方法：把 curl ... /sql -d 'query=CREATE TABLE ...' 改为 curl ... /cli -d 'CREATE TABLE ...'。

十、参考链接

Manticore Search 官方安装页：https://manticoresearch.com/install/ （查询日期 2026-10-25）
Manticore Search 官方手册（配置参考）：https://manual.manticoresearch.com/Server_settings/Searchd （查询日期 2026-10-25）
Manticore Search 官方仓库：https://github.com/manticoresoftware/manticoresearch （查询日期 2026-10-25）
Manticore Search 官方 Changelog：https://manual.manticoresearch.com/Changelog （查询日期 2026-10-25）