联犀开发者文档

对象存储与文件生命周期

约 1009 字大约 3 分钟

2025-03-03

平台通过 share/oss.Handle 封装文件存储。业务应保存稳定的对象路径并控制生命周期；签名下载 URL 是有期限的访问凭证，不应当作数据库中的永久文件标识。

桶与使用场景

桶用途使用边界
TemporaryBucket上传后尚未被业务确认的临时文件不能保证永久保留
PrivateBucket合同、附件等受保护文件访问前先校验业务权限，再签名
PublicBucket确认可公开的图片、资源不放凭据与私有业务资料

Bucket(name) 用于明确指定桶。存储端账号、访问地址、证书和策略由运行环境配置，公开教程不提供默认口令。

上传路径

平台通用接口支持两类入口：

  • POST /api/v1/system/common/upload-url/create：取得上传地址后直传。
  • POST /api/v1/system/common/upload-file：通过平台上传文件。

默认私有上传通常先到临时区，业务保存时确认。接口也支持按 isPublic、business、scene、useBy 等合同直接上传公开资源，仍受身份和用途权限限制；不能概括为所有上传一律只能到临时桶。

文件名、扩展名、大小和内容按业务校验。原始文件名用于展示，不能未经清理就作为任意对象路径。统一使用 oss.GenFilePath 等路径规则，避免跨企业覆盖同名文件。

确认业务附件

推荐顺序：

  1. 校验当前用户对目标业务对象的写权限。
  2. 确认临时对象属于本次操作可使用的范围。
  3. 复制到选定正式桶，取得稳定对象路径。
  4. 数据库提交新路径及关联关系。
  5. 成功后清理旧附件；失败时清理新建孤立对象或进入补偿。

不要在保存新文件前先删旧文件。数据库事务与对象存储复制/删除不原子，应明确失败补偿及定期清理策略。

API 片段，storage 为已初始化的 oss.Handle：

// 将已经校验过的临时对象复制到私有业务路径。
path, err := storage.PrivateBucket().CopyFromTempBucket(tempPath, dstPath)

下载和流式读取

方法返回内容调用要求
SignedGetUrl(ctx, path, expiredSec, options)有效期内可访问的签名 URL先检查文件所属业务权限
GetUrl(ctx, path, withHost)路径或访问 URL不自动为私有对象授予权限
Get(ctx, path, options)io.ReadCloser由调用方 Close，适合流式响应
GetObjectLocal(ctx, path, localPath)下载到本地限制本地路径与清理生命周期
GetObjectInfo(ctx, path)文件信息核对存在性和大小

当前 GetUrl 包含 ctx 参数。旧文章省略上下文的调用不能直接复制到当前代码。

流式下载示例函数：

// 本文件提供演示对象流式下载，调用者须先完成业务授权。
package files

import (
    "context"
    "io"
    "gitee.com/unitedrhino/share/oss"
    "gitee.com/unitedrhino/share/oss/common"
)

// WriteObject 将已授权对象写到目标流，关闭对象读取器并返回传输错误。
func WriteObject(ctx context.Context, storage oss.Handle, path string, dst io.Writer) error {
    src, err := storage.PrivateBucket().Get(ctx, path, common.OptionKv{})
    if err != nil { return err }
    defer src.Close()
    _, err = io.Copy(dst, src)
    return err
}

SignedPutUrl 与 SignedGetUrl 都使用秒级有效期，文件 URL 不写日志或公开缓存。外部自定义域名要同时验证后端签名与浏览器实际可达，不能只修改域名字符串。

删除与测试

删除先验证对象关联与权限，存在共享引用时不能直接删物理文件。临时对象清理、孤立对象清理和业务删除是不同任务。

本机验证上传 → 正式确认 → 读取 → 替换 → 删除，覆盖临时文件过期、签名过期、无权下载、复制失败、数据库失败和旧文件被引用等情况。独立应用接入平台上传接口见SDK。

更新日志

2026/10/16 19:46
查看所有更新日志
  • b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于