Webman本身不提供企业级文件存储能力，formFile()仅是上传入口，必须对接OSS/MinIO等外部存储并补全元数据管理、分片控制与权限校验；putObject因同步阻塞会锁死Worker导致504超时，且不支持分片、重试与断点续传，大文件上传必须改用uploadFile并显式配置partSize、maxRetries和contentType。
Webman 本身不提供企业级文件存储能力，formFile() 只是接收上传文件的入口，后续必须对接外部存储服务（OSS、MinIO、本地磁盘等）并补全元数据管理、分片控制、权限校验等逻辑，否则无法支撑生产环境的高并发、大文件、断点续传等需求。
为什么 Webman 里不能直接用 putObject 上传大文件
阿里云/腾讯云/OSS SDK 的 putObject 是同步阻塞式调用，在 Swoole 协程环境下会锁死整个 Worker 进程。上传一个 20MB 视频时，只要网络稍慢或 OSS 响应延迟，Nginx/ALB 的 60 秒超时立刻触发，返回 504 Gateway Timeout；日志中常见 cURL error 28: Operation timed out 或 Connection reset by peer。
它还不支持：
-
initMultipartUpload分片初始化 - 自动重试（默认
maxRetries = 0） - 客户端断点续传状态持久化
- 流式读取，大文件易导致 OOM
哪怕上传小图，也建议统一走 uploadFile，避免后期扩容踩坑。
uploadFile 必须显式配置的三个参数
uploadFile 是 SDK 封装的分片上传接口，但默认配置极不友好：分片太小会发大量请求拖慢速度，重试为 0 则弱网必失败，不设 contentType 会导致 MP4 被识别为 application/octet-stream，浏览器无法内联播放。
必须在调用时传入：
-
'partSize' => 5 * 1024 * 1024：设为 5MB，兼顾并发与单请求稳定性（100MB 文件仅 20 片） -
'maxRetries' => 3：默认是 0，必须显式设为 ≥2，否则一次抖动就失败 -
'contentType' => mime_content_type($tmp_file)：不传则依赖 OSS 自动探测，MP4/AVI 等常误判
同时确保 PHP 进程对临时目录（如 /tmp）有读写权限，否则报 failed to open stream: Permission denied。
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
本地存储 + MinIO 混合部署的关键配置点
混合方案不是“本地存一份、MinIO 存一份”，而是按业务策略分流：小图走本地加速访问，大文件/归档文件走 MinIO 长期保存。关键在于路径抽象与适配器切换。
使用 webman-storage 或 league/flysystem 时，需注意：
- MinIO endpoint 必须带协议和端口，如
http://minio:9000，不能只写域名 -
use_path_style_endpoint必须设为true，否则 URL 拼错导致403 Forbidden - bucket 需提前在 MinIO 控制台创建，region 必须与 SDK 配置一致（默认
us-east-1） - AccessKey/SecretKey 必须通过环境变量注入，禁止硬编码在配置文件中
- 本地存储路径要区分 runtime 与 public 目录：上传临时文件写
runtime/storage，对外可访问文件放public/storage
元数据（如文件哈希、上传时间、用户 ID）必须单独落库，不能依赖存储后端自带属性——MinIO 不支持自定义字段查询，本地磁盘更无此能力。
容易被忽略的权限与一致性陷阱
多 Worker 或多机器部署下，formFile()->getRealPath() 返回的是当前进程所在机器的临时路径（如 /tmp/phpXXXXXX），其他 Worker 无法访问该文件。若你在 A 节点接收文件、B 节点调用 uploadFile，会直接报文件不存在。
解决方案只有两个：
- 所有上传请求强制路由到同一节点（牺牲高可用）
- 接收后立即上传到 MinIO/RustFS，并删除本地临时文件（推荐）
另外，OSS/MinIO 的 headObject 不保证强一致性，刚上传完立刻 get 可能 404；若业务依赖“上传即可见”，需加短时重试或改用预签名 URL + 客户端直传。
