# 对象存储与搜索

Raise 平台的对象存储由环境包决定，支持本机目录卷、自建 SeaweedFS 以及云端对象存储（阿里云 OSS、腾讯云 COS、Amazon S3）；组织也可以改用自己的 S3 兼容对象存储桶。平台的搜索体系分为应用内关键词搜索、平台知识库检索（支持可选的 pgvector 语义向量检索）以及可选的联网搜索（DeepSeek 搜索，由运营方在运营控制台配置）。

## 谁能用

不同角色在对象存储与搜索配置中的权限与职责如下：

| 角色 / 身份 | 权限要求 | 权限说明 |
|---|---|---|
| 部署运维人员 | 主机系统权限 | 负责选择部署环境包（pack），配置 `--infra` 启动内置 SeaweedFS 或填写云端存储密钥；配置 pgvector 与 `KWORK_EMBED_MODEL` 启用语义向量检索。 |
| 组织管理员 | `admin.write` | 可以在「我的组织」中管理「存储」设置（开启或关闭「使用自己的存储」），以及在「Skill 与连接」中开启或关闭「允许助手联网搜索」。 |
| 组织审计员 | `admin.read` / 审计员 | 拥有只读查看权限，可以查看存储配置与测试状态，但不能修改设置。 |
| 普通成员 | 无管理权限 | 无权访问组织存储配置。若部署未开放自带存储，界面显示「自带存储不可用」与「只能使用平台存储。」。 |

> **注意**
>
> 若对象存储发生故障，平台的文件上传、下载、附件与导出功能均会失败，审计归档的封存操作也会推迟。

## 怎么打开

你可以通过以下入口进入对应的存储管理、搜索配置与文件访问端点：

1. **部署配置与运维命令**：
   - 在部署配置文件中通过 `KWORK_BLOB` 配置平台存储类型（`fs` 或 `s3`）。
   - 在终端执行存储初始化引导命令：
     ```bash
     kwork bootstrap s3
     ```
   - 公网文件访问入口（由 Caddy 反向代理）：`https://files.{base}`。
   - 使用 Helm 部署时，多副本部署必须使用 S3 存储；`storage.blob=fs` 仅允许 1 个副本。
2. **组织自带存储配置入口**：
   - 登录 [工作台](/guide/workspace)，在左侧导航进入「我的组织」→ 数据「存储」。
3. **助手联网搜索配置入口**：
   - 登录 [工作台](/guide/workspace)，在左侧导航进入「我的组织」→ 助手「Skill 与连接」→「联网搜索」。

## 界面一览

### 1. 「我的组织」→「存储」管理页

在「我的组织」的数据「存储」页面中，包含以下区域与功能项：

- **状态卡片区**：
  - **「当前使用」**：显示当前生效的存储模式，显示为「平台存储」或「自带存储」（自带存储时显示为存储桶@端点）。
  - **「已存文件」**：显示存储用量统计。若无法统计则显示无法统计状态；正常时显示说明「当前存储中的总量。」；若文件数量过多，则提示「只统计了前 5 万个文件，实际更多。」。
  - **「最近一次测试」**：显示存储连通性测试的结果，状态包括「通过」、「失败」或「未测试」。
- **「存储位置」设置区**：
  - 提供开关「使用自己的存储」，支持接入 MinIO、AWS S3、阿里云 OSS、腾讯云 COS 等 S3 兼容对象存储。
- **「连接设置」表单区**：
  - **「快速填充」**：提供常用存储模板，包括「MinIO / SeaweedFS / Ceph（自建）」、「Amazon S3」、「阿里云 OSS」、「腾讯云 COS」。
  - **配置字段**：
    | 字段 | 必填 | 说明 |
    |---|---|---|
    | 「端点」 | 是 | 对象存储的服务端点地址。 |
    | 「浏览器访问地址」 | 否 | 供浏览器直接访问的端点地址，可留空。 |
    | 「存储桶」 | 是 | 用于存放文件的存储桶名称。 |
    | 「路径前缀」 | 否 | 存储对象的前缀路径。 |
    | 「区域」 | 否 | 存储桶所在的物理区域。 |
    | 「访问密钥 Access Key 」 | 否 | 对象存储的访问密钥标识。 |
    | 「私有密钥 Secret Key」 | 否 | 对象存储的私有访问密钥。 |
    | 「路径风格寻址」 | 否 | 开关选项。MinIO、SeaweedFS 开启，AWS、OSS、COS 关闭。 |
