上传文件

POST/web/v1/files/command/uploadJWT + Turnstile

将文件上传至平台存储。文件存储在对象存储桶中，同时创建一条元数据记录用于跟踪。需要 JWT 鉴权和 Turnstile 验证。

鉴权

Auth Chain: WEB Chain — 需要 Authorization: Bearer <jwt> 和 Turnstile token。 以下 header 由系统注入（前端无需处理）： X-PORTAL-ACCESS-CODE (Nginx), X-Request-Id (Gateway)

请求参数

Name	Type	Required	In	Description
file	MultipartFile	Yes	form-data	要上传的文件
bucket	string	No	query	目标存储桶。省略时使用默认存储桶。
remark	string	No	query	文件的可选备注或描述
workspaceBizId	string	No	query	关联文件的工作空间业务 ID

成功响应

已创建201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "bizId": "file_abc123",
    "bucket": "default",
    "objectKey": "uploads/2026/03/21/file_abc123.pdf",
    "originalFilename": "invoice.pdf",
    "fileSize": 102400,
    "contentType": "application/pdf",
    "fileCategory": "DOCUMENT",
    "accessUrl": "https://storage.example.com/uploads/2026/03/21/file_abc123.pdf",
    "etag": "d41d8cd98f00b204e9800998ecf8427e"
  }
}

错误响应

Unauthorized401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Bad Request400

{
  "success": false,
  "code": "4000",
  "message": "File is required"
}

说明

• 请求必须使用 multipart/form-data 内容类型。
• 文件大小限制和允许的内容类型在服务端配置。
• etag 可用于完整性校验。