腾讯云COS接入配置

腾讯云 COS 接入配置说明

一、目标

将小程序、管理端、富文本图片统一接入腾讯云 COS，对外统一使用：

https://xxxxx.cn/{objectKey}

当前桶信息：

• 存储桶：xxxxx-img-blog-xxxxx
• 地域：ap-guangzhou
• 自定义访问域名：img.xxxxx.cn

---

二、接入后的图片链路

上传链路：

前端/管理端上传 -> 后端上传 COS -> COS 存储对象

访问链路：

前端/小程序访问 https://img.xxxxx.cn/{objectKey}

说明：

• 数据库存储的是 objectKey，不是完整域名 URL。
• 后端返回给前端时，再统一拼接完整图片 URL。
• 这样后续如果更换图片域名，只需要改配置，不需要批量改数据库。

---

三、前提条件

• 已开通腾讯云 COS 服务。
• 已创建图片存储桶。
• 已准备好可用域名 img.xxxxx.cn。
• 已具备 HTTPS 证书。
• 后端已支持 COS 上传、删除、URL 拼接。

---

四、COS 控制台配置步骤

1. 创建存储桶

路径：

腾讯云 COS 控制台 -> 存储桶列表 -> 创建存储桶

建议配置：

• 存储桶名称：自己命名
• 所属地域：可以选择你所在的区域
• 访问类型：公有读私有写

说明：

• 图片需要对外直接访问，所以读权限需要放开。
• 写权限仍保持私有，只允许后端凭密钥上传和删除。

---

2. 配置访问权限

路径：

COS 控制台 -> 存储桶详情 -> 权限管理

建议配置：

• Bucket ACL：公有读私有写

说明：

• 对应官方 ACL 口径就是 public-read。
• 不要配置成 公有读公有写，风险太大。

---

3. 配置自定义源站域名

路径：

COS 控制台 -> 存储桶详情 -> 域名与传输管理 -> 自定义源站域名

建议配置：

• 域名：img.xxxxx.cn
• 源站类型：REST

说明：

• 这是 COS 原生自定义访问域名配置。
• 如果后续接入 CDN，img.xxxxx.cn 也可以继续保留，只是解析目标从 COS 改成 CDN。

---

4. 配置 DNS 解析

路径：

域名 DNS 控制台 -> 新增解析记录

建议配置：

• 主机记录：img
• 记录类型：CNAME
• 记录值：指向 COS 控制台给出的目标地址

说明：

• 先完成域名解析，外部才能通过 img.xxxxx.cn 访问图片。
• 如果后面切 CDN，只需要把这条 CNAME 改到 CDN 提供的地址。

---

5. 配置 HTTPS 证书

路径：

COS 控制台 -> 存储桶详情 -> 域名与传输管理 -> HTTPS 配置

建议配置：

• 绑定 img.xxxxx.cn 对应证书
• 优先使用腾讯云已托管证书

说明：

• 图片访问统一走 HTTPS，避免浏览器和小程序混合内容问题。
• 官方口径里，自定义源站域名绑定证书后通常不是瞬时生效，实际生效可预留一段时间观察。

---

6. 配置防盗链

路径：

COS 控制台 -> 存储桶详情 -> 安全管理 -> 防盗链

建议配置：

• 状态：开启
• 模式：Referer 白名单
• 白名单：
  • *.xxxxx.cn
  • xxxxx.cn
  • *.servicewechat.com
  • servicewechat.com

说明：

• 用于限制图片被外站直接盗用。
• 腾讯云官方 Referer 规则支持通配符匹配。
• 如果后面发现浏览器地址栏直接打开图片被拦截，需要结合业务决定是否允许空 Referer。

---

7. 配置跨域 CORS

路径：

COS 控制台 -> 存储桶详情 -> 安全管理 -> 跨域访问 CORS 设置

建议配置：

• AllowedOrigin：按你的前端域名填写，建议带协议
• AllowedMethod：
  • GET
  • HEAD
  • 如需浏览器直传再额外放开 PUT/POST
• AllowedHeader：*
• ExposeHeader：按需
• MaxAgeSeconds：按需配置

说明：

• 官方口径中，AllowedOrigin 建议使用完整格式：协议://域名[:端口]。
• 如果只是前端展示图片，通常 GET/HEAD 就够了。
• 如果后面要做浏览器直传 COS，再补充写操作相关方法。

---

8. 配置监控告警

路径：

腾讯云监控/告警中心 -> 针对 COS 配置告警策略

当前记录：

• 默认告警阈值：5000MB/分钟
• 通知方式：绑定手机

说明：

• 主要用于发现异常流量、盗刷或突发访问。
• 后续如果图片流量长期上升，可以按实际业务量调整阈值。

---

五、后端对应配置

后端当前核心配置项：

yjx:
  cos:
    secret-id: ${YJX_COS_SECRET_ID}
    secret-key: ${YJX_COS_SECRET_KEY}
    region: ${YJX_COS_REGION:ap-guangzhou}
    bucket: ${YJX_COS_BUCKET:}
    domain: ${YJX_COS_DOMAIN:}

说明：

• bucket：COS 存储桶完整名称。
• domain：后端拼接完整图片 URL 时使用的访问域名。
• 如果后面切换图片域名，优先改 YJX_COS_DOMAIN，不改代码。

---

六、验收方式

1. 上传验收

• 单张图片上传成功。
• 批量图片上传成功。
• 产品图片上传成功。
• 编辑器图片上传成功。

2. 访问验收

• 浏览器直接访问图片 URL 可正常打开。
• 小程序可正常加载产品图、轮播图、富文本图片。
• 管理端产品图、轮播图回显正常。

3. 数据验收

• 结构化图片字段入库为 objectKey。
• 富文本图片在数据库中不再保存固定域名。
• 后端接口返回给前端的是完整 URL。

---

七、注意事项

• 不建议直接在 COS 控制台覆盖同一路径旧图片，否则可能命中 CDN 或浏览器旧缓存。
• 正常做法是通过后台重新上传，让后端生成新的 objectKey。
• 如果确实覆盖了同一路径旧图，需要去 CDN 做 URL 刷新 或 目录刷新。
• 防盗链白名单如果配得过严，可能导致浏览器直开图片失败。
• 后续如果切 CDN，不需要改数据库，只需要调整域名解析和云侧配置。

---

八、结论

本次 COS 接入的核心原则是：

• COS 负责存储图片对象。
• 数据库存 objectKey，不存固定域名。
• 后端统一拼接完整图片 URL。
• 域名、HTTPS、防盗链、CORS 都尽量在云侧配置完成。

这样后续不管是：

• 更换图片域名
• 接入 CDN
• 调整缓存策略

都可以尽量少动代码、少动数据库。