文件存储

用户上传的图片、文件、视频和后台资源，需要先确定保存位置。内核自带本地目录存储；S3 兼容存储、腾讯云 COS、阿里云 OSS 是三个独立的存储扩展包（STORAGE_S3_PACK_ENABLED / STORAGE_OSS_PACK_ENABLED / STORAGE_COS_PACK_ENABLED），关闭某个包后它不再出现在下拉里。

文件存储分为两类：

• 公开存储：用于站点 Logo、favicon、公告图片、公开头像等可以直接被浏览器访问的资源。

• 私有存储：用于用户上传、聊天附件、AI 生成结果等默认需要鉴权访问的文件。

• 后台入口：平台设置 / 文件存储

管理后台页面只保留配置项和配置状态：公共存储、私有存储各自选一种存储方式，再填对应厂商的存储桶与密钥；具体使用说明以本文档为准。

配置概述

公共存储和私有存储各自只能选一种存储方式，切换存储方式不会自动搬迁历史文件，正式环境不建议来回切换。

配置对象存储前，建议先把这些信息准备好：

1. 一个已经创建好的存储桶。
2. 存储桶所在地域，例如 us-east-1、ap-guangzhou、oss-cn-shanghai。
3. 专用访问密钥，不建议使用主账号密钥。
4. 存储桶的默认访问域名能被浏览器直接读取（公共文件会以存储桶默认地址返回，后台不再单独填写自定义域名）。
5. 一张小图片，用来保存配置后做上传测试。

存储桶名与地域按原样使用：后台填的存储桶名只去掉首尾空格，不再删改字符；不符合厂商命名规则时，上传会提示「存储桶名不合法」，地域只能包含小写字母、数字和短横线。已有文件按保存时记录的存储桶读取、删除和生成链接，改了默认存储桶也不影响它们（前提是旧存储桶仍能用当前的地域、端点和密钥访问）。早期版本会删掉桶名里的点号等字符，当时写入的文件按记录里的名字照旧访问，不做迁移。各厂商的命名规则见下文对应小节。

当前上传由服务端完成，CORS 不影响上传本身。它主要影响用户端跨域预览、读取资源，以及后续可能接入的浏览器直传。正式站点按本文配置最小可用 CORS 规则即可。

配置项详解

基础信息

配置项	说明	建议
网站地址	本地文件访问时使用的公开站点地址	填正式访问域名，例如 https://agent.example.com
文件上传数量限制	单次允许上传的文件数量	普通站点保持 5 个左右即可

本地存储最简单，但服务器迁移、扩容和备份都要自己处理。只要站点开始稳定运营，公共资源建议在「公共存储」里切到对象存储；用户上传、聊天附件、AI 生成结果等则应按“私有存储”单独配置。

用户文件管理

用户文件管理统一控制用户文件的大小、保留时间、配额和清理策略，覆盖用户上传、聊天附件、AI 生成结果、沙箱产物和微信 Bot 收到的媒体文件。

配置项	说明	建议
单文件上限 MB	单个用户文件允许保存的最大体积	默认 50 MB；视频或大文档场景可适当调大
在线预览上限 MB	超过该大小后不再直接在线预览	默认 20 MB；大文件仍可下载
单用户占用上限 MB	单个注册用户的私有文件总占用上限，含上传、成果、保留技能和待完成保存/清理的内容	默认 1024 MB；显式设 0 表示不限额
访客占用上限 MB	单个访客身份当前有效私有文件的总占用上限	默认 200 MB；多个访客身份不共享该额度，不建议设为 0
临时文件保留小时	工具中间文件的保留时间	默认 24 小时
私有文件保留天数	普通私有文件的自动过期时间	默认 30 天；0 表示不按天数自动过期
每轮清理数量	清理时每批处理的文件数：手动「执行过期清理」一次处理一批；每天的自动清理按批推进	默认 50 条，文件量大时可逐步提高

后台「私有文件」页面用于查看记录、筛选和清理内容，文件策略集中在本页配置。

清理的范围是：已到保留期的文件、保存失败的文件、处理超过 15 分钟仍未完成的文件（还没到期的沙箱交付登记除外）。服务端每天自动清理一次（见 私有文件管理），也可以在「私有文件」页手动执行。修改保留时间只影响之后新保存的文件，已有文件按保存时记下的到期时间处理；清理失败的文件会在之后的自动清理或下一次手动执行时重试。

