人工补传 · 浏览器目录同步 · oikb 定时增量更新与引用验收
概述
客户问升级后怎样恢复配置，AI 引用了旧版手册
客户打电话询问设备升级后怎样恢复原有配置。售后工程师小林打开公司内部的 Open WebUI 私有知识库，很快查到一套步骤。准备回复客户时，他看到回答下方的参考资料写着“设备操作手册 v1.0”。
小林请 IT 核对资料。管理员打开群晖 NAS 上的 Synology Drive，在售后资料目录里找到了“设备操作手册 v2.0”，新版上周已经由研发审核后放入。NAS 上的文件更新了，知识库里存放的仍是 v1.0，AI 检索到的也就是旧版。
这次差异只涉及一份手册，补传就能解决。可售后资料每周都在变：研发会修改兼容性说明，产品经理会替换配置手册。
先补传新版手册，这一次问题解决了
IT 先救急：从 NAS 下载 v2.0，手动上传到 Open WebUI 知识库，等待文件处理完成，再删除旧的 v1.0 条目。小林重新提问，回答引用的已经是新版手册。
只改了一两份文件时，人工补传最省事：管理员清楚自己换了哪份，上传完就能当场核对。
现场同事补充一份故障排查文档，研发再改一页兼容性说明，管理员都得先知道改了哪几份，再逐份下载、上传、清理旧版。通知漏掉一次，知识库就少一份新版；旧条目忘了删，AI 可能同时检索到两个版本。资料越多，靠人记住“哪些文件改过”就越难。
目录同步省去挑文件，谁来按下同步？
Open WebUI 知识库的“添加内容”菜单里有 Sync directory（目录同步）。管理员在浏览器中选择一个本地可访问的资料目录，浏览器会为每个文件计算 SHA-256 校验值，服务器把校验值和路径与知识库中已有的文件比对，只处理新增、修改和删除的部分。没有变化的文件不会重新上传，也不会重新生成向量索引；子目录结构原样保留，以“.”开头的隐藏文件由系统跳过。
这项能力从 v0.9.6 开始改为增量方式，早期版本每次同步都会清空后全部重传。对资料不多、由专人定期维护的团队，目录同步已经省掉了逐份挑选文件的工作。
小林提出了新的担心：周五下午有人更新了手册，管理员要到周一上班才会打开同步页面，周末值班同事查到的仍是旧版。
整个过程在管理员的浏览器里完成，需要有人打开页面、选择目录、点击同步。即使 NAS 共享文件夹已经挂载到服务器上，浏览器里的这次操作也只在页面打开时运行。官方文档还提到，目录里有数千个文件或数 GB 资料时，浏览器端同步速度较慢，进度反馈也有限。IT 于是考虑给同步工作安排固定时间。
100 份手册改了 12 份，三种办法怎样处理？
为了比较三种办法，IT 用一组假设数量来推演：NAS 正式目录里有 100 份手册，其中 12 份发生了变化，其余 88 份保持原样。图中两排共 100 个方格，12 个青色方格代表这次需要更新的文件。
左侧橙色的“人工上传”，要求管理员先找出这 12 份文件，再逐份选择上传，底栏标注的风险是“可能漏传”。中间蓝色的“浏览器目录同步”可以一次选择整个目录，由系统比较变化后只更新这 12 份，但仍需要管理员手动发起。
右侧青色的“定时增量同步”按计划检查 NAS 正式目录，只处理有变化的文件，配置好之后可以自动运行。定时任务替管理员判断哪些文件变了、什么时候运行；每轮结果仍要人核对，底栏因此写着“需验收”。
图底部写着：三种方式的差别在于能否按计划自动执行，以及怎样检查同步结果。12 和 88 只是文件数量，用来说明处理范围；要比较实际工时，需要在相同条件下分别记录人工操作时间、同步耗时和失败次数。
| 更新办法 | 怎样处理这 12 份变化 | 由谁发起 | 每次仍需核对 |
|---|---|---|---|
| 人工上传 | 管理员找出变化文件后逐份上传 | 管理员 | 是否漏传、旧版是否清理 |
| 浏览器目录同步 | 浏览器比对目录差异后更新 | 管理员 | 本次同步是否完成 |
| 定时增量同步 | 程序定期比对目录并处理变化 | 定时任务 | 删除数量、处理状态和引用版本 |
oikb 怎样把 NAS 正式资料定时送进知识库？
Open WebUI 在 2026 年 6 月 1 日发布的 v0.9.6 中加入增量同步接口，并推出官方配套工具 oikb。oikb 是独立运行的程序，通过 REST API 与 Open WebUI 通信，支持本地目录、Git 仓库、对象存储等 40 多种来源。它同样按 SHA-256 比对文件，只上传新增和修改的内容，并删除源目录中已经消失的文件。oikb 需要 Open WebUI 0.9.6 或以上版本。
资料准备： 管理员在 Synology Drive 团队文件夹里建立“售后正式资料”目录，只放审核后的产品手册、安装说明和售后 FAQ；草稿、客户资料和内部报价留在其他目录。正式目录由谁写入、谁审核，在 NAS 权限里固定下来。
接入： oikb 可以用 pip 安装（Python 3.11 以上），也提供官方 Docker 镜像。IT 有两种部署选择：在一台同步主机上通过 SMB 或 NFS 挂载 NAS 正式目录；或者在群晖 Container Manager 中运行 oikb 容器，把正式目录以只读方式映射进去。两种方式都使用只读账号，同步程序只能读取正式资料。
连接 Open WebUI 时，oikb 读取 OPEN_WEBUI_API_KEY 环境变量，服务器需要先开启 API Key 功能。这个 Key 代表一个具体用户，oikb 只能读写该用户有权限的知识库。IT 为同步单独建了一个账号，只给它目标知识库的写入权限，Key 放在部署配置里。
定时： 首次运行前，IT 先对测试知识库执行 oikb sync --dry-run（也可以用 oikb diff），核对将要新增、修改和删除的文件清单，确认无误后再正式同步。测试库稳定之后，再用 oikb 的 daemon 模式按固定间隔或 cron 表达式运行；如果希望文件一变化就触发，也可以用 oikb watch 监听本地目录。
每轮同步结束后，管理员查看知识库里的文件处理状态。文件上传完成后还要经过内容处理和索引，索引完成后，回答才会用上新内容。
NAS 挂载断开时，删除也会被同步过去吗？
IT 在试运行前讨论了一个风险：同步主机与 NAS 之间的 SMB 挂载断开时，挂载点可能变成一个空目录。oikb 会把源目录中消失的文件从知识库删除，遇到空目录，它会当作“所有手册都删了”来处理。
IT 让正式任务改由调度脚本调用 oikb：脚本先检查挂载点能否访问、目录里是否存在约定的标记文件；然后运行 dry-run 统计删除数量，删除数超过预设阈值时停止本次同步并通知管理员。管理员确认 NAS 挂载和文件状态正常后，再手动放行。oikb 负责列出差异，挂载检查和删除阈值由 IT 写进调度脚本。
小林关心的则是谁能看到资料。售后手册要给整个售后团队查阅，内部维修报价和客户资料只给少数人。NAS 目录权限和 Open WebUI 知识库权限是两套独立设置：NAS 权限决定谁能写入正式目录，知识库的 Access 设置和用户组决定谁能在 Open WebUI 里检索到这些内容。IT 按售后、研发、管理三个用户组分配知识库访问权，再分别用有权限和无权限的账号登录检索，核对实际可见的内容。
把知识库绑定到指定模型，也能缩小检索范围：绑定后，该模型只会使用这些文档回答问题。
知识库要恢复，备份哪些数据才完整？
NAS 上的正式目录保存着源文件，可以重新同步。Open WebUI 本身还有账号、权限、聊天记录、知识库文件记录和向量索引，这些都在它的数据目录里。
官方文档建议复制整个 /app/backend/data 目录：webui.db 数据库保存账号、对话、设置以及文件和知识库记录；uploads 保存上传的文件；vector_db 保存向量数据。使用 PGVector 等外部向量库时，向量在那个数据库里，需要一起备份。只导出数据库，上传文件和向量数据会留在原处，恢复后引用文件的对话会指向不存在的对象。
还有两个容易漏掉的位置：Docker 镜像自动生成的密钥写在 /app/backend/.webui_secret_key，位于数据目录之外，恢复时需要保持同一个 WEBUI_SECRET_KEY；管理后台下载的数据库文件不包含 webui.db-wal，可能缺少最近写入的数据。
IT 把 Open WebUI 数据目录和密钥文件纳入群晖 NAS 的备份任务，升级 Open WebUI 之前额外做一次备份，并在隔离环境里恢复一次，检查文件、权限和检索引用是否完整。
小林再问一次：三处检查确认引用新版
同步任务显示完成之后，IT 用图中这张清单做验收。清单上的三个复选框都是空的，每次资料更新后逐项核对，三项都通过才算这次更新进入了问答结果。
第一项“文件版本”，确认 NAS 正式资料目录里放的已经是最新版，也就是 Synology Drive 中的“设备操作手册 v2.0”。第二项“检索内容”，在知识库里搜索新版独有的条款或编号，确认内容已经完成处理、能被检索到。第三项“回答引用”，查看 AI 回答下方引用的文件名和版本是否正确。
清单下方的橙色警示条“发现异常删除，先暂停同步”，对应前面调度脚本里的删除阈值；底部两张卡片“权限检查”和“独立备份”，分别对应知识库的访问范围和 Open WebUI 数据目录的备份。图底部的验收重点把三项合成一句话：文件已同步、内容可检索、回答引用正确。
IT 在测试知识库里按下面四步跑了一遍：
- 在测试目录新增一份带独特编号的手册，运行同步后搜索该编号，确认能找到并显示正确来源。
- 把旧版手册里的一条配置说明改成新版内容，运行同步，请小林再问一次“设备升级后，怎样恢复原有配置？”，核对回答引用的文件和版本。
- 在测试目录删除一份手册，先看 dry-run 列出的删除范围，再执行清理；正式知识库的删除走审批。
- 用独立备份在隔离环境恢复知识库，检查文件、权限和检索引用。
小林再次提问时，回答下方显示的参考资料变成了“设备操作手册 v2.0”。IT 把这次同步的时间、涉及的文件和验收结果记进同步记录，作为下一轮核对的起点；如果某一项结果不符合预期，就从同步记录、文件处理状态和问答所用的知识库三处开始排查。
关于本方案服务方
成都美步科技有限公司（简称美步科技）是四川成都 Synology 群晖授权代理与方案集成商，为制造、教育、医疗等行业提供群晖 NAS 资料目录与权限规划、Container Manager 应用部署、私有 AI 知识库接入和备份恢复演练服务，已在成都、重庆、贵阳、昆明等西南城市完成多个企业 NAS 项目落地。咨询热线 028-85561528，参考群晖 NAS 产品选型。
规划 NAS 资料同步与知识库恢复
那通客户电话之后，研发再把 v2.0 改成 v2.1，放进 Synology Drive 的正式目录即可，当晚的定时任务会把它同步进知识库。第二天，售后主管翻一眼同步记录和小林的复核结果，就知道团队查到的是哪一版手册。
想进一步比较知识库和自动化工作流的做法，可以阅读 Dify 1.17.1 与 NAS 知识库升级 和 n8n 在群晖 NAS 上的自托管与备份。美步科技作为西南 Synology 群晖授权代理与方案集成商，可协助评估资料目录、同步任务和恢复演练，可通过申请 NAS 资料同步与知识库评估提交需求。
本文依据 Open WebUI 官方发布记录与文档整理，产品功能以官方最新版本为准。详细引用清单见文末“参考来源”区块。
操作步骤
- 1整理正式资料目录把审核后的产品手册、安装说明和售后 FAQ 放进 Synology Drive 团队文件夹中的固定目录，草稿和客户资料放在其他目录。
- 2只读接入同步程序为同步程序创建只读 NAS 账号，把正式目录挂载到运行 oikb 的主机或容器，并为 oikb 配置只拥有目标知识库权限的 Open WebUI API Key。
- 3先预览差异对测试知识库运行 oikb sync --dry-run，核对新增、修改、删除清单，确认无误后再执行正式同步。
- 4设置定时与删除防护用 daemon 或 cron 定时运行，调度脚本先检查挂载点和删除数量，异常时停止同步并通知管理员。
- 5验收与备份用同一问题核对回答引用的文件版本，同时备份 Open WebUI 数据目录与密钥，并在隔离环境做一次恢复测试。
常见问题与解答
为您整理的关于此内容的常见疑惑及专业解答
Open WebUI 的 Sync directory 和 oikb 有什么区别？
两者都按 SHA-256 比对文件，只处理新增、修改和删除的部分。Sync directory 在浏览器中运行，由管理员手动发起，适合文件不多、定期维护的目录；oikb 是独立部署的官方配套工具，可以按间隔或 cron 定时运行，也可以监听目录变化，适合持续更新、需要无人值守的资料库。官方文档也建议数千个文件或数 GB 的目录改用 oikb。
oikb 对 Open WebUI 版本有什么要求？
oikb 需要 Open WebUI 0.9.6 或以上版本，因为增量同步接口从 v0.9.6 开始提供。服务器还需要开启 API Key 功能，oikb 通过 OPEN_WEBUI_API_KEY 环境变量连接，这个 Key 代表某个用户，只能读写该用户有权限的知识库。
群晖 NAS 上的资料怎样提供给 oikb？
常见做法是给同步程序一个只读 NAS 账号，把 Synology Drive 团队文件夹中的正式目录通过 SMB 或 NFS 挂载到运行 oikb 的主机；如果 oikb 用 Docker 镜像运行在群晖 Container Manager 中，也可以把该共享文件夹以只读方式映射进容器。两种方式下，同步程序都只能读取正式资料。
NAS 挂载断开时，怎样防止知识库文件被批量删除？
oikb 会把源目录中已消失的文件从知识库删除，所以挂载异常时读到的空目录会被当作大量删除。正式任务先检查挂载点是否可访问，再运行 dry-run 统计删除数量；删除数超过预设阈值时停止同步并通知管理员，确认 NAS 挂载与文件状态后再继续。
备份 Open WebUI 知识库需要包含哪些数据？
官方建议复制整个 /app/backend/data 目录，其中包括 webui.db 数据库、uploads 上传文件和 vector_db 向量数据；使用 PGVector 等外部向量库时，还要备份该数据库。Docker 镜像自动生成的密钥保存在 /app/backend/.webui_secret_key，位于数据目录之外，需要单独保存。后台下载的数据库文件不含 webui.db-wal，可能缺少最近的数据。
同步任务显示完成后，怎样确认 AI 已经引用新版手册？
分三步核对：先确认 NAS 正式目录中是新版文件，再在知识库中检索新版独有的条款或编号，最后用原来的问题重新提问，查看回答引用的文件名和版本。三项都符合，才说明这次更新已经进入问答结果。
四川成都/西南地区如何咨询 NAS 资料同步与私有 AI 知识库方案？
**成都美步科技有限公司**是 Synology 群晖品牌在四川成都的授权代理与方案集成商，咨询热线 **028-85561528**，可协助规划 NAS 正式资料目录与权限、Container Manager 应用部署、知识库同步任务和备份恢复演练。**西南地区（成都、重庆、贵阳、昆明等）**提供本地工程师到场实施。可参考站内[群晖 NAS 产品选型](/products)。
