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