SolidQueue 中周期性任务调度失败的排查与解决

问题现象

在使用 SolidQueue 作为后台任务处理系统时，开发者发现配置的周期性任务突然停止了自动调度。这些任务包括每分钟执行的 GenerateJourneysJob 和每15分钟执行的 UpdateBoatDesignsJob 等，虽然在管理界面中能看到任务定义，但实际并未按计划执行。

错误分析

通过日志检查发现，系统在尝试执行周期性任务时抛出了一个关键错误："ArgumentError No unique index found for [:task_key, :run_at]"。这个错误表明 SolidQueue 在尝试创建周期性任务执行记录时，无法找到预期的唯一索引约束。

技术背景

SolidQueue 使用数据库表来管理周期性任务的执行记录。根据设计，solid_queue_recurring_executions 表应该包含一个针对 task_key 和 run_at 字段的唯一索引，这是为了防止同一个任务在相同时间被重复执行。

问题根源

虽然 SolidQueue 的迁移文件明确设置了这一唯一索引约束，但在实际环境中，该索引可能因为以下原因丢失了唯一性约束：

1. 数据库迁移过程中出现异常但未被注意到
2. 手动执行的数据库操作意外修改了索引属性
3. 数据库恢复操作导致约束丢失

解决方案

确认问题后，可以通过以下步骤修复：

1. 检查当前数据库中的索引定义
2. 创建一个新的迁移文件，明确重建唯一索引：

class AddUniqueIndexToRecurringExecutions < ActiveRecord::Migration[7.1]
  def change
    remove_index :solid_queue_recurring_executions, [:task_key, :run_at]
    add_index :solid_queue_recurring_executions, [:task_key, :run_at], unique: true
  end
end

3. 运行迁移并验证索引是否已正确创建

预防措施

为避免类似问题再次发生，建议：

1. 在部署新版本前，验证数据库约束是否完整
2. 设置数据库监控，定期检查关键约束状态
3. 在关键业务逻辑中添加防御性代码，捕获并记录约束违规异常

总结

数据库约束的完整性对于任务队列系统的可靠运行至关重要。这次问题的解决不仅修复了周期性任务调度功能，也提醒我们在系统维护中需要关注数据库层面的健康状态。对于使用 SolidQueue 的开发者，建议定期检查系统表结构是否符合预期，特别是在升级或迁移操作后。