Webman中直接调用putObject会504超时，根本原因是Swoole协程模型与同步阻塞的cURL调用不兼容，导致Worker进程锁死；必须改用uploadFile等异步安全方式，并正确配置分片、重试及云厂商参数。
Webman里直接调用putObject会504超时
不是SDK写得有问题，是Swoole协程模型下同步阻塞调用天然不兼容。阿里云/七牛云官方SDK的putObject底层走cURL同步请求，一旦网络抖动或OSS响应慢，整个Worker进程就被锁死——60秒后Nginx返回504 Gateway Timeout，日志里大概率看到cURL error 28: Operation timed out。
必须改用异步友好的上传方式：
-
uploadFile()（来自webman-storage插件）是封装好的协程安全入口，内部自动处理分片、重试、断点续传 - 若需直连SDK，必须用
multipartUpload（阿里云）或putFile（七牛云Java SDK）等支持分片的接口，且要显式设partSize（建议5MB）、maxRetries（建议3） - 绝对不要在
onRequest或handle里写sleep(1)或file_get_contents($url)这类同步操作，它们和putObject一样危险
webman-storage插件如何一键切换本地→七牛云/OSS
不需要改业务代码，只需两步配置：
- 在
plugin/admin/config/middleware.php中加入\plugin\storage\app\middleware\StorageMiddleware::class作为全局中间件 - 在后台「上传设置」填入对应云厂商的AK/SK/Bucket/域名（七牛云填
bucket和hostName；阿里云填accessKeyId、accessKeySecret、bucket、endpoint）
配置生效后，所有formFile()接收到的文件会自动转存到云端，返回结构里的url字段就是可直接访问的CDN地址，save_path则变成云端路径（如https://xxx.qiniu.com/xxx.png），不再指向runtime/storage/本地目录。
API层调用Storage::disk()指定不同云存储
如果你的接口需要混用多种存储（比如用户头像走七牛云、合同PDF走阿里云），不用写两套逻辑，用disk()切就行：
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
-
Storage::disk(Storage::MODE_QINIU)->uploadFile()→ 七牛云 -
Storage::disk(Storage::MODE_OSS)->uploadFile()→ 阿里云OSS -
Storage::disk(Storage::MODE_LOCAL)->uploadFile()→ 仍走本地（调试用）
注意：各云厂商的contentType（MIME类型）必须准确传入，尤其对非图片文件（如.xlsx、.pdf）。七牛云若漏传会默认为application/octet-stream，导致浏览器下载而非预览；阿里云则可能触发InvalidObjectState错误。
七牛云和阿里云OSS配置项容易填错的关键字段
填错一个字段，上传成功但无法访问，排查起来极耗时间：
- 七牛云的
hostName必须带http://或https://前缀，且不能带/结尾（正确：https://xxx.bkt.clouddn.com；错误：xxx.bkt.clouddn.com/） - 阿里云
endpoint必须与Bucket所在地域严格匹配（如华东1区是oss-cn-hangzhou.aliyuncs.com），填错会导致SignatureDoesNotMatch错误 - 两个平台的
bucket名都不能含下划线_或大写字母，只允许小写字母、数字、短横线- - 权限务必设为「公共读」，否则生成的
url会带临时签名，过期即失效
最常被忽略的是：七牛云的bucket和hostName必须属于同一空间，阿里云的bucket和endpoint必须属于同一地域——跨了就白配。
