367
0
2
Meilisearch 在 1Panel 中快速升级
2026 年 10 月更新：本文的方法已经过时，留作记录。
- 1Panel 已经内置这个参数：2025 年 12 月起，1Panel 应用商店的 Meilisearch 模板默认开启 dumpless 升级。现在模板里是环境变量
MEILI_UPGRADE_DB: true，在 1Panel 里直接点「升级」就行，不需要再改 docker-compose。我的实例现在已经通过 1Panel 升级到 v1.55。- 参数已经改名：Meilisearch v1.51（2026 年 7 月）把 dumpless 升级转为正式功能，
--experimental-dumpless-upgrade改名为--upgrade-db，官方 release notes 标注为 breaking change。如果你按本文在 command 里手动加了旧参数，升级到 v1.51 及以后之前一定要删掉，否则容器可能因为无法识别参数而起不来。- 只支持 v1.12 及以后创建的数据库。更老的版本仍然要用 dump 方式迁移。
- 升级前还是建议先打快照：官方文档明确说数据库升级不是原子操作，出问题时需要从快照恢复。
前言
我用 1Panel 管理 Meilisearch，升级版本时遇到了问题。这里记录正确的升级方法，避免直接换镜像导致的兼容性错误。
问题背景
把 Meilisearch 从 v1.19.0 升级到 v1.19.1 时，我直接在 1Panel 里改了镜像版本，结果容器起不来，报错如下：
error=Your database version (1.19.0) is incompatible with your current engine version (1.19.1).
To migrate data between Meilisearch versions, please follow our guide on
https://www.meilisearch.com/docs/learn/update_and_migration/updating.可见 Meilisearch 对数据库版本有严格的兼容性要求，即使是补丁版本，也不能直接换镜像升级。
升级方式选择
根据官方文档，Meilisearch 有两种升级方式：传统的 dump 方式，以及不需要 dump 的方式（dumpless upgrade）。
方式一：用 Dump 升级（传统方式）
- 导出数据 dump
- 升级 Meilisearch 版本
- 重新导入 dump
- 步骤多，耗时长
方式二：Dumpless 升级（推荐）
- 加上
--experimental-dumpless-upgrade参数，或设置MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE环境变量（v1.51 起分别改名为--upgrade-db和MEILI_UPGRADE_DB） - 不用导出导入数据，升级更方便
考虑到方便和效率，我选了第二种。
实施步骤
1. 先做备份
dumpless 升级当时还是实验性功能，官方建议先创建快照：
curl -X POST 'http://localhost:7700/snapshots' \
-H 'Authorization: Bearer YOUR_MASTER_KEY'成功响应示例：
{
"taskUid": 5,
"indexUid": null,
"status": "enqueued",
"type": "snapshotCreation",
"enqueuedAt": "2025-08-29T06:18:55.613950635Z"
}确认快照任务已完成：
curl -H 'Authorization: Bearer YOUR_MASTER_KEY' \
'http://localhost:7700/tasks/5'完成后的响应示例：
{
"uid": 5,
"batchUid": 4,
"indexUid": null,
"status": "succeeded",
"type": "snapshotCreation",
"canceledBy": null,
"error": null,
"duration": "PT0.021752583S",
"enqueuedAt": "2025-08-29T06:18:55.613950635Z",
"startedAt": "2025-08-29T06:18:55.615240686Z",
"finishedAt": "2025-08-29T06:18:55.636993269Z"
}2. 在 1Panel 中配置升级参数
在 1Panel 管理界面中：
- 找到 Meilisearch 应用，点击「升级」
- 选择「自定义 docker-compose 文件」
- 修改
command，加上升级参数：
networks:
1panel-network:
external: true
services:
meilisearch:
command: |
sh -c ' if [ "${MEILI_NO_ANALYTICS}" = "true" ]; then
/bin/meilisearch --experimental-dumpless-upgrade
else
/bin/meilisearch --no-analytics --experimental-dumpless-upgrade
fi'
container_name: ${CONTAINER_NAME}
# 保留其他现有参数现在的 1Panel 模板已经改为在
environment里设置MEILI_UPGRADE_DB: true，不需要再手动做这一步。
3. 执行升级并观察
确认配置后，1Panel 会自动执行升级。Meilisearch 启动后会自动创建一个 upgradeDatabase 任务。
查询升级任务：
curl -H 'Authorization: Bearer YOUR_MASTER_KEY' \
'http://localhost:7700/tasks?types=upgradeDatabase'升级任务响应示例：
{
"results": [
{
"uid": 6,
"batchUid": 5,
"indexUid": null,
"status": "succeeded",
"type": "upgradeDatabase",
"canceledBy": null,
"details": {
"upgradeFrom": "v1.19.0",
"upgradeTo": "v1.19.1"
},
"error": null,
"duration": "PT0.005163678S",
"enqueuedAt": "2025-08-29T06:28:54.104574526Z",
"startedAt": "2025-08-29T06:28:54.115044244Z",
"finishedAt": "2025-08-29T06:28:54.120207922Z"
}
],
"total": 1,
"limit": 20,
"from": 6,
"next": null
}4. 验证升级结果
查看版本：
curl -H 'Authorization: Bearer YOUR_MASTER_KEY' \
'http://localhost:7700/version'版本信息响应示例：
{
"commitSha": "abc123def456",
"commitDate": "2024-12-15T10:30:00.000000000Z",
"pkgVersion": "1.19.1"
}检查服务健康状态：
curl -H 'Authorization: Bearer YOUR_MASTER_KEY' \
'http://localhost:7700/health'健康状态响应示例：
{
"status": "available"
}确认索引完整：
curl -H 'Authorization: Bearer YOUR_MASTER_KEY' \
'http://localhost:7700/indexes'索引列表响应示例：
{
"results": [
{
"uid": "products",
"createdAt": "2025-08-28T10:15:30.000000000Z",
"updatedAt": "2025-08-29T06:28:54.120207922Z",
"primaryKey": "id"
}
],
"offset": 0,
"limit": 20,
"total": 1
}5. 清理配置
升级成功后可以删掉临时加的升级参数，保持配置整洁。我当时没删，因为不确定有没有副作用。后来证明，这个参数平时一直开着也没问题：数据库版本和程序一致时，它不会做任何事。1Panel 现在的模板就是默认开着的。
常见错误
认证错误
缺少或填错 Master Key 时，会收到这样的响应：
{
"message": "The Authorization header is missing. It must use the bearer authorization method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}任务类型写错
任务类型写错时（比如写成 databaseUpgrade），会收到：
{
"message": "Invalid value in parameter `types`: `databaseUpgrade` is not a valid task type. Available types are `documentAdditionOrUpdate`, `documentEdition`, `documentDeletion`, `settingsUpdate`, `indexCreation`, `indexDeletion`, `indexUpdate`, `indexSwap`, `taskCancelation`, `taskDeletion`, `dumpCreation`, `snapshotCreation`, `export`, `upgradeDatabase`.",
"code": "invalid_task_types",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#invalid_task_types"
}总结
在 1Panel 中用 dumpless 方式升级 Meilisearch，关键点是：
- 先备份：升级前一定要创建快照
- 配好参数：v1.51 之前用
--experimental-dumpless-upgrade，之后用--upgrade-db（环境变量MEILI_UPGRADE_DB）。新版 1Panel 模板已经内置 - 盯住任务：通过 API 查看
upgradeDatabase任务的状态 - 验证结果：确认版本、健康状态和索引都正常
- 注意改名：手动加过旧参数的，升到 v1.51 之前记得删掉
