接入资料来源
部署侧要先准备什么,九种来源各自怎么登记。
先让部署管理员准备环境
下面几项在部署配置(deploy/nexus/.env)里设置,改完后重新运行 docker compose -f deploy/nexus/compose.yaml up -d。
| 配置项 | 什么时候需要 | 说明 |
|---|---|---|
ECHOMIND_KNOWLEDGE_LOCAL_ROOTS | 读取本地目录或 NAS | 登记允许读取的根目录,是一个 JSON 数组,每项有 root_ref(根目录标识)、label(显示名)和 path(容器内的绝对路径),例如 [{"root_ref":"company_docs","label":"公司现有文库","path":"/sources/docs"}]。目录要以只读卷挂载进知汇容器。面板里只能选这里登记的根目录标识,不接收任意服务器路径 |
ECHOMIND_EGRESS_ALLOW | WebDAV、S3、Confluence、WeKnora 等在内网 | 出站默认拒绝回环、内网、链路本地和云元数据网段。内网主机或网段要在这里放行 |
ECHOMIND_KNOWLEDGE_INSECURE_ORIGINS | 来源只有明文 HTTP | 默认要求 HTTPS。确需明文的内网服务,把精确的源(如 http://nas.internal:5005)列在这里,逗号分隔 |
ECHOMIND_DINGTALK_OAUTH_REDIRECT_URI | 钉钉表单里用「扫码获取本人标识」 | 设为控制台地址加 /oauth/dingtalk/callback,并在钉钉应用的安全设置里登记完全一致的回调地址。使用 HTTPS 或本机回环的 HTTP |
ECHOMIND_KNOWLEDGE_OCR | 要识别图片和扫描 PDF | 默认关闭。设为 on,并且知汇镜像里要装有 Tesseract。默认镜像不带 Tesseract,需要基于知汇镜像另行构建 |
ECHOMIND_KNOWLEDGE_SOFFICE | 旧版 DOC、XLS、PPT | 知汇镜像内置 LibreOffice,默认已开启。在 .env 里写 ECHOMIND_KNOWLEDGE_SOFFICE=(空值)可以关闭 |
知汇的数据库和同步状态都在部署的数据卷里。备份时,来源凭据的加密密钥文件要随数据卷一起备份,丢失后已保存的凭据无法解开,需要在面板里重新填写。
登记资料来源
打开「知识库(知汇) › 资料接入」,点右上角的「新建资料来源」。页面左边是已有来源的列表,可以按名称搜索,也可以按「来源平台」筛选;右边是所选来源的配置。表单分为三组:
- 基本信息:「来源平台」和「来源名称」。名称最长 100 个字符,必填。平台在创建后不能更换。平台下拉分成两组:「已用真实账号或服务验证」和「按官方接口实现,待现场联调」。
- 读取范围:随平台不同,见下表。
- 应用凭据:见下表。凭据可以留空,先创建一个未连接的来源,以后再补。填写时要成组填写。已保存的凭据只显示「已保存 · 不回显」,留空表示保留,替换时要把必填的一组填完整。凭据只提交到知汇服务,不保存在浏览器里。
点「创建资料来源」或「保存来源配置」只保存配置,不会自动测试连接、同步或开启定时同步。表单有未保存的修改时,下面的测试和同步按钮不可用。保存时某个字段不合格,会在字段下方说明,并提示还有几项需要处理。
九种来源各自要准备什么
| 来源 | 读取范围(表单字段) | 凭据 | 还要先做的事 |
|---|---|---|---|
| 本地文库 | 「根目录标识」(下拉,只列出部署管理员登记的根目录);「子目录」可选,填根目录内的相对路径 | 无 | 部署管理员登记并只读挂载目录 |
| 飞书知识库 | 「知识空间 ID」;「起始节点 Token」可选,留空从知识空间根开始;「企业飞书域名」可选,写成 company.feishu.cn,用于生成原文链接 | 「App ID」「App Secret」 | 应用要开通只读权限 wiki:wiki:readonly、docx:document:readonly、sheets:spreadsheet:readonly、bitable:app:readonly,并且能打开该知识空间 |
| 飞书云盘 | 「云盘文件夹 Token」,填明确的文件夹 Token,不填分享链接。读取该文件夹及子文件夹 | 「App ID」「App Secret」 | 把应用加为该文件夹的协作者(可阅读)。权限为 drive:drive:readonly 和 drive:drive.metadata:readonly,只开前者会被拒绝;另需 docx:document:readonly、sheets:spreadsheet:readonly、bitable:app:readonly |
| 钉钉文档 | 读取范围二选一:「知识库 ID」(可再填「起始文件夹节点 ID」),或「指定文档节点 ID」(最多 100 个,逗号分隔)。另外必填「操作用户 unionId」 | 「App Key」加「App Secret」,由服务自动续期令牌;或只填「临时访问 Token」。两种方式不能混用 | 知识库 ID 是钉钉接口返回的 workspaceId,可能与网页链接里 spaces/ 后面的 ID 不同。不知道 unionId 时,先填好「App Key」和「App Secret」(不能填「临时访问 Token」),再点表单里的「扫码获取本人标识」,先点「打开钉钉授权页」扫码授权,回来点「读取授权结果」,授权结果 10 分钟内有效 |
| 腾讯文档 | 方式一(推荐):「授权文件夹 ID」,即云盘文件夹链接里 folder/ 后面的 ID。方式二(旧版):「旧版 OpenAPI 文件 ID」「旧版 Client ID」「旧版用户 Open ID」,三项要填全。两种方式不能混填 | 「腾讯文档连接 Token」 | Token 用腾讯文档官方的快捷接入页获取。知汇只同步指定的文件夹及其下级,不列出用户的根目录 |
| Confluence Server / Data Center | 「Confluence 站点地址」,含上下文路径,例如 https://example.com/confluence/,不含 /rest;「空间 Key」,只含字母和数字,个人空间(以 ~ 开头)暂不支持 | 「个人访问令牌(PAT)」,或「用户名」加「密码」,二选一,用户名不能含冒号 | 令牌需要 Confluence 7.9 及以上。建议用只读账号。内网地址放行出站,默认要求 HTTPS |
| WebDAV(NAS / 网盘) | 「WebDAV 目录地址」,完整的目录地址,读取该目录及子目录 | 「用户名」加「密码或应用专用密码」,或只填「Bearer Token」,二选一 | 建议用只读账号或应用专用密码。内网地址放行出站 |
| S3 兼容对象存储 | 「服务地址」只填协议、主机和端口;「区域」;「存储桶」;「对象前缀」可选;「寻址方式」可选,路径方式 path(MinIO 等,默认)或虚拟主机 virtual(阿里云 OSS、腾讯云 COS) | 「Access Key ID」「Secret Access Key」,「Session Token」可选 | 单独建一个只授予列举和读取的凭证:AWS 为 s3:ListBucket 加 s3:GetObject,OSS 为 oss:ListObjects 加 oss:GetObject,COS 为 GetBucket 加 GetObject。不要授予写入、删除或管理权限。虚拟主机寻址时存储桶名不能含点号 |
| WeKnora(腾讯知识库) | 「WeKnora 后端地址」,不含 /api/v1;「知识库 ID」,最多 100 个,逗号分隔;「空间 ID(tenant_id)」可选,只在用平台 API Key 时填;「只同步的目录」可选;「实时联合检索」可选,默认关闭;「WeKnora 前端地址」可选,必须是 https,用于引用跳回原文 | 「API Key」 | 在 WeKnora 的「设置 › 集成 › API 集成」为知汇单独建一把空间 API Key,只勾选「检索知识库」,知识库范围限定为要同步的库。知识库 ID 在 WeKnora 里打开知识库,从地址 /platform/knowledge-bases/ 后面取。WeKnora 没有文档级访问控制,只配置愿意让对应 Agent 看到的知识库 |
NAS 上的 SMB 共享,知汇不内置 SMB 客户端。做法是在宿主机以只读方式挂载共享,再把挂载点以只读卷放进知汇容器,登记为本地根目录,之后按「本地文库」配置。部署目录里有一份叠加用的示例 compose.smb.example.yaml。
飞书、钉钉、腾讯文档这类云文档来源,能否读到还取决于应用是否开通、内容是否授权、平台套餐和配额。选了这个来源,不等于已经连上账号,要靠连接测试和实际同步来确认。
改动和移除来源的后果
- 修改来源的读取范围或凭据后,该来源原有的索引会全部撤回,Agent 对这些文件的授权随之变成「资源不存在」,需要重新同步,并重新授权。只改来源名称不受影响。如果保存时提示此来源仍有文件夹授权,先移除相关授权再改。
- 「移除资料来源」只移除知汇里的接入配置、凭据和索引,来源系统里的原文不受影响。
- 来源的凭据加密保存,只写不读。部署的算法套件切换后,旧值仍可读,下次保存时重新加密。