知识库

MinIO

以 Markdown 格式查看

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 和管理员凭据：
$mc alias set myminio https://minio.example.com MINIO_ADMIN_ACCESS_KEY MINIO_ADMIN_SECRET_KEY
  1. 创建或确认 bucket，例如 aivis-docs。
  2. 将已批准文档上传到专用前缀，例如 knowledge/。
  3. 为 AIvis 创建限定范围的 policy 和 access key。不要使用 root 凭据。

最小 MinIO Policy

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

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "s3:ListBucket"
8      ],
9      "Resource": [
10        "arn:aws:s3:::aivis-docs"
11      ],
12      "Condition": {
13        "StringLike": {
14          "s3:prefix": [
15            "knowledge/",
16            "knowledge/*"
17          ]
18        }
19      }
20    },
21    {
22      "Effect": "Allow",
23      "Action": [
24        "s3:GetObject"
25      ],
26      "Resource": [
27        "arn:aws:s3:::aivis-docs/knowledge/*"
28      ]
29    }
30  ]
31}

示例 mc 流程：

$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 Nameaivis-docs只填 bucket 名称。
Prefixknowledge/必填且非空。AIvis 会移除开头的 /。
Endpoint URLhttps://minio.example.com必填。包含 scheme 和可选端口。
Regionus-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。请使用私有文档访问权限，或按受众拆分连接器。

相关官方文档