腾讯云对象存储（COS）文档处理配置指南

# 腾讯云对象存储（COS）文档处理配置指南

## 概述

腾讯云对象存储（COS）提供了文档处理功能，支持对存储在 COS 中的文档文件（如 PDF、Word、Excel、PPT 等）进行预览、格式转换、水印添加等操作。本指南介绍如何在 MuuCmf 资料下载模块中配置和使用腾讯云 COS 文档处理服务。

## 前提条件

1. 拥有腾讯云账号并开通对象存储（COS）服务
2. 创建存储桶（Bucket）用于存储文档文件
3. 开通文档处理功能（可能需要单独开通）
4. 获取 API 密钥（SecretID 和 SecretKey）

## 配置步骤

### 1. 获取腾讯云 API 密钥

1. 登录腾讯云控制台
2. 进入 [访问管理](https://console.cloud.tencent.com/cam/capi) 页面
3. 创建或使用现有的 API 密钥，获取：
   - `SecretID`
   - `SecretKey`
4. 记录下获取到的 `SecretID` 和 `SecretKey`，后续配置时需要使用
5. 为子账号添加权限，确保 API 密钥有访问对象存储、数据万象服务的权限

### 3. 开通文档处理功能

1. 在存储桶管理页面，找到「数据处理」或「文档处理」功能
2. 开通文档处理服务
3. 获取文档处理专用的 Bucket ID（通常与存储桶关联）

### 4. 系统配置

在 MuuCmf 素材管理模块的配置页面，填写以下腾讯云 COS 配置项：

| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| `tencent_SecretID` | 腾讯云 API 密钥 ID | `AKIDxxxxxxxxxxxxxxxxxxxxxxxx` |
| `tencent_SecretKEY` | 腾讯云 API 密钥 KEY | `xxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
| `tencent_Region` | 存储桶所在地域 | `ap-beijing` |
| `tencent_Bucket` | 存储桶名称 | `my-bucket-1250000000` |
| `tencent_Bucket_Domain` | 存储桶访问域名 | `https://my-bucket-1250000000.cos.ap-beijing.myqcloud.com` |
| `tencent_Bucket_Docprocess_ID` | 文档处理队列 ID | `xxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

### 5. 回调 URL 配置

系统自动生成文档处理回调 URL，用于接收文档处理完成的通知：

```
{域名}/material/api/webhook
```

请确保该 URL 可被腾讯云服务器访问（公网可访问）。

## 功能说明

### 文档预览

配置完成后，系统支持对以下格式的文档进行在线预览：

- **PDF**：直接预览
- **Word**：doc、docx
- **Excel**：xls、xlsx
- **PPT**：ppt、pptx
- **文本文件**：txt、md 等

### 文档转换

支持将文档转换为以下格式：

1. **PDF 转换**：将 Office 文档转换为 PDF 格式
2. **图片转换**：将文档页面转换为图片（PNG、JPG）
3. **HTML 转换**：将文档转换为 HTML 格式

### 水印功能

支持为预览的文档添加水印，包括：

- 文字水印
- 图片水印
- 动态水印（如用户名、时间戳）

## 项目集成

### 配置页面字段说明

在素材管理模块的配置页面（`/admin/config/index`）中，腾讯云 COS 文档处理相关配置字段如下：

| 表单字段名 | 对应配置项 | 说明 |
|------------|------------|------|
| `tencent_SecretID` | `storage.tencent.SecretID` | 腾讯云 API 密钥 ID |
| `tencent_SecretKEY` | `storage.tencent.SecretKEY` | 腾讯云 API 密钥 KEY |
| `tencent_Region` | `storage.tencent.Region` | 存储桶所在地域 |
| `tencent_Bucket` | `storage.tencent.Bucket` | 存储桶名称 |
| `tencent_Bucket_Domain` | `storage.tencent.BucketDomain` | 存储桶访问域名 |
| `tencent_Bucket_Docprocess_ID` | `storage.tencent.BucketDocprocessID` | 文档处理队列 ID |

### 配置文件存储

系统将配置数据以 JSON 格式存储在数据库表中，结构如下：

```json
{
  "storage": {
    "cloud": "tencent",
    "tencent": {
      "SecretID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxx",
      "SecretKEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "Region": "ap-beijing",
      "Bucket": "my-bucket-1250000000",
      "BucketDomain": "https://my-bucket-1250000000.cos.ap-beijing.myqcloud.com",
      "BucketDocprocessID": "bucket-1250000000"
    }
  }
}
```

### 回调 URL 配置

系统自动生成文档处理回调 URL，并在配置页面显示：

```
{域名}/material/api/webhook
```

该 URL 用于接收腾讯云文档处理完成的通知，需要在腾讯云控制台配置为回调地址。

## 代码集成

### 配置文件结构

系统将腾讯云 COS 配置存储为 JSON 格式：

### 文档处理 API 调用示例

```php
// 初始化腾讯云 COS 客户端
$cosClient = new \Qcloud\Cos\Client([
    'region' => $config['tencent']['Region'],
    'credentials' => [
        'secretId' => $config['tencent']['SecretID'],
        'secretKey' => $config['tencent']['SecretKEY']
    ]
]);

// 文档预览请求
$docProcessTask = [
    'Bucket' => $config['tencent']['Bucket'],
    'Key' => 'document/test.docx', // 文档在 COS 中的路径
    'Operations' => [
        [
            'DocProcess' => [
                'TgtType' => 'png', // 输出格式
                'PageRange' => '1-10', // 页码范围
                'ImageParams' => 'watermark/type/2/text/保密文档' // 水印参数
            ]
        ]
    ]
];

// 调用文档处理接口
$result = $cosClient->docProcess($docProcessTask);
```

## 常见问题

### 1. 文档处理失败

**可能原因**：
- 文档格式不支持
- 文档大小超过限制（通常 200MB）
- 文档处理服务未开通或欠费

**解决方案**：
1. 检查文档格式是否在支持列表中
2. 确认文档大小符合要求
3. 检查腾讯云账户余额和文档处理服务状态

### 2. 预览加载缓慢

**可能原因**：
- 文档页数过多
- 网络延迟
- 图片质量设置过高

**解决方案**：
1. 分页加载文档
2. 使用 CDN 加速
3. 调整图片质量参数

### 3. 回调 URL 无法访问

**可能原因**：
- 服务器防火墙限制
- 域名未备案（中国大陆地区）
- 回调 URL 路径错误

**解决方案**：
1. 检查服务器安全组规则，允许腾讯云 IP 段访问
2. 确保域名已完成备案
3. 验证回调 URL 是否正确

## 安全建议

1. **API 密钥保护**：不要将 SecretID 和 SecretKEY 硬编码在客户端代码中
2. **权限控制**：使用子账号或临时密钥，遵循最小权限原则
3. **访问控制**：配置存储桶的访问权限（公有读/私有读写）
4. **回调验证**：验证回调请求的签名，防止伪造请求

## 参考链接

- [腾讯云对象存储文档](https://cloud.tencent.com/document/product/436)
- [腾讯云文档处理 API](https://cloud.tencent.com/document/product/436/59325)

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-03-26 | 初始版本 |

全文搜索