Clara BBS 存储架构速览：StorageFactory 到四驱动的完整链路

学完这篇你能得到什么：你会搞清楚 Clara BBS 从「用户点上传」到「文件真正落地」这条链路上，StorageFactory 这一层做了什么、后台哪几个开关在控制它，以及上传失败时该按什么顺序排查。

一、先看整条链路的样子

一次上传在 Clara BBS 里会经过四步：

1. 浏览器提交文件 → 后端接收
2. 校验层拦截（类型白名单 + 图片二次校验）
3. StorageFactory 决定「这个文件写到哪儿」
4. 具体驱动把文件落盘 / 上传到云端，返回访问地址

你平时觉得「上传就是个上传」，其实第三、四步才是关键——它决定了文件是躺在你自己服务器的 `uploads` 目录里，还是跑到云对象存储上。

二、第一步：先找对后台入口

进后台，跟存储相关的设置分散在两个地方：

• 系统设置 → 上传设置：这里管「允许的扩展名」（管图片）和「附件允许的扩展名」（管附件），是两个独立字段。
• 系统设置 → 云存储：这里决定 StorageFactory 最终选中哪一类驱动。

注意：这两个页面经常被混在一起找。图片传不上去，先看上传统设置里的「允许的扩展名」，不要跑去云存储页翻。

另外还有一个隐藏前提：`uploads` 目录必须可写。这一步不在后台，得在面板文件管理器或 FTP 里确认权限。

三、第二步：StorageFactory 到底在做什么

你可以把它理解成一个「统一收件口」。不管前台是发帖传图、传附件，还是插件在传东西，调用方式都是一样的，由这个工厂去读后台配置、算出应该用哪一类驱动，再把活儿派下去。

好处很直接：

• 换存储方式不用改业务代码，后台切一下配置就行
• 业务层不需要知道文件最终落在哪儿
• 插件也能复用同一套入口，不用各写各的

Clara BBS 本身就是无框架、免 Composer、保存即生效的路子，所以这里也没有编译缓存要清——配置改完直接生效。

四、第三步：四个驱动，什么时候用哪个

按标题说的「四驱动」，指的是这一层下面挂着四类具体实现，通常覆盖：本地磁盘、以及后台可选的几类云对象存储。

具体是哪四个、叫什么名字，以后台「系统设置 → 云存储」页面实际列出的选项为准。本社区文档没有逐项穷举，你打开那个页面看一眼下拉框，就是准的。

选择建议很朴素：

• 小站、图片不多 → 本地磁盘，最省事，不用配密钥
• 图片量大、担心服务器带宽和磁盘 → 切云存储
• 附件特别大 → 优先考虑下面说的第五步那个「不占存储」的玩法

注意：切换驱动后，已经上传的老文件不会自动搬家。原文件还在旧位置，新文件才走新驱动。真要迁，得自己把旧文件同步过去。

五、第四步：上传失败了，按这个顺序查

不用乱猜，就三步：

1. 看后台「上传设置」里对应的扩展名字段有没有包含这个格式（图片和附件是两个字段，别查错）
2. 看 PHP 的 `upload_max_filesize` 和 `post_max_size` 是否大于文件体积。宝塔默认才 2M，手机照片经常超，建议调到 30M 以上
3. 看 `uploads` 目录是否可写

好消息是，Clara BBS 上传失败时页面会直接告诉你原因——超过 PHP 上限、白名单不符、目录不可写，提示是分开的，照着改就行。

六、第五步：还有一条「不占存储」的通道

如果你传的是软件、素材包这类大文件，其实可以根本不走存储驱动：附件支持网盘链接模式，填个链接 + 提取码就完事，服务器一个字节都不占。

同时附件还能单独定价出售，可选「所有人 / 会员 / 指定用户组」下载权限，价格填 0 就是免费。这部分在后台「附件管理」里统一看。

注意：附件被删掉也不是立刻消失，前台删除是软删除，进回收站保留 30 天（天数可配），后台「内容管理 → 帖子管理 → 状态筛选 → 回收站」能捞回来。所以别以为删了就一定释放了空间。

小结

• 链路是：接收 → 校验 → StorageFactory 派活 → 具体驱动落地
• 后台两个入口要分清：「上传设置」管白名单和大小，「云存储」管驱动选择
• 四个驱动的具体名单以后台页面实际选项为准，切换后老文件不会自动迁移
• 上传失败固定三查：扩展名字段、PHP 大小上限、`uploads` 可写
• 大文件优先用网盘链接模式附件，省存储也省带宽