中级 12 分钟每日计划

Open WebUI:将文件夹同步到 oikb

打开的笔记本电脑发出绿光,照亮深色书桌。

只要文件夹内容不变,手动将文档导入 Open WebUI 知识库就能正常工作。一旦文件夹持续变化(流程更新、新增笔记、移除文件),知识库就会逐渐偏离,模型会基于过时版本作答。借助官方文档 Ecosystem 栏目中介绍的工具 oikb 将文件夹与 Open WebUI 同步,正是为了纠正这种偏差。本指南介绍增量同步的原理、它可能删除哪些内容,以及一套稳妥的流程:备份、限定范围、测试知识库。编辑部未对其进行测试。

作者: Mohamed Meguedmi·更新于 2026-11-18·已在 Windows、macOS 和 Linux 上测试
!
本指南不照搬任何 oikb 命令
编辑部曾于 30/10/2026 查阅官方页面 docs.openwebui.com/ecosystem/knowledge-base-sync/,但在撰写本文时(18/11/2026)未能再次查阅。与其凭记忆复述可能已经变化的语法,本指南将 oikb 的安装和具体选项交由该页面说明。这里给出的命令涉及备份、范围和检查,这些都不依赖于该工具。

#为什么要将文件夹与 Open WebUI 同步

Open WebUI 的知识库(Knowledge)是一组被切分成段落并以嵌入(embeddings)形式建立索引的文件集合。当您将该知识库关联到某个模型,或在聊天中用 # 引用它时,Open WebUI 会检索与问题相近的段落,并将其加入上下文。《无需编程,使用 Ollama 搭建本地 RAG》指南详细介绍了这一机制在界面层面的运作方式。

问题会随着时间推移而显现。磁盘上被修改的文件在知识库中不会随之修改:Open WebUI 保留的是导入时的版本。从文件夹中删除的文件仍然可以被检索到。新文件在有人导入之前并不存在于知识库中。对于只有几份文档的文件夹,重新导入即可应付。但对于每周都在变化的内部流程或笔记文件夹,人们会忘记手动重新导入,助手便会言之凿凿地引用一份已被废弃的流程。

同步工具可以将这项工作自动化:它将文件夹与已上传的内容进行比较,只传输差异部分。这就是所谓的增量同步。代价是,一个能自动添加和替换的工具,同样可能自动移除。这是最需要注意的一点。

#增量同步:源、目标、状态

打造专属 AI 助手的完整套件。

借助我们的经验和引导式路径,打造你的本地助手,在日常中使用你的 AI。

  • 在线空间,终身可用
  • PDF + 文件
  • 30 天内退款

无论使用何种工具,此类同步都依赖于三个要素。理解它们,有助于带着正确的问题去阅读 oikb 的文档。

源
以其内容为准的本地(或挂载的)文件夹。其中在所选范围内的所有内容,最终都会进入知识库。因此必须谨慎划定它的范围:遗留在其中的个人子文件夹会被索引,并可被所有有权访问该知识库的人检索到。
目标
某个特定实例(URL)上 Open WebUI 的某个特定知识库。知识库标识符出错可能会混淆两个语料库,更糟的是,可能导致删除操作作用于错误的知识库。
L'authentification
该工具通过 Open WebUI 的 API,使用与某个账户绑定的密钥进行操作。它继承该账户的权限:该账户能读取、修改或删除的内容,工具同样可以。
状态
为了知道哪些内容发生了变化,工具必须记录它已经上传过的内容(内容指纹、修改日期、本地文件与 Open WebUI 端文件之间的对应关系),或者通过查询知识库来重建这些记录。如果该状态丢失或不一致,工具可能会重新上传全部内容、产生重复项,或错误地解读文件缺失。

基于这些信息,每次运行都会将文件归为四类:新增(需上传)、已修改(需替换)、未变化(忽略)、已从源中消失(从知识库中移除,或根据设置保留)。在运行 oikb 之前,请在其文档中找到以下四个问题的答案:它如何检测修改,它将状态保存在哪里,它是否会移除已消失的文件、通过哪个选项控制,以及它是否提供只显示操作而不执行的模拟模式。

#真正的风险:镜像删除

从知识库中移除源中已不存在的文件的同步是有用的:正是它让已废弃的流程文档消失。但它也会把源端的任何错误变成知识库端的数据丢失。以下是几种现实场景:

磁盘未挂载
该文件夹指向的网络共享或外部磁盘在运行时不存在。挂载点是空的:对工具而言,所有文件都已消失。
路径错误
拼写错误或工作目录变化导致源指向一个空文件夹或其他文件夹。
重新整理
重命名或移动子文件夹可能被视为“全部删除再全部重建”。最终结果可能是正确的,但知识库会被完全重新索引,指向旧文件的链接(如有)也会丢失。
共享知识库
如果其他人在同一知识库中手动添加了文件,严格镜像的工具可能会将这些文件视为不属于源的文件并将其移除。请查阅文档,确认 oikb 是否只处理它自己上传的文件。

