主题
私有文件
用户上传、聊天附件、沙箱产物和 AI 生成结果都会进入私有文件体系。私有文件默认需要登录鉴权，只有文件归属用户或具备权限的管理员可以下载、预览或清理。
配置概述
页面主要包含两部分：
- 文件记录：按文件名、文件 ID、用户 ID、可见性、状态和来源标识查询私有文件，并查看详情、预览、下载或清空文件内容。
- 清理操作：清空选中文件内容，或手动执行一次过期文件清理。
普通列表默认只展示当前仍有内容的文件。已经清空或已不存在的历史记录默认不会混入列表；如需排查历史记录，可以在状态筛选中选择“已清理”。
单文件上限、在线预览上限、单用户占用上限、保留时间、清理批量和公开策略，统一在 文件存储 / 用户文件管理 中配置。
配置项详解
公开文件与私有文件
| 类型 | 典型来源 | 访问方式 | 适合场景 |
|---|---|---|---|
| 公开文件 | 站点 Logo、favicon、公告图片、公开头像 | 知道链接即可访问 | 站点视觉资源、公开展示资源 |
| 私有文件 | 用户上传、聊天附件、沙箱产物、AI 生成结果 | 登录后带权限下载或预览 | 报表、合同、数据表、图片处理结果、中间文件 |
私有文件不会把真实存储路径、对象存储 Key、签名链接或服务器目录暴露给用户端、分享页或模型上下文。用户分享对话时，系统会按分享策略处理文件访问，不会把私有下载接口直接塞进公开页面。
/file/... 公开路径只用于真正公开的资源。用户上传、聊天附件、沙箱产物和 AI 生成结果默认都应进入私有文件链路。
头像是特殊场景：第三方登录头像或用户头像会保存为公开头像文件，方便页面稳定展示；这不代表普通用户上传图片会变成公开文件。
临时环境与长期文件
对话处理环境闲置后会回收。已保存的文件资产保持独立，可在原对话中按引用重新载入；临时目录路径不代表长期保存。保存失败的成果会暂存以供后续重试，但运行环境崩溃或超过恢复窗口后，尚未保存的内容可能丢失。
保留的技能只包含源码和依赖说明，按用户隔离并计入文件额度。安装环境、依赖缓存和任务文件不会作为通用技能快照保留。
文件记录
文件记录用于确认私有文件的来源、归属用户、大小、内容状态和创建时间。来源标识用于筛选实际入口，例如用户上传和微信 Bot；它不表示另一套应用或权限。
可见性说明：
| 可见性 | 含义 |
|---|---|
| 私有 | 默认状态，只允许归属用户或具备权限的管理员访问 |
| 临时 | 工具执行的中间文件或短期产物，到期后优先清理 |
| 公开 | 用户或系统明确允许公开访问的文件 |
常见状态说明：
| 状态 | 含义 | 建议 |
|---|---|---|
| 可用 | 文件内容仍存在，归属用户可下载；如文件类型安全且未超过预览上限，也可以在线预览 | 正常使用 |
| 过期 | 文件已经超过保留时间，等待清理任务处理 | 可手动执行清理，或等待自动清理 |
| 已清理 | 文件内容已经被清空，后台保留基础记录用于确认来源和清理结果 | 一般只用于排查历史记录 |
超级管理员可以在列表中清空选中文件内容，也可以批量清空已过期内容。清空操作只删除文件内容，不删除基础记录。
页面不会展示：
- 真实存储路径
- 对象存储 Bucket / objectKey
- 服务端绝对路径
- 沙箱命令的原始 stdout / stderr
- provider 原始响应
- 临时签名下载地址
策略配置位置
私有文件页不直接修改文件策略。和用户文件生命周期相关的配置都集中在「平台设置 / 文件存储 / 用户文件管理」中：
| 配置项 | 作用 |
|---|---|
| 单文件上限 MB | 控制用户上传、AI 生成和沙箱产物文件的最大体积 |
| 在线预览上限 MB | 控制多大的文件可以直接在线打开，超出后仅允许下载 |
| 单用户占用上限 MB | 控制单个用户当前有效私有文件的总占用 |
| 临时文件保留小时 | 控制工具中间文件的保留时间 |
| 私有文件保留天数 | 控制普通私有文件默认保留多久 |
| 每轮清理数量 | 控制清理任务单轮处理数量 |
这些配置会被上传、预览、渠道 Bot 媒体等链路共同使用。私有文件页只负责展示和清理已经产生的文件。
配置建议
- 普通商业站点可以先保持文件存储中的默认策略：单文件 50 MB，私有文件保留 30 天。
- 如果后台占用增长明显，优先缩短临时文件保留时间，再调整私有文件保留天数。
- 如果个别用户生成文件过多，再到文件存储中配置单用户占用上限。
- 售后和内部排障场景优先由超级管理员按需处理，并避免把私有文件链接复制到公开渠道。
- 定期筛选“过期”和“已清理”状态，如果过期文件持续堆积，可以手动执行一次清理。
常见问题
为什么找不到已清理的文件？
普通列表只展示仍有内容的文件；在状态筛选中选择“已清理”可查看保留记录。
对话中断后已完成的文件会丢失吗？
已经成功入库的文件仍保留稳定身份，管理员可在本页查看对应记录。同一回合重试会继续交付已完成的文件。
临时空间满了，怎样取回成果？
可让 Agent 重试文件交付。系统会在只读状态读取当前对话已登记的待交付文件并保存为私有资产；无需重新执行生成任务。存储服务仍不可用时保留待交付内容，但最长恢复窗口和容器故障的丢失边界仍适用。
当前支持哪些文件操作？
- 历史
/file/...公开资源不会自动迁移为私有文件。 - 用户上传、聊天附件、AI 生成结果等默认进入私有文件链路。
- 公开资源上传仅用于 Logo、favicon、公告图片等明确需要公开访问的场景。
- 私有文件内容可能存放在本地私有目录或对象存储私有桶中，具体取决于 文件存储 的配置。
- 对象存储的临时签名链接只在本次预览或下载时生成，不会写入聊天记录、分享页或模型上下文。