对象存储与搜索

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）。
   • 在终端执行存储初始化引导命令：

     kwork bootstrap s3

   • 公网文件访问入口（由 Caddy 反向代理）：https://files.{base}。
   • 使用 Helm 部署时，多副本部署必须使用 S3 存储；storage.blob=fs 仅允许 1 个副本。
2. 组织自带存储配置入口：
   • 登录 工作台，在左侧导航进入「我的组织」→ 数据「存储」。
3. 助手联网搜索配置入口：
   • 登录 工作台，在左侧导航进入「我的组织」→ 助手「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. 在服务器终端执行存储初始化引导命令：

      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. 登录 工作台，在左侧导航进入「我的组织」→ 数据「存储」。
5. 在「存储位置」区域，点击打开「使用自己的存储」开关。
6. 在「连接设置」区域，点击「快速填充」选择对应存储模板，或手动输入「端点」、「浏览器访问地址」、「存储桶」、「路径前缀」、「区域」、「访问密钥 Access Key 」与「私有密钥 Secret Key」。
7. 根据存储类型设置「路径风格寻址」开关（MinIO、SeaweedFS 设为开启，AWS、OSS、COS 设为关闭）。
8. 点击表单下方的「测试并保存」按钮。
9. 系统依次执行 7 项连通性测试（包含「连接与权限」、「写入」、「读取」、「列出」、「预签名上传」、「浏览器跨域（CORS）」、「删除」）。
10. 若任一必要测试项未通过，系统不会保存设置，并弹出提示「没有通过连通性测试，设置没有保存。」；全部必要项通过后，配置保存成功，密钥安全存入 OpenBao。新设置仅对后续新上传的文件生效，已有文件不会被自动迁移。

改回平台存储

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

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

配置与启用联网搜索

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

1. 运营方配置 DeepSeek 搜索（平台唯一的搜索服务）：
   1. 在 DeepSeek 开放平台创建一个 API Key，确认账户有余额。
   2. 登录运营控制台，进入「模型」→「联网搜索」，点击「配置 DeepSeek」。
   3. 填入 API Key，打开「启用」开关，点击「保存」。API Key 保存后只显示后四位，原文只保存在密钥库中。
   4. 点击「测试」，看到「通了：搜「DeepSeek」返回 N 条结果」即配置成功。测试不计入任何组织的用量。
2. 组织管理员启用联网搜索：
   1. 登录 工作台，在左侧导航进入「我的组织」→ 助手「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 与连接」	控制助手是否可以在回答问题时进行公网联网检索。	关闭	组织管理员

注意事项

• 与其他应用的关系：
  • 云盘、资料库、知识库、站点以及各业务附件均统一走当前生效的存储模式。
  • 助手的知识库检索能力始终开启，公网联网搜索仅在组织开启开关后可用。
• 文件与存储规格上限：
  • 云盘单文件体积上限为 50 MB。
  • 资料库单文件上传上限为 50 MB。
  • 站点包规格限制：解压缩后文件数量上限为 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 存储桶）。生产环境中建议将备份数据存储到另一处独立站点（详情参见备份与恢复）。

目前不支持

• 组织自带存储与平台存储之间已有文件的自动迁移。
• 除 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 分钟，检索也会自动降级为关键词搜索。