> 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.

# 华为云 OBS

> 使用最小权限 AK/SK 和明确存储桶前缀配置华为云 OBS 连接器。

华为云 OBS 连接器用于索引对象存储中已经批准的文件。建议每个知识目录配置一个连接器，并把 IAM policy 限制到 AIvis 需要读取的 bucket 和对象前缀。

## 需要准备什么

| 项目       | 要求                                                                                       |
| -------- | ---------------------------------------------------------------------------------------- |
| 存储桶      | AIvis worker 可访问的私有 OBS bucket。                                                          |
| 前缀       | 非空对象前缀，例如 `knowledge/` 或 `team/product/`。                                                |
| 区域       | 华为云 Region ID，例如 `cn-north-4` 或 `ap-southeast-1`。                                        |
| 凭据       | 拥有列举和读取权限的 IAM 用户 Access Key ID 和 Secret Access Key。                                     |
| Endpoint | 通常留空。AIvis 会按区域生成 `https://obs.{region}.myhuaweicloud.com`；私有、专线或批准的网络路径可填写自定义 endpoint。 |

OBS endpoint 按区域提供。Bucket 访问域名格式是 `BucketName.Endpoint`，例如 `bucketname.obs.ap-southeast-1.myhuaweicloud.com`。AIvis 需要分别填写区域 endpoint 和 bucket 名称，不要把完整 bucket 域名填入 Bucket Name。

## 华为云侧准备

1. 登录华为云控制台，进入 **IAM**。
2. 创建专用于 AIvis 的 IAM 用户，例如 `aivis-obs-reader`。
3. 创建编程访问用 AK/SK，并安全保存 Secret。
4. 打开 OBS bucket，确认区域 ID。
5. 将已批准文件上传到专用前缀，例如 `knowledge/`。
6. 绑定只包含该范围列举和读取权限的自定义 OBS policy。

## 最小 IAM Policy

经典 IAM policy 使用 `obs:bucket:ListBucket` 和 `obs:object:GetObject`。新版身份策略环境可能使用 `obs:bucket:listBucket` 和 `obs:object:getObject` 这类小写 action；请按当前华为云 IAM 版本要求调整。

```json
{
  "Version": "1.1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "obs:object:GetObject",
        "obs:bucket:ListBucket"
      ],
      "Resource": [
        "obs:*:*:object:aivis-docs/knowledge/*",
        "obs:*:*:bucket:aivis-docs"
      ]
    }
  ]
}
```

不要授予上传、删除、bucket policy 管理或宽泛的 `obs:*:*` 权限。如果 bucket 使用 KMS 或其他加密依赖，请用同一个 IAM 用户在生产索引前验证解密权限。

## 凭据填写

在 AIvis 中创建华为云 OBS 凭据：

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

## 连接器填写

| AIvis 字段            | 示例                                             | 说明                                           |
| ------------------- | ---------------------------------------------- | -------------------------------------------- |
| 连接器名称               | `华为云 OBS 知识库`                                  | 使用能识别部署、bucket 和业务范围的名称。                     |
| Bucket Name         | `aivis-docs`                                   | 只填 bucket 名称。                                |
| Prefix              | `knowledge/`                                   | 必填且非空。AIvis 会移除开头的 `/`。                      |
| Region              | `cn-north-4`                                   | 小写区域 ID。                                     |
| Custom Endpoint URL | 留空或 `https://obs.cn-north-4.myhuaweicloud.com` | 可选。必须包含 `https://`，且不能包含凭据、query 或 fragment。 |
| ACL 限制确认            | 勾选                                             | OBS ACL 不会同步为 AIvis 搜索权限。                    |
| 文档访问权限              | 建议选择**私有**并指定用户或用户组。                           | 按受众拆分前缀和连接器。                                 |

连接器使用 S3 兼容签名请求和虚拟主机风格寻址。如果使用内网、云专线、双栈或自定义 endpoint，请先从 AIvis worker 网络验证可达性。

## 验证

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

## 故障排查

| 现象           | 可能原因与处理方式                                                                           |
| ------------ | ----------------------------------------------------------------------------------- |
| 凭据无效         | AK/SK 不匹配、密钥被禁用或 IAM 用户错误。请轮换密钥后重试。                                                 |
| 无法访问 bucket  | 区域或 endpoint 与 bucket 不匹配。检查 OBS 区域 endpoint 格式。                                    |
| 无法列举对象       | IAM policy 缺少 bucket 上的 `obs:bucket:ListBucket` / `obs:bucket:listBucket`。          |
| 对象能列出但无法读取   | IAM policy 缺少 `bucket/prefix/*` 上的 `obs:object:GetObject` / `obs:object:getObject`。 |
| 目录只出现一部分     | OBS 列举基于前缀且分页；检查配置前缀，以及文件是否位于其他 key 前缀下。                                            |
| 用户能搜索不该访问的文件 | OBS ACL 不会同步到 AIvis。请使用私有文档访问权限，或按受众拆分连接器。                                          |

## 相关官方文档

* [华为云 OBS IAM 权限](https://support.huaweicloud.com/intl/en-us/perms-cfg-obs/obs_40_0003.html)
* [华为云 OBS endpoint 与域名](https://support.huaweicloud.com/intl/en-us/productdesc-obs/obs_03_0152.html)
* [华为云 OBS ListObjects](https://support.huaweicloud.com/intl/en-us/api-obs/obs_04_0022.html)
* [华为云 OBS 源端权限 FAQ](https://support.huaweicloud.com/intl/en-us/oms_faq/topic_0000001084426802.html)