对话中的临时处理环境会自动回收；已保存附件、成果和用户选择保留的技能存放在私有存储。保留技能不自动到期，但仍占用用户额度。保存失败的内容在清理完成前继续占额，避免同时上传与生成绕过容量限制。临时环境中的文件只有显示为成功交付后，才算已经保存。

使用本地私有存储时，应为目录配置独立容量边界和磁盘告警；账号额度不能防止所有账号合计耗尽同一块服务器磁盘。

公共存储

公共存储保存站点 Logo、favicon、公告图片、公开头像等可以直接被浏览器访问的资源。

配置项	说明	建议
公共文件存储	选择公共文件使用的存储方式（本地公开目录 / S3 兼容 / 腾讯云 COS / 阿里云 OSS，随已装载的存储包出现）	测试阶段用本地，正式站点建议对象存储
本地公开目录	本地公开文件保存位置	默认 server/public/file，经 /file 公开访问
各厂商存储桶与密钥	选定对象存储后出现对应字段	使用专用低权限密钥，不要使用主账号密钥

私有存储

私有存储用于保存需要登录鉴权后访问的文件。普通用户上传的附件、沙箱产物、AI 生成结果等默认都应进入私有存储，不会直接暴露对象存储路径、服务器真实路径或长期可访问的下载地址。

头像是例外：第三方登录头像或用户头像会以公开头像文件保存，便于页面稳定展示；普通用户上传、聊天附件和 AI 生成图片仍默认私有。

配置项	说明	建议
私有文件存储	选择私有文件使用的存储类型	小规模站点可用本地私有目录，正式站点建议使用对象存储
本地私有目录	本地私有文件保存位置	默认 server/storage/private，不要放在 public/file 下
签名链接有效期	对象存储私有文件临时访问链接的有效时间	默认 600 秒；仅用于本次预览或下载，不会保存到数据库
各厂商存储桶与密钥	选定对象存储后出现对应字段：S3 端点 / 区域 / 存储桶 / Access Key，COS 存储桶 / 地域 / SecretId / SecretKey，OSS 存储桶 / 地域 / AccessKey	使用专用低权限密钥，不要使用主账号密钥

私有本地目录不会通过 /file/... 公开访问。后续预览或下载时，后端会先校验文件归属、状态、过期时间以及是否允许预览 / 下载，再从私有目录读取文件。

对象存储私有文件会在后端鉴权通过后临时生成短期访问链接。这个链接只用于当前请求，不会写入数据库、聊天记录或前端长期状态。

S3 存储

S3 存储适合使用 Amazon S3，也适合接入兼容 S3 协议的服务，例如 MinIO、Cloudflare R2、DigitalOcean Spaces 等。

第一步：创建存储桶

1. 登录 AWS 控制台，进入 Amazon S3。
2. 选择离主要用户更近的 Region。存储桶创建后 Region 不能修改。
3. 创建 General purpose bucket。
4. Bucket 名称为 3 – 63 位小写字母、数字、点或短横线，以字母或数字开头和结尾，不能有连续的点，也不能形如 IP 地址。带点号的存储桶可以使用：生成的临时链接改用路径式地址（https://s3.<区域>.amazonaws.com/<存储桶>/...），避免 HTTPS 证书不匹配；但仍建议不用点号，部分兼容服务对它支持不好。不填端点时，临时链接与 SDK 的请求地址一致，使用区域地址 https://<存储桶>.s3.<区域>.amazonaws.com/...（us-east-1 也一样）；填了端点时按端点生成路径式地址。
5. 如果使用 CloudFront 或服务商 CDN 作为文件访问入口，可以保持 S3 Block Public Access 开启，再通过 CDN 的源站访问控制来读取文件。
6. 如果直接使用 S3 默认域名访问文件，需要确认对象访问策略允许浏览器读取，否则上传成功后用户端会打不开。

第二步：创建访问密钥

建议创建专用 IAM 用户或专用访问凭据，只授权到当前 Bucket。上传、读取、清理都由服务端用这组凭据完成，按用途授权：