- **操作按钮**：
  - **「只测试，不保存」**：仅执行连通性探测流程，不保存表单内容。
  - **「测试并保存」**：执行连通性探测，全部必要项通过后保存当前连接设置。
  - **「重新测试已保存的设置」**：配置保存后显示，用于重新验证当前配置的连通性。
  - **「将改回平台存储」**：配置自带存储后显示，用于发起切回平台存储。
- **连通性探测进度**：
  - 探测过程依次包含 7 项测试：「连接与权限」、「写入」、「读取」、「列出」、「预签名上传」、「浏览器跨域（CORS）」、「删除」。
- **「存储桶 CORS 配置」说明**：
  - 界面提供存储桶 CORS 配置示例，包含允许的跨域源地址（origins）：`https://*.apps.{base}` 与 `https://app.{base}`。
- **改回平台存储确认弹窗**：
  - 点击「将改回平台存储」后弹出确认对话框「改回平台存储？」，弹窗内提示「你存储桶里已有的文件不会被删除或迁移。」。

### 2. 「我的组织」→「Skill 与连接」→「联网搜索」设置页

在「Skill 与连接」的「联网搜索」区域中：

- 提供开关「允许助手联网搜索」。
- 平台未配置搜索服务时，开关下方提示「平台未配置搜索服务，开启暂不生效。」。
- 开关开启时，状态说明显示为「开：需要时联网搜索，并给出来源链接。」。
- 开关关闭时，状态说明显示为「关：只用你们自己的数据和已有知识回答。」。系统默认保持关闭。

## 常用操作

### 部署平台对象存储

根据运行环境与架构需求，部署平台自带存储或对接云厂商对象存储：

1. **部署自带 SeaweedFS 存储（适用于私有部署）**：
   1. 在部署配置中选用 `onprem` 环境包，并在执行安装脚本时附加 `--infra` 参数。安装脚本会自动启动 `openbao` 与 `seaweedfs` 服务，并生成身份凭据。
   2. 在服务器终端执行存储初始化引导命令：
      ```bash
      kwork bootstrap s3
      ```
      命令会自动创建平台默认存储桶 `kwork`。
   3. 系统在创建审计归档桶时，由于 SeaweedFS 不支持 S3 对象锁定功能，审计归档会退化为「独立副本，未锁定」（组织应用内会显示相应提示）。若业务需要强制对象锁定，必须改用 MinIO 或支持锁定的云端 S3 服务。
2. **对接云厂商对象存储**：
   1. 根据目标云平台选用对应的环境包（如 `aliyun`、`tencent` 或 `aws`）。
   2. 在环境配置文件 `.env` 中设置 `KWORK_BLOB=s3`。生产环境中配置为 `s3` 时必须填写端点与存储桶。
   3. 按照云厂商规则填写对应配置：
      - **阿里云 OSS**：端点设置为 `https://oss-${ALIYUN_REGION}.aliyuncs.com`，设置 `PATH_STYLE=false`，并填写存储桶名称。
      - **腾讯云 COS**：端点设置为 `https://cos.${COS_REGION}.myqcloud.com`，存储桶名称必须包含 APPID。
      - **Amazon S3**：端点设置为 `https://s3.${AWS_REGION}.amazonaws.com`。
   4. 在生产环境中必须配置 `KWORK_BLOB_SECRET` 环境变量，用于加密存储对象。
