Iris对接腾讯云COS需在handler中调用cos-go-sdk-v5，不可用FileServer；初始化client时Bucket名须为“bucket-name-appid”格式、region须精确匹配；上传大文件需避免读入内存，下载链接应使用GetPresignedURL生成。
直接用 Iris 框架对接腾讯云 COS，核心不是框架本身做了什么，而是你如何在 Iris 的 HTTP handler 里正确调用腾讯云官方 Go SDK（github.com/tencentyun/cos-go-sdk-v5），并规避常见鉴权、超时、错误处理陷阱。
为什么不能直接用 Iris 的 FileServer 或 StaticDir 对接 COS
Iris 的 FileServer 和 StaticDir 只能服务本地文件系统路径，它不理解对象存储的扁平化 key 结构、临时签名 URL、分块上传等语义。强行把 COS 挂载为本地路径（比如用 rclone mount）会引入 FUSE 层延迟、缓存一致性问题和单点故障，生产环境不推荐。
真正可行的方式是：在 Iris 的路由 handler 中，用 COS SDK 主动发起 PUT/GET/HEAD 等 REST 请求。
初始化 cos.Client 必须注意 region 和 bucket 名格式
腾讯云 COS 的 Bucket 不是简单字符串，而是 bucket-name-appid 格式（如 my-bucket-1259508442），且 region 必须与控制台创建桶时选的地域完全一致（如 ap-guangzhou，不是 gz 或 guangzhou）。填错会导致 403 Forbidden 或 404 NoSuchBucket。
示例初始化代码：
import (
"github.com/kataras/iris/v12"
"github.com/tencentyun/cos-go-sdk-v5"
)
<p>func initCOSClient() <em>cos.Client {
u, _ := url.Parse("<a href="https://www.php.cn/link/c15d12444bdba497b96841a269056108">https://www.php.cn/link/c15d12444bdba497b96841a269056108</a>")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Timeout: 30 </em> time.Second,
})
// 注意：SecretId/SecretKey 应从环境变量或 secret manager 加载，勿硬编码
client.Object.SetAuth(&cos.Credentials{
SecretID: os.Getenv("COS_SECRET_ID"),
SecretKey: os.Getenv("COS_SECRET_KEY"),
})
return client
}
</p>
-
BaseURL构造必须带完整 endpoint，不能只传https://cos.ap-guangzhou.myqcloud.com - SDK 默认不自动重试失败请求，高并发场景建议包装一层带指数退避的 wrapper
- 不要复用同一个
*cos.Client实例做跨 bucket 操作——每个 bucket 应该有独立 client 实例（因 BaseURL 不同）
上传文件时别忽略 multipart upload 的触发条件
COS Go SDK 对大于 5MB 的文件会自动切片走 InitiateMultipartUpload 流程；小于 5MB 则走单次 PutObject。这个阈值不可配置，但你必须确保 handler 能承受更长的上传时间（尤其网络不稳定时）。
腾讯云通用票据识别高级版(VatInvoiceOCR)接口调用技能。当用户需要识别发票图片中增值税专用发票、增值税普通发票、增值税电子专票、增值税电子普票、电子发票（普通/增值税专用）的全字段信息时,应使用此技能。支持识别发票图片中的发票代码、发票号码、开票日期、合计金额、校验码、税率、合计税额、价税合计、购买方...
关键实操点：
- HTTP 请求体必须用
ctx.Request().Body直接传给client.Object.Put，不要先读到内存再传——否则大文件会 OOM - 务必设置
ctx.ReadTimeout和ctx.WriteTimeout，例如：app.Run(iris.Addr(":8080"), iris.WithoutServerError(iris.ErrServerClosed), iris.WithReadTimeout(5*time.Minute), iris.WithWriteTimeout(5*time.Minute)) - 上传成功后，返回的
*cos.Response中Locationheader 是对象的可访问 URL，不是 SDK 自动拼的——它依赖你在BaseURL里填的域名
生成临时下载链接要手动拼签名校验串
COS 不像 AWS S3 提供现成的 PresignURL 方法，Go SDK v5 需要你自己构造签名 URL。漏掉 XCosSecurityToken（若使用临时密钥）、Expires 参数或签名算法版本（v4），都会导致 403。
最简安全做法是用 SDK 自带的 client.Object.GetPresignedURL：
signedURL, err := client.Object.GetPresignedURL(
http.MethodGet,
bucketName,
objectKey,
time.Now().Add(1 * time.Hour),
)
if err != nil {
ctx.StatusCode(500)
ctx.WriteString("failed to gen presigned url")
return
}
ctx.Redirect(signedURL.String(), 302)
注意：GetPresignedURL 返回的是完整 URL（含 query string），不是 path。如果前端需要直传 COS（如 Web 端 JS 上传），则必须用 client.Object.GetPresignedPostPolicy 生成 policy 表单字段，而不是拼 URL。
最容易被忽略的是：COS 的签名有效期单位是秒，而 Go 的 time.Duration 是纳秒，time.Hour 没问题，但写 3600 就容易错当成纳秒传进去导致签名瞬间失效。始终用 time.Now().Add(...) 构造过期时间。
