MeiliSearch 1.55.0 配置参数详解

目标：逐项解析 MeiliSearch 1.55.0 的全部启动参数（CLI 参数、MEILI_* 环境变量、TOML 配置键三套等价写法），给出实测默认值、取值约束与优先级验证，并提供生产配置模板。已在 Ubuntu 22.04 + MeiliSearch 1.55.0 环境逐项实测通过。

一、环境信息

本文所有命令与回显均在以下环境中实测：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• MeiliSearch 版本：1.55.0（二进制位于 /usr/local/bin/meilisearch）
• systemd 服务：meilisearch.service（监听 127.0.0.1:7700）
• Master Key（演示用）：q1w2e3r4t5y6u7i8o0p

二、概览：三套等价配置方式与优先级

MeiliSearch 的每一个配置项都有三种等价写法：CLI 参数（--db-path）、环境变量（MEILI_DB_PATH）、TOML 配置文件键（db_path）。优先级为：CLI 参数 > 环境变量 > TOML 文件，同一参数在高层指定时覆盖低层。

💡 技术拓展：「配置来源分层 + 高层覆盖低层」是服务端软件的通用设计，同类产品对比：

软件	分层结构	高优先级来源
MeiliSearch	TOML 文件 < 环境变量 < CLI 参数	CLI 参数
PostgreSQL	postgresql.conf < postgresql.auto.conf < 会话 SET	会话级
Elasticsearch	elasticsearch.yml < 环境变量（ES_*）	环境变量
Redis	redis.conf < 命令行 < CONFIG SET 运行时	运行时命令

MeiliSearch 采用「环境变量优先于文件」的云原生风格，与 Compose/Kubernetes 的 env 注入习惯一致；本文以 CLI 参数为主线演示，Compose 部署场景把同名参数换为 MEILI_* 环境变量即可（对应关系见表格）。

2.1 参数全量查看命令

meilisearch --help

实测输出共 372 行（输出节选，实测首尾）：

Usage: meilisearch [OPTIONS]

Options:
      --config-file-path <CONFIG_FILE_PATH>
          Set the path to a configuration file that should be used to setup the engine. Format must be TOML

      --db-path <DB_PATH>
          Designates the location where database files will be created and retrieved

          [env: MEILI_DB_PATH=]
          [default: ./data.ms]

      --dump-dir <DUMP_DIR>
          Sets the directory where Meilisearch will create dump files

          [env: MEILI_DUMP_DIR=]
          [default: dumps/]
...
  -V, --version
          Print version

每个参数块都标注了对应环境变量与真实默认值（如 [env: MEILI_DB_PATH=]、[default: ./data.ms]），本文第三章的参数表即逐项取自这份实测输出。

2.2 生效配置查看：启动 banner

MeiliSearch 启动时打印一张「生效配置横幅」，是核对配置是否生效的第一手段。development 模式实测（测试实例监听 7701）：

MEILI_HTTP_ADDR=127.0.0.1:7701 MEILI_NO_ANALYTICS=true meilisearch --db-path /tmp/ms-dev/data

实测输出：

888b     d888          d8b 888 d8b                                            888
8888b   d8888          Y8P 888 Y8P                                            888
88888b.d88888              888                                                888
888Y88888P888  .d88b.  888 888 888 .d8888b   .d88b.   8888b.  888d888 .d8888b 88888b.
888 Y888P 888 d8P  Y8b 888 888 888 88K      d8P  Y8b     "88b 888P"  d88P"    888 "88b
888  Y8P  888 88888888 888 888 888 "Y8888b. 888  888 888  888 .d888888 888    888      888  888
888       888  "Y8888  888 888 888      X88 Y8b.     888  888 888    Y88b.    888  888
888       888  "Y8888  888 888 888  88888P'  "Y8888  "Y888888 888     "Y8888P 888  888

Config file path:       "none"
Database path:          "/tmp/ms-dev/data"
Server listening on:    "http://127.0.0.1:7701"
Environment:            "development"
Commit SHA:             "420ff1362801adb58c938aec89700e8f7e32e566"
Commit date:            "2026-10-12T08:45:13Z"
Package version:        "1.55.0"
Anonymous telemetry:    "Disabled"



 No master key was found. The server will accept unidentified requests.

 A master key of at least 16 bytes will be required when switching to a production environment.


