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

# MinIO

> 使用限定范围的 S3 兼容访问密钥和明确 bucket 前缀配置 MinIO 连接器。

MinIO 连接器用于索引 MinIO bucket 中已经批准的文件。AIvis 通过 S3 兼容 API 连接，列举指定前缀下的对象，下载匹配对象，并索引支持的文件类型。

## 需要准备什么

| 项目           | 要求                                                                                    |
| ------------ | ------------------------------------------------------------------------------------- |
| Endpoint URL | 完整 MinIO API endpoint，例如 `https://minio.example.com` 或 `https://minio.internal:9000`。 |
| Bucket       | 已存在的 MinIO bucket。                                                                    |
| Prefix       | 非空前缀，例如 `knowledge/`。                                                                 |
| 凭据           | 对目标 bucket 和 prefix 拥有 `s3:ListBucket` 与 `s3:GetObject` 的 access key / secret key。    |
| Region       | 可选。仅当 MinIO 部署或代理要求特定 region 字符串时填写。                                                  |
| HTTP 设置      | 使用 HTTPS。仅可信内网开发环境才启用不安全 HTTP。                                                        |

AIvis 对 MinIO 使用 path-style S3 请求。Endpoint 必须是 origin URL，不能包含凭据、query 或 fragment。

## MinIO 侧准备

1. 确认 AIvis worker 能访问 MinIO API endpoint。
2. 用 `mc alias set` 验证 endpoint 和管理员凭据：

```bash
mc alias set myminio https://minio.example.com MINIO_ADMIN_ACCESS_KEY MINIO_ADMIN_SECRET_KEY
```

3. 创建或确认 bucket，例如 `aivis-docs`。
4. 将已批准文档上传到专用前缀，例如 `knowledge/`。
5. 为 AIvis 创建限定范围的 policy 和 access key。不要使用 root 凭据。

## 最小 MinIO Policy

MinIO 内置 `readonly` policy 不包含 bucket 列举权限。AIvis 需要列举配置前缀下的对象，因此请创建自定义 policy：对 bucket 允许 `s3:ListBucket`，对前缀允许 `s3:GetObject`。

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::aivis-docs"
      ],
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "knowledge/",
            "knowledge/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::aivis-docs/knowledge/*"
      ]
    }
  ]
}
```

示例 `mc` 流程：

```bash
mc admin policy create myminio aivis-knowledge-readonly ./aivis-knowledge-readonly.json
mc admin user add myminio aivis-reader '<generated-secret>'
mc admin policy attach myminio aivis-knowledge-readonly --user aivis-reader
```

如果使用现有用户的 service account 或 access key，请给该 key 绑定同等范围的 policy。该 key 不能获得超过父用户已拥有权限的访问范围。

## 凭据填写

在 AIvis 中创建 MinIO 凭据：

| AIvis 字段                       | 填写值                                       |
| ------------------------------ | ----------------------------------------- |
| Key ID / Access Key ID         | 限定用户或 service account 的 MinIO access key。 |
| Secret key / Secret Access Key | 与 access key 配套的 secret key。              |
| Session Token                  | 通常留空；仅当部署发放临时 S3 兼容凭据时填写。                 |

## 连接器填写

| AIvis 字段            | 示例                          | 说明                                          |
| ------------------- | --------------------------- | ------------------------------------------- |
| 连接器名称               | `MinIO 知识库`                 | 使用能识别部署和 bucket 范围的名称。                      |
| Bucket Name         | `aivis-docs`                | 只填 bucket 名称。                               |
| Prefix              | `knowledge/`                | 必填且非空。AIvis 会移除开头的 `/`。                     |
| Endpoint URL        | `https://minio.example.com` | 必填。包含 scheme 和可选端口。                         |
| Region              | `us-east-1` 或留空             | 可选。仅 MinIO 配置要求时填写。                         |
| Allow insecure HTTP | 关闭                          | 仅可信内网开发 endpoint（如 `http://minio:9000`）才开启。 |
| ACL 限制确认            | 勾选                          | MinIO policy 和对象 ACL 不会同步为 AIvis 搜索权限。      |
| 文档访问权限              | 建议选择**私有**并指定用户或用户组。        | 按受众拆分前缀和连接器。                                |

## 验证

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

## 故障排查

| 现象                 | 可能原因与处理方式                                                                |
| ------------------ | ------------------------------------------------------------------------ |
| Endpoint 被拒绝       | 缺少 `https://`、包含凭据/query/fragment，或使用 HTTP 但未开启 **Allow insecure HTTP**。 |
| 凭据无效               | Access key 和 secret key 不匹配、已禁用，或所属用户没有限定 policy。                        |
| 无法列举对象             | Policy 缺少 bucket 上的 `s3:ListBucket`，或 `s3:prefix` 条件排除了连接器前缀。            |
| 对象能列出但无法读取         | Policy 缺少 `bucket/prefix/*` 上的 `s3:GetObject`。                           |
| `mc` 能连接但 AIvis 不能 | 确认 endpoint 是从 AIvis worker 网络可达，而不只是本机可达。检查 DNS、TLS 证书信任、端口和私有网络策略。     |
| 用户能搜索不该访问的文件       | MinIO policy 不会同步到 AIvis。请使用私有文档访问权限，或按受众拆分连接器。                          |

## 相关官方文档

* [MinIO Client quickstart](https://minio.github.io/mc/)
* [MinIO policy-based access management](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html)
* [MinIO `mc admin policy`](https://min.io/docs/minio/linux/reference/minio-mc-admin/mc-admin-policy.html)
* [MinIO `mc admin accesskey create`](https://min.io/docs/minio/linux/reference/minio-mc-admin/mc-admin-accesskey-create.html)