# TRTC 录制存储迁移：VOD → COS

## 变更说明

将 TRTC 云端录制的存储方式从**腾讯云点播（VOD）**改为**对象存储（COS）**。

## 修改内容

### File: `server/app/common/service/TrtcCloudRecordingService.php`

#### 1. 存储配置变更

**Before (VOD):**
```php
$tencentVod = new \TencentCloud\Trtc\V20190722\Models\TencentVod();
$tencentVod->ExpireTime = 0;
$tencentVod->MediaType = 0;
$tencentVod->UserDefineRecordId = $prefix;
$tencentVod->SubAppId = $vodSubApp;

$cloudVod = new \TencentCloud\Trtc\V20190722\Models\CloudVod();
$cloudVod->TencentVod = $tencentVod;

$storage = new \TencentCloud\Trtc\V20190722\Models\StorageParams();
$storage->CloudVod = $cloudVod;
```

**After (COS):**
```php
$cloudStorage = new \TencentCloud\Trtc\V20190722\Models\CloudStorage();
$cloudStorage->Vendor = 0; // 0=腾讯云
$cloudStorage->Region = 'ap-guangzhou';
$cloudStorage->Bucket = 'your-bucket-name';
$cloudStorage->Prefix = 'trtc-recording/';

$storage = new \TencentCloud\Trtc\V20190722\Models\StorageParams();
$storage->CloudStorage = $cloudStorage;
```

#### 2. 更新日志信息
- 日志中标注存储类型为 COS
- 记录 bucket、region、prefix 等信息
- 更新提示信息

#### 3. 更新路径清理函数
- 允许路径中包含 `/` 字符（COS 路径分隔符）
- 从 `sanitizeVodUserDefineRecordId` 改为支持 COS 路径格式

## 配置要求

### 必需配置项

在 `config/trtc.php` 或 `.env` 中添加以下配置：

```php
// config/trtc.php
return [
    // ... 其他配置 ...
    
    // COS 存储配置
    'recording_cos_vendor' => 0,  // 0=腾讯云
    'recording_cos_region' => env('TRTC_RECORDING_COS_REGION', 'ap-guangzhou'),
    'recording_cos_bucket' => env('TRTC_RECORDING_COS_BUCKET', ''),
    'recording_cos_prefix' => env('TRTC_RECORDING_COS_PREFIX', 'trtc-recording/'),
];
```

### .env 配置示例

```env
# TRTC 录制 COS 存储配置
TRTC_RECORDING_COS_REGION=ap-guangzhou
TRTC_RECORDING_COS_BUCKET=your-bucket-1234567890
TRTC_RECORDING_COS_PREFIX=trtc-recording/
```

## COS Bucket 准备

### 1. 创建 COS 存储桶

1. 登录 [腾讯云 COS 控制台](https://console.cloud.tencent.com/cos)
2. 创建存储桶
   - 名称：例如 `trtc-recording-1234567890`
   - 地域：选择与 TRTC 应用相同或就近的地域
   - 访问权限：私有读写（推荐）

### 2. 配置 CORS（如需前端访问）

如果需要前端直接访问录制文件，配置 CORS 规则：

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": [],
      "MaxAgeSeconds": 3600
    }
  ]
}
```

### 3. 配置生命周期（可选）

设置自动删除过期录制文件：

- 规则名称：`auto-delete-old-recordings`
- 应用范围：前缀 `trtc-recording/`
- 删除策略：创建后 30 天删除

## 存储路径结构

### 默认路径格式

```
bucket-name/
└── trtc-recording/
    ├── room_123_20240101_120000.mp4
    ├── room_456_20240101_130000.mp4
    └── ...
```

### 自定义前缀路径

如果传入 `$vodUserDefineRecordId` 参数：

```
bucket-name/
└── custom-prefix/
    ├── file1.mp4
    ├── file2.mp4
    └── ...
