wx_service/docs/common/upload_qiniu.md

七牛（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

请求体（可选）：

{
  "filename": "avatar.png"
}

说明：

• filename 仅用于提取文件后缀（例如 .png），以便后端生成带后缀的 key；不传也可以。

成功响应示例：

{
  "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：

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）：

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 调整）：

key=$(key)&hash=$(etag)&fsize=$(fsize)&mimeType=$(mimeType)

失败重试策略

• 当前策略：
  • 验签失败：401（不可信请求，不重试）
  • 参数错误：400（请求无效，不重试）
  • 临时失败：503（可重试）
• 建议在回调处理中保证幂等（例如按 key 去重），避免重复消费。