外部 Wiki 同步
通过外部 Wiki 连接器，可以将 Wiki.js 页面、GitLab 仓库文件或 GitLab 项目 Wiki 页面绑定到知识库。绑定后的内容会转换为普通知识文档并参与通用 RAG 检索， 系统还会定时检查远端版本，在内容变化后自动更新正文和索引。
支持的连接器
| 连接器 | 可导入内容 | 添加资料时选择 | 访问凭据 |
|---|---|---|---|
| Wiki.js | Wiki.js 页面 | 页面或目录 | Wiki.js API Key |
| GitLab Repo | GitLab 仓库中的支持文件 | 仓库、分支和文件 | GitLab AppKey / Access Token |
| GitLab Wiki | GitLab 项目的 Wiki 页面 | 仓库和 Wiki 页面 | GitLab AppKey / Access Token |
Wiki.js 当前支持 2.x，最低版本 2.5.0。Wiki.js 3.x 及 2.5.0 之前的版本不在当前兼容范围内。
GitLab Repo 支持以下文件扩展名：
pdf, doc, docx, ppt, pptx, xls, xlsx, csv, txt, md, markdown
目录仅用于浏览文件，不会作为文档导入。空文件、不支持的文件类型以及超过知识库 上传大小限制的文件不能绑定。Git LFS 指针文件也不能绑定，因为仓库 API 返回内容 不包含指针引用的实际二进制文件。
工作方式
外部 Wiki 功能由三部分组成：
| 组成 | 位置 | 说明 |
|---|---|---|
| 连接管理 | 设置 → 集成 → 外部 Wiki | 保存连接器类型、站点地址和加密凭据 |
| 资料绑定 | 知识库 → 添加文档 → 外部 Wiki | 选择远端页面或文件，每项生成一篇同步文档 |
| 定时同步 | 后台定时任务 | 比较远端版本，仅更新发生变化的文档 |
与一次性网页导入不同，外部 Wiki 是持续绑定关系。再次绑定相同连接、仓库、 分支和资源时会复用已有文档，不会生成重复条目。
导入完成后使用知识库的通用索引和检索能力，不需要为 Wiki.js 或 GitLab 配置专用检索 Skill。
前置条件
通用条件
- Wegent 后端能够访问目标 Wiki.js 或 GitLab 地址。
- 当前用户拥有目标知识库的编辑权限。
- 目标连接可以使用 HTTP 或 HTTPS；站点地址必须是后端实际能够连接的地址。
Wiki.js
- Wiki.js 版本为 2.5.0 或更高的 2.x。
- 在 Admin → API 创建 API Key，其权限组包含：
read:pagesread:sourcemanage:pages，或包含delete:pages的权限组
GitLab Repo 和 GitLab Wiki
- 准备能够读取目标项目的 GitLab Access Token。产品界面中称为 GitLab AppKey / Access Token。
- 推荐最小权限为
read_api。 - Token 对目标项目具有读取权限。GitLab Repo 还需要读取仓库、分支和文件； GitLab Wiki 需要读取项目 Wiki。
- 可以使用 GitLab.com 或自建 GitLab，站点地址可为 HTTP 或 HTTPS。
凭据通过 PRIVATE-TOKEN 请求头发送，并加密存储在服务端；不会拼接到 URL
或显示在知识文档中。
配置外部 Wiki 连接
- 进入 设置 → 集成，找到 外部 Wiki。
- 点击 新连接。
- 填写连接名称并选择连接器类型。
- 根据连接器填写站点地址和凭据。
- 点击 测试连通。
- 测试成功后点击 保存。
配置 Wiki.js
- 连接器类型：
Wiki.js - 站点地址：Wiki 根地址，例如
https://wiki.example.com，不要附加/graphql - API Key：Wiki.js 后台创建的 API Key
- 默认语言（可选）：多语言站点用于路径解析，例如
zh
连接测试会检查页面列表、页面解析和正文读取，而不只是网络连通性。
配置 GitLab Repo
- 连接器类型：
GitLab Repo - 站点地址：GitLab 根地址，例如
https://gitlab.example.com或http://gitlab.internal，不要附加/api/v4 - API Key：GitLab AppKey / Access Token
连接测试会调用 GitLab API 获取当前 Token 可访问的项目。测试成功但没有项目时， 界面会提示当前 AppKey 没有可访问项目。
配置 GitLab Wiki
- 连接器类型：
GitLab Wiki - 站点地址：GitLab 根地址，不要附加
/api/v4 - API Key：GitLab AppKey / Access Token
GitLab Wiki 与 GitLab Repo 可以使用同一个 GitLab 实例和 Token，但它们是两个 独立连接，添加资料时展示的资源类型不同。
连接管理注意事项
- 仅修改连接名称、启用状态等非目标字段时，API Key 留空表示保留原凭据； 修改站点地址或连接器时必须重新输入 API Key，系统不会把旧凭据发送到新目标。
- 停用连接后，系统停止远端读取和同步；最近一次成功同步的本地正文和索引仍可使用。
- 删除连接前必须先解除引用该连接的全部同步文档。
- 连接器类型决定已绑定资源的身份和解析方式。需要切换类型时，建议新建连接并重新绑定， 不要把已有连接直接改成另一种连接器。
添加 Wiki.js 页面
- 打开目标知识库，点击 添加文档 → 外部 Wiki。
- 选择 Wiki.js 连接。
- 在页面树中选择需要绑定的页面。
- 点击 绑定选中。
页面选择器支持按标题或路径搜索、全选、取消全选和目录选择。当站点页面数超过 服务端浏览上限时，会显示截断提示并加载最近更新的页面。
添加 GitLab Repo 文件
- 打开目标知识库，点击 添加文档 → 外部 Wiki。
- 选择
GitLab Repo连接。 - 在 仓库 下拉框选择目标项目。
- 在 分支 下拉框选择目标分支。默认优先选择项目默认分支。
- 展开目录并勾选需要同步的文件。
- 点击 绑定选中。
文件选择器只允许选择受支持的文件类型。目录用于逐层浏览，不能作为知识文档导入。 绑定身份包含连接、仓库、分支和文件路径，因此：
- 同一路径在不同分支中是不同的同步文档。
- 文件改名会被视为旧文件删除和新文件出现，需要重新绑定新路径。
- 切换项目或分支后，选择器会清除上一范围中的临时选择。
绑定后系统下载文件原始内容，复用知识库现有的附件解析、转换和索引流程。
添加 GitLab Wiki 页面
- 打开目标知识库，点击 添加文档 → 外部 Wiki。
- 选择
GitLab Wiki连接。 - 在 仓库 下拉框选择目标项目。
- 在 Wiki 页面列表中选择需要同步的页面。
- 点击 绑定选中。
GitLab Wiki 页面属于项目，不需要选择分支。页面会按其格式转换为 Markdown、 AsciiDoc 或文本后进入知识库索引流程。
如果项目没有启用 Wiki、Wiki 为空，或者 Token 无权读取 Wiki，页面列表将为空 或显示对应错误。
绑定结果和文档展示
| 结果 | 说明 |
|---|---|
| 已绑定 N 个 | 新资源已创建同步文档，后台开始读取和索引 |
| 已重新同步 N 个 | 已存在的资源触发了正文刷新 |
| 正在处理中，本次跳过 | 文档仍处于转换或索引流程，没有重复派发任务 |
知识库文档列表会同时显示：
- 文件类型，例如
MD、PDF； - 连接器类型和图标，例如
wikijs、gitlab-repo、gitlab-wiki； - 最近一次成功完成索引的时间。
在 添加文档 → 外部 Wiki → 已绑定文档 中，每条文档也会显示自己的连接器 名称和图标。切换当前连接不会改变其他已绑定文档的连接器标识。
定时同步机制
定时同步默认关闭。设置 EXTERNAL_DOC_SYNC_ENABLED=true 后，后台默认每天 UTC
19:00（北京时间次日凌晨 3:00）执行巡检。该开关不影响手动导入和手动同步。
每次巡检会：
- 分批扫描所有已绑定的外部 Wiki 文档。
- 按连接和资源范围调用对应连接器。
- 比较远端版本、已下载正文版本和已建立索引版本。
- 仅为发生变化或索引缺失的文档派发任务。
不同连接器使用不同的远端版本依据：
| 连接器 | 版本依据 |
|---|---|
| Wiki.js | 页面 updatedAt |
| GitLab Repo | 文件 Blob ID |
| GitLab Wiki | 页面标题、格式和正文计算出的内容哈希 |
| 远端状态 | 系统行为 |
|---|---|
| 版本无变化且索引正常 | 不更新文档 |
| 远端内容变化 | 重新下载正文并重建索引 |
| 正文已是最新但索引缺失 | 使用现有正文重建索引 |
| 页面或文件已删除 | 标记源文档不存在，保留最近一次成功索引 |
| 仓库或分支不可访问 | 标记同步失败，保留现有内容 |
| 连接不可用、权限失败或限流 | 标记同步失败，后续巡检自动重试 |
检测到更新时，任务日志会记录文档 ID、知识库 ID、文档名、连接器、连接 ID、 资源路径、前后版本和更新动作，不记录 API Key 或文档正文。
也可以在文档详情中手动执行 同步，立即重新获取远端内容。文档正在处理时， 系统会跳过重复任务。
源资源被删除或移动
远端页面或文件被删除后，系统不会自动删除本地知识文档，而是标记源资源不存在：
- 最近一次成功同步的正文和索引继续保留，Agent 仍可检索历史内容。
- 源资源恢复后，后续巡检会自动恢复同步。
- 确认不再需要时，可以在已绑定文档列表中解除绑定。
GitLab Repo 文件改名或移动后，原路径按删除处理。新路径具有新的资源身份，需要 重新选择并绑定。
如果整个 GitLab 项目、分支或 Wiki 权限发生变化，系统会标记同步失败而不是删除 本地内容。权限恢复后会在后续巡检中重试。
管理操作
| 操作 | 位置 | 说明 |
|---|---|---|
| 查看绑定 | 添加文档 → 外部 Wiki → 已绑定文档 | 查看文档名称、连接器和同步状态 |
| 解除绑定 | 已绑定文档 → 解除绑定 | 删除本地同步文档及其索引 |
| 手动同步 | 文档详情 → 同步 | 立即拉取远端正文并重建索引 |
| 停用连接 | 设置 → 集成 → 外部 Wiki | 停止远端读取和自动同步 |
| 删除连接 | 设置 → 集成 → 外部 Wiki | 必须先解除所有引用文档 |
每个用户管理自己的外部 Wiki 连接。绑定和解除绑定需要目标知识库的编辑权限； 同步文档的可见性与知识库中的普通文档一致。
常见问题
Q：GitLab 连接成功，但没有可选仓库？
确认 Token 具有 read_api 权限，并且 Token 所属用户或访问令牌能够读取目标项目。
项目列表只展示当前 Token 可访问的项目。
Q：GitLab Repo 中看不到某个文件？
确认选择了正确的仓库和分支，并检查文件扩展名是否在支持列表中。目录、空文件、 无扩展名文件和超出知识库上传大小限制的文件不能导入。
Q：GitLab Wiki 为什么不需要选择分支？
GitLab 项目 Wiki 由独立的 Wiki API 管理，不按代码仓库分支选择。
Q：是否支持 HTTP 或内网 GitLab？
支持。系统不限制 GitLab 必须使用 HTTPS，也不限制特定域名或网段；只要 Wegent 后端能够连接该地址并且 Token 有权限即可。
Q：远端更新后多久同步？
最迟在下一次每日巡检同步。需要立即生效时，可以在文档详情中执行 同步。
Q：文档一直显示“排队中”？
后台任务按队列执行。超过 30 分钟仍未变化时，可在详情中查看失败原因并重试。
Q：同一个资源可以绑定到多个知识库吗？
可以。每个知识库拥有独立的同步文档和索引。
服务端配置参考
| 环境变量 | 默认值 | 说明 |
|---|---|---|
EXTERNAL_DOC_SYNC_ENABLED | false | 外部文档定时同步开关 |
EXTERNAL_DOC_SYNC_CRON | 0 21 * * * | 巡检调度（UTC crontab） |
EXTERNAL_DOC_SYNC_SCAN_BATCH_SIZE | 500 | 每批扫描的本地文档数 |
EXTERNAL_DOC_SYNC_RUN_MAX_DOCUMENTS | 10000 | 单次运行最多处理文档数 |
EXTERNAL_DOC_SYNC_TIME_BUDGET_SECONDS | 2700 | 单次运行时间预算（秒） |
WIKI_SYNC_REMOTE_BATCH_SIZE | 500 | 每批远端资源探测上限 |
WIKI_TREE_MAX_PAGES | 5000 | Wiki.js 页面选择器的加载上限 |
MAX_UPLOAD_FILE_SIZE_MB | 100 | GitLab Repo 等知识文档的单文件大小上限 |
REPOSITORY_READ_TIMEOUT_SECONDS | 15 | GitLab API 单次读取超时（秒） |
EXTERNAL_WIKI_DOWNLOAD_TIMEOUT_SECONDS | 300 | 单个 GitLab 文件或 Wiki 页面下载超时 |
KNOWLEDGE_ATTACHMENT_ORPHAN_RETENTION_HOURS | 24 | 孤儿附件删除前的安全保留时间 |
KNOWLEDGE_ATTACHMENT_ORPHAN_SCAN_BATCH_SIZE | 200 | 每轮孤儿附件扫描上限 |
KNOWLEDGE_ATTACHMENT_ORPHAN_SCAN_INTERVAL_SECONDS | 3600 | 孤儿附件扫描间隔（秒） |