We generated a new secure master key for you (you can safely use this token):

>> --master-key YabwOi66TeQ25gDt9ugIepqvOZ6suILp8m0IheUkuHQ <<

Restart Meilisearch with the argument above to use this new and secure master key.

横幅逐行含义：Config file path 本次是否加载 TOML 文件；Database path/Server listening on 数据与监听生效值；Environment 运行环境；Anonymous telemetry 遥测开关。development 模式下无 master key 会打印警告并自动生成一个随机密钥建议使用（production 模式则直接拒绝启动，见 3.2 节实测）。

2.3 优先级实测：CLI 覆盖 TOML

写一个监听 7702 的 TOML 配置文件 /tmp/meili-test.toml：

db_path = "/tmp/ms-toml/data"
http_addr = "127.0.0.1:7702"
master_key = "q1w2e3r4t5y6u7i8o0p"
env = "production"
no_analytics = true
log_level = "INFO"
max_indexing_memory = "2 GiB"
max_indexing_threads = 4
http_payload_size_limit = "100 MB"
dump_dir = "/tmp/ms-toml/dumps"

仅用配置文件启动：

meilisearch --config-file-path /tmp/meili-test.toml

实测输出（节选 banner）：

Config file path:       "/tmp/meili-test.toml"
Database path:          "/tmp/ms-toml/data"
Server listening on:    "http://127.0.0.1:7702"
Environment:            "production"
Anonymous telemetry:    "Disabled"

再加 CLI 参数把端口改到 7703 启动：

meilisearch --config-file-path /tmp/meili-test.toml --http-addr 127.0.0.1:7703

实测输出（节选 banner）：

Config file path:       "/tmp/meili-test.toml"
Server listening on:    "http://127.0.0.1:7703"

端口生效值从 7702 变为 7703，证实 CLI 参数覆盖 TOML 文件（环境变量与 CLI 的覆盖关系同理，环境变量优先级低于 CLI 高于文件）。

三、参数总览表

核心参数速查（默认值取自 1.55.0 --help 实测输出；TOML 键 = CLI 参数去掉 -- 并把连字符改下划线）：

参数表解读：日常部署只动 db-path、http-addr、master-key、env、no-analytics 五项；备份恢复用 import-dump/snapshot 组；性能调优用 max-indexing-* 与 http-payload-size-limit；TLS 内置参数适合没有反代的简单场景（有 Nginx 反代时在反代层做 TLS 更常见）。

四、核心参数分类详解

4.1 网络与安全：--http-addr 与 --master-key

--http-addr 决定监听地址端口，默认 localhost:7700（仅本机可访问）。改为 0.0.0.0:7700 对外服务（建议配合防火墙或反代）。验证方式即 banner 的 Server listening on 行与 curl 实测。

--master-key 是全部路由（除 GET /health）的鉴权主密钥。production 模式强制要求 ≥16 字节，两条约束均有实测报错：

MEILI_ENV=production meilisearch --http-addr 127.0.0.1:7701

实测输出：

2026-10-16T15:36:23.198420Z ERROR meilisearch: error=You must provide a master key to secure your instance in a production environment. It can be specified via the MEILI_MASTER_KEY environment variable or the --master-key launch option.

We generated a new secure master key for you (you can safely use this token):

>> --master-key DwHpHBFMdRx9MjkJ9FH8Fo0NMqdCI-MMdpwjJfPDT2Y <<

Error: You must provide a master key to secure your instance in a production environment. ...

MEILI_ENV=production meilisearch --http-addr 127.0.0.1:7701 --master-key short

实测输出：

2026-10-16T15:36:23.202241Z ERROR meilisearch: error=The master key must be at least 16 bytes in a production environment. The provided key is only 5 bytes.
Error: The master key must be at least 16 bytes in a production environment. ...

密钥生成方法：openssl rand -hex 32（实测输出示例 1d542b1e3d34e3ae1ba247dbb41d1a1fa4798a5d1c46e2c9f75ff8f4c50b0f37，每次运行不同）。配置生效后，无凭据请求返回 401、带 Authorization: Bearer <key> 返回 200（完整实测见《MeiliSearch 1.55.0 Ubuntu 22.04 安装指南》5.5 节）。

4.2 运行环境与日志：--env、--log-level、--no-analytics

