Meilisearch Docker 自托管排查：镜像、Master Key、数据卷和备份

环境和问题

这次整理 Meilisearch Docker 自托管排查。目标是给内部文档、FAQ、产品手册或 RAG 前置检索补一个轻量搜索服务。

常见问题不是"容器跑不起来"这么简单，而是这些：

text 复制代码

docker pull getmeili/meilisearch 卡住
7700 端口没有响应
没有设置 MEILI_MASTER_KEY
数据没挂载到 /meili_data，重启后索引丢失
文档导入返回 202，但搜索不到
升级前没有 dump 或 snapshot

下面按部署顺序排一遍。

1. 镜像版本先固定

官方 Docker 镜像是 getmeili/meilisearch。文档示例会使用 latest，但官方也提醒，latest 会随时间变化。生产或团队复现环境建议固定版本。

bash 复制代码

docker pull docker.1ms.run/getmeili/meilisearch:v1.47.0

这一步使用毫秒镜像只是做 Docker Hub 镜像预检。它不替代版本管理、漏洞扫描和发布审批。

2. 最小启动命令

bash 复制代码

docker run --rm \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY='replace-with-a-strong-key' \
  -v $(pwd)/meili_data:/meili_data \
  docker.1ms.run/getmeili/meilisearch:v1.47.0

参数说明：

参数	说明
`-p 7700:7700`	暴露 Meilisearch API
`MEILI_MASTER_KEY`	实例 master key，不能泄露到前端
`/meili_data`	数据目录，必须持久化
`v1.47.0`	固定版本，便于复现和回滚

3. 健康检查

bash 复制代码

curl http://127.0.0.1:7700/health

如果本机能通，外部不通，优先看安全组、防火墙和反向代理。不要先改 Meilisearch 配置。

4. Master Key 和 API Keys

MEILI_MASTER_KEY 权限非常高。官方文档建议只在管理 API keys 时使用。常规业务搜索、写入和只读操作应使用权限受限的 API keys。

建议拆成：

Key	用途
master key	创建、删除、轮换 API keys
admin key	后端导入文档、修改索引设置
search key	前端或业务查询
read-only key	运维排查和审计读取

不要把 master key 放到浏览器端代码里。

5. 导入文档后要看 task

Meilisearch 的文档写入是异步任务。导入返回成功，不代表立刻可搜。

bash 复制代码

curl -X POST http://127.0.0.1:7700/indexes/docs/documents \
  -H 'Authorization: Bearer replace-with-a-server-key' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {"id": 1, "title": "订单同步失败", "code": "ORDER_SYNC_503"},
    {"id": 2, "title": "登录跳转异常", "code": "AUTH_REDIRECT_LOOP"}
  ]'

拿到 task uid 后继续查：

bash 复制代码

curl http://127.0.0.1:7700/tasks/replace-with-task-uid \
  -H 'Authorization: Bearer replace-with-a-server-key'

如果 task 失败，先看字段类型、主键、文档格式和 payload 大小。

6. 搜索验证

精确词：

bash 复制代码

curl -X POST http://127.0.0.1:7700/indexes/docs/search \
  -H 'Authorization: Bearer replace-with-a-search-key' \
  -H 'Content-Type: application/json' \
  -d '{"q":"AUTH_REDIRECT_LOOP"}'

自然语言：

bash 复制代码

curl -X POST http://127.0.0.1:7700/indexes/docs/search \
  -H 'Authorization: Bearer replace-with-a-search-key' \
  -H 'Content-Type: application/json' \
  -d '{"q":"登录后一直回到登录页"}'

如果业务准备使用 hybrid search，还要单独验证 embedder 配置、语义结果和 full-text 结果的混合比例。注意，变更 embedder 配置可能触发重新 embedding，大索引会耗时和产生额外成本。

7. 备份策略

Meilisearch 有 snapshot 和 dump 两类备份方式：

方式	场景
snapshot	周期备份、同版本快速恢复
dump	升级迁移、跨版本迁移

建议：

日常开启周期 snapshot。
升级前创建 dump。
周期性做恢复演练。
备份文件不要只放在同一台机器上。

总结

Meilisearch Docker 自托管排查顺序可以记成：

text 复制代码

镜像 -> 端口 -> Master Key -> 数据卷 -> task -> 搜索验证 -> 备份

毫秒镜像适合解决第一层镜像预检，把 getmeili/meilisearch 先拉进环境。后面的密钥、安全、索引、备份和 hybrid search 调优，仍然要按 Meilisearch 自身的工程规则来做。