OpenCore文档与知识连接器

Web

以 Markdown 格式查看

索引内容

Web 连接器把渲染后的页面转换为 OpenCore 文档。每次运行都是 load-state 爬取；起止时间会被忽略，因此此连接器不提供增量 Web 轮询。

抓取方式或内容索引行为
recursive从 Base URL 开始，跟随渲染后 <a href> 元素中的链接。只有规范化 network authority（netloc，包含显式 port）在转为小写并去掉开头 www. 后相同，且路径等于配置路径或属于其下级路径时，链接才在范围内。管理表单没有 URL 排除、包含 pattern、爬取深度或最大页面数设置。
single只渲染配置的 URL，不会继续跟随页面中的链接。对渲染 HTML，Playwright 重定向会把文档 ID 与 section link 改为最终 URL。如果资源被识别为 PDF，Requests 下载可以跟随重定向，但文档 ID 与 section link 会保留最初配置的 URL。
sitemap获取配置的 sitemap URL，提取其中的 <loc> 值并渲染这些 URL。如果响应既没有 location 也没有 urlset，会尝试 sitemap 发现 helper。连接器不会从所得页面继续递归，也不会递归解析子 sitemap 文档。
HTML、PDF 与 JavaScriptHTML 会在启用 JavaScript 的无头 Chromium 中渲染，再清理为标题与文本。PDF 会按 URL 或 Content-Type 识别并直接提取。抓取前滚动可为延迟加载内容最多滚动 20 次。Web 文档有意不使用 Last-Modified。渲染 HTML 页面会在同一次运行内按重复标题与内容去重；PDF 文档不会进入该标题与内容去重集合。

HTML 清理会移除部署级忽略 class 与 element。默认 class 包含 sidebar,footer，默认 element 包含 nav,footer,meta,script,style,symbol,aside。运维人员可以用 WEB_CONNECTOR_IGNORED_CLASSES 与 WEB_CONNECTOR_IGNORED_ELEMENTS 替换这两组逗号分隔列表；它们不是单连接器字段。

前置条件

  • 允许 OpenCore doc-fetching worker 解析并访问每个目标 URL、重定向、PDF 与 sitemap location。
  • 在 worker 镜像中安装 Playwright Chromium runtime。JavaScript 始终启用；管理后台没有仅静态获取开关。
  • 选择包含目标内容的最窄 Base URL 路径。Recursive 模式没有 URL 排除列表、深度限制或页面数限制。
  • 检查部署的 SSRF 保护设置。在最严格级别，连接器会拒绝解析到 loopback、link-local 或私有地址的 URL；较宽松设置会改变此边界。
  • 使用 worker 信任的证书。浏览器导航创建时会忽略 HTTPS 错误，但连通性检查、sitemap 请求、PDF 下载与 content-type 探测使用的 HTTP 客户端没有证书覆盖设置。管理表单没有证书校验开关。

凭据

方式配置与边界
公开网站管理表单不会创建或选择凭据。连接器发送固定的浏览器式 request header；表单没有用户名、密码、cookie、自定义 header、OAuth token 或 client certificate 字段。
部署级 OAuth client credential如果同时设置三个 worker 变量——WEB_CONNECTOR_OAUTH_CLIENT_ID=<CLIENT_ID>、WEB_CONNECTOR_OAUTH_CLIENT_SECRET=<CLIENT_SECRET> 与 WEB_CONNECTOR_OAUTH_TOKEN_URL=<TOKEN_URL>——共享浏览器 context 会通过 client-credentials 获取 token，并放入 Authorization header 发送。这是全局 worker 配置，不是限定于单个 Web 连接器的凭据。
其他受保护站点此管理后台流程没有实现单连接器自定义 header 或交互登录。不要把 secret 放入 Base URL。当全局 OAuth token 范围过宽时，请使用单独受保护的摄取路径。

由于 HTTP probe 与 PDF 请求使用连接器固定的默认 header，部署级浏览器 OAuth header 并不能证明每条非浏览器 fetch 路径都已认证。依赖此方式前，应验证目标内容组合。

