nepiedg
1eab1b99c1
- Rename all QINIU_* config/code/docs to OSS_* to match actual Alibaba Cloud OSS - Refactor upload module from internal/common/qiniu to internal/common/upload - Add backend proxy upload endpoint (POST /api/admin/marketing/upload) to avoid CORS - Auto-generate compressed thumbnail (800px, JPEG 80%) on admin image upload - Add dev-login endpoint (POST /api/v1/auth/dev-login) for H5 debugging - Add imageutil package for server-side image resizing Made-with: Cursor
112 lines
2.9 KiB
Markdown
112 lines
2.9 KiB
Markdown
# 阿里云 OSS 直传：获取上传凭证
|
||
|
||
用途：小程序/前端把文件直接上传到阿里云 OSS，后端只负责签发上传凭证，减少带宽与压力。
|
||
|
||
## 前置条件
|
||
|
||
- 已完成登录并拿到 `session_key`（见：`docs/common/auth.md`）
|
||
- 已配置 `.env` 中的 OSS 参数（见：`.env.example`）
|
||
- 若需要上传成功回调，请额外配置：
|
||
- `OSS_CALLBACK_URL`（例如：`https://api.example.com/api/v1/common/upload/oss/callback`）
|
||
- `OSS_CALLBACK_BODY`
|
||
- `OSS_CALLBACK_BODY_TYPE`
|
||
|
||
## 接口
|
||
|
||
`POST /api/v1/common/upload/oss/token`
|
||
|
||
Header：
|
||
|
||
```
|
||
Authorization: Bearer <session_key>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求体（可选）：
|
||
|
||
```json
|
||
{
|
||
"filename": "avatar.png"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- `filename` 仅用于提取文件后缀（例如 `.png`），以便后端生成带后缀的 `key`；不传也可以。
|
||
|
||
成功响应示例（OSS PostObject 凭证）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"key": "uploads/mp_1/user_123/20251231/ab12cd34....png",
|
||
"upload_url": "https://bucket.oss-cn-beijing.aliyuncs.com",
|
||
"cdn_domain": "https://bucket.oss-cn-beijing.aliyuncs.com",
|
||
"oss_access_key_id": "LTAI5t...",
|
||
"oss_policy": "base64...",
|
||
"oss_signature": "sig..."
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `key`：后端生成的对象 key，上传时必须使用该 key
|
||
- `upload_url`：OSS PostObject 上传地址
|
||
- `cdn_domain`：CDN 访问域名，可用 `cdn_domain + "/" + key` 拼出访问 URL
|
||
- `oss_access_key_id`：OSS AccessKeyId
|
||
- `oss_policy`：Base64 编码的 Policy
|
||
- `oss_signature`：HMAC-SHA1 签名
|
||
|
||
## 使用示例（curl 直传）
|
||
|
||
1) 先请求凭证：
|
||
|
||
```bash
|
||
curl -X POST 'http://127.0.0.1:8080/api/v1/common/upload/oss/token' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer wx-session-key' \
|
||
-d '{"filename":"avatar.png"}'
|
||
```
|
||
|
||
2) 再把文件直传 OSS（multipart/form-data）：
|
||
|
||
```bash
|
||
curl -X POST '<upload_url>' \
|
||
-F "key=<上一步返回的 key>" \
|
||
-F "policy=<oss_policy>" \
|
||
-F "OSSAccessKeyId=<oss_access_key_id>" \
|
||
-F "Signature=<oss_signature>" \
|
||
-F "file=@./avatar.png"
|
||
```
|
||
|
||
OSS 成功时返回 HTTP 204（无 body）。
|
||
|
||
---
|
||
|
||
## 上传回调（服务端）
|
||
|
||
当配置了 `OSS_CALLBACK_URL` 后，上传成功后会回调：
|
||
|
||
`POST /api/v1/common/upload/oss/callback`
|
||
|
||
说明：
|
||
- 该接口无需登录（由 OSS 服务端调用）。
|
||
- 服务端会校验 `Authorization` 签名。
|
||
- 验签失败返回 `401`，直接拒绝。
|
||
- 当业务处理发生临时异常时可返回 `503`，利用回调重试机制重试。
|
||
|
||
默认回调体（可通过 `OSS_CALLBACK_BODY` 调整）：
|
||
|
||
```txt
|
||
key=$(key)&hash=$(etag)&fsize=$(fsize)&mimeType=$(mimeType)
|
||
```
|
||
|
||
### 失败重试策略
|
||
|
||
- 当前策略：
|
||
- 验签失败：`401`（不可信请求，不重试）
|
||
- 参数错误：`400`（请求无效，不重试）
|
||
- 临时失败：`503`（可重试）
|
||
- 建议在回调处理中保证幂等（例如按 `key` 去重），避免重复消费。
|