知识库

阿里云 OSS

以 Markdown 格式查看

阿里云 OSS 连接器用于索引对象存储中已经批准的文件。建议每个业务知识目录配置一个连接器，并把 RAM 权限限制到 AIvis 需要读取的存储桶和前缀。

需要准备什么

项目要求
存储桶AIvis worker 可访问的私有 OSS bucket。
前缀非空对象前缀，例如 knowledge/ 或 projects/legal/。除非整桶已专门整理，否则不要索引整个 bucket。
区域OSS Region ID，例如 cn-hangzhou 或 cn-shanghai。
凭据RAM 用户的 AccessKey ID 和 AccessKey Secret，只授予目标前缀的只读权限。
Endpoint通常留空。AIvis 会按区域生成 https://oss-{region}.aliyuncs.com；仅在网络路径或 CNAME 策略要求时填写自定义 endpoint。

OSS 使用扁平对象 key 存储。控制台里的文件夹由对象 key 前缀和 / 分隔符模拟。授权某个“文件夹”等价于授权所有以该前缀开头的对象。

阿里云侧准备

  1. 登录阿里云控制台，进入 RAM。
  2. 创建专用于 AIvis 的 RAM 用户，例如 aivis-oss-reader。
  3. 开启 OpenAPI/编程访问，并为该 RAM 用户创建 AccessKey。
  4. 立即保存 AccessKey ID 和 AccessKey Secret。AccessKey Secret 只在创建时显示一次。
  5. 打开目标 OSS bucket，确认区域，例如 cn-hangzhou。
  6. 将已批准文件上传到专用前缀，例如 knowledge/。

最小 RAM Policy

只授予列举和读取权限。列举权限通过 oss:Prefix 限制，读取权限限制到对象资源路径。

1{
2  "Version": "1",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": "oss:ListObjects",
7      "Resource": "acs:oss:*:*:aivis-docs",
8      "Condition": {
9        "StringLike": {
10          "oss:Prefix": [
11            "knowledge/",
12            "knowledge/*"
13          ]
14        }
15      }
16    },
17    {
18      "Effect": "Allow",
19      "Action": [
20        "oss:GetObject"
21      ],
22      "Resource": "acs:oss:*:*:aivis-docs/knowledge/*"
23    }
24  ]
25}

不要授予 oss:PutObject、oss:DeleteObject、bucket 管理权限或宽泛的 oss:*。如果对象使用 KMS 服务端加密，请确认该 RAM 身份读取时是否还需要 kms:Decrypt。

凭据填写

在 AIvis 中创建阿里云 OSS 凭据：

AIvis 字段填写值
Key ID / Access Key IDRAM 用户的 AccessKey ID。
Secret key / Secret Access Key与 AccessKey ID 配套的 AccessKey Secret。
Session Token永久 AccessKey 留空；仅使用 STS 临时凭据时填写。

如果密钥被共享、丢失或权限过宽，请在 RAM 中轮换。

连接器填写

AIvis 字段示例说明
连接器名称阿里云 OSS 知识库使用能识别 bucket 和业务范围的名称。
Bucket Nameaivis-docs只填 bucket 名称，不填 oss:// URL。
Prefixknowledge/必填且非空。文件夹范围建议以 / 结尾。
Regioncn-hangzhou小写区域 ID。
Custom Endpoint URL留空或 https://oss-cn-hangzhou.aliyuncs.com可选。必须包含 https://，且不能包含凭据、query 或 fragment。
ACL 限制确认勾选OSS 对象 ACL 不会同步为 AIvis 搜索权限。
文档访问权限建议选择私有并指定用户或用户组。按受众拆分前缀和连接器。

连接器使用 S3 兼容签名请求和虚拟主机风格寻址。如果 bucket 位于受阿里云 endpoint 或 CNAME 策略影响的中国内地区域，请配置有效自定义 endpoint，并确认 AIvis worker 网络可访问。

验证

  1. 确认凭据校验通过。
  2. 用小范围前缀创建连接器，例如 knowledge/test/。
  3. 执行一次索引，确认结果只包含该前缀下对象。
  4. 搜索上传文件中的代表性标题或句子。
  5. 确认未选前缀和敏感文件不在结果中。
  6. 用未授权 AIvis 用户测试，确认私有连接器内容不可搜索。

故障排查

现象可能原因与处理方式
凭据无效AccessKey ID 和 Secret 不属于同一个 RAM 用户、Secret 复制错误或密钥已禁用。请创建或轮换 RAM AccessKey。
找不到 bucketBucket 名称、区域或 endpoint 与真实 bucket 不匹配。检查 OSS bucket 区域和 endpoint。
无法列举对象RAM policy 缺少 bucket 上的 oss:ListObjects，或 oss:Prefix 条件排除了连接器前缀。
对象能列出但无法读取RAM policy 缺少 bucket/prefix/* 上的 oss:GetObject，或加密对象还需要解密权限。
索引了过多文件Prefix 过宽。使用 knowledge/ 这类业务目录，并在 RAM policy 中限制同一前缀。
用户能搜索不该访问的文件OSS 对象 ACL 不会同步到 AIvis。请使用私有文档访问权限，或按受众拆分连接器。

相关官方文档