溯仑智算
溯仑智算 SU.RUN开发者文档
获取接入支持
溯仑智算
溯仑智算 SU.RUN
开发者文档
开始使用
文档中心
阅读路径、接入顺序与专题总览
存储接入快速开始
第一次接入时优先阅读
存储接入总览
能力边界、使用路径与整体说明
本地配置与验证指南
在本地完成示例接口与最小验证
上传与下载
授权上传指南
浏览器、App 与客户端上传方式
授权下载指南
受控下载、权限判断与短时授权
前端直传安全规范
长期密钥保护与权限边界
大文件上传实战
大文件上传、重试与断点续传
规划与治理
文件路径命名规范
存储桶、路径、目录与归档规则
自定义域名接入
品牌化访问、证书与上线准备
接口说明
服务端接入方式、鉴权边界与返回结构
最小后端接入示例
上传下载授权与确认入库的完整串联
代码示例
JavaScript、Python 与 Go 接入示例
AI 与工作流
AI 环境接入说明
常见 AI 环境的接入说明
AI 训练数据与结果回写规范
模型、数据集、日志与输出治理
排障与帮助
错误码与问题排查
常见异常定位与恢复建议
接入常见问题总览
按角色整理的常见问题说明
支持中心
获取接入支持
获取接入支持
开始使用
文档中心存储接入快速开始存储接入总览本地配置与验证指南
上传与下载
授权上传指南授权下载指南前端直传安全规范大文件上传实战
规划与治理
文件路径命名规范自定义域名接入接口说明最小后端接入示例代码示例
AI 与工作流
AI 环境接入说明AI 训练数据与结果回写规范
排障与帮助
错误码与问题排查接入常见问题总览
当前文档
存储桶、路径、目录与归档规则
文档中心

文件路径命名规范

文件路径规划看起来像小事,但它会直接影响权限控制、生命周期策略、AI 工作流和后续批量治理效率。

规范咨询
support@su.run

存储桶规划 / 文件前缀 / AI 目录设计

路径首先服务于治理,而不是只服务于上传成功

一个文件路径如果只能让文件传上去,却无法支撑后续的权限控制、批量清理、生命周期策略、AI 训练管理和审计回溯,那么它就是短期方案,不是正式方案。

业务语义优先于随机字符串

objectKey 可以包含随机片段来防冲突,但不应只剩随机值。建议至少保留环境、业务线、项目或日期等语义,让排障和协作更高效。

后端统一生成,前端只消费

文件路径本质上是资源定位规则,建议由业务后端统一生成和校验。前端、移动端和第三方客户端只拿最终可用的 objectKey,不自行拼接关键目录。

存储桶命名建议

  • 按业务拆桶,例如 media-assets、training-assets、user-uploads。
  • 测试和生产环境尽量拆开。
  • 不同团队或系统,至少按前缀隔离,理想情况下按桶隔离。

文件路径建议

  • 路径建议包含环境、业务线、日期,例如 prod/ugc/2026/06/file.png。
  • 文件路径建议由后端统一生成。
  • AI 场景建议使用 models/、datasets/、outputs/ 这类语义前缀。
  • 不要把关键文件路径完全交给客户端自己拼接。

普通业务素材

适合内容封面、业务附件、资料归档。包含环境、项目和日期,后续容易做权限与生命周期治理。

prod/projects/{projectId}/assets/2026/06/cover.png

用户上传文件

适合头像、简历、用户附件等场景。按用户或组织隔离,有利于权限判断和批量清理。

prod/users/{userId}/uploads/2026/06/avatar.png

AI 模型与结果

适合模型、数据集、日志和推理结果。建议再配合 outputs/、datasets/、logs/ 等前缀分层。

prod/ai/{projectId}/models/base/v1/model.safetensors

常见反模式

  • 只使用类似 9f3a6b7c8d.png 这类完全无语义的路径。
  • 把测试和生产环境都写进同一桶、同一目录层级。
  • 让前端或脚本临时拼接关键业务目录,导致同一类资源分散在多个路径。
  • 模型、数据集和结果输出混在一个前缀里,后续很难清理和做权限隔离。

团队协作建议

  • 团队内统一约定环境前缀,例如 dev/、staging/、prod/。
  • 统一约定对象路径由哪个服务生成,避免多个后端各写一套规则。
  • AI 项目建议统一版本目录规范,例如 models/base/v1/、datasets/project-a/2026-06/。
  • 上线前至少拿一个真实项目把上传、下载、删除和归档路径跑通,确认目录结构可维护。

接入常见问题

文件路径里是否一定要包含日期?

不一定,但强烈建议保留某种可归档维度。日期是最常见的一种,因为它对排障、清理和生命周期策略都非常有帮助。

已有旧路径规则时应如何处理?

可以先从新业务或新目录开始收口,不一定一次迁完全部历史数据。但新规则必须先定清楚,否则会持续累积混乱。

模型文件和用户上传文件是否可以放在同一个存储桶?

技术上可以,但正式治理上通常不建议。它们的权限、生命周期、调用频率和审计方式都不同,至少要前缀隔离,理想情况下分桶。

上一篇
大文件上传实战
大文件上传、重试与断点续传
下一篇
自定义域名接入
品牌化访问、证书与上线准备
更多帮助

你可能还需要这些帮助入口

文档中心帮助你完成接入,客户服务页帮助你了解采购、支持与服务信息。

邮件支持

需要迁移协助或接入支持时,可以直接进入邮件支持入口。

进入支持中心

客户常见问题

采购、测试申请、迁移安排与售后问题,可先查看这份常见问题说明。

查看常见问题

价格与采购说明

需要确认容量区间、采购方式、续费与对账说明时,可从这里继续查看。

查看价格说明