在自托管 Meilisearch 时，您可以通过 命令行选项、环境变量 或 配置文件 来配置实例的启动参数。

这些启动选项会影响整个 Meilisearch 实例，而不仅仅是单个索引。如需设置仅影响单个索引内的搜索行为，请参阅索引设置。

​
命令行选项与标志

在启动 Meilisearch 实例时传递 命令行选项 及其对应的值。

./meilisearch --db-path ./meilifiles --http-addr 'localhost:7700'

上述示例中，./meilisearch 是启动 Meilisearch 实例的命令，而 --db-path 和 --http-addr 是用于修改实例行为的选项。

Meilisearch 还提供了一系列 命令行标志。与命令行选项不同，标志不接受参数值。如果指定了某个标志，则会激活该功能并改变 Meilisearch 的默认行为。

./meilisearch --no-analytics

上述标志会禁用 Meilisearch 实例的分析功能，且不接受任何参数值。

命令行选项和命令行标志的优先级高于环境变量。 所有命令行选项和标志都以 -- 开头。

​
环境变量

要使用环境变量配置 Meilisearch 实例，请在启动实例前设置环境变量。如果不确定如何操作，可以阅读更多关于设置和列出环境变量的内容，或者改用命令行选项。

在前面的示例中，./meilisearch 是启动 Meilisearch 实例的命令，而 MEILI_DB_PATH 和 MEILI_HTTP_ADDR 是修改该实例行为的环境变量。

用于命令行标志的环境变量接受 n、no、f、false、off 和 0 作为 false 值。未设置的环境变量也会被视为 false。任何其他值都将被视为 true。

环境变量总是与对应的命令行选项相同，但需要添加 MEILI_ 前缀并全部大写。

​
配置文件

Meilisearch 接受 .toml 格式的配置文件作为命令行选项和环境变量的替代方案。配置文件易于共享和版本控制，并允许您定义多个选项。

当同时使用时，环境变量会覆盖配置文件，而命令行选项会覆盖环境变量。

您可以使用以下命令下载默认配置文件：

curl https://raw.githubusercontent.com/meilisearch/meilisearch/latest/config.toml > config.toml

默认情况下，Meilisearch 会在工作目录中查找 config.toml 文件。如果存在该文件，它将被用作配置文件。您可以在启动 Meilisearch 时验证这一点：

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. 88888888 .d888888 888    888      888  888
888   "   888 Y8b.     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.toml"

如果 配置文件路径 显示的不是 "none"，则表示已成功找到并使用配置文件启动了 Meilisearch。

您可以使用 MEILI_CONFIG_FILE_PATH 环境变量或 --config-file-path CLI 选项来覆盖配置文件的默认位置：

​
配置文件格式

您可以使用配置文件来配置任何环境变量或命令行选项。在配置文件中，选项必须使用蛇形命名法书写。例如，--import-dump 应写作 import_dump。

import_dump = "./example.dump"

在配置文件中指定 config_file_path 选项会抛出错误。这是唯一不能在配置文件中设置的配置选项。

​
配置云端托管实例

要在云端托管实例中使用命令行选项配置 Meilisearch，请编辑其服务文件。服务文件的默认位置是 /etc/systemd/system/meilisearch.service。

要在云端托管实例中使用环境变量配置 Meilisearch，请修改 Meilisearch 的 env 文件。其默认位置是 /var/opt/meilisearch/env。

编辑配置选项后，重新启动 Meilisearch 服务：

systemctl restart meilisearch

Meilisearch Cloud 提供了最优化的预配置环境。当您在 Meilisearch Cloud 上托管项目时，不需要使用本页列出的任何配置选项。

​
所有实例选项

​
配置文件路径

环境变量: MEILI_CONFIG_FILE_PATH

命令行选项: --config-file-path

默认值: ./config.toml

期望值: 文件路径

指定启动时要加载的配置文件位置。

在配置文件本身中指定此选项会抛出错误（假设 Meilisearch 能找到您的配置文件）。