权限	用途	是否必需
s3:PutObject	服务端保存上传文件、AI 成果与沙箱产物	必需
s3:GetObject	服务端读取私有文件（预览、下载、交给模型与沙箱，也用于核对对象是否存在）；用户端直接打开公开文件时，浏览器也要能读取	必需
s3:DeleteObject	到期清理与用户删除文件时删除对象	必需；缺少时清理会失败，文件状态停在「失败」、生命周期为待清理，占用的额度也不会释放
s3:ListBucket	排查文件是否写入	非必需，常用于调试

服务端删除对象用的是这组凭据的权限，与浏览器的 CORS 规则无关。

Access Key 创建后请立即保存，Secret 通常只在创建时完整展示。后台只填写专用访问密钥，不使用主账号密钥。

第三步：填写后台

在「公共存储」或「私有存储」的下拉里选中该存储方式后，填写下面的字段（两个作用域各填一套）：

配置项	填写方式
端点地址	Amazon S3 可填 https://s3.amazonaws.com 或地域端点；兼容服务填服务商提供的 Endpoint
区域	Amazon S3 必填，例如 us-east-1；部分兼容服务可按服务商要求填写
存储桶	Bucket 名称
Access Key ID	访问密钥 ID
Secret Access Key	访问密钥 Secret

示例：

端点地址：https://s3.us-east-1.amazonaws.com
区域：us-east-1
存储桶：agent-assets

第四步：配置 CORS

如果只是服务端上传、浏览器展示图片，一般先配置 GET、HEAD 即可。后续如果要浏览器直传，再增加 PUT、POST。

示例规则：

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://agent.example.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

如果有多个访问域名，把 AllowedOrigins 增加到对应域名，不建议长期使用 *。

官方指引：

• Amazon S3 创建 Bucket
• Amazon S3 CORS 配置
• AWS IAM Access Key 管理

腾讯云 COS

腾讯云 COS 的 Bucket 名称带有 APPID，例如 examplebucket-1250000000。后台填写时要复制完整名称，不要只填前半段：名称部分只含小写字母、数字或短横线且不以短横线开头或结尾，APPID 为数字，完整访问域名 <存储桶>.cos.<地域>.myqcloud.com 不超过 60 个字符。

第一步：创建存储桶

1. 登录腾讯云控制台，进入对象存储 COS。
2. 在“存储桶列表”中创建存储桶。
3. 选择所属地域，例如广州为 ap-guangzhou。地域创建后不能修改。
4. 复制完整 Bucket 名称，例如 agent-assets-1250000000。
5. 访问权限按实际安全要求选择。若用户端需要直接打开对象存储 URL，需要保证对象或 CDN 域名可被浏览器访问。

第二步：创建 SecretId 和 SecretKey

建议在访问管理 CAM 中创建子账号或协作者密钥，并只授权当前 COS Bucket：上传（name/cos:PutObject）、服务端读取（name/cos:GetObject、name/cos:HeadObject）与删除（name/cos:DeleteObject）。缺少删除权限时到期清理会失败，文件状态停在「失败」、生命周期为待清理；删除权限与浏览器 CORS 无关。腾讯云 SecretKey 创建后需要立即保存，后续通常无法再次查看完整 SecretKey。

第三步：填写后台

在「公共存储」或「私有存储」的下拉里选中该存储方式后，填写下面的字段（两个作用域各填一套）：

配置项	填写方式
存储桶名称	完整 Bucket 名称，例如 agent-assets-1250000000
所属地域	地域简称，例如 ap-guangzhou
SecretId	腾讯云访问密钥 ID
SecretKey	腾讯云访问密钥 Key

第四步：配置 CORS

在 Bucket 详情中进入“安全管理 / 跨域访问 CORS”，新增规则：

配置	建议值
来源 Origin	用户端正式域名，例如 https://agent.example.com
允许操作 Methods	GET、HEAD；浏览器直传时再加 PUT、POST
允许 Headers	*
暴露 Headers	ETag、x-cos-request-id
缓存时间	3600 或 86400

官方指引：

• 腾讯云 COS 创建存储桶
• 腾讯云 COS 设置跨域访问
• 腾讯云子账号访问密钥

阿里云 OSS

阿里云 OSS 的后台“所属地域”填写的是 OSS Region，例如 oss-cn-shanghai，不是普通地域名 cn-shanghai。

第一步：创建 Bucket

