> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 阿里云 OSS

> 使用最小权限 RAM AccessKey 和明确存储桶前缀配置阿里云 OSS 连接器。

阿里云 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` 限制，读取权限限制到对象资源路径。

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "oss:ListObjects",
      "Resource": "acs:oss:*:*:aivis-docs",
      "Condition": {
        "StringLike": {
          "oss:Prefix": [
            "knowledge/",
            "knowledge/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject"
      ],
      "Resource": "acs:oss:*:*:aivis-docs/knowledge/*"
    }
  ]
}
```

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

## 凭据填写

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

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

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

## 连接器填写

| AIvis 字段            | 示例                                         | 说明                                           |
| ------------------- | ------------------------------------------ | -------------------------------------------- |
| 连接器名称               | `阿里云 OSS 知识库`                              | 使用能识别 bucket 和业务范围的名称。                       |
| Bucket Name         | `aivis-docs`                               | 只填 bucket 名称，不填 `oss://` URL。                |
| Prefix              | `knowledge/`                               | 必填且非空。文件夹范围建议以 `/` 结尾。                       |
| Region              | `cn-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。 |
| 找不到 bucket   | Bucket 名称、区域或 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。请使用私有文档访问权限，或按受众拆分连接器。                               |

## 相关官方文档

* [阿里云 OSS RAM Policy 访问控制](https://www.alibabacloud.com/help/en/oss/user-guide/access-control-base-on-ram-policy)
* [阿里云 OSS 地域和 endpoint](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints)
* [阿里云 RAM AccessKey](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair)
* [阿里云 OSS ListObjects](https://www.alibabacloud.com/help/en/oss/developer-reference/listobjects)
* [阿里云 OSS GetObject](https://www.alibabacloud.com/help/en/oss/developer-reference/getobject)