​
数据库路径

环境变量: MEILI_DB_PATH

命令行选项: --db-path

默认值: "data.ms/"

期望值: 文件路径

指定数据库文件创建和检索的位置。

​
环境配置

环境变量: MEILI_ENV

命令行选项: --env

默认值: development

期望值: production 或 development

配置实例的运行环境。值必须为 production 或 development。

production 模式:

  • 必须设置至少16字节的主密钥。如果未提供主密钥或密钥长度不足16字节，Meilisearch 会建议自动生成一个安全的主密钥
  • 禁用搜索预览界面

development 模式:

  • 设置主密钥是可选的。如果未提供主密钥或密钥长度不足16字节，Meilisearch 会建议自动生成一个安全的主密钥
  • 启用搜索预览功能

当服务器环境设置为 development 时，不强制要求提供主密钥。这在调试和原型开发时很有用，但由于API路由不受保护，其他情况下可能存在风险。

​
HTTP地址与端口绑定

环境变量: MEILI_HTTP_ADDR

命令行选项: --http-addr

默认值: "localhost:7700"

期望值: HTTP地址和端口号

设置 Meilisearch 使用的HTTP地址和端口。

​
主密钥

环境变量: MEILI_MASTER_KEY

命令行选项: --master-key

默认值: None

预期值：至少16字节的UTF-8字符串

设置实例的主密钥，自动保护除 GET /health 外的所有路由。这意味着您需要有效的API密钥才能访问其他所有端点。

当 --env 设置为 production 时，必须提供主密钥。如果未提供或密钥不足16字节，Meilisearch 将抛出错误并拒绝启动。

当 --env 设置为 development 时，提供主密钥是可选的。如果未提供，所有路由将不受保护且可公开访问。

如果在 production 或 development 环境中未提供主密钥或密钥不足16字节，Meilisearch 会建议一个安全自动生成的主密钥，供您在重启实例时使用。

了解更多关于 Meilisearch 安全密钥的使用

​
禁用分析功能

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量：MEILI_NO_ANALYTICS

CLI选项：--no-analytics

提供此选项时，禁用 Meilisearch 的内置遥测功能。

Meilisearch 会自动收集所有未通过此标志选择退出的实例数据。所有收集的数据仅用于改进 Meilisearch，并且可以随时删除。

阅读更多关于我们的数据收集政策，或查看我们收集的所有数据点的完整列表。

​
无转储升级 experimental

环境变量：MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE

CLI选项：--experimental-dumpless-upgrade

默认值：无

预期值：无

在手动更新 Meilisearch 二进制文件后，将数据库迁移至新版本。

了解更多关于更新 Meilisearch 到新版本的信息。

​
执行无转储升级前创建快照

在执行无转储升级前，请为您的实例创建快照。

当前无转储升级操作不具备原子性。某些进程可能失败而 Meilisearch 仍会完成升级，这可能导致数据库损坏和数据丢失。

​
转储目录

环境变量：MEILI_DUMP_DIR

命令行选项：--dump-dir

默认值：dumps/

预期值：指向有效目录的文件路径

设置 Meilisearch 创建转储文件的目录。

了解更多关于创建转储的信息。

​
导入转储

环境变量：MEILI_IMPORT_DUMP

命令行选项：--import-dump

默认值：无

预期值：指向 .dump 文件的文件路径

导入指定路径的转储文件。路径必须指向 .dump 文件。若数据库已存在，Meilisearch 将抛出错误并中止启动。

Meilisearch 仅在转储数据完全索引后才会启动，所需时间取决于转储文件大小。

​
忽略缺失的转储

🚩 此选项不接受任何值。赋值将导致错误。🚩

环境变量：MEILI_IGNORE_MISSING_DUMP

命令行选项：--ignore-missing-dump

当 --import-dump 未指向有效转储文件时，阻止 Meilisearch 抛出错误。相反，Meilisearch 将正常启动而不导入任何转储。