3. **使用单机本地卷存储（仅限开发与测试）**：
   1. 在 `single` 或 `dev` 环境包中设置 `KWORK_BLOB=fs`，数据保存在本机卷中。
   2. 禁止在多副本集群环境中使用 `fs`。使用 Helm 部署多副本时必须配置为 S3，`storage.blob=fs` 仅允许运行 1 个副本。

### 配置组织自带存储（BYO）

组织管理员可以将文件存储迁移至组织自备的 S3 兼容对象存储中：

1. 在对象存储服务商（如 AWS、阿里云、腾讯云或自建 MinIO）控制台中创建存储桶。
2. 为该存储桶创建访问密钥（Access Key 与 Secret Key），确保密钥拥有读、写、列出和删除权限。
3. 在云存储控制台中配置存储桶的 CORS 跨域规则，在允许来源（origins）中填入 `https://*.apps.{base}` 与 `https://app.{base}`。
4. 登录 [工作台](/guide/workspace)，在左侧导航进入「我的组织」→ 数据「存储」。
5. 在「存储位置」区域，点击打开「使用自己的存储」开关。
6. 在「连接设置」区域，点击「快速填充」选择对应存储模板，或手动输入「端点」、「浏览器访问地址」、「存储桶」、「路径前缀」、「区域」、「访问密钥 Access Key 」与「私有密钥 Secret Key」。
7. 根据存储类型设置「路径风格寻址」开关（MinIO、SeaweedFS 设为开启，AWS、OSS、COS 设为关闭）。
8. 点击表单下方的「测试并保存」按钮。
9. 系统依次执行 7 项连通性测试（包含「连接与权限」、「写入」、「读取」、「列出」、「预签名上传」、「浏览器跨域（CORS）」、「删除」）。
10. 若任一必要测试项未通过，系统不会保存设置，并弹出提示「没有通过连通性测试，设置没有保存。」；全部必要项通过后，配置保存成功，密钥安全存入 OpenBao。新设置仅对后续新上传的文件生效，已有文件不会被自动迁移。

### 改回平台存储

若不再使用自备存储桶，可以随时切回平台存储：

1. 登录 [工作台](/guide/workspace)，在左侧导航进入「我的组织」→ 数据「存储」。
2. 在存储配置区域，点击「将改回平台存储」按钮。
3. 界面弹出确认对话框「改回平台存储？」，阅读确认提示「你存储桶里已有的文件不会被删除或迁移。」。
4. 点击确认。切换后新上传的文件将保存至平台存储中；自备存储桶中的文件不会被删除，但在切回平台存储期间无法直接从平台访问这些文件。

### 配置与启用联网搜索

平台运营方配置搜索服务后，组织管理员可在后台开启助手联网搜索：

1. **运营方配置 DeepSeek 搜索**（平台唯一的搜索服务）：
   1. 在 DeepSeek 开放平台创建一个 API Key，确认账户有余额。
   2. 登录运营控制台，进入「模型」→「联网搜索」，点击「配置 DeepSeek」。
   3. 填入 API Key，打开「启用」开关，点击「保存」。API Key 保存后只显示后四位，原文只保存在密钥库中。
   4. 点击「测试」，看到「通了：搜「DeepSeek」返回 N 条结果」即配置成功。测试不计入任何组织的用量。
2. **组织管理员启用联网搜索**：
   1. 登录 [工作台](/guide/workspace)，在左侧导航进入「我的组织」→ 助手「Skill 与连接」→「联网搜索」。
   2. 点击打开「允许助手联网搜索」开关，状态变更为「开：需要时联网搜索，并给出来源链接。」。
3. **运行机制与限制**：
   - 运营台未配置或未启用联网搜索时，助手不会显示联网搜索能力，请求接口会返回 501 `web_search_unavailable`。
   - 平台已配置但组织未开启开关时，请求接口会返回 403 `web_search_disabled`。
   - 每次联网搜索均会记录审计日志（记录发起的用户或助手、搜索关键词、使用的搜索服务以及返回的结果数）。
   - 每次成功的搜索按点数向组织计费。
   - 搜索调用受频率限制，通过 `KWORK_WEBSEARCH_PER_MINUTE` 控制，默认每组织每分钟上限为 20 次。

