系统升级
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
PUT | /settings/github-proxy | 保存 GitHub 更新代理配置 |
GET | /settings/github-proxy | 获取 GitHub 更新代理配置 |
GET | /upgrade/check | 检查更新 |
GET | /upgrade/progress | 获取升级进度 |
POST | /upgrade/reset | 回退到底包版本 |
POST | /upgrade/start | 开始升级 |
POST | /upgrade/upload | 上传二进制文件升级 |
POST | /upgrade/upload/confirm | 确认执行上传升级 |
GET | /upgrade/versions | 获取可用版本信息 |
PUT /settings/github-proxy
保存 GitHub 更新代理配置
设置检查更新 / 升级使用的 GitHub 代理前缀（如 https://ghfast.top/）。设为空字符串则直连。仅持久化，不影响其它模块的全局 HTTP 代理。
需要认证
此接口需要 Bearer Token 认证
请求体
GitHub 更新代理配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
proxy | string | 否 |
响应
200 - 保存后的配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
proxy | string | 否 |
400 - 请求格式错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 保存配置失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/github-proxy
获取 GitHub 更新代理配置
获取检查更新 / 升级时使用的 GitHub 代理前缀（如 https://ghfast.top/）。前端会记住上次使用的代理并在检查更新时自动带上。未配置时返回空字符串（直连）。
需要认证
此接口需要 Bearer Token 认证
响应
200 - GitHub 更新代理配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
proxy | string | 否 |
内容类型
- 响应：
application/json
GET /upgrade/check
检查更新
检查是否有可用的新版本
需要认证
此接口需要 Bearer Token 认证
响应
200 - 成功返回更新检查结果
类型： map[string]any
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 检查更新失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
GET /upgrade/progress
获取升级进度
获取当前升级任务的进度信息
需要认证
此接口需要 Bearer Token 认证
响应
200 - 成功返回升级进度
类型： UpgradeProgress
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
current_step | string | 否 | 当前步骤描述 示例: "正在下载新版本..." |
error | string | 否 | 错误信息（如有） 示例: "下载失败" |
progress | integer | 否 | 进度百分比 (0-100) 示例: 50 |
status | string | 否 | 状态 可选值: idle, downloading, testing, replacing, restarting, completed, failed 示例: "downloading" |
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
POST /upgrade/reset
回退到底包版本
将二进制文件回退到 Docker 镜像中的原始版本，然后重启服务
需要认证
此接口需要 Bearer Token 认证
响应
200 - 回退已开始
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
403 - 非 Docker 环境不支持回退
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
POST /upgrade/start
开始升级
开始升级到指定版本
需要认证
此接口需要 Bearer Token 认证
请求体
升级请求 {version_type: stable|dev}
类型： map[string]string
响应
200 - 升级已开始
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
400 - 请求参数错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 升级失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
POST /upgrade/upload
上传二进制文件升级
上传 Songloft 二进制文件进行离线升级。上传后验证文件可执行并提取版本信息返回给前端，由前端判断是否需要二次确认（如跨通道升级）。确认后调用 /upgrade/upload/confirm 执行实际替换。
需要认证
此接口需要 Bearer Token 认证
表单参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | Songloft 二进制文件 |
响应
200 - 上传文件的版本信息
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
build_time | string | 否 | 上传文件的构建时间 示例: "2026-08-01" |
build_type | string | 否 | 上传文件的构建类型（full/lite） 示例: "full" |
channel | string | 否 | 上传文件的通道（stable/dev） 示例: "stable" |
channel_mismatch | boolean | 否 | 通道是否不匹配（需前端二次确认） 示例: true |
current_channel | string | 否 | 当前运行通道 示例: "dev" |
current_version | string | 否 | 当前运行版本 示例: "v2.10.0" |
version | string | 否 | 上传文件的版本号 示例: "v2.11.0" |
400 - 请求参数错误或文件无效
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 保存或验证文件失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
multipart/form-data - 响应：
application/json
POST /upgrade/upload/confirm
确认执行上传升级
确认对已上传的二进制文件执行升级替换。前端在收到 /upgrade/upload 响应后，若需要二次确认（如跨通道），用户确认后调用此接口。升级进度通过 /upgrade/progress 轮询。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 升级已开始
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
400 - 未找到已上传的升级文件
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json
GET /upgrade/versions
获取可用版本信息
获取正式版和测试版的版本信息
需要认证
此接口需要 Bearer Token 认证
响应
200 - 成功返回版本信息
类型： map[string]any
403 - 非 Docker 环境不支持升级
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 获取版本信息失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json