若未定义 --import-dump，此选项将触发错误。

​
数据库存在时忽略转储

🚩 此选项不接受任何值。赋值将导致错误。🚩

环境变量: MEILI_IGNORE_DUMP_IF_DB_EXISTS

CLI 选项: --ignore-dump-if-db-exists

当使用 --import-dump 时，防止已有数据库的 Meilisearch 实例抛出错误。相反，dump 文件会被忽略，Meilisearch 将使用现有数据库启动。

如果未定义 --import-dump，此选项将触发错误。

​
日志级别

环境变量: MEILI_LOG_LEVEL

CLI 选项: --log-level

默认值: 'INFO'

可选值: ERROR, WARN, INFO, DEBUG, TRACE 或 OFF

定义 Meilisearch 日志应包含的详细程度。

Meilisearch 目前支持五种日志级别，按详细程度递增排列：

  • 'ERROR': 仅记录表明 Meilisearch 未按预期运行的意外事件
  • 'WARN': 记录所有意外事件，无论其严重程度如何
  • 'INFO': 记录所有事件。这是 --log-level 的默认值
  • 'DEBUG': 记录所有事件并包含 Meilisearch 内部流程的详细信息。诊断问题和调试时有用
  • 'TRACE': 记录所有事件并包含更详细的 Meilisearch 内部流程信息。不建议使用此级别，因为它极其冗长。在考虑 'TRACE' 之前先使用 'DEBUG'
  • 'OFF': 禁用日志记录

​
自定义日志输出 experimental

环境变量: MEILI_EXPERIMENTAL_LOGS_MODE

CLI 选项: --experimental-logs-mode

默认值: 'human'

可选值: human 或 json

定义日志应输出人类可读文本还是 JSON 数据。

​
最大索引内存

环境变量: MEILI_MAX_INDEXING_MEMORY

CLI 选项: --max-indexing-memory

默认值: 可用内存的 2/3

预期值：整数（104857600）或人类可读的大小（'100Mb'）

设置 Meilisearch 在索引时能使用的最大内存量。默认情况下，Meilisearch 使用的内存不超过可用内存的三分之二。

该值必须以字节为单位或明确指定基本单位：107374182400、'107.7Gb' 或 '107374 Mb'。

在索引过程中，Meilisearch 可能会略微超过设定的内存限制。在大多数环境和机器上，这个超出量可以忽略不计，对稳定性和性能几乎没有影响。

将 --max-indexing-memory 设置为大于或等于机器总内存的值可能导致实例崩溃。

​
减少索引内存使用量 experimental

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量：MEILI_EXPERIMENTAL_REDUCE_INDEXING_MEMORY_USAGE

命令行选项：--experimental-reduce-indexing-memory-usage

默认值：None

启用 MDB_WRITEMAP（一个 LMDB 选项）。激活此选项可能会在某些 UNIX 和类 UNIX 系统中降低内存使用量，但也可能对写入速度和整体性能产生负面影响。

​
最大索引线程数

环境变量：MEILI_MAX_INDEXING_THREADS

命令行选项：--max-indexing-threads

默认值：可用线程数的一半

预期值：整数

设置 Meilisearch 在索引过程中可使用的最大线程数。默认情况下，索引器会避免使用超过机器总处理单元一半的线程。这确保 Meilisearch 始终能够执行搜索，即使在更新索引时也是如此。

如果 --max-indexing-threads 设置的值高于机器实际可用的核心数，Meilisearch 将使用最大可用核心数。

在单核机器上，Meilisearch 只能使用唯一的可用核心进行索引。这可能导致索引期间的搜索体验下降。

避免将 --max-indexing-threads 设置为机器处理器核心总数。虽然这样做可能加快索引速度，但很可能会严重影响搜索体验。

​
负载大小限制

环境变量：MEILI_HTTP_PAYLOAD_SIZE_LIMIT

命令行选项：--http-payload-size-limit

默认值：104857600 (~100MB)

预期值：整数