1. 登录阿里云 OSS 控制台，进入 Bucket 列表。
2. 创建 Bucket，填写名称并选择地域。
3. Bucket 创建后名称和地域不能修改。
4. 默认私有更安全；如果用户端需要直接访问上传后的文件，要确认公共读、Bucket Policy、CDN 回源鉴权等访问方案已经配好。
5. 记录地域对应的外网 Endpoint，例如杭州地域常见为 oss-cn-hangzhou.aliyuncs.com。

第二步：创建 AccessKey

建议创建 RAM 用户，并只给这个 RAM 用户授权当前 Bucket：上传（oss:PutObject）、服务端读取（oss:GetObject）与删除（oss:DeleteObject）。缺少删除权限时到期清理会失败，文件状态停在「失败」、生命周期为待清理；删除权限与浏览器 CORS 无关。不要使用主账号 AccessKey。AccessKey Secret 创建后只展示一次，请立即保存。

第三步：填写后台

在「公共存储」或「私有存储」的下拉里选中该存储方式后，填写下面的字段（两个作用域各填一套）：

配置项	填写方式
存储桶名称	Bucket 名称，例如 agent-assets：3 – 63 位小写字母、数字或短横线，以字母或数字开头和结尾
所属地域	OSS Region，例如 oss-cn-shanghai
AccessKeyId	RAM 用户 AccessKey ID
AccessKeySecret	RAM 用户 AccessKey Secret

第四步：配置 CORS

进入目标 Bucket 的“数据安全 / 跨域设置”，新增规则：

配置	建议值
来源	用户端正式域名，例如 https://agent.example.com
允许 Methods	GET、HEAD；浏览器直传时再加 PUT、POST
允许 Headers	*
暴露 Headers	ETag、x-oss-request-id
缓存时间	3600
返回 Vary: Origin	多域名或通配符来源时建议开启

官方指引：

• 阿里云 OSS 创建 Bucket
• 阿里云 OSS 访问域名与 Endpoint
• 阿里云 OSS CORS 配置
• 阿里云 RAM AccessKey

本地分区余量

本地存储在写入前检查目标分区，默认保留 1024 MB 空间和 1000 个 inode。管理员可通过 FILE_ASSET_LOCAL_MIN_FREE_MB、FILE_ASSET_LOCAL_MIN_FREE_INODES 调整；空间不足或无法观测时暂停新文件写入，已有文件仍可读取。用户额度限制个人占用，全站仍需规划独立数据分区并监控余量。

配置建议

验证方法

1. 保存后台配置。
2. 测试公共资源：在基础信息中上传 Logo 或 favicon，确认用户端可正常展示，复制公开地址后在无登录状态的新窗口中也能打开。
3. 测试私有文件：在用户端上传一个聊天附件，确认登录状态下可以预览或下载。
4. 退出登录后直接访问私有文件预览或下载地址，应被拒绝或要求登录。
5. 到对象存储控制台检查文件是否写入对应公开目录或私有目录。

公开资源上传成功但用户端打不开，通常是文件访问域名、访问权限、CDN 回源或 HTTPS 证书没有配好。私有文件不应依赖公开 URL 打开，应通过后端鉴权接口读取。

使用建议

• 测试阶段可以先用本地存储，正式运营建议使用对象存储。
• 访问密钥使用专用子账号，并定期轮换。
• 自定义域名配置 HTTPS，避免用户端混合内容报错。
• 文件大小限制不要盲目调大，视频和大文件会明显增加带宽成本。
• 切换存储前先确认历史文件是否需要迁移，系统不会自动把旧文件搬到新 Bucket。

常见问题

文件上传成功但打不开？

优先检查文件 URL 是否能在无登录窗口打开。打不开时，再检查 Bucket 读权限、CDN 回源、域名解析和 HTTPS 证书。

CORS 已经配置，为什么还是打不开？

CORS 只决定浏览器是否允许跨域读取响应，不等于文件本身有访问权限。私有 Bucket 没有签名 URL 或 CDN 鉴权放行时，仍然会打不开。

可以把 Bucket 设成公共读吗？

可以，但要确认上传内容是否适合公开访问。若站点涉及隐私文件，建议使用私有 Bucket 配合 CDN 鉴权或签名访问方案。

私有链接有效期是否按文件类型分别配置？

私有链接有效期对所有私有文件统一生效，默认 600 秒，可配置范围为 60–3600 秒。更改后新生成的链接使用新值；已签发链接仍按原有效期失效。

相关文档

• 基础信息
• 模型管理