文档中心

授权下载指南

授权下载的核心不是生成一个 URL，而是让下载动作仍然受到业务权限、有效期和日志体系控制。

下载接入

support@su.run

受控下载 / 报表下载 / AI 结果下载

什么时候适合使用授权下载

当终端用户、内部后台、第三方系统或 AI 作业需要在短时间内拿到可用下载入口，但又不应直接暴露长期凭证时，授权下载通常是更稳妥的方案。

什么时候不应直接下发链接

如果文件涉及权限校验、组织隔离、有效期控制或审计要求，就不应把长期可访问的公共链接直接交给客户端，而应由后端按需签发短期下载地址。

常见使用场景

用户下载自己上传的文件。
业务后台下载报表、素材或归档文件。
AI 任务读取中间产物或结果文件。
第三方系统在有限时间内获取受控下载链接。

第一步：前端向业务后端申请下载授权

前端只提交 objectKey 或业务主键，不自行拼接底层下载链接。真正的权限判断由业务后端完成。

POST /api/storage/presign-download
{
  "objectKey": "projects/proj_xxx/reports/2026/06/result.pdf",
  "resourceType": "project-report"
}

第二步：后端校验权限并签发短时地址

后端确认当前用户、组织或任务是否有权读取该文件，再生成带有效期的 downloadUrl，同时记录 requestId 以便审计和排查。

{
  "success": true,
  "bucket": "media-assets",
  "objectKey": "projects/proj_xxx/reports/2026/06/result.pdf",
  "downloadUrl": "https://your-download-url",
  "expiresIn": 300,
  "requestId": "req_xxx"
}

第三步：客户端使用 downloadUrl 发起下载

客户端下载时只消费短期地址。若链接过期或权限变化，重新向业务后端申请，而不是缓存旧链接长期复用。

async function downloadFile(objectKey: string) {
  const response = await fetch('/api/storage/presign-download', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ objectKey }),
  });

  const { downloadUrl } = await response.json();
  window.location.href = downloadUrl;
}

后端签发示例

下载授权同样建议由业务后端签发，而不是把对象路径和长期权限直接交给客户端。

import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const client = new S3Client({
  region: 'auto',
  endpoint: process.env.SURUN_S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.SURUN_ACCESS_KEY_ID!,
    secretAccessKey: process.env.SURUN_SECRET_ACCESS_KEY!,
  },
});

export async function createDownloadAuthorization(params: {
  objectKey: string;
  currentUserId: string;
}) {
  // 这里先做业务权限判断，例如确认当前用户是否能读取该对象

  const command = new GetObjectCommand({
    Bucket: 'media-assets',
    Key: params.objectKey,
  });

  const downloadUrl = await getSignedUrl(client, command, { expiresIn: 300 });

  return {
    bucket: 'media-assets',
    objectKey: params.objectKey,
    downloadUrl,
    expiresIn: 300,
  };
}

前端调用示例

前端只负责向业务后端申请下载授权，再跳转到短时有效的 downloadUrl。

async function downloadFile(objectKey: string) {
  const response = await fetch('/api/storage/presign-download', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ objectKey }),
  });

  const { downloadUrl } = await response.json();
  window.location.href = downloadUrl;
}

链接刚生成就提示失效

优先检查前后端时间是否有偏差、expiresIn 是否设置过短，或者用户拿到链接后是否隔了很久才开始下载。

后端能签发，但用户仍然打不开

优先确认 objectKey 是否就是用户真正有权限访问的那个文件，以及下载授权接口里是否有业务权限收口逻辑。

下载成功，但日志里查不到

建议在签发下载地址时就记录 requestId、用户标识和 objectKey，不要把审计放到浏览器跳转之后再猜测。

排查优先顺序

先确认业务后端是否真的做了权限判断，而不是只凭 objectKey 就直接签发。
确认 objectKey 与 bucket 是否对应到用户真正需要的文件。
确认 downloadUrl 过期时间是否太短，或前后端机器时间是否有明显偏差。
确认下载动作在日志里带了 requestId、用户身份和 objectKey。
如果是 AI 任务或批处理读取失败，再额外检查任务环境变量与实际执行节点的时间同步。

