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