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

# 腾讯云 COS

> 配置腾讯云 COS 连接器，用最小只读权限索引指定存储桶前缀下的文件。

腾讯云 COS 连接器用于索引对象存储中已经批准的文件范围。建议为每个业务知识目录配置单独连接器，并把腾讯云 CAM 权限限制到具体存储桶和前缀。

## 适用场景

| 场景       | 建议                                     |
| -------- | -------------------------------------- |
| COS 知识目录 | 使用固定存储桶和前缀，例如 `knowledge/`，只同步该目录下的对象。 |
| 项目资料检索   | 每个项目使用独立前缀，便于授权、停用和重新索引。               |
| 受限文件     | 使用艾维斯**私有**文档访问权限并指定用户或用户组。            |
| 公共桶迁移    | 先把 COS 存储桶改为**私有读写**，再用最小只读 CAM 子账号接入。 |

## 腾讯云侧准备

1. 登录腾讯云控制台。
2. 进入**访问管理 CAM** → **用户** → **用户列表**。
3. 推荐新建一个专用于该部署的子用户，例如 `aivis-cos-reader`。不要使用主账号密钥。
4. 打开该子用户详情，进入**API 密钥**，点击**新建密钥**。
5. 创建后保存 `SecretId` 和 `SecretKey`：
   * `SecretId` 填入艾维斯凭据的**密钥 ID**。
   * `SecretKey` 填入艾维斯凭据的**密钥**。
   * 使用永久密钥时，**Session Token** 留空。

腾讯云自 2023 年 11 月 30 日起关闭查询 `SecretKey` 的功能，新建密钥只在创建时显示一次。如果之前没有保存，无法再次查看，只能新建一组密钥，并在验证成功后删除或禁用旧密钥。参见[腾讯云子账号访问密钥管理](https://cloud.tencent.com/document/product/598/37140)。

## COS 文件与权限

在 COS 控制台中完成以下配置：

1. 打开目标存储桶，例如 `aivis-cos-test-1250000000`。
2. 在**文件列表**中创建 `knowledge/` 文件夹。
3. 将待索引的 PDF、Word、Markdown、TXT 等文件上传到该文件夹。
4. 给 CAM 子账号授予只读权限，范围限制到 `aivis-cos-test-1250000000/knowledge/*`。

至少允许以下操作：

| 权限              | 用途                      |
| --------------- | ----------------------- |
| `cos:GetBucket` | 列举 `knowledge/` 前缀下的对象。 |
| `cos:GetObject` | 读取对象内容用于索引。             |

不要授予写入或删除权限。若当前存储桶仍为**公有读写**，请先改为**私有读写**，再创建或启用连接器。

## 凭据填写

在艾维斯中创建腾讯云 COS 凭据：

![创建腾讯云 COS 凭据弹窗，填写 SecretId、SecretKey，永久密钥的 Session Token 留空](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2e6591cb1b734a6c05a1e86372777bd413e08bab81aa3a53ca69946498afff71/assets/aivis/tencent-cos/tencent-cos-credential-form.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T115905Z&X-Amz-Expires=604800&X-Amz-Signature=c129b7d13655a59f32e3bb15fa815f38a94b3b67c0cd4e33df3c6c5c421d58a8&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| 字段               | 填写值                                      |
| ---------------- | ---------------------------------------- |
| SecretId / 密钥 ID | 腾讯云 CAM 子账号生成的 `SecretId`，通常以 `AKID` 开头。 |
| SecretKey / 密钥   | 与该 `SecretId` 配套的 `SecretKey`。           |
| Session Token    | 使用永久密钥时留空；仅在使用临时密钥时填写。                   |

不要填写其他系统的 `cli_...` Client ID，也不要把 `SecretKey` 发给任何人或提交到代码仓库。

## 连接器填写示例

以下示例对应一个只索引 `knowledge/` 目录的测试连接器：

![腾讯云 COS 连接器表单，填写连接器名称、存储桶名称、前缀、区域，并确认对象 ACL 限制](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/4f5ddda82bcb75f488f1f92d53b4de67a52f953da6a63b53554d79bfbca9f413/assets/aivis/tencent-cos/tencent-cos-connector-form.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T115905Z&X-Amz-Expires=604800&X-Amz-Signature=58b5f8bcb17d8bd8f14531b8c0d045e451de4eeefdc67a2b4b2cfcc7f2828fa5&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| 字段          | 填写值                         |
| ----------- | --------------------------- |
| 连接器名称       | 腾讯云 COS 测试                  |
| 存储桶名称       | `aivis-cos-test-1250000000` |
| 前缀          | `knowledge/`                |
| 区域          | `ap-guangzhou`              |
| 高级 Endpoint | 留空                          |
| ACL 限制确认    | 勾选                          |
| 文档访问权限      | 建议选择**私有**并指定用户或用户组。        |

前缀应以 `/` 之外的普通目录名开头，并建议以 `/` 结尾。不要把未获批准的目录放在同一个连接器范围内。

## 验证

![腾讯云 COS 连接器列表显示正在索引、组织内公开和已索引文档数量](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/34ae57acd3f5dad750d9c312444a862a91e908d7133679b5c2bc0a733bb68858/assets/aivis/tencent-cos/tencent-cos-indexing-list.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T115905Z&X-Amz-Expires=604800&X-Amz-Signature=fc3db4c24e6765a9209ca085334af7a345274f67a8e9998fccf331a8753b7ab1&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

1. 创建凭据后，确认凭据校验通过。
2. 创建连接器并运行一次索引尝试。
3. 确认索引结果只包含 `knowledge/` 前缀下的对象。
4. 搜索上传文件中的代表性标题或句子，确认可以命中并引用来源。
5. 使用未被授权的艾维斯用户验证私有连接器内容不可搜索。

## 故障排查

| 现象           | 可能原因与处理方式                                                                   |
| ------------ | --------------------------------------------------------------------------- |
| 凭据无效         | 确认 `SecretId` 和 `SecretKey` 属于同一个 CAM 子账号，且没有把 `cli_...` Client ID 填入密钥 ID。 |
| 无法列举对象       | 确认子账号拥有目标存储桶和前缀的 `cos:GetBucket` 权限，并检查区域是否为 `ap-guangzhou` 等真实桶区域。         |
| 对象列出但读取失败    | 确认子账号拥有 `cos:GetObject` 权限，且授权范围覆盖 `knowledge/*`。                           |
| 索引了过多文件      | 检查前缀是否过宽。请使用 `knowledge/` 这类明确目录，并把 CAM 策略限制到同一前缀。                          |
| 用户能搜索不该访问的文件 | COS 文件 ACL 不会自动同步为艾维斯搜索权限。请使用私有文档访问权限，或按受众拆分存储桶前缀和连接器。                      |

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)