不同下载场景建议

报表下载

建议先根据组织、时间范围和报表类型定位对象，再签发短时下载地址。这样后续做对账、过期清理和审计都更明确。

用户附件下载

建议把 objectKey 与业务记录绑定，不要让前端直接输入任意路径。用户看到的是文件记录，而不是底层文件路径。

AI 结果回读

如果模型推理、训练输出或知识库中间产物需要回读，建议按 jobId 或 taskId 管理目录，并在签发下载前再次校验任务归属。

SECURITY NOTICE

下载授权安全边界

所有下载授权都应先经过业务权限判断。
downloadUrl 必须有明确有效期。
高敏感文件建议带审计日志和 requestId。
不要把长期可访问链接直接当成业务下载方案。

生产上线检查表

所有下载入口都先走业务后端，不直接公开长期下载链接。
下载地址有效期与业务场景匹配，默认保持分钟级。
高敏感文件具备下载审计日志和 requestId。
下载失败时前端展示业务可理解文案，而不是底层异常。
报表、媒体、AI 结果等文件都已规划清晰的目录和授权边界。

接入常见问题

为什么下载也要走后端？

因为下载本身就是权限行为。谁能下载、能下载多久、下载什么文件，都应由业务系统判断。

下载地址有效期建议多长？

通常几分钟级别就够了。有效期越短，泄露后的风险越低。

更多帮助

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

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

邮件支持

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

进入支持中心

客户常见问题

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

查看常见问题

价格与采购说明

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

查看价格说明

文档中心

授权下载指南

授权下载的核心不是生成一个 URL，而是让下载动作仍然受到业务权限、有效期和日志体系控制。

下载接入

support@su.run

受控下载 / 报表下载 / AI 结果下载

什么时候适合使用授权下载

当终端用户、内部后台、第三方系统或 AI 作业需要在短时间内拿到可用下载入口，但又不应直接暴露长期凭证时，授权下载通常是更稳妥的方案。

什么时候不应直接下发链接

如果文件涉及权限校验、组织隔离、有效期控制或审计要求，就不应把长期可访问的公共链接直接交给客户端，而应由后端按需签发短期下载地址。

常见使用场景

用户下载自己上传的文件。
业务后台下载报表、素材或归档文件。
AI 任务读取中间产物或结果文件。
第三方系统在有限时间内获取受控下载链接。

第一步：前端向业务后端申请下载授权

前端只提交 objectKey 或业务主键，不自行拼接底层下载链接。真正的权限判断由业务后端完成。

POST /api/storage/presign-download
{
  "objectKey": "projects/proj_xxx/reports/2026/06/result.pdf",
  "resourceType": "project-report"
}

第二步：后端校验权限并签发短时地址

后端确认当前用户、组织或任务是否有权读取该文件，再生成带有效期的 downloadUrl，同时记录 requestId 以便审计和排查。

{
  "success": true,
  "bucket": "media-assets",
  "objectKey": "projects/proj_xxx/reports/2026/06/result.pdf",
  "downloadUrl": "https://your-download-url",
  "expiresIn": 300,
  "requestId": "req_xxx"
}

第三步：客户端使用 downloadUrl 发起下载

客户端下载时只消费短期地址。若链接过期或权限变化，重新向业务后端申请，而不是缓存旧链接长期复用。

async function downloadFile(objectKey: string) {
  const response = await fetch('/api/storage/presign-download', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ objectKey }),
  });

  const { downloadUrl } = await response.json();
  window.location.href = downloadUrl;
}

后端签发示例

下载授权同样建议由业务后端签发，而不是把对象路径和长期权限直接交给客户端。

import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const client = new S3Client({
  region: 'auto',
  endpoint: process.env.SURUN_S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.SURUN_ACCESS_KEY_ID!,
    secretAccessKey: process.env.SURUN_SECRET_ACCESS_KEY!,
  },
});

export async function createDownloadAuthorization(params: {
  objectKey: string;
  currentUserId: string;
}) {
  // 这里先做业务权限判断，例如确认当前用户是否能读取该对象

  const command = new GetObjectCommand({
    Bucket: 'media-assets',
    Key: params.objectKey,
  });

  const downloadUrl = await getSignedUrl(client, command, { expiresIn: 300 });

  return {
    bucket: 'media-assets',
    objectKey: params.objectKey,
    downloadUrl,
    expiresIn: 300,
  };
}

