Skip to content

Commit a1fa4e1

Browse files
25121328392512132839
committed
fix: i18n && 界面样式 && api直传接口 bug
refactor: 统一存储接口抽象化 per: 优化webdav部分逻辑
1 parent 376e83d commit a1fa4e1

File tree

1 file changed

+27
-33
lines changed

1 file changed

+27
-33
lines changed

‎Api-s3_direct.md‎

Lines changed: 27 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
## 接口概述
44

5-
`/api/upload-direct`接口提供了一种简单高效的方式，可以直接上传文件到 S3 兼容的存储服务（如 AWS S3、Backblaze B2、Cloudflare R2 等）。该接口支持各种认证方式，并提供了丰富的参数控制文件存储和访问方式。
5+
`/api/upload-direct` 接口提供了一种简单高效的方式，可以将文件直接上传到后端配置的对象存储（如 S3 兼容存储、WebDAV 等具备写入能力的存储驱动）。该接口支持多种认证方式，并提供了丰富的参数控制文件存储和访问方式。
66

77
## 请求方法
88

9-
- **HTTP 方法**: `PUT`
9+
- **HTTP 方法**: `PUT`
1010

1111
## URL 格式
1212

@@ -22,18 +22,19 @@ https://{域名}/api/upload-direct/{filename}
2222

2323
以下查询参数可以附加到请求 URL 中:
2424

25-
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
26-
| ----------------- | ------ | ---- | -------- | ------------------------------------------------------------------------------------------- |
27-
| slug | string | 否 | 自动生成 | 自定义短链接，用于访问文件。只能包含字母、数字、下划线和横杠。 |
28-
| path | string | 否 | 空 | 自定义路径，文件将存储在这个路径下。如果提供，会自动添加斜杠作为目录路径。 |
29-
| storage_config_id | string | 否 | 默认配置 | 指定存储配置 ID。若不提供，系统选择默认配置（API 密钥用户仅可使用公开配置）。 |
30-
| expires_in | number | 否 | 0 | 文件过期时间（小时）。0 表示永不过期。 |
31-
| max_views | number | 否 | 0 | 文件最大查看次数。0 表示无限制。 |
32-
| remark | string | 否 | 空 | 文件备注信息。 |
33-
| password | string | 否 | 空 | 访问密码，设置后需要密码才能访问文件。 |
34-
| use_proxy | string | 否 | 0 | 是否使用代理访问。默认直链（0），传 "1" 可强制走代理。 |
35-
| override | string | 否 | "false" | 是否覆盖同名 slug 的已存在文件。"true"表示覆盖，"false"表示不覆盖。只能覆盖自己创建的文件。 |
36-
| original_filename | string | 否 | "false" | 是否使用原始文件名存储。"true"表示使用原始文件名，"false"表示添加随机前缀。 |
25+
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
26+
| ----------------- | ------ | ---- | ------------ | -------------------------------------------------------------------------------------------------------- |
27+
| slug | string | 否 | 自动生成 | 自定义短链接，用于访问文件。只能包含字母、数字、下划线和横杠。 |
28+
| path | string | 否 | 空 | 自定义路径，文件将存储在这个路径下。如果提供，会自动添加斜杠作为目录路径。 |
29+
| storage_config_id | string | 否 | 默认配置 | 指定存储配置 ID。若不提供，系统选择默认配置（API 密钥用户仅可使用公开配置）。 |
30+
| expires_in | number | 否 | 0 | 文件过期时间（小时）。0 表示永不过期。 |
31+
| max_views | number | 否 | 0 | 文件最大查看次数。0 表示无限制。 |
32+
| remark | string | 否 | 空 | 文件备注信息。 |
33+
| password | string | 否 | 空 | 访问密码。设置后文件在公共接口中需要密码才能访问；upload-direct 响应中始终返回 rawUrl，便于受信任端使用。 |
34+
| use_proxy | string | 否 | 系统设置 | 是否使用代理访问。未提供时按系统设置 `default_use_proxy` 决定（默认直链），传 "1" 强制代理，传 "0" 强制直链。 |
35+
| override | string | 否 | "false" | 是否覆盖同名 slug 的已存在文件。"true"表示覆盖，"false"表示不覆盖。只能覆盖自己创建的文件。 |
36+
| original_filename | string | 否 | "false" | 是否标记使用原始文件名。直传场景下具体命名仍由系统策略决定，此参数主要作为元数据标记。 |
37+
| upload_id | string | 否 | 空 | 上传会话 ID，用于支持续传/分片等能力的存储驱动复用同一上传会话。 |
3738

3839
## 请求头
3940