在 OpenCore 中配置

  1. 在管理后台打开连接器，选择 Web，并填写易识别的连接器名称。
  2. 填写准确的 Base URL。即使后端会把缺失的 scheme 规范化为 HTTPS，也应明确写出 https://，便于审计预期 scheme。
  3. 按上表范围选择 recursive、single 或 sitemap。Sitemap 模式应填写 sitemap URL，而不是站点首页，除非有意依赖发现逻辑。
  4. 仅在所需内容需要滚动后才出现时启用抓取前滚动。此设置不会改变 single、recursive 或 sitemap 的 URL 范围。
  5. 受限内容应选择 OpenCore 私有群组。仅当每个 OpenCore 账号都可以搜索爬取范围内的全部页面时才选择公开。
  6. 设置刷新与清理选项，创建连接器并运行一次索引。每次刷新都会重新爬取配置范围，而不是应用 HTTP 更新时间窗口。

权限

Web 连接器不会读取或同步源站用户、session、群组、页面 ACL、robots 授权或逐页可见性。当前管理后台访问选择器不把 Web 作为自动同步权限源。

搜索访问仅由连接器的 OpenCore 私有群组或公开模式控制。任何能访问连接器的用户都可以搜索爬虫产生的全部页面，即使该用户无法在浏览器中打开源页面。部署级 OAuth token 还会让这些 worker 上的全部 Web 连接器使用同一个源身份。

不得共享内容的不同受众应使用独立连接器和 OpenCore 私有群组。除非整个输出范围都可以共享给所选 OpenCore 受众，否则不要用此连接器爬取同时包含公开与受限内容的路径。

验证

  1. 运行连接器，并在 attempt 状态中检查连接、Playwright、TLS、HTTP 或 sitemap 错误。
  2. 搜索 Base URL 中一个独特标题和句子。确认 navigation、footer、script 与其他忽略内容按预期不存在。
  3. 对 recursive 模式分别测试一个下级 URL、一个 Base URL 外的同级路径、一个不同 port 的 URL 与一个外部 authority 链接。只有 network authority 规范化后相同的下级 URL 应被索引。
  4. 对 single 模式确认链接页面不存在。对 sitemap 模式把已索引文档 ID 与 sitemap location 对账，并检查子 sitemap URL 没有被误当作内容页面。
  5. 如果启用了滚动，请用一个已知的延迟加载句子对比关闭滚动的运行结果。
  6. 分别测试 HTML 重定向与 PDF 重定向。渲染 HTML 重定向应使用最终 URL 作为文档 ID 与 link；PDF 重定向应保留最初配置的 URL。同时比较重复的渲染 HTML 页面与重复 PDF，因为只有渲染 HTML 使用标题与内容去重。
  7. 测试每个已分配 OpenCore 群组和一个群组外用户，因为搜索时不会重新向源站授权。

故障排除

症状检查项
Recursive 爬取范围远大于预期缩小 Base URL 路径。当前表单没有 URL 排除、深度或页面数设置，recursive 范围会跟随渲染 HTML 中发现的同站下级链接。
同站页面缺失确认其 network authority（netloc，包含显式 port）在转为小写并做 www. 规范化后匹配、路径位于 Base URL 路径下，并且存在渲染后的 anchor 链接。只在页面加载或可选滚动以外的交互后创建的链接可能不会被发现。
重定向文档显示了非预期 URL检查内容路径。渲染 HTML 重定向会把文档 ID 与 link 替换为最终 Playwright URL；PDF 下载可以跟随重定向，但文档中会保留最初配置的 URL。
Sitemap 创建失败或索引了 XML提供可访问且包含直接页面 <loc> 值的 sitemap。连接器不会递归展开子 sitemap 文档。
静态 HTML 正常，但 PDF 或 probe 返回 401/403浏览器 context 可以接收部署级 OAuth header，而连接器的 HTTP probe 与 PDF 请求使用固定默认 header。请使用受支持的摄取路径，或重新设计源访问边界。
Chromium 忽略 HTTPS 错误，但自签名站点仍失败爬取前连通性检查及其他 HTTP-client 路径仍会校验证书。请把签发 CA 安装到 worker trust store；没有单连接器绕过设置。
动态内容缺失确认 Chromium 已安装，并且脚本能在连接器的 load-state wait 内完成。只有需要滚动触发加载时才启用滚动；连接器没有可配置 JavaScript delay。
用户能搜索自己无法在源站打开的页面这是预期行为，因为源 ACL 不会同步。请用 OpenCore 私有群组限制连接器，或按受众拆分爬取。

相关页面