MeiliSearch 1.55.0 Docker Compose 部署指南

目标：使用官方镜像 getmeili/meilisearch:v1.55.0，通过 Docker Compose 一键部署 MeiliSearch 全文搜索引擎，覆盖镜像选型、端口映射、数据卷持久化、master key 配置、健康检查、数据重启保留验证与常用运维命令。已在 Docker Engine 29.8.0 + Docker Compose v5.5.1 环境逐条实测通过。

一、环境信息

本文所有命令与回显均在以下环境中实测：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Docker Engine：29.8.0（docker version 确认）
Docker Compose：v5.5.1（docker compose version 确认）
MeiliSearch 镜像：getmeili/meilisearch:v1.55.0（官方镜像）
部署目录：/opt/meilisearch
数据卷：宿主机 ./meili_data 挂载到容器内 /meili_data
对外端口：7700
Master Key（演示用测试口令）：q1w2e3r4t5y6u7i8o0p

二、镜像选型说明

MeiliSearch 官方在 Docker Hub 维护 getmeili/meilisearch 镜像仓库。镜像 tag 选型对照：

Tag	内容	适用场景
getmeili/meilisearch:v1.55.0	指定版本，不可变	生产环境（本文使用）
getmeili/meilisearch:latest	最新版，随发布漂移	本地体验，不建议生产
getmeili/meilisearch:v1.55	次版本最新补丁	想自动跟进补丁的场景

关键差异与选型：生产环境固定完整版本号 v1.55.0，保证升级节奏可控、回滚有据；latest 会在官方发版后漂移，导致 compose 重新拉取后行为变化，禁止用于生产。

确认镜像架构与内置组件（镜像内自带 curl/wget，可直接用于健康检查）：

docker run --rm --entrypoint sh getmeili/meilisearch:v1.55.0 -c "which curl wget; ls /bin/meilisearch; meilisearch --version"

实测输出：

/usr/bin/curl
/usr/bin/wget
/bin/meilisearch
meilisearch 1.55.0

💡 技术拓展：容器内进程管理器方面，官方镜像使用 tini 作为 PID 1 入口（compose ps 的 COMMAND 列可见 tini -- /bin/sh -c ...），负责转发信号与回收僵尸进程；镜像基于精简 Linux 发行版构建，运行时二进制以 musl libc 静态链接，因此不要把该镜像内的 meilisearch 二进制拷到 Debian/Ubuntu 主机上直接运行（glibc 环境会报 no such file or directory），主机安装请使用 GitHub Release 的 glibc 版本二进制。

三、前置条件

服务器已安装 Docker Engine 与 Compose 插件，逐条验证：

docker version --format 'docker {{.ServerVersion}}'

实测输出：

docker 29.8.0

docker compose version

实测输出：

Docker Compose version v5.5.1

拉取官方镜像：

docker pull getmeili/meilisearch:v1.55.0

实测输出（节选）：

Digest: sha256:ff546679970126f8822e15d1b6a06bfbff1f2ce2e43f810cfb5258012f92de5c
Status: Downloaded newer image for getmeili/meilisearch:v1.55.0
docker.io/getmeili/meilisearch:v1.55.0

mkdir -p /opt/meilisearch && cd /opt/meilisearch

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/meilisearch 下创建 docker-compose.yml：

services:
  meilisearch:
    image: getmeili/meilisearch:v1.55.0
    container_name: meilisearch
    restart: unless-stopped
    ports:
      - "7700:7700"
    volumes:
      - ./meili_data:/meili_data
    environment:
      MEILI_MASTER_KEY: "q1w2e3r4t5y6u7i8o0p"
      MEILI_ENV: "production"
      MEILI_NO_ANALYTICS: "true"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:7700/health"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 10s

逐项说明：

image：固定官方版本 v1.55.0（见第二章选型说明）；
container_name：固定实例名，便于 docker 命令直接引用；
restart: unless-stopped：宿主机重启后自动拉起，人工 stop 后不自动重启；
ports：宿主机 7700 → 容器 7700，MeiliSearch 默认监听端口；
volumes：bind mount 把宿主机 ./meili_data 挂到容器 /meili_data（镜像默认 MEILI_DB_PATH=/meili_data，数据、dump 全部落在这里，见第五章）；
MEILI_MASTER_KEY：实例主密钥（生产环境必须修改，至少 16 字节）；
MEILI_ENV: "production"：生产模式；
MEILI_NO_ANALYTICS: "true"：关闭匿名遥测上报；
healthcheck：用镜像自带的 curl 探测 /health，15 秒一次，10 秒启动宽限期。

4.2 启动服务

docker compose up -d

实测输出：

 Network meilisearch_default Creating
 Network meilisearch_default Created
 Container meilisearch Creating
 Container meilisearch Created
 Container meilisearch Starting
 Container meilisearch Started

4.3 验证运行状态与健康检查

docker compose ps

