在启动时配置 Meilisearch
在启动时通过命令行选项、环境变量或配置文件配置 Meilisearch。
自托管 Meilisearch 时,您可以在启动时通过命令行选项、环境变量或配置文件配置您的实例。
这些启动选项会影响整个 Meilisearch 实例,而不仅仅是单个索引。有关影响单个索引内搜索的设置,请参阅索引设置。
命令行选项和标志
在启动 Meilisearch 实例时传递命令行选项及其相应的值。
在前面的示例中,./meilisearch
是启动 Meilisearch 实例的命令,而--db-path
和 --http-addr
是修改此实例行为的选项。
Meilisearch 还有许多命令行标志。与命令行选项不同,标志不带值。如果给定标志,它将被激活并更改 Meilisearch 的默认行为。
上述标志禁用 Meilisearch 实例的分析功能,并且不接受值。
命令行选项和命令行标志都优先于环境变量。所有命令行选项和标志都以--
开头。
环境变量
要使用环境变量配置 Meilisearch 实例,请在启动实例之前设置环境变量。如果您不确定如何操作,请阅读有关设置和列出环境变量的更多信息,或改用命令行选项。
在前面的示例中,./meilisearch
是启动 Meilisearch 实例的命令,而MEILI_DB_PATH
和 MEILI_HTTP_ADDR
是修改此实例行为的环境变量。
命令行标志的环境变量接受n
、no
、f
、false
、off
和0
作为false
。缺席的环境变量也将被视为false
。任何其他值都被视为true
。
环境变量始终与相应的命令行选项相同,但以MEILI_
开头且全部大写。
配置文件
Meilisearch 接受.toml
格式的配置文件,作为命令行选项和环境变量的替代方案。配置文件易于共享和版本控制,并允许您定义多个选项。
同时使用时,环境变量会覆盖配置文件,而命令行选项会覆盖环境变量。
您可以使用以下命令下载默认配置文件
默认情况下,Meilisearch 将在工作目录中查找config.toml
文件。如果存在,它将用作配置文件。您可以在启动 Meilisearch 时验证这一点
如果Config file path
(配置文件路径)不是"none"
,则表示已成功找到并使用配置文件来启动 Meilisearch。
您可以使用MEILI_CONFIG_FILE_PATH
环境变量或--config-file-path
CLI 选项覆盖配置文件的默认位置
配置文件格式
您可以使用配置文件配置任何环境变量或 CLI 选项。在配置文件中,选项必须以蛇形命名法编写。例如,--import-dump
将被写为import_dump
。
在配置文件中指定config_file_path
选项将引发错误。这是唯一不能在配置文件中设置的配置选项。
配置云托管实例
要在云托管实例中使用命令行选项配置 Meilisearch,请编辑其服务文件。服务文件的默认位置是/etc/systemd/system/meilisearch.service
。
要在云托管实例中使用环境变量配置 Meilisearch,请修改 Meilisearch 的env
文件。其默认位置是/var/opt/meilisearch/env
。
编辑配置选项后,重新启动 Meilisearch 服务
Meilisearch 云提供优化的预配置环境。当您在 Meilisearch 云上托管您的项目时,无需使用此页面中列出的任何配置选项。
所有实例选项
配置文件路径
环境变量:MEILI_CONFIG_FILE_PATH
CLI 选项:--config-file-path
默认值:./config.toml
预期值:文件路径
指定启动时要加载的配置文件位置。
在配置文件本身中指定此选项将引发错误(假设 Meilisearch 能够找到您的配置文件)。
数据库路径
环境变量:MEILI_DB_PATH
CLI 选项:--db-path
默认值:"data.ms/"
预期值:文件路径
指定创建和检索数据库文件的位置。
环境
环境变量:MEILI_ENV
CLI 选项:--env
默认值:development
预期值:production
或 development
配置实例的环境。值必须是production
或development
。
生产环境
:
- 设置至少 16 字节的主密钥是强制性的。如果未提供主密钥或其少于 16 字节,Meilisearch 将建议一个安全的自动生成主密钥
- 搜索预览界面已禁用
开发环境
:
- 设置主密钥是可选的。如果未提供主密钥或其少于 16 字节,Meilisearch 将建议一个安全的自动生成主密钥
- 搜索预览已启用
当服务器环境设置为development
时,提供主密钥不是强制性的。这在调试和原型开发时很有用,但否则很危险,因为 API 路由不受保护。
HTTP 地址和端口绑定
环境变量:MEILI_HTTP_ADDR
CLI 选项:--http-addr
默认值:"localhost:7700"
预期值:HTTP 地址和端口
设置 Meilisearch 将使用的 HTTP 地址和端口。
主密钥
环境变量:MEILI_MASTER_KEY
CLI 选项:--master-key
默认值:无
预期值:至少 16 字节的 UTF-8 字符串
设置实例的主密钥,自动保护除GET /health
之外的所有路由。这意味着您需要一个有效的 API 密钥才能访问所有其他端点。
当--env
设置为production
时,提供主密钥是强制性的。如果未提供,或其少于 16 字节,Meilisearch 将引发错误并拒绝启动。
当--env
设置为development
时,提供主密钥是可选的。如果未提供,所有路由将不受保护且可公开访问。
如果您在production
或development
环境中未提供主密钥或其少于 16 字节,Meilisearch 将建议一个安全的自动生成主密钥,您可以在重新启动实例时使用。
禁用分析
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_NO_ANALYTICS
CLI 选项:--no-analytics
提供此选项时,停用 Meilisearch 的内置遥测功能。
Meilisearch 会自动从所有未使用此标志选择退出的实例收集数据。所有收集的数据仅用于改进 Meilisearch,并且可以随时删除。
阅读有关我们数据收集政策的更多信息,或查看我们收集的所有数据点的完整列表。
无转储升级 实验性
环境变量:MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE
CLI 选项:--experimental-dumpless-upgrade
默认值:无
预期值:无
在您手动更新二进制文件后,将数据库迁移到新的 Meilisearch 版本。
了解有关将 Meilisearch 更新到新版本的更多信息.
转储目录
环境变量:MEILI_DUMP_DIR
CLI 选项:--dump-dir
默认值:dumps/
预期值:指向有效目录的文件路径
设置 Meilisearch 将创建转储文件的目录。
导入转储
环境变量:MEILI_IMPORT_DUMP
CLI 选项:--import-dump
默认值:无
预期值:指向.dump
文件的文件路径
导入位于指定路径的转储文件。路径必须指向.dump
文件。如果数据库已存在,Meilisearch 将引发错误并中止启动。
Meilisearch 只有在转储数据完全索引后才会启动。这所需的时间取决于转储文件的大小。
忽略缺失的转储
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_IGNORE_MISSING_DUMP
CLI 选项:--ignore-missing-dump
当--import-dump
未指向有效的转储文件时,防止 Meilisearch 抛出错误。相反,Meilisearch 将正常启动而不导入任何转储。
如果未定义--import-dump
,此选项将触发错误。
如果数据库存在则忽略转储
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_IGNORE_DUMP_IF_DB_EXISTS
CLI 选项:--ignore-dump-if-db-exists
当使用--import-dump
时,防止已存在数据库的 Meilisearch 实例抛出错误。相反,转储将被忽略,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'
:禁用日志记录
自定义日志输出 实验性
环境变量:MEILI_EXPERIMENTAL_LOGS_MODE
CLI 选项:--experimental-logs-mode
默认值:'human'
预期值:human
或 json
之一
定义日志是输出人类可读的文本还是 JSON 数据。
最大索引内存
环境变量:MEILI_MAX_INDEXING_MEMORY
CLI 选项:--max-indexing-memory
默认值:可用 RAM 的 2/3
预期值:整数 (104857600
) 或人类可读的大小 ('100Mb'
)
设置 Meilisearch 索引时可使用的最大 RAM 量。默认情况下,Meilisearch 使用不超过可用内存的 2/3。
该值必须以字节为单位或明确说明基本单位:107374182400
、'107.7Gb'
或'107374 Mb'
。
在索引过程中,Meilisearch 可能会超出精确的 RAM 限制。在大多数情况下和机器上,这应该是一个可忽略不计的量,对稳定性和性能几乎没有影响。
将--max-indexing-memory
设置为大于或等于您机器总内存的值可能会导致您的实例崩溃。
减少索引内存使用 实验性
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_EXPERIMENTAL_REDUCE_INDEXING_MEMORY_USAGE
CLI 选项:--experimental-reduce-indexing-memory-usage
默认值:无
启用MDB_WRITEMAP
,一个 LMDB 选项。激活此选项可能会在某些 UNIX 和类 UNIX 设置中减少 RAM 使用量。但是,它也可能会对写入速度和整体性能产生负面影响。
最大索引线程数
环境变量:MEILI_MAX_INDEXING_THREADS
CLI 选项:--max-indexing-threads
默认值:可用线程的一半
预期值:整数
设置 Meilisearch 在索引期间可使用的最大线程数。默认情况下,索引器避免使用超过机器总处理单元一半的线程。这确保 Meilisearch 始终准备好执行搜索,即使在您更新索引时也是如此。
如果--max-indexing-threads
高于机器中可用的实际核心数,Meilisearch 将使用最大可用核心数。
在单核机器中,Meilisearch 别无选择,只能使用唯一可用于索引的核心。这可能导致在索引期间搜索体验下降。
避免将--max-indexing-threads
设置为机器处理器核心的总数。尽管这样做可能会加快索引速度,但它很可能会严重影响搜索体验。
负载限制大小
环境变量:MEILI_HTTP_PAYLOAD_SIZE_LIMIT
CLI 选项:--http-payload-size-limit
默认值:104857600
(~100MB)
预期值:整数
设置接受负载的最大大小。该值必须以字节为单位或明确说明基本单位。例如,默认值可以写为107374182400
、'107.7Gb'
或'107374 Mb'
。
搜索队列大小 实验性
环境变量:MEILI_EXPERIMENTAL_SEARCH_QUEUE_SIZE
CLI 选项:--experimental-search-queue-size
默认值:1000
预期值:整数
配置最大并发搜索请求量。默认情况下,Meilisearch 在任何给定时刻最多排队 1000 个搜索请求。此限制的存在是为了防止 Meilisearch 消耗无限量的 RAM。
搜索查询嵌入缓存 实验性
环境变量:MEILI_EXPERIMENTAL_EMBEDDING_CACHE_ENTRIES
CLI 选项:--experimental-embedding-cache-entries
默认值:0
预期值:整数
设置搜索查询嵌入缓存的大小。默认情况下,Meilisearch 为每个新的搜索查询生成一个嵌入。当此选项设置为大于 0 的整数时,如果 Meilisearch 最近执行了相同的查询,它将返回先前生成的嵌入。
最近最少使用的条目首先被逐出。具有相同配置的嵌入器共享相同的缓存,即使它们在不同的索引中声明也是如此。
安排快照创建
环境变量:MEILI_SCHEDULE_SNAPSHOT
CLI 选项:--schedule-snapshot
默认值:如果不存在则禁用,如果存在但没有值则为86400
预期值:无
或整数
激活计划快照。快照默认禁用。
可以不带值使用--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
默认值:无
预期值:指向快照文件的文件路径
在导入给定文件路径的先前生成的快照后启动 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
默认值:无
预期值:URL 字符串
每当 Meilisearch 完成处理任务或任务批次时,通知配置的 URL。Meilisearch 按原样使用该 URL,保留任何指定的查询参数。
Webhook 负载包含ndjson格式的已完成任务列表。有关更多信息,请查阅专用任务 Webhook 指南。
任务 Webhook 授权头
环境变量:MEILI_TASK_WEBHOOK_AUTHORIZATION_HEADER
CLI 选项:--task-webhook-authorization-header
默认值:无
预期值:身份验证令牌字符串
在通知Webhook URL时,在授权头中包含身份验证令牌。
最大批处理任务数 实验性
环境变量:MEILI_EXPERIMENTAL_MAX_NUMBER_OF_BATCHED_TASKS
CLI 选项:--experimental-max-number-of-batched-tasks
默认值:无
预期值:整数
限制 Meilisearch 在单个批次中执行的任务数量。这可能会提高处理大量资源密集型任务队列的系统的稳定性。
最大批处理负载大小 实验性
环境变量:MEILI_EXPERIMENTAL_LIMIT_BATCHED_TASKS_TOTAL_SIZE
CLI 选项:--experimental-limit-batched-tasks-total-size
默认值:无
预期值:整数
设置批处理的最大负载大小(以字节为单位)。较小的批处理效率较低,但消耗的 RAM 更少,并减少即时延迟。
复制参数 实验性
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_EXPERIMENTAL_REPLICATION_PARAMETERS
CLI 选项:--experimental-replication-parameters
默认值:无
有助于在集群环境中运行 Meilisearch。它通过以下三种方式修改任务处理
- 任务自动删除已禁用
- 允许您通过在 API 请求中添加自定义
TaskId
头来手动设置任务 UID - 允许您通过在请求中指定
DryRun: true
头来干运行注册任务
SSL 选项
SSL 身份验证路径
环境变量:MEILI_SSL_AUTH_PATH
CLI 选项:--ssl-auth-path
默认值:无
预期值:文件路径
在指定路径中启用客户端身份验证。
SSL 证书路径
环境变量:MEILI_SSL_CERT_PATH
CLI 选项:--ssl-cert-path
默认值:无
预期值:指向有效 SSL 证书的文件路径
设置服务器的 SSL 证书。
值必须是 PEM 格式证书的路径。第一个证书应证明--ssl-key-path
提供的 KEYFILE。最后一个证书应为根 CA。
SSL 密钥路径
环境变量:MEILI_SSL_KEY_PATH
CLI 选项:--ssl-key-path
默认值:无
预期值:指向有效 SSL 密钥文件的文件路径
设置服务器的 SSL 密钥文件。
值必须是 RSA 私钥或 PKCS8 编码私钥的路径,两者都应采用 PEM 格式。
SSL OCSP 路径
环境变量:MEILI_SSL_OCSP_PATH
CLI 选项:--ssl-ocsp-path
默认值:无
预期值:指向有效 OCSP 证书的文件路径
设置服务器的 OCSP 文件。可选
从 OCSPFILE 读取 DER 编码的 OCSP 响应并将其附加到证书。
SSL 需要身份验证
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_SSL_REQUIRE_AUTH
CLI 选项:--ssl-require-auth
默认值:无
使 SSL 身份验证成为强制性的。
如果客户端未完成客户端身份验证,则发送致命警报。
SSL 会话恢复
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_SSL_RESUMPTION
CLI 选项:--ssl-resumption
默认值:无
激活 SSL 会话恢复。
SSL 票据
🚩 此选项不接受任何值。赋值将引发错误。🚩
环境变量:MEILI_SSL_TICKETS
CLI 选项:--ssl-tickets
默认值:无
激活 SSL 票据。