77 lines
6.9 KiB
Markdown
77 lines
6.9 KiB
Markdown
# 前端直传腾讯云 COS（视频大文件）
|
||
|
||
## Goal
|
||
|
||
让管理后台的视频上传绕开 PHP 服务器的中转通道，由浏览器直接把视频文件分片上传到腾讯云 COS。
|
||
解决两类痛点：(1) 服务器双倍带宽消耗（client→server→COS）；(2) PHP `upload_max_filesize` / `post_max_size` 与 fpm 进程内存对大视频不友好。
|
||
首发场景：诊单 `CallRecordPanel.vue` 上传通话回放视频。
|
||
|
||
## What I already know
|
||
|
||
- 现有上传链路：`admin/src/components/upload/index.vue` → `POST /upload/video`（`UploadController::video`）→ `UploadService::video()` → `storage/Driver` → `engine/Qcloud::upload()` 用 `putObject`。
|
||
- 服务端入参依赖 `$_FILES`，受 PHP 上传上限约束；返回 `{id, cid, type, name, uri, url}`，`uri` 经 `FileService::getFileUrl()` 拼接 OSS/CDN 域名。
|
||
- 存储驱动配置走 `dev_config.storage`（管理员可在后台「存储配置」切换 local/qiniu/aliyun/qcloud；本任务只对 qcloud 启用直传）。
|
||
- composer 已有 `qcloud/cos-sdk-v5 ^2.5`，但 STS 临时凭证需要再装 `qcloud/cos-sts-sdk`。
|
||
- 未提交代码：`CallRecordPanel.vue` 已加「上传视频」按钮，调用 `createManualCallRecord` + `attachLocalCallRecording`，依赖上传组件吐出的 `response.data.uri/url`。AuthMiddleware 已为 `tcm.diagnosis/uploadcallrecording` 等加白名单 — 直传新接口与之解耦，不需要白名单。
|
||
|
||
## Assumptions (temporary)
|
||
|
||
- 生产环境默认存储引擎已经是 `qcloud`；切到 `local/aliyun/qiniu` 时 direct 模式需要降级回老链路。
|
||
- COS Bucket 已开启跨域 CORS（直传必须）。如未开启，需要运维在 COS 控制台配置 `AllowedOrigin = 后台域名 + 本地 dev`、`AllowedMethod = PUT/POST/HEAD`、`AllowedHeader = *`、`ExposeHeader: ETag`。
|
||
- 后台域名固定（暂无多租户独立域名）。
|
||
- 视频文件大小有合理上限（建议 2GB）。
|
||
|
||
## Decisions (locked)
|
||
|
||
- 视频上限 **2 GB**（写进 STS policy `numeric_less_than_equal cos:content-length` + 前端 `file.size` 预检）。
|
||
- 保留 `/upload/video` 老接口；`upload/index.vue` 的 `direct` prop 默认 `false`，仅 `CallRecordPanel.vue` 这类显式声明的视频场景启用直传。
|
||
- STS 凭证有效期 **30 分钟**（1800 秒）。
|
||
- 直传完成后**必须等 `oss-confirm`** 返回（写完 `file` 表 + HEAD 校验通过）才 emit `success`，保证业务侧拿到的 `uri/url` 一定有 `file_id`。
|
||
|
||
## Requirements (evolving)
|
||
|
||
- [R1] 后端新增 `POST /adminapi/upload/oss-credentials`，仅当 `storage.default == qcloud` 时返回 `{provider, bucket, region, credentials, expiredTime, key, host, cdn_url_base}`；其它 driver 返回 `{provider: '<engine>', fallback: true}` 让前端自动降级到老链路。
|
||
- [R2] 后端新增 `POST /adminapi/upload/oss-confirm`，HEAD 一下 `key` 校验确实存在 + size 在阈值内，写入 `file` 表（沿用 `FileService::getFileUrl`），返回与 `UploadService::video()` 完全对齐的 `{id, cid, type, name, uri, url}`。
|
||
- [R3] 新装 composer 依赖 `qcloud/cos-sts-sdk`；在 `engine/Qcloud.php` 增加 `getStsCredentials($keyPrefix, $maxSize)` 方法，复用现有 `access_key/secret_key/bucket/region`。
|
||
- [R4] STS policy 限定 action：`name/cos:PostObject`、`name/cos:PutObject`、`name/cos:InitiateMultipartUpload`、`name/cos:UploadPart`、`name/cos:CompleteMultipartUpload`、`name/cos:AbortMultipartUpload`、`name/cos:ListParts`；resource 限定 `qcs::cos:${region}:uid/${appId}:${bucket}/uploads/video/{YYYYMMDD}/*`。
|
||
- [R5] 前端新增 npm 依赖 `cos-js-sdk-v5`；`upload/index.vue` 增加 `direct: boolean` prop（默认 `false`），`type==='video' && direct===true` 时走 STS + `cos.uploadFile`（含 `SliceSize=5MB`、`onProgress`），仍发出原 `success` 事件 `{ code, data: { uri, url, ... } }` 保持调用侧兼容。
|
||
- [R6] `CallRecordPanel.vue` 切到 `<upload type="video" direct :show-progress="true">`，并支持上传过程中显示百分比（沿用组件内置 `el-dialog` 进度）。
|
||
- [R7] 失败/降级路径：STS 接口失败 / response 标记 `fallback=true` / `cos-js-sdk-v5` 上传报错时，自动降级到老的 `POST /upload/video`，提示「直传失败，已切换到普通上传」。
|
||
- [R8] 安全：保留登录鉴权；STS 凭证 30 分钟有效期；前端拒绝不在 `accept` 列表的扩展名（沿用现有 `.wmv,.avi,...,.mp4,.mkv`）。
|
||
|
||
## Acceptance Criteria (evolving)
|
||
|
||
- [ ] 在 storage=qcloud 环境，从 `CallRecordPanel.vue` 上传 1.5GB mp4 文件，浏览器 Network 面板能看到流量直接打到 `*.cos.*.myqcloud.com`，`/upload/video` 没有调用。
|
||
- [ ] 上传过程中能看到分片进度条（5MB 一片，并发 ≥3）。
|
||
- [ ] 上传完成后，`call_record` 表正确写入 `recording_urls`，前端表格 `recording_urls_list` 渲染出可播放视频。
|
||
- [ ] `file` 表新增一行，`uri` 形如 `uploads/video/20260508/xxxxx.mp4`，`url` 拼接了 CDN/COS 域名。
|
||
- [ ] 把 `dev_config.storage.default` 改成 `local`，再次上传，自动降级到老 `/upload/video` 路径，整体功能正常。
|
||
- [ ] 凭证接口未登录调用返回 401。
|
||
- [ ] 上传一个被 STS policy resource 拒绝的 key（人为篡改 prefix），COS 返回 403，前端给出明确错误。
|
||
|
||
## Definition of Done
|
||
|
||
- 单元/集成测试：暂无 PHPUnit 工程，跳过自动化测试；保证手测覆盖 AC 全部场景。
|
||
- 前端 `npm run type-check` 通过、`npm run lint` 无新增告警。
|
||
- 后端 `php -l` 通过，新接口在 admin 路由可访问。
|
||
- 文档：在 `.trellis/spec/`（如已有上传相关 spec）补充直传规范；PRD 同步关闭 Open Questions。
|
||
- COS CORS / STS 子账号最小权限策略整理为 ops 备忘（写到 prd.md 的 Technical Notes）。
|
||
|
||
## Out of Scope (explicit)
|
||
|
||
- 不做断点续传（刷新页面不保留 UploadId）。
|
||
- 不做 PostObject 回调链路。
|
||
- 不做 aliyun / qiniu 直传。
|
||
- 不改 `upload/image`、`upload/file` 链路（图片小文件用老链路即可）。
|
||
- 不做客户端 H5/uniapp 端直传（uniapp 本来就不走 admin）。
|
||
- 不做并发上传限流 / 全局上传队列。
|
||
|
||
## Technical Notes
|
||
|
||
- 关键文件：`server/app/common/service/storage/engine/Qcloud.php`、`server/app/common/service/UploadService.php`、`server/app/adminapi/controller/UploadController.php`、`admin/src/components/upload/index.vue`、`admin/src/views/tcm/diagnosis/components/CallRecordPanel.vue`。
|
||
- composer 新增：`qcloud/cos-sts-sdk: ^3.0`。
|
||
- npm 新增：`cos-js-sdk-v5`。
|
||
- COS CORS 配置（运维）：`AllowedOrigin: <admin 域名>`、`AllowedMethod: PUT,POST,HEAD,GET`、`AllowedHeader: *`、`ExposeHeader: ETag,x-cos-request-id,x-cos-version-id`。
|
||
- STS 子账号最小权限：仅赋予对 `${bucket}/uploads/video/*` 的 `cos:Get*`、`cos:Put*`、`cos:Post*`、Multipart 系列动作；STS policy 在此基础上再用 condition + resource 收敛。
|
||
- Key 命名：`uploads/video/${YYYYMMDD}/${ulid}.${ext}`，与现有 `UploadService::getUploadUrl()` 的 `Ymd` 分日目录保持一致。
|