ThinkPHP 6.1 分布式部署下文件上传核心问题是本地存储导致节点间文件不可见，必须弃用 moveTo()，统一使用 Filesystem::disk('cos/oss')->putFile() 和 url() 方法对接云存储，并通过临时密钥、权限控制、事件解耦保障安全与可扩展性。
ThinkPHP 6.1 分布式部署下，文件上传最核心的问题是：用户上传的文件只落在某一台服务器上，其他节点无法访问，导致图片 404、附件打不开、审核失败等。这不是框架缺陷，而是架构必须解决的共享存储问题。
必须弃用本地 moveUploadedFile
集群中继续用 $file->moveTo('public/uploads/xxx.jpg') 是根本性错误。它会让文件写死在单机磁盘，彻底破坏无状态设计。
- 所有上传逻辑要剥离“存哪”的判断，交由统一存储层处理
- 控制器里不再出现
moveTo()，改用Filesystem::disk('xxx')->put()或putFile() - 确保
config/filesystem.php中 default disk 已切换为远程驱动（如 cos、oss、fastdfs），而非 local
推荐方案：直连腾讯云 COS 或阿里 OSS
对大多数 TP6.1 项目，接入云对象存储是最省事、最可靠的选择。官方扩展已成熟，无需自研 SDK 封装。
- 安装对应扩展：
composer require topthink/think-filesystem-cos（COS）或topthink/think-filesystem-oss（OSS） - 在
config/filesystem.php中配置 bucket、region、密钥（建议从环境变量读取，如env('COS_SECRET_ID')） - 上传时统一走：
Filesystem::disk('cos')->putFile('images', $file)，返回值是相对路径（如images/abc.png） - 生成可访问 URL 必须用：
Filesystem::disk('cos')->url($path)，它会自动拼域名、加签名（若非 public-read）
临时密钥与安全控制要点
生产环境不建议长期暴露主账号密钥。TP6.1 可结合 COS 的临时凭证机制提升安全性。
立即学习“PHP免费学习笔记（深入）”；
- 后端接口生成临时密钥（
GetFederationToken），返回给前端用于直传（减少服务端带宽压力） - 或服务端转存时，使用 STS 临时密钥初始化 COS Client，避免硬编码 SecretKey
- Bucket ACL 设为
public-read仅适用于公开资源；含敏感内容的文件务必设为私有，并通过temporaryUrl()生成带签名的限时链接 - 上传前强制校验：
validate(['ext' => 'jpg,png,pdf', 'size' => 5242880])，防止恶意文件绕过
上传回调与业务解耦
文件存到 COS 后，常需触发后续动作（如写数据库记录、发起内容审核）。这些逻辑不能写在控制器里直接调 COS SDK。
- 用事件监听或消息队列（如 think-swoole + Redis Queue）解耦上传与业务
- 例如：上传成功后 dispatch 一个
FileUploaded事件，由独立 listener 处理入库和审核调用 - 删除操作也必须走同一套 Filesystem 接口：
Filesystem::disk('cos')->delete($path)，保证一致性
