ThinkPHP集群部署需统一存储层解决文件不一致问题，应弃用move_uploaded_file()本地写入，改用FastDFS或云存储驱动，并通过StorageService统一封装上传、删除及URL生成逻辑。
ThinkPHP 文件上传后集群节点间文件不一致
集群部署时，用户上传的文件只落在某台服务器本地磁盘，其他节点访问 public/uploads/xxx.jpg 会 404。这不是 ThinkPHP 的 bug，是架构设计没绕过「共享存储」这个坎。
- 别再用
move_uploaded_file()往本机写——这是单机思维惯性 - 上传逻辑必须剥离「保存到哪」的决策，交由统一存储层处理
- ThinkPHP 自带的
think\File只负责接收和校验，后续写入动作要拦截重写 - 若强行用 NFS 或 rsync 同步 uploads 目录，会遇到并发写冲突、延迟导致 404、删除不同步等问题
替换默认上传驱动：对接 FastDFS 的关键三步
ThinkPHP 6+ 支持自定义 filesystem 驱动，FastDFS 不在官方驱动列表里，但可通过扩展包或手动注册实现。核心不是“怎么连 FastDFS”，而是“怎么让 File::moveTo() 走你的上传逻辑”。
- 安装
topthink/think-filesystem并确保已启用think\facade\Filesystem - 在
config/filesystem.php中新增 fastdfs 驱动配置，指向 tracker server 地址和端口 - 创建
app/common/driver/FastdfsDriver.php，继承think\filesystem\Driver，重写write()、read()、delete()方法，内部调用fastdfs-client-php的storage_upload_by_filename() - 上传接口中不再调用
$file->moveTo(...)，改用Filesystem::disk('fastdfs')->put($path, $file->getRealPath())
切云存储（如阿里 OSS、腾讯 COS）更简单但要注意 URL 生效时机
云存储本质是 HTTP 接口 + 签名授权，ThinkPHP 官方已有 think-filesystem-oss 和 think-filesystem-cos 扩展，装上就能用。真正容易出问题的是「返回给前端的 URL」。
- 别直接返回
https://bucket.oss-cn-hangzhou.aliyuncs.com/path.jpg—— 这个地址可能需要签名才能访问，未配置 public-read 时会 403 - 若设为 public-read，URL 可直接用，但注意 OSS 的
putObject默认不覆盖同名文件，需显式传['x-oss-forbid-overwrite' => 'false'] - COS 的
putObject默认允许覆盖，但需确认BucketACL是public-read或使用临时签名 URL - 上传成功后，应返回经
Filesystem::disk('oss')->url($path)生成的链接，它会自动处理签名或拼接公网域名
上传回调与删除同步：别让业务代码直连存储 SDK
上传完成后的通知（比如写数据库记录、触发审核）、文件删除操作，如果在控制器里直接 new 一个 OSSClient 或调 FastDFSClient::deleteFile()，等于把存储细节散落在各处，后期换存储方案成本极高。
立即学习“PHP免费学习笔记（深入）”；
- 所有存储操作必须收口到一个 service 类，例如
app/service/StorageService.php，提供upload()、delete()、getPublicUrl()三个方法 - 上传回调逻辑放在该 service 内部，而不是控制器里——比如上传成功后自动往
attachment表插入一条记录 - 删除时不要只删数据库，必须同步调
$this->storage->delete($path)；否则下次访问旧 URL 会 404 或返回错误内容 - FastDFS 删除失败不会抛异常，默认静默，务必检查
storage_delete_file()返回值是否为 0
最常被忽略的一点：上传表单里的 enctype="multipart/form-data" 和 Nginx 的 client_max_body_size 必须对齐，否则大文件上传会在反向代理层就中断，根本到不了 PHP，更别说走什么 FastDFS 了。