@@ -70,23 +71,15 @@ https://{域名}/api/upload-direct/{filename}
7071
"max_views": null, // 最大查看次数限制
7172
"expires_at": null, // 过期时间
7273

73-
// 主要访问URL（根据use_proxy参数决定使用代理还是直接URL）
74-
"previewUrl": "https://...", // 预览URL
75-
"downloadUrl": "https://...", // 下载URL
76-
// 当 use_proxy=0 时，previewUrl/downloadUrl 为直链；use_proxy=1 则返回代理端点
77-
"proxy_preview_url": "https://...", // 代理预览URL（总是可用）
78-
"proxy_download_url": "https://...", // 代理下载URL（总是可用）
79-
80-
// 其他信息
74+
"rawUrl": "https://cdn.example.com/file/abcd12", // 最终可对外访问的 URL（直链或基于 `/api/s/:slug` 的代理 URL）
75+
"linkType": "direct", // "direct" | "proxy"
8176
"use_proxy": 1, // 是否使用代理 (1=代理, 0=直接)
82-
"created_by": "admin:1", // 创建者信息 (admin:ID 或 apikey:ID)
83-
"used_original_filename": true // 是否使用了原始文件名
77+
"created_by": "admin:1" // 创建者信息 (admin:ID 或 apikey:ID)
8478
},
8579
"success": true
8680
}
8781
```
8882

89-
> **注意**: 当上传时设置了`password`参数，返回的**代理访问 URL**（proxy_preview_url 和 proxy_download_url）将自动包含密码参数，使用户能够直接通过这些链接访问受密码保护的文件，而无需再次输入密码。公共直链（publicUrl）为预签名 URL，不包含密码参数。
9083

9184
## 授权方式
9285

@@ -177,11 +170,12 @@ curl -X PUT "https://your-domain.com/api/upload-direct/important-document.docx?o
177170

178171
## 注意事项
179172

180-
1. **预签名 URL**: 返回的直接访问 URL 是预签名的，有效期根据 S3 配置的`signature_expires_in`设置，默认为 1 小时。
181-
2. **MIME 类型**: 如果未提供 Content-Type 或提供了通用类型(application/octet-stream)，系统会根据文件扩展名推断 MIME 类型。
182-
3. **S3 服务商兼容性**: 系统针对不同 S3 服务商(如 AWS S3、Backblaze B2、Cloudflare R2)进行了特殊处理，确保上传过程的兼容性。
183-
4. **文件覆盖**: 使用`override=true`参数可以覆盖已存在的同名 slug 文件。只能覆盖自己创建的文件，覆盖过程会删除旧文件并上传新文件，保持相同的访问链接。
184-
5. **原始文件名**: 使用`original_filename=true`参数时，系统将使用原始文件名存储文件，不添加随机前缀。
185-
6. **存储空间限制**: 系统会检查 S3 配置的存储空间限制，如果上传后会超出限制则拒绝上传。
186-
7. **权限控制**: API 密钥用户只能使用公开的 S3 配置，管理员可以使用自己创建的所有配置。
187-
8. **路径处理**: 如果提供了自定义路径，系统会自动添加斜杠确保作为目录路径处理。
173+
1. **流式上传**: 后端统一使用流式上传管线（`uploadStream`），支持大文件和长链接上传，不需要一次性将文件读入内存。
174+
2. **预签名 URL**: 返回的直接访问 URL 是预签名的，有效期由存储配置的 `signature_expires_in` 设置，默认为 1 小时（具体取决于存储类型与配置）。
175+
3. **MIME 类型**: 如果未提供 Content-Type 或提供了通用类型（`application/octet-stream`），系统会根据文件扩展名推断 MIME 类型。
176+
4. **多存储支持**: 只要存储驱动具备写入能力（WRITER）且支持流式上传（`uploadStream`），即可通过此接口完成直传。目前支持 S3 兼容对象存储、WebDAV 等。
177+
5. **文件覆盖**: 使用 `override=true` 参数可以覆盖已存在的同名 slug 文件。只能覆盖自己创建的文件，覆盖过程会删除旧文件并上传新文件，保持相同访问链接。
178+
6. **原始文件名**: 使用 `original_filename=true` 参数时，系统将使用原始文件名存储文件，不添加随机前缀。
179+
7. **存储空间限制**: 系统会检查存储配置的配额，如果上传后会超出限制则拒绝上传。
180+
8. **权限控制**: API 密钥用户只能使用公开的存储配置，管理员可以使用自己创建的所有配置。
181+
9. **路径处理**: 如果提供了自定义路径，系统会自动添加斜杠确保作为目录路径处理。

0 commit comments

Comments
 (0)