由此得出两条规则。首先,同步的知识库应专用于同步:不要在其中手动添加内容。其次,在测试知识库上观察到该工具的行为之前,不要在日常使用的知识库上启用删除功能。

#先决条件

可正常运行的 Open WebUI
一个已更新至最新版本、连接到 Ollama(默认位于 http://localhost:11434)并配置了嵌入模型的实例。《Open WebUI 搭配 Ollama:完整指南》涵盖了安装过程。
专用账户
理想情况下,应使用专为同步创建、作为该知识库所有者的用户账户,而不是管理员账户。这样密钥的权限范围就仅限于该账户所需的内容。
已允许的 API 密钥
视版本而定,管理员需要先在管理设置中启用 API 密钥,用户才能在“设置 > 账户”中生成密钥。具体选项名称因版本而异:请以您所用的版本为准。
一份近期备份
一份经过验证的 Open WebUI Docker 数据卷归档。如果知识库被误清空,这是唯一真正的回退手段。
oikb 特有的前提条件
编程语言、版本和安装方式以官方页面为准。不要自行假定。

#将文件夹与 Open WebUI 同步:5 步流程

  1. 01
    1. 备份实例
    停止容器,归档数据卷,重新启动,计算校验值。包含恢复步骤在内的完整流程见指南《故障后恢复 Open WebUI 和 Ollama》。从未恢复过的备份只是一种假设:至少在一个对照实例上测试一次。
  2. 02
    2. 划定范围
    不要将 oikb 指向整个“文档”文件夹。准备一个发布文件夹,其中只包含要放入知识库的文件,且格式为 Open WebUI 能够提取的格式(文本、Markdown、文本型 PDF 等)。为其编制清单:这是您之后核对知识库中实际收到哪些内容的依据。
  3. 03
    3. 创建测试知识库和密钥
    在“工作空间 > 知识库”中创建一个知识库,例如命名为“essai-sync”。其 ID 会显示在该知识库页面的地址中。为同步账户生成 API 密钥,将其保存在仅您本人可读的文件中,并通过一次简单调用确认它可以正常使用。
  4. 04
    4. 在测试知识库上首次运行
    按照官方页面安装并运行 oikb,目标设为测试知识库,不启用删除;如果工具提供模拟模式,则使用模拟模式。在正式运行之前,先阅读工具列出的操作清单。然后将知识库中的文件数量与您的清单进行比对。
  5. 05
    5. 验证边界情况,然后切换
    在测试知识库上:修改一个文件,新增一个文件,删除一个文件,然后重新运行。确认只有被修改的文件被替换,且被删除的文件的处理方式与文档描述一致。接着暂时清空源(重命名该文件夹),观察工具打算执行哪些操作:这就是“磁盘未挂载”测试。只有在此之后,才将 oikb 指向正式知识库。

第 2 步可以借助 rsync,从工作文件夹构建发布文件夹,只保留特定扩展名的文件。下面的示例会复制 Markdown 和 PDF 文件,保留目录结构,并忽略其他所有内容。它不使用 --delete:从工作文件夹中移除的文件会一直保留在发布文件夹中,直到您手动将其移除,这样在知识库端发生任何删除之前,都需要经过人工决定。

终端——第 2 步:发布文件夹与清单
# Dossier de travail (à adapter) et dossier réservé à la synchronisation
SOURCE=~/Documents/procedures/
PUBLI=~/oikb-publication/
mkdir -p "$PUBLI"

# Simulation d'abord (-n), puis relancer sans -n
rsync -avn --prune-empty-dirs \
  --include='*/' --include='*.md' --include='*.pdf' --exclude='*' \
  "$SOURCE" "$PUBLI"

# Inventaire daté avec empreintes, à garder avec la sauvegarde
cd "$PUBLI" && find . -type f -print0 | sort -z | xargs -0 sha256sum \
  > ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt
wc -l ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt

对于第 3 步,可以在不做任何修改的情况下测试密钥。Open WebUI 的 API 接受通过 Authorization: Bearer 请求头传递的密钥;下面的调用会列出该账户可见的模型。返回 JSON 响应即表示 URL 和密钥均正确;返回 401 或 403 错误则表示密钥无效,或管理员未允许使用 API 密钥。

终端——第 3 步:密钥不进入历史记录,并进行只读测试
# Clé dans un fichier privé, pas dans l'historique du shell
install -m 600 /dev/null ~/.config/oikb-cle
${EDITOR:-nano} ~/.config/oikb-cle

U=http://localhost:3000
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $(cat ~/.config/oikb-cle)" \
  "$U/api/models"

端口 3000 对应最常见的 Docker 命令(-p 3000:8080);请根据您的安装进行调整。oikb 读取密钥的方式(环境变量、命令选项、配置文件)在其文档中有说明:请优先使用环境变量或文件,而不是命令行选项,因为后者会在进程列表和历史记录中保持可见。

→
每个源对应一个知识库
将一个发布文件夹只关联到一个知识库,并为两者使用相同的名称(文件夹和知识库都叫“procedures-qualite”)。如果对某次运行的目标有疑问,仅凭名称就能在错误扩散之前发现问题。

#在不暴露风险的前提下自动化同步

在测试知识库上观察到工具行为后,人们很容易想把同步安排为每小时运行一次。在此之前,请先添加一些不依赖于该工具的防护措施。

每次运行前检查源
一个脚本:如果发布文件夹为空,或其文件数量与上一次清点相比骤降,就拒绝启动同步。这是防范磁盘未挂载的最简单保护措施。
保留日志
将每次运行的输出重定向到带日期的文件中。如果助手给出出人意料的回答,日志可以显示某个文件是何时进入或移出知识库的。
拉长运行间隔
对于每周只变化几次的文档,每天运行一次就足够了,还能减轻计算嵌入的机器上的索引负担。
事前备份,而不只是事后备份
定期备份数据卷,且独立于同步流程。如果某次运行清空了知识库,恢复备份还能同时找回嵌入向量(embeddings),无需全部重新索引。
终端 — 运行前的防护措施
#!/usr/bin/env bash
set -euo pipefail
PUBLI=~/oikb-publication
MIN=10   # seuil à adapter : en dessous, on refuse

N=$(find "$PUBLI" -type f | wc -l)
if [ "$N" -lt "$MIN" ]; then
  echo "$(date -Is) source suspecte : $N fichiers, passage annulé" >&2
  exit 1
fi

# Lancer ici la commande oikb indiquée par la documentation officielle,
# en redirigeant sa sortie vers un journal daté.

此脚本有意不包含 oikb 命令:请从官方页面获取该命令,并粘贴到标注的位置。MIN 阈值是随意设定的;更精细的检查方式是将文件数量与上一次清点结果进行比较,若减少超过一定比例则拒绝执行。

#故障排除

API 返回 401 或 403
密钥已过期、已被吊销,或复制时带上了空格。还要确认管理员允许使用 API 密钥,并且该账户有权访问目标知识库。
已上传但在聊天中找不到的文件
上传和索引是两个步骤。没有文本层的扫描版 PDF 可能会被接受,却无法生成可用的文本片段。在知识库中打开该文件查看提取出的文本;扫描件请先经过 OCR 处理再发布。
知识库中的重复项
这通常表明状态丢失,或者首次运行时所针对的知识库中已包含手动导入的相同文件。请改用一个专供同步使用的空知识库重新开始。
重新索引耗时长
在 Open WebUI 的设置中更换嵌入模型需要重新索引文档。避免同时修改此设置和同步:否则您将无法判断是哪一项导致了差异。
回答仍是旧内容
在知识库中确认旧版本确实已被替换,而不是被并列添加。请开启一个新对话:在现有对话中已引用过的段落会保留在其历史记录中。

#已验证的内容与未验证的内容

本指南未对 oikb 进行任何测试:没有安装,没有运行,也没有测量耗时或数据量。官方文档页面曾于 30/10/2026 在准备本主题时查阅,之后于 18/11/2026 未能再次查阅。备份命令沿用本站恢复指南中的命令;密钥测试使用 Open WebUI API 的 Bearer 标头和 /api/models 路由,需在您的版本上确认。需要向文档求证的问题(变更检测、状态、删除、模拟运行)是通用标准,并非对 oikb 运作方式的描述。

i
关键词与搜索数据
本主题于 30/10/2026 根据查询词“open webui synchroniser dossier”选定。数据采集工具(DataForSEO、Google Ads、法国)未返回任何搜索量数值:该查询词的关注度既未得到确认,也没有具体数据。

#深入了解

使用 Ollama 实现本地 RAG,无需写代码
Open WebUI 的知识库在界面层面如何运作,以及何时应优先选择 AnythingLLM:https://quelllm.fr/guide/rag-local-ollama-sans-coder
故障后恢复 Open WebUI 和 Ollama
数据卷备份、恢复和对照实例,即第 1 步的前提条件:https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
Open WebUI 搭配 Ollama:完整指南
界面的安装与基本设置:https://quelllm.fr/guide/open-webui-ollama-tutoriel
一手来源
Open WebUI,Ecosystem 文档,Knowledge Base Sync:https://docs.openwebui.com/ecosystem/knowledge-base-sync/(查阅于 30/10/2026,18/11/2026 未重新核对)。
这份指南对您有帮助吗?

有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。