### 配置与启用语义向量检索

启用基于向量的语义检索，需要底层数据库支持与嵌入模型配置：

1. **部署 pgvector 扩展**：
   - 新部署环境直接使用包含 pgvector 的数据库镜像，设置 `POSTGRES_IMAGE=pgvector/pgvector:pg17`。
   - 已有 Alpine 数据卷环境需使用专用的 Dockerfile 将扩展编译进同一 Alpine 基础镜像中。切勿直接更换为 Debian 镜像，以免操作系统排序规则变动损坏既有的文本索引。
2. **执行数据库迁移**：
   在扩展安装完成后执行数据库迁移，创建向量数据表。
3. **配置嵌入模型**：
   运营人员在平台模型目录中上架嵌入模型并完成定价，部署运维人员在环境变量 `KWORK_EMBED_MODEL` 中填入该嵌入模型的 ID。
4. **组织模型策略匹配**：
   组织的模型使用策略必须允许调用该嵌入模型。若组织未获授权、模型额度耗尽或所在区域不符，该组织的语义索引会暂停 5 分钟，搜索自动由语义混合检索降级为纯关键词检索。
5. **未配置降级**：
   若环境中未配置嵌入模型或未安装 pgvector，系统会自动且静默地将混合检索降级为关键词检索。

## 状态说明

### 存储模式与测试状态

| 状态类型 | 状态名称 | 说明 |
|---|---|---|
| 当前存储 | 「平台存储」 | 使用平台统一配置的对象存储或本地卷。 |
| 当前存储 | 「自带存储」 | 使用组织自备的 S3 兼容对象存储桶，界面显示为存储桶@端点。 |
| 测试结果 | 「通过」 | 连通性探测所有必要步骤均验证通过。 |
| 测试结果 | 「失败」 | 连通性探测中出现失败项，当前设置未保存或存在异常。 |
| 测试结果 | 「未测试」 | 尚未对当前配置执行连通性测试。 |

### 连通性探测步骤说明

| 探测步骤 | 检查内容 |
|---|---|
| 「连接与权限」 | 验证能否成功连接对象存储端点，并校验访问密钥权限。 |
| 「写入」 | 测试向存储桶中写入临时测试对象。 |
| 「读取」 | 测试从存储桶中读取刚才写入的测试对象。 |
| 「列出」 | 测试列出存储桶内对象列表的能力。 |
| 「预签名上传」 | 测试生成预签名上传链接并完成上传。 |
| 「浏览器跨域（CORS）」 | 测试浏览器跨域配置。此项未通过可能仅显示为警告，但会导致浏览器前端直传失败。 |
| 「删除」 | 测试清理并删除前面写入的临时测试对象。 |

### 联网搜索状态

| 状态说明 | 说明 |
|---|---|
| 「关：只用你们自己的数据和已有知识回答。」 | 默认状态。助手仅使用组织内部数据与已有知识回答，不进行公网检索。 |
| 「开：需要时联网搜索，并给出来源链接。」 | 开启状态。助手在回答需要最新公网信息的问题时会自动联网搜索，并在回答末尾附带来源链接。 |

## 让助手帮你做

你可以让助手起草组织存储设置与切换操作。助手起草完成后，需要由人工确认并填写敏感凭据。

你可以对助手说：

> "把文件存到我们自己的 OSS"
> "测一下桶能不能用再保存"
> "改回平台存储"

### 人工确认事项

- **配置自带存储**：助手仅起草「使用自己的存储」操作，访问密钥与私有密钥必须由人工在界面中输入，在点击保存时系统才会真正触发连通性探测流程。
- **改回平台存储**：助手仅起草「改回平台存储」操作，必须由人工在确认弹窗中确认切换。
- **只测不改限制**：独立的连通性测试不提供助手自动化操作，必须在界面中手动点击「只测试，不保存」。