```

## 文件命名规则

COS 存储的文件名由 TRTC 自动生成，通常包含：
- 房间号
- 时间戳
- 用户 ID（单流录制）
- 文件格式（.mp4）

示例：
```
trtc-recording/sdkappid_roomid_userid_timestamp.mp4
```

## 权限配置

### TRTC 服务需要的 COS 权限

确保 TRTC 服务有权限写入 COS：

1. **方式一：使用主账号密钥**（不推荐生产环境）
   - 使用主账号的 SecretId 和 SecretKey

2. **方式二：使用子账号密钥**（推荐）
   - 创建子账号
   - 授予 COS 写入权限策略：
     ```json
     {
       "version": "2.0",
       "statement": [
         {
           "effect": "allow",
           "action": [
             "cos:PutObject",
             "cos:PostObject",
             "cos:InitiateMultipartUpload",
             "cos:UploadPart",
             "cos:CompleteMultipartUpload"
           ],
           "resource": [
             "qcs::cos:ap-guangzhou:uid/1234567890:your-bucket-1234567890/*"
           ]
         }
       ]
     }
     ```

3. **方式三：使用服务角色**（最佳实践）
   - 为 TRTC 服务创建角色
   - 授予角色 COS 写入权限
   - TRTC 自动使用角色权限

## 对比：VOD vs COS

| 特性 | VOD（点播） | COS（对象存储） |
|------|------------|----------------|
| **存储成本** | 较高 | 较低 |
| **功能** | 媒体处理、转码、播放 | 纯存储 |
| **访问方式** | 点播 API/播放器 | HTTP/HTTPS 直接访问 |
| **适用场景** | 需要转码、加密、播放统计 | 简单存储和下载 |
| **计费** | 存储+流量+转码 | 存储+流量 |
| **管理** | 媒资管理系统 | 文件管理 |

## 迁移步骤

### 1. 准备 COS 存储桶
按照上述"COS Bucket 准备"步骤创建并配置存储桶

### 2. 更新配置文件
在 `.env` 中添加 COS 配置项

### 3. 部署代码
部署更新后的 `TrtcCloudRecordingService.php`

### 4. 测试录制
1. 发起一次测试录制
2. 检查 COS 控制台是否有文件上传
3. 验证文件可以正常下载和播放

### 5. 监控日志
查看日志确认录制状态：
```
CreateCloudRecording mix (COS)
DescribeCloudRecording(合流校验-COS)
```

## 获取录制文件

### 方式一：COS 控制台
1. 登录 COS 控制台
2. 进入对应存储桶
3. 浏览 `trtc-recording/` 目录
4. 下载或获取文件 URL

### 方式二：COS SDK
```php
use Qcloud\Cos\Client;

$cosClient = new Client([
    'region' => 'ap-guangzhou',
    'credentials' => [
        'secretId' => 'your-secret-id',
        'secretKey' => 'your-secret-key',
    ],
]);

// 列出录制文件
$result = $cosClient->listObjects([
    'Bucket' => 'your-bucket-1234567890',
    'Prefix' => 'trtc-recording/',
]);

foreach ($result['Contents'] as $file) {
    echo $file['Key'] . "\n";
}
```

### 方式三：生成临时访问 URL
```php
$url = $cosClient->getObjectUrl(
    'your-bucket-1234567890',
    'trtc-recording/file.mp4',
    '+10 minutes'  // URL 有效期
);
```

## 回调通知

### COS 事件通知
可以配置 COS 事件通知，在文件上传完成时触发回调：

1. 在 COS 控制台配置事件通知
2. 选择事件类型：`cos:ObjectCreated:*`
3. 配置回调 URL
4. 接收通知并处理

### 回调数据示例
```json
{
  "Records": [
    {
      "event": {
        "eventName": "cos:ObjectCreated:Put",
        "eventTime": "2024-01-01T12:00:00Z"
      },
      "cos": {
        "cosObject": {
          "key": "trtc-recording/room_123_20240101_120000.mp4",
          "size": 12345678,
          "url": "https://bucket.cos.ap-guangzhou.myqcloud.com/..."
        }
      }
    }
  ]
}
```

## 故障排查

### 问题1：录制文件未上传到 COS
**检查项：**
- COS Bucket 名称是否正确
- Region 是否匹配
- TRTC 服务是否有 COS 写入权限
- 查看日志中的错误信息

### 问题2：无法访问录制文件
**检查项：**
- Bucket 访问权限设置
- 文件路径是否正确
- 是否需要签名 URL

### 问题3：录制状态一直是 Idle
**检查项：**
- RoomIdType 是否与客户端一致
- 房间内是否有用户推流
- 网络连接是否正常

## 成本估算

### COS 存储成本（以广州地域为例）

**存储费用：**
- 标准存储：0.118 元/GB/月
- 低频存储：0.08 元/GB/月

**流量费用：**
- 外网下行流量：0.5 元/GB
- CDN 回源流量：0.15 元/GB

**示例计算：**
- 每天录制 10 小时，每小时 500MB
- 月存储量：10 × 30 × 0.5 = 150GB
- 月存储费用：150 × 0.118 = 17.7 元
- 月流量（假设下载 50GB）：50 × 0.5 = 25 元
- **月总费用：约 42.7 元**

## 相关文档

- [TRTC 云端录制](https://cloud.tencent.com/document/product/647/16823)
- [COS 对象存储](https://cloud.tencent.com/document/product/436)
- [COS PHP SDK](https://cloud.tencent.com/document/product/436/12266)

## 总结

✅ 存储方式从 VOD 改为 COS  
✅ 降低存储成本  
✅ 简化文件管理  
✅ 支持自定义路径前缀  
✅ 更新日志和提示信息  
✅ 需要配置 COS Bucket 和权限  

迁移到 COS 后，录制文件将直接存储到对象存储桶，成本更低，管理更简单！