实测输出（STATUS 列出现 (healthy) 说明 healthcheck 已通过）：

NAME          IMAGE                          COMMAND                  SERVICE       CREATED         STATUS                   PORTS
meilisearch   getmeili/meilisearch:v1.55.0   "tini -- /bin/sh -c …"   meilisearch   6 seconds ago   Up 6 seconds (healthy)   0.0.0.0:7700->7700/tcp, [::]:7700->7700/tcp

在容器内验证健康端点：

docker compose exec -T meilisearch curl -fsS http://localhost:7700/health

实测输出：

{"status":"available"}

在宿主机验证 API 鉴权与版本：

curl -s http://127.0.0.1:7700/version -H 'Authorization: Bearer q1w2e3r4t5y6u7i8o0p'

实测输出：

{"commitSha":"420ff1362801adb58c938aec89700e8f7e32e566","commitDate":"2026-10-12T08:45:13.000000000Z","pkgVersion":"1.55.0"}

写入一条验证文档确认读写链路可用：

docker compose exec -T meilisearch curl -s -X POST "http://localhost:7700/indexes/books/documents?primaryKey=id" -H "Authorization: Bearer q1w2e3r4t5y6u7i8o0p" -H "Content-Type: application/json" --data-binary "[{\"id\": 1, \"title\": \"部署验证用书\"}]"

实测输出：

{"taskUid":0,"indexUid":"books","status":"enqueued","type":"documentAdditionOrUpdate","enqueuedAt":"2026-10-16T15:35:36.723618979Z"}

sleep 3 && docker compose exec -T meilisearch curl -s "http://localhost:7700/indexes/books/documents/1" -H "Authorization: Bearer q1w2e3r4t5y6u7i8o0p"

实测输出：

{"id":1,"title":"部署验证用书"}

五、数据持久化说明

5.1 数据落盘位置

镜像内默认数据目录为 /meili_data，本方案已 bind mount 到宿主机 ./meili_data。启动后查看目录结构：

ls /opt/meilisearch/meili_data/

实测输出：

data.ms
dumps

data.ms：LMDB 数据库文件（全部索引数据）；
dumps：dump 导出文件的默认输出目录。

5.2 重建实例验证数据保留

down 会删除容器与网络但保留 bind mount 目录，up 重新创建后数据仍在——实测验证：

docker compose down && docker compose up -d

实测输出（节选）：

 Container meilisearch  Stopping
 Container meilisearch  Stopped
 Container meilisearch  Removed
 Container meilisearch  Created
 Container meilisearch  Started

重新查询之前写入的文档：

sleep 5 && docker compose exec -T meilisearch curl -s "http://localhost:7700/indexes/books/documents/1" -H "Authorization: Bearer q1w2e3r4t5y6u7i8o0p"

实测输出：

{"id":1,"title":"部署验证用书"}

docker compose ps

实测输出：

NAME          IMAGE                          COMMAND                  SERVICE       CREATED         STATUS                   PORTS
meilisearch   getmeili/meilisearch:v1.55.0   "tini -- /bin/sh -c …"   meilisearch   6 seconds ago   Up 5 seconds (healthy)   0.0.0.0:7700->7700/tcp, [::]:7700->7700/tcp

数据完整保留且服务重新进入 healthy 状态。

⚠️ 注意：docker compose down -v 才会清理卷，本方案用的是 bind mount（普通 down 永不删除 ./meili_data）；但直接 rm -rf ./meili_data 会永久删除数据，操作前务必先导出 dump。

六、环境变量表

MeiliSearch 的全部 CLI 参数都有对应的 MEILI_* 环境变量，Compose 场景通过 environment: 注入。本部署涉及与常用变量如下（完整参数解析见《MeiliSearch 1.55.0 配置参数详解》）：

环境变量	本文取值	默认值	说明
MEILI_MASTER_KEY	q1w2e3r4t5y6u7i8o0p	无	实例主密钥，production 模式必填且 ≥16 字节
MEILI_ENV	production	development	运行环境，production 日志更严格
MEILI_NO_ANALYTICS	true	false	关闭匿名遥测
MEILI_DB_PATH	/meili_data（镜像默认）	/meili_data	数据库落盘路径
MEILI_HTTP_ADDR	0.0.0.0:7700（镜像默认）	localhost:7700	容器内需监听 0.0.0.0 才能被端口映射访问
MEILI_DUMP_DIR	dumps/（相对 db-path）	dumps/	dump 输出目录
MEILI_LOG_LEVEL	INFO（默认）	INFO	日志级别 OFF/ERROR/WARN/INFO/DEBUG/TRACE

💡 说明：镜像的 entrypoint 已内置 --http-addr 0.0.0.0:7700 与 --db-path /meili_data 的容器化默认值，因此 compose 文件里无需再显式设置这两项；若自定义了 MEILI_HTTP_ADDR，必须保证监听 0.0.0.0 而不是 127.0.0.1，否则端口映射后宿主机无法访问（这是容器部署最常见的故障点之一）。

