下面是整理后的学习笔记（已去掉第十和第十三部分，并将关键数据结构改为表格形式）。

阿里云 OSS 与 Agent 联动学习笔记

一、OSS 是什么

Alibaba Cloud OSS（Object Storage Service）是一个云端对象存储服务。

它用于存放图片、视频、文档、日志、模型输出等文件。

在系统架构中：

  • 数据库：存业务数据
  • OSS：存文件本体
  • Agent：处理逻辑 + 调用 OSS

二、OSS 核心概念

概念 含义 示例
Bucket 存储空间（类似顶级目录） product-images
Object 实际文件 main.jpg
Object Key 文件路径 products/10001/main.jpg
Endpoint 访问域名 oss-cn-hangzhou.aliyuncs.com
AccessKey 访问凭证 AK / SK

补充说明：

  • Bucket 必须全局唯一
  • Object Key 本质是字符串路径（没有真实文件夹）
  • Endpoint 必须与地域一致

三、Agent 为什么需要 OSS

Agent 本质会“产出文件”，OSS 是这些文件的最终存储层。

典型用途：

  • 生成图片 → 存 OSS → 返回 URL
  • 生成 PDF / Word / Excel → 存 OSS
  • 处理用户上传文件 → 结果存 OSS
  • 日志 / JSON / 中间结果归档

一句话：

OSS = Agent 的文件存储基础设施

四、Agent 与 OSS 的标准流程

步骤 动作
1 用户提交任务
2 Agent 解析任务
3 Agent 生成/处理文件
4 上传文件到 OSS
5 OSS 返回 object key
6 生成访问 URL
7 写入数据库
8 返回给前端

五、Agent 中 OSS 配置项

配置项 示例 说明
OSS_REGION cn-hangzhou 存储地域
OSS_ENDPOINT oss-cn-hangzhou.aliyuncs.com 接口地址
OSS_BUCKET agent-bucket 存储桶
OSS_ACCESS_KEY_ID xxx 身份ID
OSS_ACCESS_KEY_SECRET xxx 密钥
OSS_PUBLIC_BASE_URL https://bucket.oss-cn-hangzhou.aliyuncs.com 访问前缀
OSS_PREFIX agent-output/ 统一路径前缀

六、文件命名规范（强烈建议）

场景 规则 示例
通用任务文件 agent-output/{taskId}/{timestamp}_{name} agent-output/task001/1714300_result.pdf
商品图片 products/{productId}/{picName}.jpg products/SP001/main.jpg
Agent结果 result/{date}/{uuid}.json result/2026-04-28/xxx.json

设计原则：

  • 可读
  • 不重复
  • 可追踪
  • 可分区（按业务 / 时间）

七、Agent 上传 OSS 的核心步骤

步骤 说明
读取文件 本地文件 / 内存流
生成 key 按规范生成路径
上传 OSS SDK 调用
设置类型 Content-Type
获取 URL 拼接或返回
持久化 写数据库

八、权限设计建议

方案 是否推荐 原因
主账号 AK 不推荐 权限过大
RAM 子账号 推荐 最小权限
硬编码 AK 不推荐 安全风险
环境变量 推荐 安全隔离
公共读写 不推荐 风险高
公共读 + 私有写 推荐 常规方案
STS 临时授权 强烈推荐 前端直传

九、推荐架构（Agent + OSS）

层级 作用
Agent 业务逻辑 + 文件生成
OSS 文件存储
数据库 存 URL / 元数据
前端 通过 URL 展示

对比：

错误做法 正确做法
数据库存图片 blob 存 OSS URL
本地磁盘存文件 上传 OSS
Agent 不持久化文件 OSS 持久化

十、常见 Agent + OSS 场景

场景 流程
图片同步 SQL Server → OSS → URL
文档生成 Agent → PDF → OSS
数据报表 Agent → Excel → OSS
多媒体处理 视频/音频 → OSS
日志归档 JSON → OSS

十一、配置注意事项

项目 要点
Endpoint 必须匹配地域
Key 命名 不要特殊字符
文件校验 不为空
Content-Type 必须正确
大文件 分片上传
私有文件 使用签名 URL

常见 Content-Type：

文件类型 Content-Type
jpg image/jpeg
png image/png
pdf application/pdf
docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

核心总结（工程视角）

  • OSS 是文件存储，不是数据库
  • Agent 负责“产生文件 + 上传文件”
  • 数据库只存 URL / key
  • 文件访问统一走 OSS（可挂 CDN）