Hoarder项目Worker服务启动故障排查指南

现象描述

在部署Hoarder项目时，用户发现后台任务队列完全停滞，包括索引和推理功能均无法正常工作。系统日志仅显示基础服务启动信息，缺乏worker进程的具体运行日志。管理界面显示"Worker service not detected"警告提示，且存在多个重复的待处理任务。

故障分析

通过日志分析可发现以下关键现象：

1. 容器日志中缺失worker进程的启动信息
2. 系统仅输出web服务启动成功的消息
3. 管理界面检测不到worker服务

根本原因在于使用了错误的Docker镜像配置。用户误使用了hoarder-web镜像而非完整的hoarder镜像，导致worker组件未被包含在部署环境中。

解决方案

1. 修正Docker镜像配置： 将docker-compose.yml文件中的镜像名称从：

   image: ghcr.io/hoarder-app/hoarder-web:latest
   

   修改为：

   image: ghcr.io/hoarder-app/hoarder:latest
   

2. 环境变量调整建议：

   • 对于网络受限环境，建议设置CRAWLER_ENABLE_ADBLOCKER=false以避免依赖外部资源
   • 确保DATA_DIR配置与volume挂载路径一致

3. 服务重启：

   docker-compose down && docker-compose up -d
   

技术原理

Hoarder项目的现代版本采用一体化容器设计，将web界面和worker服务整合在同一个容器中。这种设计相比早期分离式架构具有以下优势：

• 简化部署流程
• 降低组件间通信开销
• 确保版本一致性
• 便于资源监控和管理

worker服务主要负责：

• 后台任务队列处理
• 内容索引构建
• AI推理任务执行
• 定时作业调度

最佳实践建议

1. 部署时验证容器组件完整性
2. 定期检查后台任务执行状态
3. 合理设置任务并发数
4. 建立完善的日志监控机制
5. 保持镜像版本更新

故障预防

为避免类似问题，建议：

1. 使用官方提供的标准docker-compose模板
2. 部署完成后检查所有必要服务状态
3. 对关键组件设置健康检查
4. 建立部署检查清单
5. 定期review容器日志

通过以上措施，可以确保Hoarder项目的各项功能正常运行，充分发挥其作为知识管理工具的价值。