Meilisearch production 模式不设 master key 拒绝启动

Meilisearch 在 production 模式下不设 MEILI_MASTER_KEY（或不足 16 字节）会直接拒绝启动。根因是 production 强制要求 ≥16 字节的 master key 作为安全基线，development 模式则允许裸跑但会警告。解法是启动时传 --master-key 或设 MEILI_MASTER_KEY 环境变量，值至少 16 字节 UTF-8 字符串。适用 Meilisearch 全版本。

Issue & Env（案发现场与环境）

业务场景：本地开发用 development 模式跑通后，切换到 production 模式准备上线，Meilisearch 进程直接退出。
环境：Meilisearch v1.54.3，macOS / Linux / Docker 均可复现，客户端语言不限。
关键区分：development 模式不设 master key 可以启动（但所有路由公开可访问）；production 模式不设 master key 进程根本起不来，不是“启动了但报 401”，是直接 abort。

StackTrace（堆栈日志）

在 production 模式下不设 master key 启动 Meilisearch，进程拒绝启动。官方配置文档原文描述：

When --env is set to production, providing a master key is mandatory. If none is given, or it is under 16 bytes, Meilisearch will throw an error and refuse to launch.

如果在 development 模式下不设 master key 后尝试访问 /keys 路由，Meilisearch 返回 missing_master_key 错误（v0.30 引入）：

{
    "message": "Meilisearch is running without a master key. To access this API endpoint, you must have set a master key at launch.",
    "code": "missing_master_key",
    "type": "auth",
    "link": "https://docs.meilisearch.com/errors#missing_master_key"
}

社区实测确认：Docker 容器在 MEILI_ENV=production 下不设 MEILI_MASTER_KEY 时无法保持运行，直到 key 被设置为 ≥16 字节的 UTF-8 字符串后容器才正常启动。

Reproduce（复现代码）

最小复现——直接以 production 模式启动不设 master key：

# 方式一：CLI 参数
./meilisearch --env production

# 方式二：环境变量
MEILI_ENV=production ./meilisearch

# 方式三：Docker
docker run -d \
  -p 7700:7700 \
  -e MEILI_ENV=production \
  getmeili/meilisearch:v1.54.3

以上三种方式不设 master key 时，进程都会退出。对比 development 模式：

# development 模式：不设 key 能启动，但会警告
./meilisearch --env development
# 日志输出：A master key has been set... 或警告建议设置 master key

Root Cause（根因分析）

production 模式强制安全基线

Meilisearch 的 MEILI_ENV 有两个值：development 和 production。两者的核心差异在安全策略上。

官方 API Keys 规范明确描述了 production 模式下的行为：

If Meilisearch is launched with the production value for the MEILI_ENV environment variable or the --env CLI option, a master key of at least 16 bytes is mandatory. If the master key is omitted in that particular case, or is too short, Meilisearch launch is aborted and displays an error.

这不是配置建议，是硬性约束。production 模式下 master key 的缺失或长度不足会直接触发 abort，进程不会进入服务监听阶段。

16 字节下限的设计意图

master key 必须 ≥16 字节 UTF-8 字符串。这个下限不是随意的——Meilisearch 用 master key 作为运行时锁来激活安全层，首次启动时自动派生 Default Search API Key、Default Admin API Key 等子密钥。master key 本身不存储在数据库里，不通过 /keys 端点暴露，只在启动时存在。如果 master key 太短，派生的 API key 安全强度不足，所以 production 模式直接拒绝。

development 模式的宽容行为

development 模式下不设 master key 也能启动，但所有路由公开可访问（除 GET /health 外）。Meilisearch 会在启动日志中建议设置 master key，甚至生成一个推荐的安全 key 供你使用：

We generated a new secure master key for you (you can safely use this token):
>> --master-key E8H-DDQUGhZhFWhTq263Ohd80UErhFmLIFnlQK81oeQ <<
Restart Meilisearch with the argument above to use this new and secure master key.

这个推荐 key 总是 ≥16 字节。开发阶段可以忽略，但切到 production 前必须显式设置。

The Fix（解决方案）

第一步：生成一个 ≥16 字节的 master key

# 方式一：openssl 生成
openssl rand -base64 48

# 方式二：uuidgen
uuidgen

# 方式三：shasum
echo -n "your-secret-seed" | shasum -a 256

第二步：启动时传入 master key

CLI 参数：

./meilisearch --env production --master-key="E8H-DDQUGhZhFWhTq263Ohd80UErhFmLIFnlQK81oeQ"

环境变量（推荐，避免 key 出现在进程列表）：

export MEILI_ENV=production
export MEILI_MASTER_KEY="E8H-DDQUGhZhFWhTq263Ohd80UErhFmLIFnlQK81oeQ"
./meilisearch

Docker：

docker run -d \
  -p 7700:7700 \
  -e MEILI_ENV=production \
  -e MEILI_MASTER_KEY="E8H-DDQUGhZhFWhTq263Ohd80UErhFmLIFnlQK81oeQ" \
  getmeili/meilisearch:v1.54.3

第三步：验证启动成功

curl http://localhost:7700/health
# 期望输出：{"status":"available"}

启动成功后日志应包含：

A master key has been set. Requests to Meilisearch won't be authorized unless you provide an authentication key.

不带 auth 头访问受保护路由应返回 401：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:7700/indexes
# 期望输出：401

注意事项

master key 只用于管理 API keys，不要用于搜索或前端调用。首次启动后用 master key 访问 /keys 获取 Default Search API Key 和 Default Admin API Key。
更换 master key 会使之前派生的所有 API keys 失效，需要重新获取。
master key 不会出现在 /keys 端点返回结果中，无法事后查询，务必妥善保存。

References（参考来源）

Configuration reference — Meilisearch 官方文档meilisearch-docs
Configuring Meilisearch at launch — Meilisearch 官方文档meilisearch-docs
Securing your project — Meilisearch 官方文档meilisearch-docs
What's new in v0.30 — Meilisearch 官方博客meilisearch-blog
API Keys — Meilisearch 规范文档meilisearch-spec