文件存储

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

文件存储分为两类：

公开存储：用于站点 Logo、favicon、公告图片、公开头像等可以直接被浏览器访问的资源。
私有存储：用于用户上传、聊天附件、AI 生成结果等默认需要鉴权访问的文件。
后台入口：平台设置 / 文件存储

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

配置概述

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

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

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

当前上传由服务端完成，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 条，文件量大时可逐步提高

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

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

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

公共存储

公共存储保存站点 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 等。

第一步：创建存储桶

登录 AWS 控制台，进入 Amazon S3。
选择离主要用户更近的 Region。存储桶创建后 Region 不能修改。
创建 General purpose bucket。
Bucket 名称使用小写字母、数字和短横线，建议不要使用点号，避免 HTTPS 证书和兼容服务解析问题。
如果使用 CloudFront 或服务商 CDN 作为文件访问入口，可以保持 S3 Block Public Access 开启，再通过 CDN 的源站访问控制来读取文件。
如果直接使用 S3 默认域名访问文件，需要确认对象访问策略允许浏览器读取，否则上传成功后用户端会打不开。

第二步：创建访问密钥

建议创建专用 IAM 用户或专用访问凭据，只授权到当前 Bucket。最少需要允许上传对象；如果希望用户端通过对象存储域名直接打开文件，还需要读取对象权限。

常用权限如下：

权限范围	用途
`PutObject`	服务端上传文件
`GetObject`	浏览器读取已上传文件
`ListBucket`	排查文件是否写入，非必需但常用于调试

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

第三步：填写后台

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

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

示例：

text

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

第四步：配置 CORS

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

示例规则：

json

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

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

官方指引：

腾讯云 COS

腾讯云 COS 的 Bucket 名称通常带有 APPID，例如 examplebucket-1250000000。后台填写时要复制完整名称，不要只填前半段。

第一步：创建存储桶

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

第二步：创建 SecretId 和 SecretKey

建议在访问管理 CAM 中创建子账号或协作者密钥，并只授权当前 COS Bucket 的读写能力。腾讯云 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`

官方指引：

阿里云 OSS

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

第一步：创建 Bucket

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

第二步：创建 AccessKey

建议创建 RAM 用户，并给这个 RAM 用户授权访问当前 Bucket。不要使用主账号 AccessKey。AccessKey Secret 创建后只展示一次，请立即保存。

第三步：填写后台

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

配置项	填写方式
存储桶名称	Bucket 名称，例如 `agent-assets`
所属地域	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	多域名或通配符来源时建议开启

官方指引：

本地分区余量

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

配置建议

验证方法

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

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

使用建议

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

常见问题

文件上传成功但打不开？

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

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

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

可以把 Bucket 设成公共读吗？

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

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

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

平台设置

AI 能力

用户运营

登录接入

登录配置

微信配置 · 微信包

支付财务 · 商业包

安全风控 · 内容安全包

文件存储

配置概述

配置项详解

基础信息

用户文件管理

公共存储

私有存储

S3 存储

第一步：创建存储桶

第二步：创建访问密钥

第三步：填写后台

第四步：配置 CORS

腾讯云 COS

第一步：创建存储桶

第二步：创建 SecretId 和 SecretKey

第三步：填写后台

第四步：配置 CORS

阿里云 OSS

第一步：创建 Bucket

第二步：创建 AccessKey

第三步：填写后台

第四步：配置 CORS

本地分区余量

配置建议

验证方法

使用建议

常见问题

文件上传成功但打不开？

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

可以把 Bucket 设成公共读吗？

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

相关文档

登录配置

微信配置 · 微信包

文件存储 ​

配置概述 ​

配置项详解 ​

基础信息 ​

用户文件管理 ​

公共存储 ​

私有存储 ​

S3 存储 ​

第一步：创建存储桶 ​

第二步：创建访问密钥 ​

第三步：填写后台 ​

第四步：配置 CORS ​

腾讯云 COS ​

第一步：创建存储桶 ​

第二步：创建 SecretId 和 SecretKey ​

第三步：填写后台 ​

第四步：配置 CORS ​

阿里云 OSS ​

第一步：创建 Bucket ​

第二步：创建 AccessKey ​

第三步：填写后台 ​

第四步：配置 CORS ​

本地分区余量 ​

配置建议 ​

验证方法 ​

使用建议 ​

常见问题 ​

文件上传成功但打不开？ ​

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

可以把 Bucket 设成公共读吗？ ​

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

相关文档 ​

文件存储

配置概述

配置项详解

基础信息

用户文件管理

公共存储

私有存储

S3 存储

第一步：创建存储桶

第二步：创建访问密钥

第三步：填写后台

第四步：配置 CORS

腾讯云 COS

第一步：创建存储桶

第二步：创建 SecretId 和 SecretKey

第三步：填写后台

第四步：配置 CORS

阿里云 OSS

第一步：创建 Bucket

第二步：创建 AccessKey

第三步：填写后台

第四步：配置 CORS

本地分区余量

配置建议

验证方法

使用建议

常见问题

文件上传成功但打不开？

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

可以把 Bucket 设成公共读吗？

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

相关文档