资源代理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /proxy | 代理外部资源 |
GET | /proxy/transcode | 代理并实时转码外部音频 |
PUT | /settings/proxy-private-allowlist | 更新私网代理白名单 |
GET | /settings/proxy-private-allowlist | 获取私网代理白名单 |
GET /proxy
代理外部资源
代理外部资源（图片、音频、视频流等），解决浏览器 CORS 限制。支持流式转发、Range 请求透传、Content-Type 透传和域名白名单校验
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 目标资源的 URL（URL 编码） |
响应
200 - 代理的资源内容
类型： file
206 - 部分内容（Range 请求）
类型： file
400 - 缺少 url 参数或 URL 无效
类型： map[string]string
403 - 域名不在白名单中
类型： map[string]string
502 - 上游请求失败
类型： map[string]string
内容类型
- 响应：
application/octet-stream
GET /proxy/transcode
代理并实时转码外部音频
服务端拉取远程音频 URL，经 ffmpeg 实时转码为 mp3（CBR 320k）后流式返回。用于「不入库直接播放」场景下，外部搜索源返回 webm/opus 等音箱无法解码的直链：客户端把该端点 URL 推给音箱即可播放。复用 /settings/proxy-private-allowlist 做 SSRF 防护；不落盘、不入库、不缓存。ffmpeg 直拉远程 URL，低首字节延迟；并发与 seek/均衡流共享 cap=4，满则 503。ffmpeg 缺失或上游不可解码时返回 503。
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 目标音频 URL（URL 编码） |
format | string | 否 | 目标格式，目前仅 mp3 可选值: mp3 |
bitrate | integer | 否 | 目标码率 kbps，默认 320 |
duration | number | 否 | 音频时长（秒），用于设置硬超时；未知可不传 |
user_agent | string | 否 | 拉流 User-Agent，缺省用浏览器 UA |
referer | string | 否 | 拉流 Referer |
响应
200 - 转码后的 mp3 音频流
类型： file
400 - 缺少 url 或 URL 无效
类型： map[string]string
403 - 域名不在白名单
类型： map[string]string
503 - 转码服务未配置 / 并发已满 / ffmpeg 缺失或上游不可解码
类型： map[string]string
内容类型
- 响应：
application/octet-stream
PUT /settings/proxy-private-allowlist
更新私网代理白名单
覆盖式更新私网代理白名单。每条须为单个 IP（IPv4/IPv6）或 CIDR 网段；空白条目自动忽略。任一条目非法返回 400。设置后，目标解析到的私网地址若被白名单覆盖，/proxy 即放行（用于「公网 Songloft 代理内网 WebDAV」等场景）。
需要认证
此接口需要 Bearer Token 认证
请求体
白名单条目列表（IP 或 CIDR）
类型： proxyAllowlistSettingRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
allowlist | string[] | 否 |
响应
200 - 返回更新后的白名单
类型： proxyAllowlistSettingRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
allowlist | string[] | 否 |
400 - 请求格式错误或含非法条目
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/proxy-private-allowlist
获取私网代理白名单
获取「允许 /proxy 代理的私网地址」白名单。默认空数组：私网 / 回环 / 链路本地地址一律拒绝（SSRF 防护）。每条为单个 IP（如 192.168.1.100）或 CIDR 网段（如 192.168.1.0/24）。仅影响通用 /proxy 端点，不影响 HLS 反代。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 返回 allowlist 字段，当前白名单条目列表
类型： proxyAllowlistSettingRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
allowlist | string[] | 否 |
内容类型
- 响应：
application/json