issue: knowledge sync/cleanup swallows vector DB errors — file row is deleted, its KB vectors stay, outdated content remains searchable and

快速结论：当知识库同步接口 POST /api/v1/knowledge/{id}/sync/cleanup 在删除文件向量时遇到向量库异常（重启、OOM、超时等），异常被吞掉，接口仍返回 200 {"status": true} 并删除文件记录，导致旧版本向量永久残留、可被检索且无 API 路径清理。优先排查同步期间向量库是否可用，并核对文件记录删除后向量点是否真正消失。

适用环境：Open WebUI v0.13.0（Docker 镜像 ghcr.io/open-webui/open-webui:v0.13.0）及 dev 分支（commit 393dd668）；生产环境首次出现于 v0.12.5；向量库为 Qdrant v1.17.1，多租户模式（默认）；Ubuntu 26.04（Linux 7.0）、Docker 29.9.2；默认 SQLite 存储。

最快修复方案：暂无确认的一步修复方案。Issue 中维护者关闭为“基础设施问题”，未提供代码修复；报告者确认的可行做法是确保同步任务不在向量库停止或备份窗口内运行。

注意事项：避开备份窗口只能减少触发概率，不能消除问题：任何一次向量删除调用的瞬时失败（重启、OOM kill、超时）都会产生同样的残留向量，且后续 diff 会把该路径报告为 unmodified_count: 1，客户端不再重试清理。Issue 中的诉求（失败时不返回成功、不删文件记录或至少记录日志）未被采纳，该行为在报告版本中仍存在。

问题场景

在 Open WebUI 中使用外部同步客户端维护知识库（KB）时，客户端按“diff → 清理旧 stale_file_id → 上传新版本”的流程替换变动的文件。若 cleanup 阶段向量库短暂不可用，例如夜间同步在开机后追赶、而备份任务恰好把 Qdrant 停止了约 100 秒，则旧文件的向量删除失败但被静默忽略。生产环境中两个被替换的文件共残留 175 个孤立向量点（148 + 27），旧版本内容仍可被检索返回。

报错原文

issue: knowledge sync/cleanup swallows vector DB errors — file row is deleted, its KB vectors stay, outdated content remains searchable and is never cleaned up

POST /api/v1/knowledge/{id}/sync/cleanup → 200 {"status": true}  (向量删除失败，无错误日志)
GET /api/v1/files/{old_id} → 404  (文件记录已被删除)
sync/diff → unmodified_count: 1  (旧文件 id 不再出现在 diff 中)

原因分析

可能原因：cleanup 接口把向量库删除调用包在 try: ... except Exception: pass 中，异常被吞掉且不记录日志，随后无论向量删除是否成功，都会继续解除关联并删除文件记录。于是向量库中的点变为无文件记录引用的孤儿数据，仍留在 open-webui_knowledge 集合中并可被检索命中。

同一讨论中提到，其他删除路径（DELETE /files/{id}、knowledge/{id}/file/remove）至少会记录异常，而 cleanup 路径连日志都没有，因此故障期间容器日志中错误行数为 0，难以发现。维护者认为向量库不可达期间无法删除向量属于部署侧问题（同步不应在向量库停止期间运行）；报告者则认为问题在于失败被报告为成功且文件记录被丢弃，任何瞬时失败均可触发。

环境排查

确认 Open WebUI 版本与 commit（v0.13.0 / dev 393dd668 / v0.12.5 均出现过）。
确认 VECTOR_DB=qdrant 及 Qdrant 版本（报告中为 v1.17.1）与是否为多租户模式。
确认存储后端为默认 SQLite。
确认同步任务运行时间是否与容器重启、备份、OOM kill、Qdrant 停机窗口重叠。
检查容器日志中 cleanup 期间是否有错误行（本 Issue 中为 0，说明日志不可作为检测手段）。
核对 Qdrant 中 open-webui_knowledge 集合的点数量是否多于当前文件记录数。

解决步骤

调整部署调度：不要在意向量库停止、重启或备份期间运行知识库同步任务，避开备份窗口（报告者已采用的措施）。
排查并消除向量库瞬时不可用的诱因，例如备份任务与同步任务的时间冲突、资源不足导致的 OOM kill、以及到达 Qdrant 的网络超时。
对曾发生故障的时间段，按文件 id 逐项比对：若 GET /api/v1/files/{old_id} 返回 404，但仍能在检索中命中旧版本内容，说明存在残留向量。
对确认的残留向量进行人工清理（Issue 未给出具体命令，需结合自身 Qdrant 部署执行），并在清理前保留记录以便核对。
若在向量库运行健康、无停机的情况下仍能复现，按维护者要求携带复现步骤和日志提交新 Issue。

验证方法

在向量库可用时执行一次完整的“上传旧版本 → cleanup → 上传新版本”循环：清理后旧文件 id 在 open-webui_knowledge 中的点数量应从 4 降为 0，新文件 id 保持 4 个点；用一个只存在于旧版本中的短语进行检索，不应再返回旧分块；下一次 sync/diff 不应再出现指向孤立向量的 unmodified_count 记录。