Wanderer项目中的MeiliSearch索引迁移问题分析与解决

问题背景

在Wanderer项目从v0.8.2升级到v0.12.0版本后，用户遇到了两个主要的技术问题：

1. 在/trails页面无法显示任何已保存的路线记录
2. 系统日志中频繁出现关于"elevation_loss"属性不可过滤的错误提示

错误现象分析

系统日志显示的关键错误信息表明，MeiliSearch搜索引擎无法处理包含"elevation_loss"属性的过滤查询。错误明确指出，该属性未被配置为可过滤属性，而系统当前可用的过滤属性列表为：shares、_geo、public、distance、elevation_gain、date、difficulty、author、completed和category。

此外，还出现了关于经度值超出有效范围的错误（-220.74320793206138），这通常表示地理坐标数据存在异常。

根本原因

经过深入分析，发现问题源于数据库迁移未正确执行。具体来说，v0.10.1版本引入了一个重要的数据库迁移（1731158298_update_sortable_filterable_attributes.go），该迁移本应将"elevation_loss"属性添加为可过滤属性，但在升级过程中未能成功应用。

另一个相关因素是，在v0.10.1版本之前创建的路线记录，"elevation_loss"属性默认为0，需要通过编辑并重新保存来更新这些记录。

解决方案

针对这一问题，我们提供了两种修复方案：

1. 手动添加过滤属性： 直接通过MeiliSearch的管理接口将"elevation_loss"属性配置为可过滤属性。这种方法适用于熟悉MeiliSearch管理操作的技术人员。

2. 重新应用数据库迁移： 进入PocketBase容器内部，执行以下命令：

   ./pocketbase migrate down 22 && ./pocketbase migrate up
   

   其中数字22表示需要回退的迁移数量，确保包含前述的关键迁移。执行前务必备份数据。

补充问题与解决

在解决主要问题后，还发现了一个用户界面相关的次要问题：/trails页面默认不显示任何路线记录，需要先选择至少一个过滤条件（如类别或难度）才能显示结果。

临时解决方案是通过界面操作（如更改排序或显示选项）来触发本地存储的设置保存。长期解决方案需要等待项目维护者发布补丁修复此界面行为。

经验总结

1. 在升级涉及数据库变更的版本时，务必确认所有迁移已正确执行
2. 对于搜索引擎索引属性的变更，需要同时考虑新数据的处理和旧数据的兼容
3. 复杂的系统升级建议采用分阶段逐步升级的方式，便于问题定位
4. 重要操作前进行数据备份是必不可少的步骤

通过系统性地分析和解决这些问题，不仅恢复了系统功能，也为类似的技术升级场景提供了有价值的参考经验。