--env 只有 development 与 production 两个合法值（--help 标注 possible values: development, production）。development 的差异（实测 banner）：允许无 master key 启动（警告 + 自动生成建议密钥）、日志更冗长、可访问调试性路由。production 则强制密钥并收紧日志。

--log-level 支持 OFF/ERROR/WARN/INFO/DEBUG/TRACE 六级，默认 INFO。实测 production INFO 级别的请求日志（journalctl 采集）：

2026-10-16T15:42:47.197435Z  INFO HTTP request{method=GET host="127.0.0.1:7700" route=/health query_parameters= user_agent=curl/7.81.0 status_code=200}: meilisearch: close time.busy=179µs time.idle=15.0µs

每个请求一行结构化日志（含路由、状态码、耗时），排查慢查询时临时调 DEBUG。

--no-analytics 关闭匿名遥测（版本、实例 UID、平台等信息上报）。验证：banner 的 Anonymous telemetry: "Disabled"（实测见 2.3 TOML 配置 no_analytics = true 后的输出）。

4.3 存储路径：--db-path、--dump-dir、--snapshot-dir

--db-path 数据库根目录，默认 ./data.ms（相对启动时的工作目录——systemd 部署必须显式给绝对路径，否则数据落到用户主目录）。目录结构实测（dump 目录同属数据根下的 dumps/）：

data.ms        # LMDB 数据库文件
dumps/         # dump 导出目录

--dump-dir 指定 dump 输出目录（默认 dumps/，相对 db-path）；--snapshot-dir 指定快照目录（默认 snapshots/）。dump 与快照的区别与用法见《MeiliSearch 1.55.0 进阶实战与运维》第五章。

4.4 备份导入与容错组合：--import-dump / --import-snapshot 及 ignore 系列

--import-dump <file.dump>：启动时把 dump 导入到（空的）db-path，是版本迁移的标准手段，全流程实测见《MeiliSearch 1.55.0 进阶实战与运维》第五章。

配套容错参数（均为开关型）：

• --ignore-dump-if-db-exists：db-path 已有数据时跳过导入继续启动（否则报错退出）；
• --ignore-missing-dump：dump 文件不存在时不报错，正常启动；
• --import-snapshot 与 --ignore-snapshot-if-db-exists、--ignore-missing-snapshot：快照导入的同等容错逻辑。

⚠️ 注意：--help 明确标注：单独使用 ignore 系列而不给 --import-dump/--import-snapshot 时会直接报错（This option will trigger an error if --import-dump is not defined），四个容错参数必须与对应 import 参数成对出现。

4.5 性能与资源：--max-indexing-memory、--max-indexing-threads、--http-payload-size-limit

--max-indexing-memory 索引期内存上限，默认取「可用内存的 2/3」动态计算——实测某 40GB 内存的机器上 --help 显示默认值为 "26.08491770364344 GiB"（≈40GB×2/3），不同机器该默认值不同。手动指定支持单位写法："2 GiB"、"2048 Mb"、2147483648（字节）。

--max-indexing-threads 索引线程数，默认半数 CPU（--help 显示 unlimited 表示由引擎按 CPU 数量自行决定），留给搜索请求核数的思路：16 核机器设 8。

--http-payload-size-limit 单次请求体上限，默认 100000000 字节（≈100 MB）。批量导入超大文件时按需调大：

http_payload_size_limit = "100 MB"   # TOML 写法，与默认值等效

💡 说明：超大批量导入更推荐拆分为多个小批次（每个任务亚秒级完成、失败可单独重试），而不是一味调大单请求上限。

4.6 TLS 与回调：--ssl-* 与 --task-webhook-*

MeiliSearch 内置 TLS 支持：--ssl-cert-path + --ssl-key-path 启用 HTTPS；--ssl-auth-path 指定客户端 CA 后可要求双向认证（配合 --ssl-require-auth 强制）；--ssl-resumption/--ssl-tickets 开启会话复用；--ssl-ocsp-path 提供 OCSP 装订。有 Nginx/Caddy 反代时无需这组参数。

--task-webhook-url 在每个任务完成时回调指定 URL 通知第三方系统，--task-webhook-authorization-header 为回调请求附加鉴权头。适合把「索引任务完成」事件推送到内部运维系统的场景。

4.7 实验特性：--experimental-* 系列