七、配置参数说明

需要修改 MeiliSearch 行为时优先用环境变量（如第六章表格）；参数较多时可用 TOML 配置文件：将 config.toml 放到部署目录，compose 里追加挂载并指定路径：

    volumes:
      - ./meili_data:/meili_data
      - ./config.toml:/config.toml:ro
    environment:
      MEILI_CONFIG_FILE_PATH: "/config.toml"

config.toml 键名与 CLI 参数一一对应（连字符改下划线），例如：

env = "production"
db_path = "/meili_data"
http_addr = "0.0.0.0:7700"
master_key = "q1w2e3r4t5y6u7i8o0p"
log_level = "INFO"

配置优先级为命令行参数 > 环境变量 > TOML 文件，同一参数高层覆盖低层（实测验证过程见《MeiliSearch 1.55.0 配置参数详解》第三章）。

八、常用运维命令

以下命令均在部署目录 /opt/meilisearch 内执行，实测回显见第四章与第五章对应小节：

docker compose ps                  # 查看实例状态（healthy 与否）
docker compose logs -f --tail 100  # 实时查看最近 100 行日志
docker compose stop                # 停止（保留容器）
docker compose start               # 启动已停止的容器
docker compose restart             # 重启
docker compose down                # 停止并删除容器与网络（保留数据目录）
docker compose pull                # 拉取新版本镜像（配合升级）

升级版本的标准流程：修改 docker-compose.yml 中 image 的版本 tag → docker compose pull → docker compose up -d（会重建实例）；升级前先用 POST /dumps 导出备份（见《MeiliSearch 1.55.0 进阶实战与运维》）。

查看启动日志确认运行正常（healthcheck 每 15 秒探测一次，日志中有对应记录即为健康）：

docker compose logs --tail 2

实测输出：

meilisearch  | 2026-10-16T15:55:06.981933Z  INFO HTTP request{method=GET host="localhost:7700" route=/health query_parameters= user_agent=curl/8.14.1 status_code=200}: meilisearch: close time.busy=37.3µs time.idle=9.27µs
meilisearch  | 2026-10-16T15:55:22.008042Z  INFO HTTP request{method=GET host="localhost:7700" route=/health query_parameters= user_agent=curl/8.14.1 status_code=200}: meilisearch: close time.busy=37.0µs time.idle=8.76µs

九、常见问题（FAQ）

Q1：docker compose ps 一直显示 (health: starting) 或 (unhealthy)。

排查：先看业务端口是否可用 curl -s http://127.0.0.1:7700/health；端口可用而 healthcheck 失败，多是 healthcheck 的 test 命令问题——本方案使用镜像自带 curl（实测镜像内 /usr/bin/curl 存在），若换成 wget 需按 wget 的退出码语义写法。start_period 内的失败不会计入 retries，服务冷启动慢时可调大。

Q2：宿主机 curl 127.0.0.1:7700 连接被拒绝。

按顺序排查：docker compose ps 确认实例 Up 且端口映射存在（PORTS 列应有 0.0.0.0:7700->7700/tcp）；确认没有把 MEILI_HTTP_ADDR 设成 127.0.0.1:7700（容器内回环地址不参与端口映射，必须 0.0.0.0，见第六章 💡 说明）。

Q3：启动即退出，日志报 You must provide a master key... 或 The master key must be at least 16 bytes...。

production 模式必须提供 ≥16 字节的 MEILI_MASTER_KEY（实测报错与解决见《MeiliSearch 1.55.0 Ubuntu 22.04 安装指南》Q2，行为一致）。修改 environment 后需 docker compose up -d 重建实例。

Q4：升级镜像后数据"丢失"。

数据没有丢：新版实例启动时若 MEILI_DB_PATH 与旧版不一致（例如自定义时写错路径），会挂载到空目录。核对 compose 里 volumes 与 MEILI_DB_PATH 是否仍指向 ./meili_data:/meili_data；如确认要全新开始，也请先把 ./meili_data 备份再操作。

Q5：多个 MeiliSearch 实例端口冲突。

修改 compose 的 ports 左侧宿主机端口（如 "17700:7700"），容器内端口不变；两个实例分别使用不同部署目录与 ./meili_data 数据目录。

十、参考链接

官方 Docker 部署文档：https://www.meilisearch.com/docs/learn/self_hosted/install_meilisearch_with_docker
官方镜像仓库：https://hub.docker.com/r/getmeili/meilisearch
GitHub 仓库：https://github.com/meilisearch/meilisearch
Compose 文件参考：https://docs.docker.com/reference/compose-file/
相关文档：《MeiliSearch 1.55.0 Ubuntu 22.04 安装指南》《MeiliSearch 1.55.0 配置参数详解》《MeiliSearch 1.55.0 进阶实战与运维》