### 助手不能做的事

- 助手不能自动迁移已有文件。
- 助手不能删除组织在第三方服务商处的存储桶。
- 助手不能配置联网搜索服务（DeepSeek API Key 只能由运营方在运营控制台填写）。
- 助手不能修改 `KWORK_EMBED_MODEL` 等系统环境变量。
- 助手在联网搜索时不能抓取网页全文。

## 设置

### 系统环境变量配置

| 变量名 | 作用说明 | 默认值 | 配置人员 |
|---|---|---|---|
| `KWORK_BLOB` | 平台对象存储引擎，可选值为 `fs`（本地卷）或 `s3`（对象存储）。 | `fs`（代码默认，环境包常覆盖） | 部署运维人员 |
| `KWORK_S3_ENDPOINT` 等 | S3 兼容对象存储连接端点及关联参数。 | 依据环境包预置 | 部署运维人员 |
| `KWORK_S3_PATH_STYLE` | 是否开启 S3 路径风格寻址。 | `true` | 部署运维人员 |
| `KWORK_S3_REGION` | S3 存储区域。 | `us-east-1` | 部署运维人员 |
| `KWORK_BLOB_SECRET` | 对象加密密钥。生产环境使用 `s3` 时必填。 | 空 | 部署运维人员 |
| `KWORK_WEBSEARCH_ALLOW_PRIVATE` | 是否允许运营台填写的搜索接口地址位于私有网络，仅测试使用。 | 未设置（默认否） | 部署运维人员 |
| `KWORK_WEBSEARCH_PER_MINUTE` | 每组织每分钟允许发起的联网搜索请求数上限。 | `20` | 部署运维人员 |
| `KWORK_EMBED_MODEL` | 向量嵌入模型的 ID。配置后启用语义检索。 | 空 | 部署运维人员 |

### 环境包预置存储方案

| 环境包（pack） | 存储配置（`KWORK_BLOB`） | 默认端点与说明 |
|---|---|---|
| `single` / `dev` | `fs` | 本机目录卷。**禁止用于多副本部署**。 |
| `onprem` | `s3` | 内置 SeaweedFS，端点为 `http://seaweedfs:8333`，默认存储桶为 `kwork`，开启路径风格寻址。 |
| `aliyun` | `s3` | 阿里云 OSS，端点为 `https://oss-${ALIYUN_REGION}.aliyuncs.com`，`PATH_STYLE=false`，必须填写存储桶。 |
| `tencent` | `s3` | 腾讯云 COS，端点为 `https://cos.${COS_REGION}.myqcloud.com`，存储桶名称必须包含 APPID。 |
| `aws` | `s3` | Amazon S3，端点为 `https://s3.${AWS_REGION}.amazonaws.com`。 |

### 界面设置项

| 设置项 | 界面位置 | 作用说明 | 默认状态 | 配置人员 |
|---|---|---|---|---|
| 「使用自己的存储」 | 「我的组织」→「存储」 | 切换组织文件存储为自备的 S3 兼容存储桶。 | 关闭（使用平台存储） | 组织管理员 |
| 「允许助手联网搜索」 | 「我的组织」→「Skill 与连接」 | 控制助手是否可以在回答问题时进行公网联网检索。 | 关闭 | 组织管理员 |

## 注意事项

- **与其他应用的关系**：
  - 云盘、[资料库](/apps/library)、[知识库](/apps/wiki)、[站点](/apps/site)以及各业务附件均统一走当前生效的存储模式。
  - 助手的知识库检索能力始终开启，公网联网搜索仅在组织开启开关后可用。
- **文件与存储规格上限**：
  - 云盘单文件体积上限为 50 MB。
  - [资料库](/apps/library)单文件上传上限为 50 MB。
  - [站点](/apps/site)包规格限制：解压缩后文件数量上限为 300 个，解压缩后总容量上限为 30 MiB，解压缩后单文件上限为 5 MiB，上传 zip 包体积上限为 32 MiB。