设置可接受负载的最大大小。值必须以字节为单位或明确指定基本单位。例如，默认值可以表示为 107374182400、'107.7Gb' 或 '107374 Mb'。

​
搜索队列大小 experimental

环境变量：MEILI_EXPERIMENTAL_SEARCH_QUEUE_SIZE

命令行选项：--experimental-search-queue-size

默认值：1000

预期值：整数

配置同时处理的最大搜索请求数量。默认情况下，Meilisearch 在任何时刻最多排队 1000 个搜索请求。此限制旨在防止 Meilisearch 消耗无限量的内存。

​
搜索查询嵌入缓存 experimental

环境变量：MEILI_EXPERIMENTAL_EMBEDDING_CACHE_ENTRIES

CLI 选项: --experimental-embedding-cache-entries

默认值: 0

期望值: 整数

设置搜索查询嵌入缓存的大小。默认情况下，Meilisearch 会为每个新的搜索查询生成嵌入向量。当该选项设置为大于0的整数时，如果最近执行过相同的查询，Meilisearch 会返回之前生成的嵌入向量。

缓存采用最近最少使用（LRU）淘汰策略。具有相同配置的嵌入器共享同一个缓存，即使它们是在不同的索引中声明的。

​
定时快照创建

环境变量: MEILI_SCHEDULE_SNAPSHOT

CLI 选项: --schedule-snapshot

默认值: 未设置时禁用，若存在但无值则为 86400

期望值: None 或整数

启用定时快照功能。快照功能默认是禁用的。

可以使用不带值的 --schedule-snapshot。如果在启动实例时存在 --schedule-snapshot 但未赋值，Meilisearch 会每24小时创建一个新快照。

如需更精确控制快照时间间隔，可以传入一个表示秒数的整数值。当 --schedule-snapshot=3600 时，Meilisearch 每小时创建一个新快照。

使用配置文件时，也可以为 schedule_snapshot 显式传递布尔值。当 schedule_snapshot=true 时，Meilisearch 每24小时创建一次快照；schedule_snapshot=false 时则不创建快照。

了解更多关于快照的信息。

​
快照存储目录

环境变量: MEILI_SNAPSHOT_DIR

CLI 选项: --snapshot-dir

默认值: snapshots/

期望值: 指向有效目录的文件路径

设置 Meilisearch 存储快照的目录。

​
未压缩快照 实验性功能

环境变量: MEILI_EXPERIMENTAL_NO_SNAPSHOT_COMPACTION

CLI 选项: --experimental-no-snapshot-compaction

禁用快照压缩。这可能会显著加快快照创建速度，但会导致快照文件体积增大。

​
导入快照

环境变量: MEILI_IMPORT_SNAPSHOT

CLI 选项: --import-snapshot

默认值: None

期望值: 指向快照文件的路径

在给定路径导入先前生成的快照后启动 Meilisearch。

以下情况会抛出错误：

  • 数据库已存在
  • 指定路径找不到有效快照

此行为可分别通过 --ignore-snapshot-if-db-exists 和 --ignore-missing-snapshot 选项修改。

​
忽略缺失的快照

🚩 此选项不接受任何值。赋值会抛出错误。🚩

环境变量: MEILI_IGNORE_MISSING_SNAPSHOT

CLI 选项: --ignore-missing-snapshot

当 --import-snapshot 指向无效快照文件时，防止 Meilisearch 实例抛出错误。

如果未定义 --import-snapshot，此命令会抛出错误。

​
数据库存在时忽略快照

🚩 此选项不接受任何值。赋值会抛出错误。🚩

环境变量: MEILI_IGNORE_SNAPSHOT_IF_DB_EXISTS

CLI 选项: --ignore-snapshot-if-db-exists

当使用 --import-snapshot 时，防止已有数据库的 Meilisearch 实例抛出错误。相反，将忽略快照并使用现有数据库启动 Meilisearch。

如果未定义 --import-snapshot，此命令会抛出错误。

