Tolgee平台数据库索引损坏导致翻译编辑失败的故障排查与修复

在Tolgee本地化平台的实际使用过程中，数据库迁移后可能会出现一个隐蔽但影响严重的故障现象：当用户尝试编辑特定键名的翻译时，系统返回"Not found"错误。本文将通过一个真实案例，深入分析该问题的技术原理和解决方案。

故障现象分析

用户报告在将PostgreSQL数据库迁移到新服务器后，出现以下异常行为：

1. 部分翻译键名在特定语言环境下无法编辑，提交时前端显示"Not found"提示
2. 后端API返回404状态码及{"code":"key_not_found"}错误信息
3. 通过文件导入方式却能成功添加这些"找不到"的翻译
4. 问题键名没有固定模式，影响范围随机分布在不同的语言组合中

技术排查过程

初步诊断

通过开启SQL日志记录，我们捕获到执行失败的查询语句：

SELECT k1_0.id,k1_0.name 
FROM key k1_0 
LEFT JOIN namespace n1_0 ON n1_0.id=k1_0.namespace_id 
WHERE k1_0.name=? AND k1_0.project_id=? 
AND (n1_0.name=? OR (k1_0.namespace_id IS NULL AND ? IS NULL))

查询分解测试

在psql客户端中逐步测试发现一个异常现象：

• 单独使用键名、项目ID或命名空间条件都能正确返回结果
• 但当组合使用键名+项目ID+命名空间条件时，查询意外返回空结果集

根本原因定位

这种矛盾现象通常指向数据库索引损坏。PostgreSQL中索引损坏可能导致：

1. 查询优化器选择错误的执行计划
2. 索引与实际数据不一致
3. 组合条件查询时出现错误结果过滤

解决方案

执行数据库重建索引命令彻底解决问题：

REINDEX DATABASE postgres;

经验总结

1. 数据库迁移风险：跨服务器迁移数据库时，索引是最容易出问题的部分

2. 故障特征识别：当查询单独条件正常但组合条件异常时，应优先怀疑索引问题

3. 预防措施：

   • 迁移后建议执行REINDEX操作
   • 定期检查数据库健康状况
   • 考虑使用pg_cron设置定期维护任务

4. Tolgee平台特性：

   • 依赖命名空间(namespace)的多级查询
   • 键名(name)+项目ID(project_id)+命名空间(namespace)构成复合查询条件
   • 索引损坏会直接影响核心翻译功能

通过这次故障排查，我们不仅解决了具体问题，更深入理解了Tolgee平台与数据库的交互机制，为后续运维工作积累了宝贵经验。