hello-dd-code
108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
# 七牛（Kodo）直传：获取上传凭证
|
||
|
||
用途：小程序/前端把文件直接上传到七牛（CDN 源站），后端只负责签发上传 token，减少带宽与压力。
|
||
|
||
## 前置条件
|
||
|
||
- 已完成登录并拿到 `session_key`（见：`docs/common/auth.md`）
|
||
- 已配置 `.env` 中的七牛参数（见：`.env.example`）
|
||
- 若需要上传成功回调，请额外配置：
|
||
- `QINIU_CALLBACK_URL`（例如：`https://api.example.com/api/v1/common/upload/qiniu/callback`）
|
||
- `QINIU_CALLBACK_BODY`
|
||
- `QINIU_CALLBACK_BODY_TYPE`
|
||
|
||
## 接口
|
||
|
||
`POST /api/v1/common/upload/qiniu/token`
|
||
|
||
Header：
|
||
|
||
```
|
||
Authorization: Bearer <session_key>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求体（可选）：
|
||
|
||
```json
|
||
{
|
||
"filename": "avatar.png"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- `filename` 仅用于提取文件后缀（例如 `.png`），以便后端生成带后缀的 `key`；不传也可以。
|
||
|
||
成功响应示例：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"token": "xxx",
|
||
"key": "uploads/mp_1/user_123/20251231/ab12cd34ef....png",
|
||
"upload_url": "https://upload.qiniup.com",
|
||
"expire": 1767150000,
|
||
"cdn_domain": "https://cdn.example.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `token`：七牛上传凭证（uptoken）
|
||
- `key`：后端生成的对象 key，上传时必须使用该 key
|
||
- `upload_url`：上传入口（表单上传 URL）
|
||
- `expire`：token 过期时间（Unix 秒）
|
||
- `cdn_domain`：可选；如果配置了，可用 `cdn_domain + "/" + key` 拼出访问 URL
|
||
|
||
## 使用示例（curl 直传）
|
||
|
||
1) 先请求 token：
|
||
|
||
```bash
|
||
curl -X POST 'http://127.0.0.1:8080/api/v1/common/upload/qiniu/token' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer wx-session-key' \
|
||
-d '{"filename":"avatar.png"}'
|
||
```
|
||
|
||
2) 再把文件直传七牛（multipart/form-data）：
|
||
|
||
```bash
|
||
curl -X POST 'https://upload.qiniup.com' \
|
||
-F "token=上一步返回的 token" \
|
||
-F "key=上一步返回的 key" \
|
||
-F "file=@./avatar.png"
|
||
```
|
||
|
||
七牛成功时会返回 JSON（字段可能因配置不同略有差异），其中一般会包含 `key/hash`。
|
||
|
||
---
|
||
|
||
## 上传回调（服务端）
|
||
|
||
当配置了 `QINIU_CALLBACK_URL` 后，后端签发的 putPolicy 会包含 callback 参数。七牛上传成功后会回调：
|
||
|
||
`POST /api/v1/common/upload/qiniu/callback`
|
||
|
||
说明：
|
||
- 该接口无需登录（由七牛服务端调用）。
|
||
- 服务端会校验 `Authorization: QBox ...` 签名。
|
||
- 验签失败返回 `401`，直接拒绝。
|
||
- 当业务处理发生临时异常时可返回 `503`，利用七牛回调重试机制重试。
|
||
|
||
默认回调体（可通过 `QINIU_CALLBACK_BODY` 调整）：
|
||
|
||
```txt
|
||
key=$(key)&hash=$(etag)&fsize=$(fsize)&mimeType=$(mimeType)
|
||
```
|
||
|
||
### 失败重试策略
|
||
|
||
- 当前策略：
|
||
- 验签失败：`401`（不可信请求，不重试）
|
||
- 参数错误：`400`（请求无效，不重试）
|
||
- 临时失败：`503`（可重试）
|
||
- 建议在回调处理中保证幂等（例如按 `key` 去重），避免重复消费。
|