- **集群架构限制**：
  - 本地卷模式（`KWORK_BLOB=fs`）不支持多副本。在 Kubernetes 中使用 Helm 部署多副本集群时，必须使用 S3 存储；若配置为 `fs` 则 Pod 仅允许运行 1 个副本。
- **自带存储连通性与 CORS**：
  - 连通性探测流程会在存储桶中实际写入并删除测试文件。
  - 必须在云存储控制台中配置 CORS 规则，将 `https://*.apps.{base}` 与 `https://app.{base}` 加入允许源。若未配置 CORS，浏览器直传文件将会失败。
  - 切换存储只影响后续新上传的文件，已有文件不会自动迁移。
- **联网搜索特性与配额**：
  - 联网搜索不会抓取网页全文，也不会向组织扣费计费。
  - 搜索结果标题限制在 200 字以内，内容摘要限制在 500 字以内。
- **知识库与向量切分上限**：
  - 在资料库中，若成员可见文件数超过 20000 个，系统仅在最近修改的 20000 个文件中进行检索。
  - 文本向量化切分时，单个文件最多切分为 400 个文本段进入向量索引，系统默认切分提取 80 段，上限为 1000 段。
  - 更换 `KWORK_EMBED_MODEL` 嵌入模型时，历史向量会随着文档更新逐步被替换；在替换过渡期间，新模型的语义检索命中可能暂时缺失，但关键词检索始终不受影响。
- **系统备份建议**：
  - 使用 `--backup` 备份时，默认可将数据备份到当前这套对象存储中（在自建环境中默认发送至 `kwork-backup` 存储桶）。生产环境中建议将备份数据存储到另一处独立站点（详情参见[备份与恢复](/deploy/backup)）。

## 目前不支持

- 组织自带存储与平台存储之间已有文件的自动迁移。
- 除 DeepSeek 搜索以外的其他联网搜索服务提供商。
- 抓取网页全文。
- 工作台独立的全局全站搜索框（搜索能力统一通过助手对话使用）。

## 常见问题

### 切换到「使用自己的存储」后，原有的历史文件会被删除或自动迁移吗？
不会。切换存储设置只对新上传的文件生效，已有文件不会被自动迁移到新存储桶中，也不会被删除。在改用自带存储期间，由于平台指向了新桶，你将无法直接从平台访问此前保存在原存储桶里的历史文件。

### 为什么开启了「允许助手联网搜索」后，助手依然不能联网搜索？
请联系平台运营方确认运营控制台「模型」→「联网搜索」已配置并启用。未配置或未启用时，界面会显示提示「平台未配置搜索服务，开启暂不生效。」，调用搜索接口会返回 501 错误。

### 自建 SeaweedFS 可以实现审计日志的合规防篡改锁定吗？
不能。SeaweedFS 不支持 S3 对象锁定功能。在 SeaweedFS 上创建的审计归档桶会退化为「独立副本，未锁定」（组织应用内会有相应提示）。若业务合规强制要求对象锁定防篡改，必须改用 MinIO 或支持对象锁定的云端 S3 对象存储。

### 连通性测试中「浏览器跨域（CORS）」显示警告，会有什么影响？
如果 CORS 跨域测试未通过，用户在浏览器端向对象存储直接上传文件（预签名直传）将会失败。请登录云存储服务商控制台，检查存储桶的 CORS 规则，确保已将 `https://*.apps.{base}` 与 `https://app.{base}` 加入允许来源（origins）。

### 为什么知识库搜索有时没有语义理解效果，只能搜出完全匹配的关键词？
语义向量检索需要同时具备三项条件：PostgreSQL 安装了 pgvector 扩展、部署方配置了 `KWORK_EMBED_MODEL` 嵌入模型、且组织策略允许使用该模型。若缺少 pgvector 或嵌入模型，系统会自动静默降级为关键词检索；若组织额度耗尽、未获授权或区域不符，语义索引会暂停 5 分钟，检索也会自动降级为关键词搜索。