​
任务 webhook URL

环境变量: MEILI_TASK_WEBHOOK_URL

CLI 选项: --task-webhook-url

默认值: None

期望值: URL 字符串

当 Meilisearch 完成处理任务 或任务批次时，会通知配置的 URL。Meilisearch 会原样使用给定的 URL，保留所有指定的查询参数。

Webhook 负载包含以 ndjson 格式列出的已完成任务。更多信息请参阅 专门的任务 webhook 指南。

​
任务 webhook 授权头

环境变量: MEILI_TASK_WEBHOOK_AUTHORIZATION_HEADER

CLI 选项: --task-webhook-authorization-header

默认值: None

期望值: 认证令牌字符串

在通知 webhook URL 时，在授权头中包含认证令牌。

​
批量任务最大数量 experimental

环境变量: MEILI_EXPERIMENTAL_MAX_NUMBER_OF_BATCHED_TASKS

CLI 选项: --experimental-max-number-of-batched-tasks

默认值: None

期望值: 整数

限制 Meilisearch 单批次执行的任务数量。可提升处理大量资源密集型任务队列的系统稳定性。

​
批量负载最大大小 experimental

环境变量: MEILI_EXPERIMENTAL_LIMIT_BATCHED_TASKS_TOTAL_SIZE

CLI 选项: --experimental-limit-batched-tasks-total-size

默认值: None

期望值: 整数

设置批次负载的最大字节大小。较小的批次效率较低，但会减少内存消耗并降低即时延迟。

​
复制参数 experimental

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量: MEILI_EXPERIMENTAL_REPLICATION_PARAMETERS

CLI 选项: --experimental-replication-parameters

默认值: None

帮助 Meilisearch 在集群环境中运行。通过以下三种方式修改任务处理行为实现：

  • 禁用任务自动删除功能
  • 允许通过向 API 请求添加自定义 TaskId 标头来手动设置任务 UID
  • 允许通过在请求中指定 DryRun: true 标头来干注册任务

​
SSL 选项

​
SSL 认证路径

环境变量: MEILI_SSL_AUTH_PATH

CLI 选项: --ssl-auth-path

默认值: None

期望值: 文件路径

在指定路径启用客户端认证功能。

​
SSL 证书路径

环境变量: MEILI_SSL_CERT_PATH

CLI 选项: --ssl-cert-path

默认值: None

期望值: 指向有效 SSL 证书的文件路径

设置服务器的 SSL 证书。

值必须是 PEM 格式证书的路径。第一个证书应对应 --ssl-key-path 提供的 KEYFILE 进行认证。最后一个证书应是根 CA 证书。

​
SSL 密钥路径

环境变量: MEILI_SSL_KEY_PATH

CLI 选项: --ssl-key-path

默认值: None

期望值: 指向有效 SSL 密钥文件的文件路径

设置服务器的 SSL 密钥文件。

值必须是 PEM 格式的 RSA 私钥或 PKCS8 编码私钥的路径。

​
SSL OCSP 路径

环境变量: MEILI_SSL_OCSP_PATH

CLI 选项: --ssl-ocsp-path

默认值: None

期望值：指向有效 OCSP 证书的文件路径

设置服务器的 OCSP 文件。可选

从 OCSPFILE 读取 DER 编码的 OCSP 响应并钉扎到证书。

​
SSL 要求认证

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量：MEILI_SSL_REQUIRE_AUTH

命令行选项：--ssl-require-auth

默认值：None

强制要求 SSL 认证。

如果客户端未完成客户端认证，则发送致命警报。

​
SSL 会话恢复

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量：MEILI_SSL_RESUMPTION

命令行选项：--ssl-resumption

默认值：None

启用 SSL 会话恢复功能。

​
SSL 票据

🚩 此选项不接受任何值。赋值将抛出错误。🚩

环境变量：MEILI_SSL_TICKETS

命令行选项：--ssl-tickets

默认值：None

启用 SSL 票据功能。