前言

在使用 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 环境变量
无需导出导入数据，升级过程更加便捷

考虑到便捷性和效率，选择第二种 dumpless 升级方式。

实施步骤

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}
      # 保留其他现有参数

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. 清理配置

升级成功后，可以移除临时的升级参数，保持配置整洁（我暂时没有移除，不清楚是否有副作用）。

错误响应处理

认证错误

如果 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"
}

任务类型错误

如果使用错误的任务类型查询，会收到：

{
  "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"
}