server/HuanMengAdmin

Fork 0

zpc 215107a625 抽离cos服务

2025-11-12 00:13:56 +08:00

6.4 KiB

Raw Permalink Blame History

腾讯云COS服务接口迁移文档

📋 更新概述

本次更新将腾讯云COS相关接口从 TImageConfigController 迁移到独立的 CosController，实现服务分离，COS服务不再与业务数据库关联。

🆕 一、新增接口

1.1 获取COS签名

接口信息：

请求路径：GET /api/v1/admin/Cos/GetCosSign
请求方法：GET
是否需要认证：是
描述：获取腾讯云COS预签名URL

请求参数： 无

响应示例：

"https://cos.ap-shanghai.myqcloud.com/miaoyu-1308826010/exampleobject?sign=..."

响应字段说明：

返回类型：string
说明：预签名的COS上传URL

1.2 获取临时密钥

接口信息：

请求路径：GET /api/v1/admin/Cos/GetGenerateTemporaryKey
请求方法：GET
是否需要认证：是
描述：获取腾讯云COS临时访问密钥（STS）

请求参数：

参数名	类型	必填	说明
fileName	string	否	文件名，不传则生成时间戳文件名
modelName	string	否	模型名称，默认值为 "images"

请求示例：

GET /api/v1/admin/Cos/GetGenerateTemporaryKey?fileName=test.jpg&modelName=images

响应示例：

{
  "credentials": {
    "token": "xxx",
    "tmpSecretId": "xxx",
    "tmpSecretKey": "xxx"
  },
  "expiration": "2024-12-07T10:00:00Z",
  "expiredTime": 1701936000,
  "startTime": 1701935400,
  "requestId": "xxx",
  "bucket": "miaoyu-1308826010",
  "region": "ap-shanghai",
  "prefixes": "miaoyu",
  "filePath": "miaoyu/images/20241207/1701936000.jpg",
  "domainName": "https://cos.shhuanmeng.com/"
}

响应字段说明：

字段名	类型	说明
credentials	object	临时访问凭证
credentials.token	string	临时Token
credentials.tmpSecretId	string	临时SecretId
credentials.tmpSecretKey	string	临时SecretKey
expiration	string	过期时间（ISO8601格式）
expiredTime	number	过期时间（Unix时间戳）
startTime	number	开始时间（Unix时间戳）
requestId	string	请求ID
bucket	string	存储桶名称
region	string	地域
prefixes	string	路径前缀
filePath	string	文件路径
domainName	string	访问域名

⚠️ 二、废弃接口

以下接口已废弃，请使用新的接口替代：

2.1 废弃：获取COS签名

旧接口路径：GET /api/v1/admin/TImageConfig/GetCosSign
新接口路径：GET /api/v1/admin/Cos/GetCosSign
状态：❌ 已废弃，请使用新接口

2.2 废弃：获取临时密钥

旧接口路径：GET /api/v1/admin/TImageConfig/GetGenerateTemporaryKey
新接口路径：GET /api/v1/admin/Cos/GetGenerateTemporaryKey
状态：❌ 已废弃，请使用新接口

🔄 三、接口迁移对照表

功能	旧接口	新接口	状态
获取COS签名	`GET /api/v1/admin/TImageConfig/GetCosSign`	`GET /api/v1/admin/Cos/GetCosSign`	✅ 已迁移
获取临时密钥	`GET /api/v1/admin/TImageConfig/GetGenerateTemporaryKey`	`GET /api/v1/admin/Cos/GetGenerateTemporaryKey`	✅ 已迁移

📝 四、前端修改说明

4.1 接口地址变更

修改前：

// 获取COS签名
const getCosSign = async () => {
  return axios.get('/api/v1/admin/TImageConfig/GetCosSign');
};

// 获取临时密钥
const getTemporaryKey = async (fileName?: string, modelName?: string) => {
  return axios.get('/api/v1/admin/TImageConfig/GetGenerateTemporaryKey', {
    params: { fileName, modelName }
  });
};

修改后：

// 获取COS签名
const getCosSign = async () => {
  return axios.get('/api/v1/admin/Cos/GetCosSign');
};

// 获取临时密钥
const getTemporaryKey = async (fileName?: string, modelName?: string) => {
  return axios.get('/api/v1/admin/Cos/GetGenerateTemporaryKey', {
    params: { fileName, modelName }
  });
};

4.2 API服务更新

建议更新 API 服务文件：

// api/cos.ts
export const cosApi = {
  // 获取COS签名
  getCosSign: (): Promise<string> => {
    return axios.get('/api/v1/admin/Cos/GetCosSign').then(res => res.data);
  },

  // 获取临时密钥
  getTemporaryKey: (params?: {
    fileName?: string;
    modelName?: string;
  }): Promise<GenerateTemporaryModel> => {
    return axios.get('/api/v1/admin/Cos/GetGenerateTemporaryKey', {
      params
    }).then(res => res.data);
  }
};

4.3 类型定义（如需要）

// types/cos.ts
export interface GenerateTemporaryModel {
  credentials: {
    token: string;
    tmpSecretId: string;
    tmpSecretKey: string;
  };
  expiration: string;
  expiredTime: number;
  startTime: number;
  requestId: string;
  bucket: string;
  region: string;
  prefixes: string;
  filePath: string;
  domainName: string;
}

✨ 五、注意事项

5.1 接口兼容性

旧接口已完全废弃，不再可用
新接口的参数和返回值与旧接口完全一致，仅路径变更
无需修改业务逻辑，只需更新接口地址

5.2 权限控制

新接口需要认证（[Authorize]）
权限控制规则与旧接口一致
如果旧接口有特殊权限配置，新接口保持相同配置

5.3 错误处理

错误响应格式保持不变
错误码和错误信息保持一致
前端错误处理逻辑无需修改

🔍 六、验证清单

请确认以下内容已完成：

更新所有调用 TImageConfig/GetCosSign 的代码
更新所有调用 TImageConfig/GetGenerateTemporaryKey 的代码
更新 API 服务文件中的接口地址
测试新接口是否正常工作
移除对旧接口的引用
更新相关文档和注释

📞 七、技术支持

如有疑问，请联系后端开发团队。

文档版本：v1.0
更新日期：2024年12月
后端版本：COS服务分离重构版本

📚 附录：完整接口列表

新接口列表

获取COS签名
- GET /api/v1/admin/Cos/GetCosSign
获取临时密钥
- GET /api/v1/admin/Cos/GetGenerateTemporaryKey?fileName={fileName}&modelName={modelName}

已废弃接口列表

~~GET /api/v1/admin/TImageConfig/GetCosSign~~ ❌
~~GET /api/v1/admin/TImageConfig/GetGenerateTemporaryKey~~ ❌

文档结束

6.4 KiB Raw Permalink Blame History Unescape Escape