前端调用示例

前端只负责向业务后端申请下载授权，再跳转到短时有效的 downloadUrl。

async function downloadFile(objectKey: string) {
  const response = await fetch('/api/storage/presign-download', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ objectKey }),
  });

  const { downloadUrl } = await response.json();
  window.location.href = downloadUrl;
}

链接刚生成就提示失效

优先检查前后端时间是否有偏差、expiresIn 是否设置过短，或者用户拿到链接后是否隔了很久才开始下载。

后端能签发，但用户仍然打不开

优先确认 objectKey 是否就是用户真正有权限访问的那个文件，以及下载授权接口里是否有业务权限收口逻辑。

下载成功，但日志里查不到

建议在签发下载地址时就记录 requestId、用户标识和 objectKey，不要把审计放到浏览器跳转之后再猜测。

排查优先顺序

先确认业务后端是否真的做了权限判断，而不是只凭 objectKey 就直接签发。
确认 objectKey 与 bucket 是否对应到用户真正需要的文件。
确认 downloadUrl 过期时间是否太短，或前后端机器时间是否有明显偏差。
确认下载动作在日志里带了 requestId、用户身份和 objectKey。
如果是 AI 任务或批处理读取失败，再额外检查任务环境变量与实际执行节点的时间同步。

不同下载场景建议

报表下载

建议先根据组织、时间范围和报表类型定位对象，再签发短时下载地址。这样后续做对账、过期清理和审计都更明确。

用户附件下载

建议把 objectKey 与业务记录绑定，不要让前端直接输入任意路径。用户看到的是文件记录，而不是底层文件路径。

AI 结果回读

如果模型推理、训练输出或知识库中间产物需要回读，建议按 jobId 或 taskId 管理目录，并在签发下载前再次校验任务归属。

SECURITY NOTICE

下载授权安全边界

所有下载授权都应先经过业务权限判断。
downloadUrl 必须有明确有效期。
高敏感文件建议带审计日志和 requestId。
不要把长期可访问链接直接当成业务下载方案。

生产上线检查表

所有下载入口都先走业务后端，不直接公开长期下载链接。
下载地址有效期与业务场景匹配，默认保持分钟级。
高敏感文件具备下载审计日志和 requestId。
下载失败时前端展示业务可理解文案，而不是底层异常。
报表、媒体、AI 结果等文件都已规划清晰的目录和授权边界。

接入常见问题

为什么下载也要走后端？

因为下载本身就是权限行为。谁能下载、能下载多久、下载什么文件，都应由业务系统判断。

下载地址有效期建议多长？

通常几分钟级别就够了。有效期越短，泄露后的风险越低。

更多帮助

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

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

邮件支持

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

进入支持中心

客户常见问题

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

查看常见问题

价格与采购说明

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

查看价格说明

什么时候适合使用授权下载

什么时候不应直接下发链接

常见使用场景

推荐规则

推荐请求结构

推荐返回结构

第一步：前端向业务后端申请下载授权

第二步：后端校验权限并签发短时地址

第三步：客户端使用 downloadUrl 发起下载

后端签发示例

前端调用示例

链接刚生成就提示失效

后端能签发，但用户仍然打不开

下载成功，但日志里查不到

排查优先顺序

不同下载场景建议

下载授权安全边界

生产上线检查表

接入常见问题

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

邮件支持

客户常见问题

价格与采购说明

什么时候适合使用授权下载

什么时候不应直接下发链接

常见使用场景

推荐规则

推荐请求结构

推荐返回结构

第一步：前端向业务后端申请下载授权

第二步：后端校验权限并签发短时地址

第三步：客户端使用 downloadUrl 发起下载

后端签发示例

前端调用示例

链接刚生成就提示失效

后端能签发，但用户仍然打不开

下载成功，但日志里查不到

排查优先顺序

不同下载场景建议

下载授权安全边界

生产上线检查表

接入常见问题

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

邮件支持

客户常见问题

价格与采购说明