Add media proxy feature for resource downloading

- Introduced a new API endpoint `GET /api/v1/video/proxy` to facilitate media resource downloads, allowing users to bypass domain restrictions imposed by WeChat. - Updated configuration to include proxy settings such as `SHORT_VIDEO_PROXY_ENABLED`, `SHORT_VIDEO_PROXY_ALLOWED_DOMAINS`, `SHORT_VIDEO_PROXY_MAX_SIZE_MB`, and `SHORT_VIDEO_PROXY_TIMEOUT_SECONDS`. - Enhanced the `ShortVideoConfig` struct to accommodate new proxy-related fields. - Improved error handling for proxy requests, including checks for allowed domains and file size limits. - Updated documentation to reflect the new proxy functionality and its configuration options, ensuring clarity for users and developers.
2026-02-06 11:28:02 +00:00
parent 9200600b1c
commit 1b8ff310eb
7 changed files with 1049 additions and 3 deletions
@@ -121,3 +121,104 @@ curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark/unlock' \
 | `userAgent` | string，可选 | 报告端的 UA，默认取 HTTP 头 |

 服务端会额外记录请求来源 IP（`client_ip`），并存入 `video_download_failures` 表，便于后续排查白名单或 CDN 问题。
+
+## 6. 媒体代理下载
+
+`GET /api/v1/video/proxy`
+
+该接口用于代理媒体资源（视频/图片等）的下载，使小程序可以通过当前服务域名下载资源，避免微信对第三方域名的限制。
+
+| 项目 | 说明 |
+| --- | --- |
+| Header | 无需鉴权 |
+| Query 参数 | `url` - 需要代理的原始媒体地址（必填，需 URL 编码） |
+| 响应 | 流式返回原始媒体内容，Content-Type 与源文件一致 |
+
+curl 示例：
+
+```bash
+# 代理视频下载
+curl -L 'http://127.0.0.1:8080/api/v1/video/proxy?url=https%3A%2F%2Fexample.com%2Fvideo.mp4' \
+  -o video.mp4
+
+# 代理图片下载
+curl -L 'http://127.0.0.1:8080/api/v1/video/proxy?url=https%3A%2F%2Fexample.com%2Fcover.jpg' \
+  -o cover.jpg
+```
+
+小程序端使用示例：
+
+```javascript
+// 使用 wx.downloadFile 下载
+const proxyUrl = 'https://your-domain.com/api/v1/video/proxy';
+const originalUrl = 'https://cdn.example.com/video.mp4';
+
+wx.downloadFile({
+  url: `${proxyUrl}?url=${encodeURIComponent(originalUrl)}`,
+  success(res) {
+    if (res.statusCode === 200) {
+      // 下载成功，res.tempFilePath 为临时文件路径
+      wx.saveVideoToPhotosAlbum({
+        filePath: res.tempFilePath,
+        success() {
+          wx.showToast({ title: '保存成功' });
+        }
+      });
+    }
+  },
+  fail(err) {
+    console.error('下载失败', err);
+  }
+});
+```
+
+**成功响应**
+
+- HTTP 状态码：200
+- Content-Type：与源文件一致（如 `video/mp4`、`image/jpeg`）
+- Body：媒体文件二进制流
+
+**错误返回**
+
+| HTTP 码 | code | message | 说明 |
+| --- | --- | --- | --- |
+| 400 | 400 | `请求参数错误，缺少 url 参数` | 未传 `url` 参数 |
+| 400 | 400 | `无效的代理地址` | URL 格式不正确或协议不支持 |
+| 403 | 403 | `该域名不在允许列表中` | 目标域名未在白名单内 |
+| 413 | 413 | `文件过大，超出限制` | 文件大小超过配置的最大值 |
+| 502 | 502 | `上游服务返回错误` | 源服务器返回非 2xx 状态码 |
+| 503 | 503 | `代理服务未启用` | 代理功能被禁用 |
+| 500 | 500 | `代理请求失败` | 其他内部错误 |
+
+**配置项**
+
+可通过环境变量配置代理行为：
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `SHORT_VIDEO_PROXY_ENABLED` | `true` | 是否启用代理功能 |
+| `SHORT_VIDEO_PROXY_ALLOWED_DOMAINS` | 空（允许所有） | 允许代理的域名白名单，多个用逗号分隔 |
+| `SHORT_VIDEO_PROXY_MAX_SIZE_MB` | `100` | 代理文件最大大小（MB） |
+| `SHORT_VIDEO_PROXY_TIMEOUT_SECONDS` | `60` | 代理请求超时时间（秒） |
+
+配置示例（`.env`）：
+
+```bash
+# 启用代理
+SHORT_VIDEO_PROXY_ENABLED=true
+
+# 限制只能代理特定域名（安全推荐）
+SHORT_VIDEO_PROXY_ALLOWED_DOMAINS=cdn.example.com,video.example.com,aweme.snssdk.com
+
+# 最大文件 200MB
+SHORT_VIDEO_PROXY_MAX_SIZE_MB=200
+
+# 超时 120 秒
+SHORT_VIDEO_PROXY_TIMEOUT_SECONDS=120
+```
+
+**安全建议**
+
+1. **配置域名白名单**：强烈建议配置 `SHORT_VIDEO_PROXY_ALLOWED_DOMAINS`，只允许代理已知的 CDN 域名，防止被滥用为开放代理。
+2. **设置合理的文件大小限制**：根据实际需求设置 `SHORT_VIDEO_PROXY_MAX_SIZE_MB`，避免服务器带宽被大文件消耗。
+3. **监控带宽使用**：代理功能会消耗服务器带宽，建议监控流量并设置告警。