Webman接入阿里云OSS 实现图片视频的高效云存储-php教程-PHP中文网

webman中oss上传常失败或返回504，根本原因是官方php sdk的putobject为同步阻塞式，不支持协程、分片与重试，在swoole环境下易阻塞worker并触发nginx/alb 60秒超时；须改用uploadfile（自动分片上传）并配置partsize、maxretries及合法contenttype等元数据。

webman接入阿里云oss 实现图片视频的高效云存储

Webman 项目直接用 OSS SDK 上传大文件（尤其是视频）容易卡死或超时，根本原因是默认的 putObject 是同步阻塞式上传，且未启用分片和重试机制。 必须改用 uploadFile 或手动分片 + initMultipartUpload 才能稳定处理 10MB 以上的文件。

为什么 Webman 的 OSS 上传常失败或返回 504

Webman 默认运行在 Swoole 上，而阿里云官方 PHP SDK（aliyun-oss-php-sdk）v2.x 的 putObject 方法底层依赖 cURL 同步请求，在协程环境下会阻塞整个 Worker 进程；上传视频这类大文件时，若网络抖动或 OSS 响应慢，极易触发 Nginx 或 ALB 的 60 秒超时，返回 504 Gateway Timeout。

现象：上传 20MB 视频时，前端长时间无响应，日志里出现 cURL error 28: Operation timed out 或 Swoole 报 Connection reset by peer
根本原因：SDK 未适配协程，putObject 不支持断点续传，也不自动分片
兼容方案：必须切换到 uploadFile —— 它内部自动调用分片上传接口，支持进度回调、失败重试、临时磁盘缓存
注意：uploadFile 要求本地临时路径可写（如 /tmp），且 PHP 进程有读取该文件的权限

Webman 中配置 OSS 客户端的正确姿势

不要在每次请求中 new 一个 OssClient，也不要在 config/autoload/oss.php 里硬编码密钥。应该利用 Webman 的容器绑定 + 环境变量驱动：

Webman 2.2.0

Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。

下载

把 AccessKeyId、AccessKeySecret、Endpoint、Bucket 全部设为环境变量，例如 ALIYUN_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com

在 app/bootstrap.php 中绑定单例：

$container->bind('OssClient', function ($container) {
    return new \Aliyun\OSS\OssClient(
        $_ENV['ALIYUN_OSS_ACCESS_KEY_ID'] ?? '',
        $_ENV['ALIYUN_OSS_ACCESS_KEY_SECRET'] ?? '',
        $_ENV['ALIYUN_OSS_ENDPOINT'] ?? ''
    );
});

上传时显式指定 options：['partSize' => 5 * 1024 * 1024, 'maxRetries' => 3]，避免小分片拖慢速度，也防止弱网下反复失败
禁用 SDK 自动检测 endpoint：确保 Endpoint 值带协议（https://），否则可能因 DNS 解析失败导致连接异常

上传视频前必须校验的三件事

用户上传 MP4 文件不等于就能直接扔进 OSS —— 阿里云对 object 的 key（即文件名）、Content-Type、元数据都有隐性约束，漏掉任意一项都可能导致 CDN 回源失败或浏览器无法播放：

key 必须是合法路径格式，不能含 ../、空字符或控制符；建议用 md5(uniqid()).'.mp4' 生成，再拼上目录前缀如 video/
必须显式设置 ContentType：MP4 对应 video/mp4，AVI 是 video/x-msvideo，否则 OSS 默认存为 application/octet-stream，CDN 或浏览器可能拒绝解析
关键元数据要补全：['Expires' => '+1 year', 'Cache-Control' => 'public, max-age=31536000']，否则 CDN 节点不会缓存，每次请求都回源，流量翻倍
额外提醒：如果用自定义域名访问视频，需确认该域名已备案、已绑定 Bucket、且 CNAME 解析生效（通常需 10–30 分钟）

OSS 回源到 CDN 时常见的 403 和 404

把视频传到 OSS 后，用 CDN 域名访问却返回 403 Forbidden 或 404 Not Found，90% 是权限与路由错配：

403：Bucket 权限不是 public-read，或开启了“阻止公共访问”（新版控制台默认开启，必须手动关闭）
404：CDN 源站填的是内网 endpoint（如 oss-cn-hangzhou-internal.aliyuncs.com）—— CDN 节点无法访问阿里云内网，必须填外网域名（xxx.oss-cn-hangzhou.aliyuncs.com）
CDN 缓存规则没配：默认只缓存图片类后缀，需手动添加 .mp4、.mov 到“缓存策略”的扩展名列表中
测试技巧：直接用 curl -I https://your-cdn-domain.com/test.mp4 看 X-Cache 头，如果是 HIT 说明缓存生效，MISS 或 EXPIRED 就要查源站连通性和缓存规则

真正麻烦的不是上传本身，而是上传之后的链路完整性：从 OSS 权限、CDN 源站配置、缓存规则、自定义域名解析，到前端 video 标签的 preload 和 controls 属性是否合理 —— 任一环断裂，用户看到的就是黑屏或无限 loading。动手前先用最小化 MP4 文件走通整条链路，比堆代码更省时间。