1.55.0 提供的 experimental 参数（均来自 --help 实测，启用前评估稳定性）：

开启 Prometheus 指标的典型用法：systemd 单元 ExecStart 追加 --experimental-enable-metrics，重启后 curl -s http://127.0.0.1:7700/metrics -H 'Authorization: Bearer <master-key>' 即可被 Prometheus 抓取。

五、生产配置模板

5.1 systemd 部署模板（8–16 GB 内存、NVMe SSD、中小流量站点搜索）

/etc/systemd/system/meilisearch.service（本文实测环境的原始模板）：

[Unit]
Description=MeiliSearch full-text search engine
After=network.target

[Service]
Type=simple
User=meilisearch
Group=meilisearch
ExecStart=/usr/local/bin/meilisearch --http-addr 127.0.0.1:7700 --env production --master-key q1w2e3r4t5y6u7i8o0p --db-path /var/lib/meilisearch/data --dump-dir /var/lib/meilisearch/dumps
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

5.2 Compose 部署模板（等效配置）

services:
  meilisearch:
    image: getmeili/meilisearch:v1.55.0
    restart: unless-stopped
    ports:
      - "7700:7700"
    volumes:
      - ./meili_data:/meili_data
    environment:
      MEILI_MASTER_KEY: "q1w2e3r4t5y6u7i8o0p"
      MEILI_ENV: "production"
      MEILI_NO_ANALYTICS: "true"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:7700/health"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 10s

5.3 TOML 模板（配置集中管理场景）

env = "production"
http_addr = "127.0.0.1:7700"
master_key = "q1w2e3r4t5y6u7i8o0p"
db_path = "/var/lib/meilisearch/data"
dump_dir = "/var/lib/meilisearch/dumps"
no_analytics = true
log_level = "INFO"
max_indexing_memory = "2 GiB"
max_indexing_threads = 4
http_payload_size_limit = "100 MB"

三个模板对应同一组生效值（实测验证：TOML 模板启动 banner 见 2.3 节），按部署形态任选其一。内存预算建议：8GB 机器 max-indexing-memory 设 2~3 GiB 并留足系统与搜索缓存；索引数据量超过内存 70% 时优先加内存或用 --experimental-reduce-indexing-memory-usage 评估（非生产）。

六、常见问题（FAQ）

Q1：改了配置但没生效？

按优先级排查：是否有更高层的同名覆盖（CLI 参数 > 环境变量 > TOML）；改的是 systemd 单元时是否漏了 systemctl daemon-reload；最终以启动 banner 的生效值为准（见 2.2）。

Q2：TOML 里写错键名会怎样？

MeiliSearch 对 TOML 中未知键直接报错退出并指出无效键名，不会静默忽略；键名与 CLI 参数一一对应（连字符改下划线），写错时按报错信息改键名即可。

Q3：production 启动报 master key 相关错误？

两种实测报错与解法见 4.1：必须提供密钥、密钥必须 ≥16 字节。开发环境临时体验可用 development 模式（无密钥可启动，banner 会给出自动生成的建议密钥，见 2.2 实测）。

Q4：数据目录可以改到别的磁盘吗？

改 --db-path 到新路径后重启即可；要迁移已有数据，停服务后把整个 data 目录 rsync 到新盘（保留属主与权限），再改配置重启；跨版本迁移则用 dump 导入（见《MeiliSearch 1.55.0 进阶实战与运维》第五章）。

Q5：监听 127.0.0.1 后外部访问不到？

localhost:7700 默认只听回环。主机部署改 --http-addr 0.0.0.0:7700；Compose 部署保持镜像默认（实例内 0.0.0.0），由 ports 映射对外——实例内写 127.0.0.1 会导致映射失效（详见同专栏 Compose 部署指南 Q2）。

七、参考链接

• 全部 CLI 参数官方文档：https://www.meilisearch.com/docs/learn/configuration/instance_options
• 配置文件说明：https://www.meilisearch.com/docs/learn/configuration/configure_meilisearch_at_launch
• 环境变量清单：https://www.meilisearch.com/docs/learn/configuration/environment_variables
• TLS 配置：https://www.meilisearch.com/docs/learn/security/securing_meilisearch
• 相关文档：《MeiliSearch 1.55.0 Ubuntu 22.04 安装指南》《MeiliSearch 1.55.0 进阶实战与运维》