WorkBuddy搜索失效主因是Elasticsearch服务未正确连接或配置错误，需依次排查：服务状态与端口、网络绑定与CORS、Java版本与JVM内存、索引mapping结构、防火墙及容器网络。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已安装WorkBuddy但搜索功能无法返回结果、持续显示“正在思考…”或报错“模型调用失败”，则极可能源于其依赖的Elasticsearch后端服务未正确连接或配置失效。WorkBuddy的本地搜索能力完全依托于本地运行的Elasticsearch实例提供索引与检索支持，若客户端无法访问该服务，所有基于内容的搜索操作将直接中断。以下是针对性排查与修复步骤：
一、验证Elasticsearch服务是否已启动并监听正确端口
Elasticsearch必须处于活跃运行状态，且明确绑定到WorkBuddy所预期的地址与端口（默认为http://localhost:9200）。若服务未启动、崩溃退出或监听地址被限制，WorkBuddy将无法建立初始连接。
1、在终端执行curl -X GET http://localhost:9200/，观察是否返回包含"name"、"version"和"tagline"字段的JSON响应。
2、若返回Connection refused或超时，说明服务未运行。请根据您的安装方式执行对应启动命令：Mac Homebrew用户运行brew services start elasticsearch；Linux手动解压用户进入bin/目录执行./elasticsearch -d；Docker用户确认容器状态为Up且端口映射正常（docker ps | grep 9200）。
3、若返回Could not resolve host，检查URL中是否遗漏http://协议头——NEST及WorkBuddy客户端均要求完整URI格式，new Uri("9200")非法，必须为new Uri("http://localhost:9200")。
二、核对Elasticsearch网络绑定与跨域设置
WorkBuddy客户端运行于本地桌面环境，需通过HTTP协议向Elasticsearch发起请求。若Elasticsearch仅绑定127.0.0.1或localhost，在部分系统（如macOS Monterey+或启用了IPv6优先策略）下可能导致连接不稳定；若未启用CORS，则浏览器内嵌搜索界面可能被拦截。
1、打开config/elasticsearch.yml文件，确认存在且未注释以下两行：network.host: 0.0.0.0与http.port: 9200。
2、在同一配置文件中，追加CORS开放配置：http.cors.enabled: true与http.cors.allow-origin: "*"（生产环境建议限定为WorkBuddy前端域名）。
3、保存后重启Elasticsearch服务，并再次执行curl http://localhost:9200/验证响应是否恢复。
三、检查Java运行时与JVM内存配置兼容性
WorkBuddy调用的Elasticsearch 8.x要求Java 17+运行时环境，且JVM堆内存设置不当会导致服务启动后迅速OOM退出，表现为进程存在但9200端口无响应。
1、在终端执行java -version，确认输出含17.字样；若为Java 8、11或21，必须降级或升级至JDK 17（推荐OpenJDK 17.0.2+或Oracle JDK 17.0.1+）。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
2、编辑config/jvm.options，将-Xms与-Xmx值设为相同且不超过物理内存50%，例如-Xms512m与-Xmx512m；避免使用-Xms1g -Xmx4g类不平衡配置。
3、启动服务后，立即执行ps aux | grep elasticsearch | grep -v grep，确认Java进程参数中包含所设堆大小。
四、确认索引结构与字段映射匹配WorkBuddy数据模型
WorkBuddy向Elasticsearch写入文档时，依赖预定义的mapping结构（如content、title、file_path等字段）。若索引不存在、mapping缺失或字段类型不匹配（例如content被误设为keyword而非text），全文搜索将静默失败——无报错，但Hits.Count恒为0。
1、使用curl -X GET "http://localhost:9200/workbuddy_docs/_mapping?pretty"检查目标索引的mapping定义。
2、确认关键字段如content的类型为text，且已启用ik_smart中文分词器（若处理中文内容）；若为keyword类型，需重建索引并指定"type": "text", "analyzer": "ik_smart"。
3、若索引不存在，WorkBuddy首次搜索时应自动创建，但需确保其具备create_index权限；否则手动创建：curl -X PUT "http://localhost:9200/workbuddy_docs" -H "Content-Type: application/json" -d '{"mappings":{"properties":{"content":{"type":"text","analyzer":"ik_smart"},"title":{"type":"text","analyzer":"ik_smart"}}}}'。
五、排查防火墙、SELinux及Docker网络隔离
即使Elasticsearch进程运行且端口监听，操作系统级防护机制或容器网络策略仍可拦截WorkBuddy发起的HTTP请求，导致连接被拒绝或超时。
1、Linux用户执行sudo ufw status，若状态为active，运行sudo ufw allow 9200放行端口。
2、CentOS/RHEL用户检查SELinux：执行getenforce，若返回Enforcing，临时设为宽容模式sudo setenforce 0测试；如确认为干扰源，后续需添加semanage port -a -t http_port_t -p tcp 9200永久放行。
3、Docker用户确认运行命令中包含-p 9200:9200，且未遗漏-e "discovery.type=single-node"；执行docker network inspect bridge | grep -A 10 "elasticsearch"验证容器IP是否可达，再从宿主机执行curl http://[容器IP]:9200/直连测试。
