mirror of
https://github.com/truewhile/MeBox.git
synced 2026-09-28 11:16:37 +08:00
Compare commits
26 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 github-actions[bot]
|
1b06a01603 | ||
|
truewhile
|
fe407caf9e | ||
|
github-actions[bot]
|
ae02c14d27 | ||
|
truewhile
|
5404e7773f | ||
|
github-actions[bot]
|
a368110e60 | ||
|
truewhile
|
0e9fb2c937 | ||
|
github-actions[bot]
|
d00b14df55 | ||
|
truewhile
|
1407b9b5c4 | ||
|
github-actions[bot]
|
7fa05391e1 | ||
|
truewhile
|
4790f7753e | ||
|
github-actions[bot]
|
a311438aa1 | ||
|
truewhile
|
203abd106a | ||
|
github-actions[bot]
|
cc40169616 | ||
|
truewhile
|
cd720ae879 | ||
|
github-actions[bot]
|
fc84291346 | ||
|
truewhile
|
c37e936f48 | ||
|
github-actions[bot]
|
389cb99bcf | ||
|
truewhile
|
1b611a6181 | ||
|
github-actions[bot]
|
25c03f2b0d | ||
|
truewhile
|
a56b1801f9 | ||
|
github-actions[bot]
|
99c755dc29 | ||
|
truewhile
|
086c0307c3 | ||
|
github-actions[bot]
|
51d0f5010e | ||
|
truewhile
|
b9dd09a5d2 | ||
|
github-actions[bot]
|
e79f393969 | ||
|
truewhile
|
e422ecce53 |
@@ -0,0 +1,96 @@
|
||||
## 删除用户云下载任务
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 删除用户云下载任务 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /del_task |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
删除当前授权用户的指定云下载任务，可选择同时删除对应源文件。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/del_task
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------------|:-------|:-----|:-------|:---------------------------|:-------------|
|
||||
| info_hash | string | 是 | - | 需删除的任务Hash | `<info_hash>` |
|
||||
| del_source_file | int | 否 | 0 | 是否删除源文件，1=删除 0=不删除 | 0 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/del_task' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--form-string 'info_hash=<info_hash>' \
|
||||
--form-string 'del_source_file=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:--------|:----------------------|
|
||||
| state | boolean | 操作结果状态 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 返回数据，成功时为空数组 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:---------|:-------------------------|
|
||||
| 990002 | 参数错误 | 检查 `info_hash` 参数 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 未传 `del_source_file` 时默认不删除源文件。
|
||||
- `del_source_file=1` 会删除任务对应的源文件，操作前需确认影响范围。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 删除结果以响应中的 `state`、`code` 和 `message` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,111 @@
|
||||
## 添加云下载BT任务
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 添加云下载BT任务 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /add_task_bt |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据已解析的BT种子信息添加云下载BT任务。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/add_task_bt
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------------|:-------|:-----|:-------|:----------------------------------|:----------------|
|
||||
| info_hash | string | 是 | - | BT任务Hash | `<info_hash>` |
|
||||
| wanted | string | 是 | - | 选中下载的文件索引，使用半角逗号分隔 | `<file_indexes>` |
|
||||
| save_path | string | 是 | - | BT任务文件保存路径 | `A/B` |
|
||||
| torrent_sha1 | string | 是 | - | BT种子SHA1 | `<torrent_sha1>` |
|
||||
| pick_code | string | 是 | - | BT种子文件提取码 | `<pick_code>` |
|
||||
| wp_path_id | string | 否 | 0 | 保存目标文件夹ID | 0 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/add_task_bt' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--form-string 'info_hash=<info_hash>' \
|
||||
--form-string 'wanted=<file_indexes>' \
|
||||
--form-string 'save_path=A/B' \
|
||||
--form-string 'torrent_sha1=<torrent_sha1>' \
|
||||
--form-string 'pick_code=<pick_code>' \
|
||||
--form-string 'wp_path_id=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:--------|:----------------------|
|
||||
| state | boolean | 操作结果状态 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 返回数据，成功时为空数组 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:--------|:---------------------|:-------------------------------|
|
||||
| 20018 | 文件不存在或已删除 | 检查提取码、文件归属和种子SHA1 |
|
||||
| 91006 | 存储空间不足 | 扩充存储空间后重试 |
|
||||
| 990002 | 参数错误 | 检查必填参数 |
|
||||
| 1000012 | 云下载配额已用完 | 购买配额或获得更多配额后重试 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- `wanted` 可以为 `0`，但不能是空字符串。
|
||||
- 种子文件需属于当前授权用户、位于指定存储区域，并且文件SHA1与 `torrent_sha1` 一致。
|
||||
- 不传 `wp_path_id` 时默认保存到根目录；`save_path` 是相对于 `wp_path_id` 所在文件夹的路径。例如，`wp_path_id` 不传或传云下载文件夹ID且 `save_path=A/B` 时，最终路径为根目录下的 `A/B/`。
|
||||
- 添加任务前会检查当前授权账号的剩余存储空间；空间不足时不扣减云下载配额。
|
||||
- 云下载服务返回状态码 `10007` 或 `10010` 时，接口统一返回错误码 `1000012`。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
- 种子文件必须属于当前授权账号，并且文件SHA1与 `torrent_sha1` 一致。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 任务处理结果以响应中的 `data` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,115 @@
|
||||
## 添加云下载链接任务
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 添加云下载链接任务 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /add_task_urls |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
批量添加云下载链接任务。多个链接使用换行符分隔，支持HTTP(S)、FTP、磁力链和电驴链接。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/add_task_urls
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-----------|:-------|:-----|:-------|:----------------------------------------|:----------------|
|
||||
| urls | string | 是 | - | 云下载链接，多个链接使用换行符分隔 | `<download_url>` |
|
||||
| wp_path_id | string | 否 | 0 | 保存目标文件夹ID；不传或传0时保存到根目录 | 0 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/add_task_urls' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--form-string 'urls=<download_url>' \
|
||||
--form-string 'wp_path_id=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-----------------|:---------|:-------------------------------|
|
||||
| state | boolean | 操作结果状态 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 各链接任务的添加结果 |
|
||||
| data[].state | boolean | 链接任务添加状态 |
|
||||
| data[].code | int | 链接任务状态码 |
|
||||
| data[].message | string | 链接任务状态描述 |
|
||||
| data[].info_hash | string | 链接任务SHA1，仅任务成功时返回 |
|
||||
| data[].url | string | 链接任务URL |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:--------|:---------------------------|:-----------------------------|
|
||||
| 91006 | 存储空间不足 | 扩充存储空间后重试 |
|
||||
| 980004 | 操作失败 | 稍后重试 |
|
||||
| 990002 | 参数错误 | 检查必填参数 |
|
||||
| 1000011 | 链接数量超过115个 | 将链接拆分为每批不超过115个 |
|
||||
| 1000012 | 云下载配额已用完 | 购买配额或获得更多配额后重试 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": [
|
||||
{
|
||||
"state": true,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"info_hash": "",
|
||||
"url": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 服务端按换行符拆分并清理链接，单次最多提交115个链接。
|
||||
- 添加任务前会检查当前授权账号的剩余存储空间；空间不足时不扣减云下载配额。
|
||||
- 云下载服务返回状态码 `10007` 或 `10010` 时，接口统一返回错误码 `1000012`。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
- 本接口限制单批链接数量，避免不受控的批量请求。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 任务处理结果以响应中的 `data` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,104 @@
|
||||
## 清空云下载任务
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 清空云下载任务 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /clear_task |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
按指定类型清空当前授权用户的云下载任务。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/clear_task
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------|:-----|:-----|:-------|:-----------------------|:----------|
|
||||
| flag | int | 是 | - | 清空任务类型，见下方枚举表格 | 1 |
|
||||
|
||||
#### 请求参数中的 flag 参数枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:---|:-----------------------------|:-----|
|
||||
| 0 | 清空已完成任务 | - |
|
||||
| 1 | 清空全部任务 | - |
|
||||
| 2 | 清空失败任务 | - |
|
||||
| 3 | 清空进行中任务 | - |
|
||||
| 4 | 清空已完成任务并删除对应源文件 | - |
|
||||
| 5 | 清空全部任务并删除对应源文件 | - |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/clear_task' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--form-string 'flag=1'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:--------|:-----------------|
|
||||
| state | boolean | 操作结果状态 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 返回数据，成功时为空数组 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:---------|:--------------------------|
|
||||
| 990002 | 参数错误 | 检查 `flag` 是否为0至5的整数 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- `flag=4` 或 `flag=5` 会同时删除对应源文件，操作前需确认清理范围。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 清空结果以响应中的 `state`、`code` 和 `message` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,101 @@
|
||||
## 获取云下载配额信息
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 获取云下载配额信息 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /get_quota_info |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取当前授权用户各类云下载配额的使用情况和过期明细。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/get_quota_info
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
无。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/get_quota_info' \
|
||||
-H 'Authorization: Bearer <access_token>'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------------------------------------------|:---------|:---------------------|
|
||||
| state | boolean | 状态，true表示成功 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 云下载配额数据 |
|
||||
| data.package | object[] | 配额类型列表 |
|
||||
| data.package[].surplus | int | 该类型剩余配额 |
|
||||
| data.package[].used | int | 该类型已用配额 |
|
||||
| data.package[].count | int | 该类型总配额 |
|
||||
| data.package[].name | string | 该类型配额名称 |
|
||||
| data.package[].expire_info | object[] | 该类型配额过期明细 |
|
||||
| data.package[].expire_info[].surplus | int | 明细项剩余配额 |
|
||||
| data.package[].expire_info[].expire_time | int | 明细项过期时间 |
|
||||
| data.count | int | 用户总配额数量 |
|
||||
| data.surplus | int | 用户总剩余配额数量 |
|
||||
| data.used | int | 用户总已用配额数量 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:---------|:-------------|
|
||||
| 990002 | 参数错误 | 检查授权信息 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"package": [],
|
||||
"count": 0,
|
||||
"surplus": 0,
|
||||
"used": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 云下载配额以响应中的 `data` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,136 @@
|
||||
## 获取用户云下载任务列表
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 获取用户云下载任务列表 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /get_task_list |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
分页获取当前授权用户的云下载任务列表。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/get_task_list
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------|:-----|:-----|:-------|:---------|:----------|
|
||||
| page | int | 否 | 1 | 页码 | 1 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/offline/get_task_list' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--data-urlencode 'page=1'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------------|:---------|:--------------------------------------|
|
||||
| state | boolean | 状态，true表示成功 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 分页任务数据 |
|
||||
| data.page | int | 当前页码 |
|
||||
| data.page_count | int | 总页数 |
|
||||
| data.count | int | 任务总数 |
|
||||
| data.tasks | object[] | 云下载任务列表 |
|
||||
| data.tasks[].info_hash | string | 任务SHA1 |
|
||||
| data.tasks[].add_time | int | 任务添加时间戳 |
|
||||
| data.tasks[].percentDone | int | 任务下载进度 |
|
||||
| data.tasks[].size | int | 任务总大小，单位为字节 |
|
||||
| data.tasks[].name | string | 任务名称 |
|
||||
| data.tasks[].last_update | int | 任务最后更新时间戳 |
|
||||
| data.tasks[].file_id | string | 任务源文件或文件夹ID |
|
||||
| data.tasks[].delete_file_id | string | 删除任务并删除源文件时需传递的文件或文件夹ID |
|
||||
| data.tasks[].status | int | 任务状态，见下方枚举表格 |
|
||||
| data.tasks[].url | string | 链接任务URL |
|
||||
| data.tasks[].wp_path_id | string | 任务源文件所在父文件夹ID |
|
||||
| data.tasks[].def2 | int | 视频清晰度，见下方枚举表格 |
|
||||
| data.tasks[].play_long | int | 视频时长 |
|
||||
| data.tasks[].can_appeal | int | 是否可以申诉 |
|
||||
|
||||
#### 响应的 data.tasks[].status 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:---|:---------|:-----|
|
||||
| -1 | 下载失败 | - |
|
||||
| 0 | 分配中 | - |
|
||||
| 1 | 下载中 | - |
|
||||
| 2 | 下载成功 | - |
|
||||
|
||||
#### 响应的 data.tasks[].def2 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:----|:------|:-----|
|
||||
| 1 | 标清 | - |
|
||||
| 2 | 高清 | - |
|
||||
| 3 | 超清 | - |
|
||||
| 4 | 1080P | - |
|
||||
| 5 | 4K | - |
|
||||
| 100 | 原画 | - |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:---------|:---------------|
|
||||
| 990002 | 参数错误 | 检查授权信息 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"page": 1,
|
||||
"page_count": 0,
|
||||
"count": 0,
|
||||
"tasks": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 未传 `page` 或参数值为空时，默认查询第1页。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
- 任务列表按 `page` 分页，实际返回数量以响应为准。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 云下载任务状态和字段以响应中的 `data` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,118 @@
|
||||
## 解析BT种子
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:----------------------------------|
|
||||
| 接口名称 | 解析BT种子 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /torrent |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
解析已上传的BT种子文件，返回种子任务信息和文件列表。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/offline/torrent
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------------|:-------|:-----|:-------|:---------------|:----------------|
|
||||
| torrent_sha1 | string | 是 | - | BT种子文件SHA1 | `<torrent_sha1>` |
|
||||
| pick_code | string | 是 | - | BT种子文件提取码 | `<pick_code>` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/offline/torrent' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--form-string 'torrent_sha1=<torrent_sha1>' \
|
||||
--form-string 'pick_code=<pick_code>'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------------------|:---------|:---------------------|
|
||||
| state | boolean | 状态，true表示成功 |
|
||||
| message | string | 返回信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 种子解析结果 |
|
||||
| data.file_size | int | 任务大小 |
|
||||
| data.torrent_name | string | 任务名称 |
|
||||
| data.file_count | int | 文件数量 |
|
||||
| data.info_hash | string | 任务SHA1 |
|
||||
| data.torrent_filelist | object[] | 文件列表 |
|
||||
| data.torrent_filelist[].size | int | 文件大小 |
|
||||
| data.torrent_filelist[].path | string | 文件路径 |
|
||||
| data.torrent_filelist[].wanted | int | 文件是否默认选中 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:---------------------|:---------------------------------|
|
||||
| 20018 | 文件不存在或已删除 | 检查提取码、文件归属和种子SHA1 |
|
||||
| 990002 | 参数错误 | 检查必填参数 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"file_size": 0,
|
||||
"torrent_name": "",
|
||||
"file_count": 0,
|
||||
"info_hash": "",
|
||||
"torrent_filelist": [
|
||||
{
|
||||
"size": 0,
|
||||
"path": "",
|
||||
"wanted": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 种子文件需属于当前授权用户、位于指定存储区域，并且文件SHA1与 `torrent_sha1` 一致。
|
||||
- 现有开放平台文档建议先将种子文件上传至“云下载/种子文件”文件夹，但该目录不是硬性要求。
|
||||
|
||||
### 性能与安全说明
|
||||
|
||||
- 用户身份由 Bearer access_token 解析，请求参数不能指定115账号。
|
||||
- 接口按应用、用户和接口维度执行频率限制。
|
||||
- 种子文件必须属于当前授权账号，并且文件SHA1与 `torrent_sha1` 一致。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 种子解析结果以响应中的 `data` 字段为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,172 @@
|
||||
## 开发者商业价值转化：推广产品得收益
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------|:--------------------|
|
||||
| 文档名称 | 开发者商业价值转化：推广产品得收益 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
## 一、简介
|
||||
|
||||
为帮助开发者实现商业价值转化，115生活开放平台推出“推广产品得收益”计划，通过“推广有奖、收益共享”的方式，与开发者共同构建可持续发展的开放生态。
|
||||
|
||||
开发者接入标准化服务接口后，可以在用户需要升级使用权限、扩充长期存储空间或增加云下载配额时，引导用户购买对应的 115 增值服务，并基于用户实际购买的产品获取相应推广收益。
|
||||
|
||||
## 二、服务形式说明
|
||||
|
||||
### 1. 标准化服务接口
|
||||
|
||||
标准化服务接口覆盖以下核心场景。
|
||||
|
||||
#### 1.1. VIP 服务
|
||||
|
||||
适用于用户对应功能使用权限不足的场景：
|
||||
|
||||
- 视频播放权限升级：解决非 VIP 用户不支持在线预览视频、年费VIP以下用户不支持视频 4K 超轻转码等权限限制。
|
||||
- 大文件上传权限升级：解决月费VIP以下用户不支持上传 115GB 大文件等权限限制。
|
||||
|
||||
开发者可以引导用户升级至更高的 VIP 类型，以获取对应使用权限。
|
||||
|
||||
#### 1.2. 长期存储空间扩容服务
|
||||
|
||||
适用于用户存储空间不足的场景，可解决因空间容量不足导致文件上传、复制及添加云下载失败等问题。
|
||||
|
||||
开发者可以引导用户购买 VIP 服务以获取更多长期存储空间，或单独购买长期存储空间进行扩容。
|
||||
|
||||
#### 1.3. 云下载配额
|
||||
|
||||
适用于用户云下载配额不足的场景，可解决因服务配额不足导致添加云下载失败等问题。
|
||||
|
||||
开发者可以引导用户升级至更高的 VIP 类型以获取更多云下载配额，或单独购买云下载配额。
|
||||
|
||||
### 2. 收益获取模式
|
||||
|
||||
用户通过开发者应用进入购买页面并成功购买以下任一服务产品后，开发者可以获得对应推广收益：
|
||||
|
||||
- 115生活 VIP 服务，包括月费VIP、年费VIP等。
|
||||
- 长期存储空间扩容。
|
||||
- 云下载配额。
|
||||
|
||||
VIP 服务购买页面示例：
|
||||
|
||||
|
||||
|
||||
长期存储空间扩容购买页面示例：
|
||||
|
||||
|
||||
|
||||
## 三、接入流程
|
||||
|
||||
### 1. 成为开发者
|
||||
|
||||
已成为 115 生活开发者的用户可以直接进行接口接入；未注册的开发者，请先参考[接入流程](../接入指南/接入流程.md)完成注册。
|
||||
|
||||
### 2. 接口接入
|
||||
|
||||
开发者可以调用“获取产品列表地址”接口取得购买页面地址，并在对应业务场景中引导用户访问。
|
||||
|
||||
#### 接口信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------|:------------|
|
||||
| 接口名称 | 获取产品列表地址 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /vip/qr_url |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于获取 115 生活开放平台增值服务产品列表地址。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/vip/qr_url
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------------------|:-------|:---|:-----|:---------------------------|:--------------------------------------------------------|
|
||||
| default_product_id | int | 否 | null | 打开产品列表时默认选中的产品 ID | 月费：`5`；年费：`1`；尝鲜 1 天：`101`；长期VIP(至尊版)：`24072401` |
|
||||
| open_device | string | 是 | - | 设备号 | `DEVICE_ID_PLACEHOLDER` |
|
||||
| hide_title | int | 否 | 0 | 是否隐藏购买页推荐人信息：0-不隐藏；1-隐藏 | `0` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/vip/qr_url' \
|
||||
-H 'Authorization: Bearer ACCESS_TOKEN_PLACEHOLDER' \
|
||||
--data-urlencode 'default_product_id=1' \
|
||||
--data-urlencode 'open_device=DEVICE_ID_PLACEHOLDER' \
|
||||
--data-urlencode 'hide_title=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------|:--------|:--------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 响应信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.qrcode_url | string | 开放平台产品列表地址 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"qrcode_url": "PRODUCT_LIST_URL_PLACEHOLDER"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 接口根据 `access_token` 识别授权信息，调用方无需额外传入 115 账号和 AppID。
|
||||
- `open_device` 不能为空；未传或传入空值时，接口返回参数错误。
|
||||
- `default_product_id` 未传或为空时，服务端不指定默认产品。
|
||||
- `hide_title` 大于 0 时，服务端会将该参数传递给产品列表服务。
|
||||
- `access_token` 属于敏感凭证，不得写入公开仓库、客户端日志或公开沟通内容。
|
||||
|
||||
### 3. 场景触发与收益
|
||||
|
||||
完成接口接入后，开发者可以在用户使用权限不足、长期存储空间不足或云下载配额不足时触发对应引导。用户完成购买后，开发者可以获得对应推广收益。
|
||||
|
||||
## 四、收益管理与结算
|
||||
|
||||
### 1. 收益查看与提现
|
||||
|
||||
开发者可以登录“115生活-生活-联盟”，或直接访问[115联盟](https://union.115.com/)，查看收益明细等推广收益情况并进行提现操作。
|
||||
|
||||
|
||||
|
||||
### 2. 规则说明
|
||||
|
||||
收益计算方式、结算方式和提现流程等详情，参见[联盟规则](https://union.115.com/?ac=help&i=10)。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----------------|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月05日(周三) 17:30:01 | 恢复业务说明、接入流程及示例图片 |
|
||||
| 2026年08月19日(周三) 11:00:08 | 长期VIP默认产品名称改为至尊版 |
|
||||
@@ -0,0 +1,79 @@
|
||||
## 删除或清空回收站
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 删除或清空回收站 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /del |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
批量彻底删除回收站中的文件(夹)，或在不传 `tid` 时清空回收站。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/rb/del
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----|:-------|:---|:----|:--------------------------------|:------|
|
||||
| tid | string | 否 | "" | 需要删除的回收站ID，多个ID用半角逗号分隔，最多 1150 个；不传时清空回收站 | 1,2,3,4 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/rb/del' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'tid=1,2,3,4'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:---------|:--------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | string[] | 响应数据 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
- 不传 `tid` 会清空当前授权用户的整个回收站，操作后无法恢复。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,80 @@
|
||||
## 删除文件
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 删除文件 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /delete |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
批量删除文件(夹)，删除操作异步执行并将目标移入回收站。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/delete
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:-----------------------|:-------------------------------------------|
|
||||
| file_ids | string | 是 | - | 需要删除的文件(夹)ID，多个ID用半角逗号分隔 | 3073323042143855813,3073323042143855822 |
|
||||
| parent_id | string | 否 | 0 | 待删除文件(夹)所在的父目录ID | 3073311192547189943 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/ufile/delete' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'file_ids=3073323042143855813,3073323042143855822' \
|
||||
--form-string 'parent_id=3073311192547189943'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:---------|:-----------------|
|
||||
| state | boolean | 状态码，true 表示请求已受理 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | string[] | 响应数据 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,126 @@
|
||||
## 回收站列表
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 回收站列表 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /list |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
分页获取当前授权用户的回收站文件(夹)列表。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/rb/list
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------|:----|:---|:----|:--------|:------|
|
||||
| limit | int | 否 | 30 | 单页记录数 | 最大 200 |
|
||||
| offset | int | 否 | 0 | 数据显示偏移量 | 0 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/rb/list' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--data-urlencode 'limit=30' \
|
||||
--data-urlencode 'offset=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------|:--------|:-------------------------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.offset | int | 数据显示偏移量 |
|
||||
| data.limit | int | 单页记录数 |
|
||||
| data.count | string | 回收站文件(夹)总数 |
|
||||
| data.rb_pass | int | 是否设置回收站密码：1-是，0-否 |
|
||||
| data.{回收站ID} | object | 以回收站ID为键的文件(夹)信息 |
|
||||
| data.{回收站ID}.id | string | 回收站ID |
|
||||
| data.{回收站ID}.file_name | string | 文件(夹)名称 |
|
||||
| data.{回收站ID}.type | string | 类型：1-文件，2-文件夹 |
|
||||
| data.{回收站ID}.file_size | string | 文件大小，单位为字节 |
|
||||
| data.{回收站ID}.dtime | string | 删除时间 |
|
||||
| data.{回收站ID}.thumb_url | string | 缩略图地址 |
|
||||
| data.{回收站ID}.status | string | 还原状态：-1-还原中，0-正常 |
|
||||
| data.{回收站ID}.cid | int | 原文件(夹)的父目录ID |
|
||||
| data.{回收站ID}.parent_name | string | 原文件(夹)的父目录名称 |
|
||||
| data.{回收站ID}.pick_code | string | 文件提取码 |
|
||||
| data.{回收站ID}.isv | int | 是否为视频文件，按文件类型返回 |
|
||||
| data.{回收站ID}.def2 | int | 视频清晰度，按文件类型返回 |
|
||||
| data.{回收站ID}.ico | string | 文件扩展名，按文件类型返回 |
|
||||
| data.{回收站ID}.muc | string | 音频封面地址，按文件类型返回 |
|
||||
| data.{回收站ID}.d_img | string | 文档缩略图地址，按文件类型返回 |
|
||||
| data.{回收站ID}.play_long | int | 音视频时长，按文件类型返回 |
|
||||
| data.{回收站ID}.sha1 | string | 文件 SHA1 值，按文件类型返回 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"offset": 0,
|
||||
"limit": 30,
|
||||
"count": "0",
|
||||
"rb_pass": 0,
|
||||
"3074054555277845747": {
|
||||
"id": "3074054555277845747",
|
||||
"file_name": "",
|
||||
"type": "1",
|
||||
"file_size": "0",
|
||||
"dtime": "",
|
||||
"thumb_url": "",
|
||||
"status": "0",
|
||||
"cid": 0,
|
||||
"parent_name": "",
|
||||
"pick_code": "",
|
||||
"isv": 0,
|
||||
"def2": 0,
|
||||
"ico": "",
|
||||
"muc": "",
|
||||
"d_img": "",
|
||||
"play_long": 0,
|
||||
"sha1": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月05日(周三) 17:15:28 | 补充单页记录数上限 |
|
||||
@@ -0,0 +1,78 @@
|
||||
## 回收站还原
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 回收站还原 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /revert |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
批量还原回收站中的文件(夹)。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/rb/revert
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----|:-------|:---|:----|:---------------------------|:--------------|
|
||||
| tid | string | 是 | - | 需要还原的回收站ID，多个ID用半角逗号分隔，最多 1150 个 | 111,222,333,444 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/rb/revert' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'tid=111,222,333,444'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:---------|:--------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | string[] | 响应数据 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,87 @@
|
||||
## 文件(夹)更新
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 文件(夹)更新 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /update |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
更新文件(夹)名称或星标状态。`file_name` 与 `star` 至少传入一个。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/update
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------|:-------|:---|:----|:----------------------|:------------------|
|
||||
| file_id | string | 是 | - | 需要更新的文件(夹)ID | 3073323042143855813 |
|
||||
| file_name | string | 否 | null | 新的文件(夹)名称，文件夹名称限制 255 字节 | 新的名字 |
|
||||
| star | int | 否 | null | 是否星标：1-星标，0-取消星标 | 1 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/ufile/update' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'file_id=3073323042143855813' \
|
||||
--form-string 'file_name=新的名字' \
|
||||
--form-string 'star=1'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:---------------|:--------|:------------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.file_name | string | 更新后的文件(夹)名称 |
|
||||
| data.star | int | 更新后的星标状态：1-星标，0-取消星标 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"file_name": "新的名字",
|
||||
"star": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# 上传流程
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:---------|:------------------------------|
|
||||
| 文档名称 | 上传流程 |
|
||||
| 文档版本 | v1.0 |
|
||||
| 适用场景 | 115开放平台文件上传 |
|
||||
|
||||
### 文档说明
|
||||
|
||||
本文档说明 115 开放平台的文件秒传、普通上传和断点续传流程。
|
||||
|
||||
## 流程概览
|
||||
|
||||
1. 请求「文件上传」接口初始化上传。
|
||||
2. 若响应中 `status=2`，表示秒传成功，上传流程结束。
|
||||
3. 若响应提示需要二次认证，按 `sign_check` 指定的字节范围计算大写 SHA1，然后携带 `sign_key` 和 `sign_val` 重新请求「文件上传」接口。
|
||||
4. 若 `status=1`，携带初始化响应中的 `bucket`、`object`、`callback` 及「获取上传凭证」接口返回的凭证，向对象存储上传文件。
|
||||
5. 需要续传时，携带初始化响应中的 `pick_code` 及待上传文件信息请求「断点续传」接口，获取新的对象存储上传参数。
|
||||
6. 对象存储返回上传成功后，普通上传或断点续传完成。
|
||||
|
||||
## 相关接口
|
||||
|
||||
- [文件上传](文件上传.md)
|
||||
- [获取上传凭证](获取上传凭证.md)
|
||||
- [断点续传](断点续传.md)
|
||||
- [阿里云 OSS 上传文件说明](https://help.aliyun.com/zh/oss/user-guide/upload-objects-to-oss/)
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 对象存储上传不请求 `proapi.115.com`，应使用「获取上传凭证」和上传调度接口返回的域名、对象标识、临时凭证与回调参数发起请求。
|
||||
- `sign_check` 的起止字节均在 SHA1 计算范围内。例如 `0-99` 表示计算共 100 字节的内容。
|
||||
- 调用开放平台接口时必须携带 `Authorization: Bearer access_token`，并妥善保管临时上传凭证。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,141 @@
|
||||
## 文件上传
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:---------|:------------------------------|
|
||||
| 接口名称 | 文件上传 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /upload/init |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
初始化断点续传调度，完成秒传判定、二次认证调度或返回对象存储上传参数。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/upload/init
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-----|:---|:----|:---------------------------|:--------------------|
|
||||
| file_name | string | 是 | - | 文件名 | 图片.jpg |
|
||||
| file_size | int | 是 | - | 文件大小，单位为字节 | 5335 |
|
||||
| target | string | 是 | - | 文件上传目标 | `U_1_0`，格式为 `U_1_<文件夹ID>` |
|
||||
| fileid | string | 是 | - | 文件 SHA1 值 | `<FILE_SHA1>` |
|
||||
| preid | string | 否 | "" | 文件前 128 KiB 内容的 SHA1 值 | `<PREID_SHA1>` |
|
||||
| path | string | 否 | "" | 上传路径 | "" |
|
||||
| pick_code | string | 否 | "" | 上传任务唯一标识，用于续传 | `<PICK_CODE>` |
|
||||
| topupload | int | 否 | "" | 上传调度文件类型标记，见下方枚举表格 | 0 |
|
||||
| sign_key | string | 否 | "" | 二次认证标识 | `<SIGN_KEY>` |
|
||||
| sign_val | string | 否 | "" | 根据 `sign_check` 计算的大写 SHA1 值 | `<SIGN_VAL>` |
|
||||
|
||||
#### 请求参数中的 topupload 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:---|:---------------------------|:---|
|
||||
| -1 | 没有上传调度文件类型标记 | - |
|
||||
| 0 | 单文件上传任务，记录一条独立上传记录 | - |
|
||||
| 1 | 文件夹任务的第一个子文件，记录一次文件夹上传 | - |
|
||||
| 2 | 文件夹任务的其他子文件，不单独记录上传记录 | - |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/upload/init' \
|
||||
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
||||
-F 'file_name=图片.jpg' \
|
||||
-F 'file_size=5335' \
|
||||
-F 'target=U_1_0' \
|
||||
-F 'fileid=<FILE_SHA1>' \
|
||||
-F 'topupload=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------------------------|:------|:----------------------------------------|
|
||||
| state | boolean | 状态码，是表示成功，否表示异常 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 上传调度数据 |
|
||||
| data.status | int | 上传状态：1-非秒传 2-秒传 |
|
||||
| data.code | int | 上传调度状态码 |
|
||||
| data.pick_code | string | 上传任务唯一标识，用于续传 |
|
||||
| data.target | string | 文件上传目标 |
|
||||
| data.bucket | string | 对象存储 bucket |
|
||||
| data.object | string | OSS 对象标识 |
|
||||
| data.callback | object | 上传完成回调数据 |
|
||||
| data.callback.callback | string | 上传完成回调信息 |
|
||||
| data.callback.callback_var | string | 上传完成回调参数 |
|
||||
| data.sign_key | string | 本次二次认证的 SHA1 标识 |
|
||||
| data.sign_check | string | 二次认证所需本地文件 SHA1 计算的字节范围 |
|
||||
| data.file_id | string | 秒传成功时新增文件 ID |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"status": 1,
|
||||
"code": 0,
|
||||
"pick_code": "",
|
||||
"target": "U_1_0",
|
||||
"bucket": "",
|
||||
"object": "",
|
||||
"callback": {
|
||||
"callback": "",
|
||||
"callback_var": ""
|
||||
},
|
||||
"sign_key": "",
|
||||
"sign_check": "",
|
||||
"file_id": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- `target` 必须匹配 `U_1_<数字文件夹ID>`；`U_1_0` 表示网盘根目录。
|
||||
- 非 VIP 用户单文件大小不得超过 5 GiB；尝鲜VIP、体验VIP用户单文件大小不得超过 15 GiB。
|
||||
- 上传前会检查用户剩余空间和盗播上传封禁状态。
|
||||
- 二次认证调度结果见下表。
|
||||
|
||||
| code | status | 说明 | 后续处理 |
|
||||
|:-----|:-------|:---------|:------|
|
||||
| 700 | 6 | 签名认证后失败 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||||
| 701 | 7 | 需要认证签名 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||||
| 702 | 8 | 签名认证失败 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `sign_check` 格式为 `起始字节-结束字节`，起止字节均包含在 SHA1 计算范围内；例如 `2392148-2392298` 需计算该范围内文件内容的 SHA1。
|
||||
- 省略 `topupload` 时，服务端会将其归一化为空字符串；显式传入枚举值时会归一化为整数。
|
||||
- 请妥善保管 `access_token`、上传凭证与回调数据，不要在日志或客户端可见信息中输出。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,110 @@
|
||||
## 断点续传
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:---------|:------------------------------|
|
||||
| 接口名称 | 断点续传 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /upload/resume |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据已有上传任务和待上传文件信息，获取断点续传所需的对象存储上传参数。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/upload/resume
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-----|:---|:----|:------------------|:--------------------|
|
||||
| file_size | int | 是 | - | 文件大小，单位为字节 | 5335 |
|
||||
| target | string | 是 | - | 文件上传目标 | `U_1_0`，格式为 `U_1_<文件夹ID>` |
|
||||
| fileid | string | 是 | - | 文件 SHA1 值 | `<FILE_SHA1>` |
|
||||
| pick_code | string | 是 | - | 上传任务唯一标识 | `<PICK_CODE>` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/upload/resume' \
|
||||
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
||||
-F 'file_size=5335' \
|
||||
-F 'target=U_1_0' \
|
||||
-F 'fileid=<FILE_SHA1>' \
|
||||
-F 'pick_code=<PICK_CODE>'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------------------------|:------|:----------------------|
|
||||
| state | boolean | 状态码，是表示成功，否表示异常 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 续传调度数据 |
|
||||
| data.version | string | 上传接口版本 |
|
||||
| data.target | string | 文件上传目标 |
|
||||
| data.pick_code | string | 上传任务唯一标识 |
|
||||
| data.bucket | string | 对象存储 bucket |
|
||||
| data.object | string | OSS 对象标识 |
|
||||
| data.callback | object | 上传完成回调数据 |
|
||||
| data.callback.callback | string | 上传完成回调信息 |
|
||||
| data.callback.callback_var | string | 上传完成回调参数 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"version": "",
|
||||
"target": "U_1_0",
|
||||
"pick_code": "",
|
||||
"bucket": "",
|
||||
"object": "",
|
||||
"callback": {
|
||||
"callback": "",
|
||||
"callback_var": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- `target` 必须匹配 `U_1_<数字文件夹ID>`；`U_1_0` 表示网盘根目录。
|
||||
- 非 VIP 用户单文件大小不得超过 5 GiB；尝鲜VIP、体验VIP用户单文件大小不得超过 15 GiB。
|
||||
- 续传前会检查用户剩余空间和盗播上传封禁状态。
|
||||
- 上游调度结果的 `status` 只有为 1 或 2 时才按成功响应返回续传参数。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `pick_code` 必须来自原上传初始化调度响应，并与当前文件信息匹配。
|
||||
- 请妥善保管 `access_token`、上传凭证与回调数据，不要在日志或客户端可见信息中输出。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,87 @@
|
||||
## 获取上传凭证
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:---------|:------------------------------|
|
||||
| 接口名称 | 获取上传凭证 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /upload/get_token |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取对象存储上传域名和临时上传凭证。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/upload/get_token
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
无
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/upload/get_token' \
|
||||
-H 'Authorization: Bearer <ACCESS_TOKEN>'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------|:------|:---------------|
|
||||
| state | boolean | 状态码，是表示成功，否表示异常 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 上传凭证数据 |
|
||||
| data.endpoint | string | 上传域名 |
|
||||
| data.AccessKeySecret | string | 临时上传凭证密钥 |
|
||||
| data.SecurityToken | string | 临时安全令牌 |
|
||||
| data.Expiration | string | 上传凭证过期时间 |
|
||||
| data.AccessKeyId | string | 临时上传凭证 ID |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"endpoint": "",
|
||||
"AccessKeySecret": "",
|
||||
"SecurityToken": "",
|
||||
"Expiration": "",
|
||||
"AccessKeyId": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 网页版文档中的密钥字段名存在拼写误差，服务端实际返回字段为 `AccessKeySecret`。
|
||||
- 上传凭证为敏感信息，仅用于当前上传流程；不要写入日志、持久化存储或对外暴露。
|
||||
- 服务端通过当前 `access_token` 识别用户，不接收用户账号请求参数。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,84 @@
|
||||
## 文件复制
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 文件复制 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /copy |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
将一个或多个文件、文件夹复制到指定目录。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/copy
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:--------|:-------|:---|:----|:------------------------------------|:--------------------|
|
||||
| pid | string | 否 | "0" | 目标目录ID，根目录ID为 `0` | 1054251402869818368 |
|
||||
| file_id | string | 是 | - | 待复制的文件或文件夹ID，多个ID使用半角逗号分隔 | 2323423573680609857 |
|
||||
| nodupli | int | 否 | 0 | 目标目录是否不允许同名：0-允许，1-不允许 | 1 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/ufile/copy' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'pid=1054251402869818368' \
|
||||
--form-string 'file_id=2323423573680609857' \
|
||||
--form-string 'nodupli=1'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:---------|:--------------------|
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object[] | 响应数据 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `pid` 不传或传 `0` 时复制到根目录。
|
||||
- 接口受文件操作频率限制；触发限制时返回异常。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,121 @@
|
||||
## 文件搜索
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 文件搜索 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /search |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据文件名搜索文件或文件夹，支持按目录、文件标签、时间范围和文件类型筛选。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/search
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:------------|:-------|:---|:----|:----------------------------------------------------------|:---------|
|
||||
| search_value | string | 否 | "" | 搜索关键词；与 `file_label` 至少传一个，最多取前40个字符 | "文件" |
|
||||
| limit | int | 否 | 20 | 单页记录数；`offset + limit` 最大不超过10000 | 20 |
|
||||
| offset | int | 否 | 0 | 数据显示偏移量 | 0 |
|
||||
| file_label | string | 否 | "" | 文件标签；与 `search_value` 至少传一个 | "1" |
|
||||
| cid | int | 否 | 0 | 目标目录ID；`-1` 表示不返回任何列表内容 | 0 |
|
||||
| gte_day | string | 否 | "" | 搜索结果匹配的开始日期 | 2020-11-19 |
|
||||
| lte_day | string | 否 | "" | 搜索结果匹配的结束日期 | 2020-11-20 |
|
||||
| fc | int | 否 | 0 | 显示类型：1-只显示文件夹，2-只显示文件，0-全部 | 0 |
|
||||
| type | int | 否 | 0 | 一级筛选大分类，见下方枚举表格 | 1 |
|
||||
| suffix | string | 否 | "" | 一级筛选选择“其他”时填写的后缀名 | "pdf" |
|
||||
|
||||
#### 请求参数中的 type 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:--|:----|:---|
|
||||
| 1 | 文档 | - |
|
||||
| 2 | 图片 | - |
|
||||
| 3 | 音频 | - |
|
||||
| 4 | 视频 | - |
|
||||
| 5 | 压缩包 | - |
|
||||
| 6 | 应用 | - |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/ufile/search' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--data-urlencode 'search_value=文件' \
|
||||
--data-urlencode 'limit=20' \
|
||||
--data-urlencode 'offset=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------|:---------|:----------------------------------------|
|
||||
| count | int | 符合条件的文件或文件夹总数 |
|
||||
| data | object[] | 文件或文件夹列表 |
|
||||
| data[].file_id | string | 文件或文件夹ID |
|
||||
| data[].user_id | string | 115账号 |
|
||||
| data[].sha1 | string | 文件SHA-1值 |
|
||||
| data[].file_name | string | 文件或文件夹名称 |
|
||||
| data[].file_size | string | 文件大小 |
|
||||
| data[].user_ptime | string | 上传时间 |
|
||||
| data[].user_utime | string | 更新时间 |
|
||||
| data[].pick_code | string | 文件提取码 |
|
||||
| data[].parent_id | string | 父目录ID |
|
||||
| data[].area_id | string | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除 |
|
||||
| data[].is_private | int | 文件是否隐藏：0-未隐藏，1-已隐藏 |
|
||||
| data[].file_category | string | 文件属性：1-文件，0-文件夹 |
|
||||
| data[].ico | string | 文件后缀 |
|
||||
| limit | int | 分页数量 |
|
||||
| offset | int | 偏移量 |
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"count": 0,
|
||||
"data": [],
|
||||
"limit": 20,
|
||||
"offset": 0,
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `search_value` 与 `file_label` 至少传一个；搜索关键词最多取前40个字符。
|
||||
- 当 `offset + limit` 超过10000时，服务端按 `offset=0`、`limit=115` 查询。
|
||||
- 搜索结果会过滤不属于正常区域的文件；当前账号未开启隐藏文件展示时，也会过滤隐藏文件。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,91 @@
|
||||
## 文件移动
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 文件移动 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /move |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
将一个或多个文件、文件夹移动到指定目录。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/move
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------|:-------|:---|:----|:------------------------------------|:----------------------------------------|
|
||||
| file_ids | string | 是 | - | 待移动的文件或文件夹ID，多个ID使用半角逗号分隔 | 3073323042143855813,3073323042143855822 |
|
||||
| to_cid | string | 否 | "0" | 目标目录ID；`0` 表示根目录，非 `0` 时必须指向正常可用的目录 | 3073311192547189943 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/ufile/move' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'file_ids=3073323042143855813,3073323042143855822' \
|
||||
--form-string 'to_cid=3073311192547189943'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:---------|:--------------------|
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object[] | 响应数据 |
|
||||
|
||||
#### 响应的 code 字段(错误码)说明
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|:-------|:-----------------------------------|:-----------------------------|
|
||||
| 20009 | 目标目录不存在或目标ID不是目录 | 确认 to_cid 指向存在的目录 |
|
||||
| 20018 | 目标目录不在正常区域或已经删除 | 选择正常可用的目标目录 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `to_cid` 不传或传 `0` 时移动到根目录。
|
||||
- `to_cid` 非 `0` 时，目标必须是正常可用的目录；目标不存在、不是目录或已经删除时，移动失败。
|
||||
- 接口受文件操作频率限制；触发限制时返回异常。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:---------------------------------|:---------------------------------------|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月14日(周五) 15:38:44 | 补充移动目标目录有效性约束及错误码 |
|
||||
@@ -0,0 +1,86 @@
|
||||
## 新建文件夹
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 新建文件夹 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /add |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
在指定父目录下新建文件夹。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/folder/add
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------|:-------|:---|:----|:---------------------------|:--------------------|
|
||||
| pid | string | 否 | "0" | 父目录ID，根目录ID为 `0` | 3073323042143855813 |
|
||||
| file_name | string | 是 | - | 文件夹名称，最多255个字符 | 新建文件夹名称 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/folder/add' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'pid=3073323042143855813' \
|
||||
--form-string 'file_name=新建文件夹名称'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:---------------|:--------|:----------------------|
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.file_name | string | 新建的文件夹名称 |
|
||||
| data.file_id | string | 新建的文件夹ID |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"file_name": "",
|
||||
"file_id": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `pid` 不传或传 `0` 时在根目录下新建文件夹。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,114 @@
|
||||
## 按ID获取
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 按ID获取 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /get_info |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据文件或文件夹ID获取详情。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/folder/get_info
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------|:-------|:---|:----|:----------|:--------------------|
|
||||
| file_id | string | 是 | - | 文件或文件夹ID | 1288444975268439877 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/folder/get_info' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--data-urlencode 'file_id=1288444975268439877'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------|:---------|:----------------------------------------|
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 文件或文件夹详情 |
|
||||
| data.count | int | 包含的文件总数 |
|
||||
| data.size | string | 文件或文件夹总大小 |
|
||||
| data.size_byte | int | 文件或文件夹总大小，单位为字节 |
|
||||
| data.folder_count | int | 包含的文件夹总数 |
|
||||
| data.play_long | int | 视频时长；`-1` 表示正在统计，其他数值单位为秒 |
|
||||
| data.show_play_long | int | 是否开启展示视频时长 |
|
||||
| data.ptime | string | 上传时间 |
|
||||
| data.utime | string | 修改时间 |
|
||||
| data.file_name | string | 文件或文件夹名称 |
|
||||
| data.pick_code | string | 文件提取码 |
|
||||
| data.sha1 | string | 文件SHA-1值 |
|
||||
| data.file_id | string | 文件或文件夹ID |
|
||||
| data.is_mark | string | 是否星标 |
|
||||
| data.open_time | int | 文件或文件夹最近打开时间 |
|
||||
| data.file_category | string | 文件属性：1-文件，0-文件夹 |
|
||||
| data.paths | object[] | 文件或文件夹所在路径 |
|
||||
| data.paths[].file_id | string | 父目录ID |
|
||||
| data.paths[].file_name | string | 父目录名称 |
|
||||
| data.paths[].iss | int | 父目录共享状态标识 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"count": 0,
|
||||
"size": "",
|
||||
"size_byte": 0,
|
||||
"folder_count": 0,
|
||||
"play_long": 0,
|
||||
"show_play_long": 0,
|
||||
"ptime": "",
|
||||
"utime": "",
|
||||
"file_name": "",
|
||||
"pick_code": "",
|
||||
"sha1": "",
|
||||
"file_id": "",
|
||||
"is_mark": "",
|
||||
"open_time": 0,
|
||||
"file_category": "",
|
||||
"paths": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 文件或文件夹已进入回收站或被彻底删除时，接口返回异常。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,115 @@
|
||||
## 按路径获取
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 按路径获取 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /get_info |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据文件或文件夹路径获取详情。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/folder/get_info
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----|:-------|:---|:----|:----------------------------------------------------------------|:-------------------|
|
||||
| path | string | 是 | - | 文件路径，支持 `/`、`>` 两种分隔符；路径需以分隔符开头，并用同一分隔符分隔目录层级 | /a/b/c.png 或 >a>b>c |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/folder/get_info' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'path=/a/b/c.png'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------|:---------|:----------------------------------------|
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 文件或文件夹详情 |
|
||||
| data.count | int | 包含的文件总数 |
|
||||
| data.size | string | 文件或文件夹总大小 |
|
||||
| data.size_byte | int | 文件或文件夹总大小，单位为字节 |
|
||||
| data.folder_count | int | 包含的文件夹总数 |
|
||||
| data.play_long | int | 视频时长；`-1` 表示正在统计，其他数值单位为秒 |
|
||||
| data.show_play_long | int | 是否开启展示视频时长 |
|
||||
| data.ptime | string | 上传时间 |
|
||||
| data.utime | string | 修改时间 |
|
||||
| data.file_name | string | 文件或文件夹名称 |
|
||||
| data.pick_code | string | 文件提取码 |
|
||||
| data.sha1 | string | 文件SHA-1值 |
|
||||
| data.file_id | string | 文件或文件夹ID |
|
||||
| data.is_mark | string | 是否星标 |
|
||||
| data.open_time | int | 文件或文件夹最近打开时间 |
|
||||
| data.file_category | string | 文件属性：1-文件，0-文件夹 |
|
||||
| data.paths | object[] | 文件或文件夹所在路径 |
|
||||
| data.paths[].file_id | string | 父目录ID |
|
||||
| data.paths[].file_name | string | 父目录名称 |
|
||||
| data.paths[].iss | int | 父目录共享状态标识 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"count": 0,
|
||||
"size": "",
|
||||
"size_byte": 0,
|
||||
"folder_count": 0,
|
||||
"play_long": 0,
|
||||
"show_play_long": 0,
|
||||
"ptime": "",
|
||||
"utime": "",
|
||||
"file_name": "",
|
||||
"pick_code": "",
|
||||
"sha1": "",
|
||||
"file_id": "",
|
||||
"is_mark": "",
|
||||
"open_time": 0,
|
||||
"file_category": "",
|
||||
"paths": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 文件或文件夹已进入回收站或被彻底删除时，接口返回异常。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,98 @@
|
||||
## 获取文件下载地址
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:--------------------------------|
|
||||
| 接口名称 | 获取文件下载地址 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /downurl |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
根据文件提取码获取文件下载地址。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/downurl
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------|:-------|:---|:----|:------|:-----------------|
|
||||
| pick_code | string | 是 | - | 文件提取码，多个提取码用半角逗号分隔 | dtctprlmfkl4exiok |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/ufile/downurl' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--form-string 'pick_code=dtctprlmfkl4exiok'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:---------------------------|:--------|:---------------------------|
|
||||
| state | boolean | 状态码，true 表示成功 |
|
||||
| message | string | 错误信息 |
|
||||
| code | int | 错误码 |
|
||||
| errno | int | 下载地址获取失败时返回的错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.{文件ID} | object | 以文件ID为键的文件下载信息 |
|
||||
| data.{文件ID}.file_name | string | 文件名 |
|
||||
| data.{文件ID}.file_size | int | 文件大小，单位为字节 |
|
||||
| data.{文件ID}.pick_code | string | 文件提取码 |
|
||||
| data.{文件ID}.sha1 | string | 文件 SHA1 值 |
|
||||
| data.{文件ID}.url | object | 下载地址信息 |
|
||||
| data.{文件ID}.url.url | string | 文件下载地址 |
|
||||
| data.can_appeal | boolean | 文件违规时是否可以申诉，按错误场景返回 |
|
||||
| data.want_appeal_id | string | 文件违规时的申诉标识，按错误场景返回 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"2323423573680609857": {
|
||||
"file_name": "",
|
||||
"file_size": 0,
|
||||
"pick_code": "",
|
||||
"sha1": "",
|
||||
"url": {
|
||||
"url": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 由开放平台授权流程获取，并通过 `Authorization` 请求头传递。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,204 @@
|
||||
## 获取文件列表
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 获取文件列表 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /files |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取指定目录中的文件和文件夹列表，支持分页、排序以及按文件类型、后缀名和星标状态筛选。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/ufile/files
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-----------|:-------|:---|:----------|:-------------------------------------------------------|:----------|
|
||||
| cid | string | 否 | "0" | 目录ID，对应 `parent_id`；根目录ID为 `0` | "0" |
|
||||
| type | int | 否 | 0 | 文件类型，见下方枚举表格 | 1 |
|
||||
| limit | int | 否 | 20 | 查询数量，最大1150 | 20 |
|
||||
| offset | int | 否 | 0 | 查询起始位置 | 0 |
|
||||
| suffix | string | 否 | "" | 文件后缀名 | "pdf" |
|
||||
| asc | int | 否 | 0 | 排序方向：1-升序，0-降序 | 0 |
|
||||
| o | string | 否 | user_ptime | 排序字段，见下方枚举表格 | file_name |
|
||||
| custom_order | int | 否 | 0 | 排序模式，见下方枚举表格 | 0 |
|
||||
| stdir | int | 否 | 0 | 筛选文件时是否显示文件夹：1-显示，0-不显示 | 1 |
|
||||
| star | int | 否 | 0 | 星标筛选：1-仅显示星标文件，0-全部 | 0 |
|
||||
| cur | int | 否 | 0 | 是否只显示当前文件夹内的文件：1-是，0-否 | 1 |
|
||||
| show_dir | int | 否 | 0 | 是否显示目录：1-是，0-否 | 0 |
|
||||
|
||||
#### 请求参数中的 type 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:--|:----|:---|
|
||||
| 1 | 文档 | - |
|
||||
| 2 | 图片 | - |
|
||||
| 3 | 音频 | - |
|
||||
| 4 | 视频 | - |
|
||||
| 5 | 压缩包 | - |
|
||||
| 6 | 应用 | - |
|
||||
| 7 | 书籍 | - |
|
||||
|
||||
#### 请求参数中的 o 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:-----------|:-------|:---|
|
||||
| file_name | 文件名 | - |
|
||||
| file_size | 文件大小 | - |
|
||||
| user_ptime | 上传时间 | 默认值 |
|
||||
| user_utime | 更新时间 | - |
|
||||
| file_type | 文件类型 | - |
|
||||
|
||||
#### 请求参数中的 custom_order 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:--|:----------------------|:---|
|
||||
| 0 | 使用记忆排序，自定义排序失效 | 默认值 |
|
||||
| 1 | 使用自定义排序，不使用记忆排序 | - |
|
||||
| 2 | 使用自定义排序，非文件夹置顶 | - |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/ufile/files' \
|
||||
-H 'Authorization: Bearer access_token' \
|
||||
--data-urlencode 'cid=0' \
|
||||
--data-urlencode 'limit=20' \
|
||||
--data-urlencode 'offset=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------|:---------|:----------------------------------------------------------|
|
||||
| data | object[] | 文件和文件夹列表 |
|
||||
| data[].fid | string | 文件或文件夹ID |
|
||||
| data[].aid | string | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除 |
|
||||
| data[].pid | string | 父目录ID |
|
||||
| data[].fc | string | 文件分类：0-文件夹，1-文件 |
|
||||
| data[].fn | string | 文件或文件夹名称 |
|
||||
| data[].fco | string | 文件夹封面 |
|
||||
| data[].ism | string | 是否星标，1表示星标 |
|
||||
| data[].isp | int | 是否加密，1表示加密 |
|
||||
| data[].pc | string | 文件提取码 |
|
||||
| data[].upt | int | 修改时间 |
|
||||
| data[].uet | int | 修改时间 |
|
||||
| data[].uppt | int | 上传时间 |
|
||||
| data[].cm | int | 特殊目录标识 |
|
||||
| data[].fdesc | string | 文件备注 |
|
||||
| data[].ispl | int | 是否统计文件夹下视频时长 |
|
||||
| data[].fl | object[] | 文件标签 |
|
||||
| data[].fl[].id | string | 文件标签ID |
|
||||
| data[].fl[].name | string | 文件标签名称 |
|
||||
| data[].fl[].sort | string | 文件标签排序 |
|
||||
| data[].fl[].color | string | 文件标签颜色 |
|
||||
| data[].fl[].is_default | int | 文件标签类型：0-最近使用，1-非最近使用，2-默认标签 |
|
||||
| data[].fl[].update_time | int | 文件标签更新时间 |
|
||||
| data[].fl[].create_time | int | 文件标签创建时间 |
|
||||
| data[].sha1 | string | 文件SHA-1值 |
|
||||
| data[].fs | int | 文件大小，单位为字节 |
|
||||
| data[].fta | string | 文件状态：0或2-未上传完成，1-已上传完成 |
|
||||
| data[].ico | string | 文件后缀名 |
|
||||
| data[].fatr | string | 音频长度 |
|
||||
| data[].isv | int | 是否为视频 |
|
||||
| data[].def | int | 视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画 |
|
||||
| data[].def2 | int | 视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画 |
|
||||
| data[].play_long | int | 音视频时长，单位为秒 |
|
||||
| data[].v_img | string | 视频缩略图地址 |
|
||||
| data[].thumb | string | 图片缩略图地址 |
|
||||
| data[].uo | string | 原图地址 |
|
||||
| count | int | 当前目录文件数量 |
|
||||
| sys_count | int | 系统文件夹数量 |
|
||||
| offset | int | 偏移量 |
|
||||
| limit | int | 分页数量 |
|
||||
| aid | string | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除 |
|
||||
| cid | int | 父目录ID |
|
||||
| is_asc | int | 排序方向：1-升序，0-降序 |
|
||||
| min_size | int | 最小文件大小筛选值 |
|
||||
| max_size | int | 最大文件大小筛选值 |
|
||||
| sys_dir | string | 系统目录 |
|
||||
| hide_data | string | 是否返回文件数据 |
|
||||
| record_open_time | string | 是否记录文件夹打开时间 |
|
||||
| star | int | 是否星标：1-星标，0-未星标 |
|
||||
| type | int | 一级筛选大分类，见请求参数中的 `type` 字段枚举 |
|
||||
| suffix | string | 一级筛选选择“其他”时填写的后缀名 |
|
||||
| path | object[] | 父目录树 |
|
||||
| path[].name | string | 父目录名称 |
|
||||
| path[].aid | int | 父目录文件状态 |
|
||||
| path[].cid | int | 父目录ID |
|
||||
| path[].pid | int | 上级父目录ID |
|
||||
| path[].isp | int | 父目录是否加密 |
|
||||
| path[].p_cid | string | 父目录路径标识 |
|
||||
| path[].fv | string | 父目录属性 |
|
||||
| cur | int | 是否只显示当前文件夹内的文件 |
|
||||
| stdir | int | 筛选文件时是否显示文件夹 |
|
||||
| fields | string | 指定返回字段 |
|
||||
| order | string | 实际使用的排序字段 |
|
||||
| state | boolean | 接口状态，true表示成功 |
|
||||
| code | int | 异常码 |
|
||||
| message | string | 异常信息 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [],
|
||||
"count": 0,
|
||||
"sys_count": 0,
|
||||
"offset": 0,
|
||||
"limit": 20,
|
||||
"aid": "1",
|
||||
"cid": 0,
|
||||
"is_asc": 0,
|
||||
"min_size": 0,
|
||||
"max_size": 0,
|
||||
"sys_dir": "",
|
||||
"hide_data": "",
|
||||
"record_open_time": "",
|
||||
"star": 0,
|
||||
"type": 0,
|
||||
"suffix": "",
|
||||
"path": [],
|
||||
"cur": 0,
|
||||
"stdir": 0,
|
||||
"fields": "",
|
||||
"order": "user_ptime",
|
||||
"state": true,
|
||||
"code": 0,
|
||||
"message": ""
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `limit` 最大为1150。
|
||||
- 当 `cid` 指向不存在或已删除的目录时，接口返回异常；当目录为加密目录时，不返回目录内容。
|
||||
- `user_id` 由服务端根据 access token 获取，无需传入。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,140 @@
|
||||
## 用户信息
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:---------|:------------------------------|
|
||||
| 接口名称 | 用户信息 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /user/info |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取当前授权用户的基本信息、网盘空间信息、VIP 等级信息以及第三方畅用权益信息。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/user/info
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
无
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/user/info' \
|
||||
-H 'Authorization: Bearer <ACCESS_TOKEN>'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------------------------|:------|:----------------------------------------|
|
||||
| state | boolean | 状态码，是表示成功，否表示异常 |
|
||||
| message | string | 异常信息 |
|
||||
| code | int | 异常码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.user_id | int | 用户115账号 |
|
||||
| data.user_name | string | 用户名称 |
|
||||
| data.user_face_s | string | 小尺寸用户头像 |
|
||||
| data.user_face_m | string | 中尺寸用户头像 |
|
||||
| data.user_face_l | string | 大尺寸用户头像 |
|
||||
| data.rt_space_info | object | 用户实时空间信息 |
|
||||
| data.rt_space_info.all_total | object | 用户总空间 |
|
||||
| data.rt_space_info.all_total.size | int | 用户总空间大小，单位为字节 |
|
||||
| data.rt_space_info.all_total.size_format | string | 用户总空间大小，格式化文本 |
|
||||
| data.rt_space_info.all_remain | object | 用户剩余空间 |
|
||||
| data.rt_space_info.all_remain.size | int | 用户剩余空间大小，单位为字节 |
|
||||
| data.rt_space_info.all_remain.size_format | string | 用户剩余空间大小，格式化文本 |
|
||||
| data.rt_space_info.all_use | object | 用户已使用空间 |
|
||||
| data.rt_space_info.all_use.size | int | 用户已使用空间大小，单位为字节 |
|
||||
| data.rt_space_info.all_use.size_format | string | 用户已使用空间大小，格式化文本 |
|
||||
| data.vip_info | object | 用户 VIP 等级信息 |
|
||||
| data.vip_info.level_name | string | VIP 等级名称，见下方枚举表格 |
|
||||
| data.vip_info.expire | int | VIP 过期时间戳，无 VIP 时为 0 |
|
||||
| data.vip_info.tp_rights | object | 第三方畅用权益信息 |
|
||||
| data.vip_info.tp_rights.is_tp_rights | int | 是否具有当前应用的第三方畅用权益：0-否 1-是 |
|
||||
| data.vip_info.tp_rights.tp_rights_time | int | 第三方畅用权益过期时间戳，无有效权益时为 0 |
|
||||
|
||||
#### 响应的 data.vip_info.level_name 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:----------|:---|:---|
|
||||
| 原石会员 | 原石用户 | 无有效 VIP 等级时的服务端固定返回值 |
|
||||
| 尝鲜VIP | 尝鲜VIP | - |
|
||||
| 体验VIP | 体验VIP | - |
|
||||
| 月费VIP | 月费VIP | - |
|
||||
| 年费VIP | 年费VIP | - |
|
||||
| 长期VIP(高级版) | 长期VIP(高级版) | - |
|
||||
| 长期VIP(特级版) | 长期VIP(特级版) | - |
|
||||
| 长期VIP(超级版) | 长期VIP(超级版) | - |
|
||||
| 长期VIP(至尊版) | 长期VIP(至尊版) | - |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"user_id": 0,
|
||||
"user_name": "",
|
||||
"user_face_s": "",
|
||||
"user_face_m": "",
|
||||
"user_face_l": "",
|
||||
"rt_space_info": {
|
||||
"all_total": {
|
||||
"size": 0,
|
||||
"size_format": ""
|
||||
},
|
||||
"all_remain": {
|
||||
"size": 0,
|
||||
"size_format": ""
|
||||
},
|
||||
"all_use": {
|
||||
"size": 0,
|
||||
"size_format": ""
|
||||
}
|
||||
},
|
||||
"vip_info": {
|
||||
"expire": 0,
|
||||
"level_name": "原石会员",
|
||||
"tp_rights": {
|
||||
"is_tp_rights": 0,
|
||||
"tp_rights_time": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 决定当前用户和开放应用，接口不接收用户账号请求参数。
|
||||
- `rt_space_info` 为实时空间数据，`all_use` 由总空间减去剩余空间计算得出。
|
||||
- 请妥善保管 `access_token`，不要在日志或客户端可见信息中输出。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月18日(周二) 14:40:25 | 更新四种长期VIP等级名称枚举 |
|
||||
@@ -0,0 +1,88 @@
|
||||
## 提交视频转码
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:--------------------------------|
|
||||
| 接口名称 | 提交视频转码 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /video_push |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
按 VIP 等级或消耗枫币提交视频加速转码。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/video/video_push
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:----------------------------------------|:-----------------|
|
||||
| pick_code | string | 是 | - | 视频文件提取码 | b53gu6z3hvqji8wrm |
|
||||
| op | string | 是 | - | 加速转码方式，`vip_push`：按 VIP 等级加速；`pay_push`：消耗枫币加速 | vip_push |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/video/video_push' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
-F 'pick_code=b53gu6z3hvqji8wrm' \
|
||||
-F 'op=vip_push'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:------|:---------|:----------------------|
|
||||
| state | boolean | 操作结果状态，true：成功；false：失败 |
|
||||
| message | string | 返回信息，成功时为空字符串 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 响应数据，成功时为空数组 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 仅支持为当前授权用户所属的视频文件提交加速转码。
|
||||
- 已完成转码的视频无需重复提交。
|
||||
- 两种加速转码方式均要求当前用户具备 VIP 权益；`pay_push` 在枫币余额不足时提交失败。
|
||||
- 提交成功后，系统通知转码服务重新计算排队信息，并在 3 小时内记录已加速状态。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 通过 `Authorization` 请求头传递，请将请求示例中的占位符替换为实际访问令牌。
|
||||
- 请勿对同一视频重复提交加速转码。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,125 @@
|
||||
## 获取视频在线播放地址
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:--------------------------------|
|
||||
| 接口名称 | 获取视频在线播放地址 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /play |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取指定视频的在线播放地址、清晰度、音轨及文件基础信息。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/video/play
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:----------|:-----------------|
|
||||
| pick_code | string | 是 | - | 视频文件提取码 | b53gu6z3hvqji8wrm |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/video/play' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--data-urlencode 'pick_code=b53gu6z3hvqji8wrm'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:---------------------------------|:---------|:----------------------------------------|
|
||||
| state | boolean | 操作结果状态，true：成功；false：失败 |
|
||||
| message | string | 返回信息，成功时为空字符串 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 视频播放及文件数据 |
|
||||
| data.file_id | string | 文件ID |
|
||||
| data.parent_id | string | 文件父目录ID |
|
||||
| data.file_name | string | 文件名称 |
|
||||
| data.file_size | string | 文件大小，单位为字节 |
|
||||
| data.file_sha1 | string | 文件哈希值 |
|
||||
| data.file_type | string | 文件类型 |
|
||||
| data.is_private | string | 文件是否加密隐藏，0：否；1：是 |
|
||||
| data.play_long | string | 视频时长 |
|
||||
| data.user_def | int | 记忆的清晰度，1：标清；2：高清；3：超清；4：1080P；5：4K；100：原画 |
|
||||
| data.user_rotate | int | 记忆的视频旋转角度，取值为 0、90、180、270 |
|
||||
| data.user_turn | int | 视频翻转方向，0：不翻转；1：水平翻转；2：垂直翻转 |
|
||||
| data.multitrack_list | object | 多音轨列表，键为音轨序号 |
|
||||
| data.multitrack_list.*.title | string | 音轨标题 |
|
||||
| data.multitrack_list.*.is_selected | string | 音轨是否为上次选中，1：是 |
|
||||
| data.multitrack_list.*.sync_time | string | 音轨同步时间 |
|
||||
| data.definition_list | object | 清晰度列表，键为清晰度值，值为清晰度名称 |
|
||||
| data.definition_list_new | object | 新版清晰度列表，键为清晰度值，值为清晰度名称 |
|
||||
| data.video_url | object[] | 各清晰度的播放地址信息 |
|
||||
| data.video_url[].url | string | 播放地址 |
|
||||
| data.video_url[].height | int | 视频高度 |
|
||||
| data.video_url[].width | int | 视频宽度 |
|
||||
| data.video_url[].definition | int | 视频清晰度 |
|
||||
| data.video_url[].title | string | 视频清晰度名称 |
|
||||
| data.video_url[].definition_n | int | 新版视频清晰度 |
|
||||
| data.video_push_state | boolean | 视频尚未完成转码时是否已提交加速转码，仅对应失败响应返回 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"file_id": "",
|
||||
"parent_id": "",
|
||||
"file_name": "",
|
||||
"file_size": "0",
|
||||
"file_sha1": "",
|
||||
"file_type": "",
|
||||
"is_private": "0",
|
||||
"play_long": "0",
|
||||
"user_def": 0,
|
||||
"user_rotate": 0,
|
||||
"user_turn": 0,
|
||||
"multitrack_list": {},
|
||||
"definition_list": {},
|
||||
"definition_list_new": {},
|
||||
"video_url": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 切换音轨时，在返回的播放地址后增加整型参数 `audio_track`，参数值取 `multitrack_list` 对应的键；音轨下标从 `0` 开始。
|
||||
- 年费VIP以下用户不支持播放 4K 视频；选择 4K 清晰度时会返回引导升级的视频地址。
|
||||
- 接口不返回下载地址字段 `down_url`。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 通过 `Authorization` 请求头传递，请将请求示例中的占位符替换为实际访问令牌。
|
||||
- 播放地址具有时效性，请勿缓存或向无关方披露。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,96 @@
|
||||
## 获取视频播放进度
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:--------------------------------|
|
||||
| 接口名称 | 获取视频播放进度 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /history |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取指定视频已记录的播放进度。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/video/history
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:----------|:-----------------|
|
||||
| pick_code | string | 是 | - | 视频文件提取码 | b53gu6z3hvqji8wrm |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/video/history' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--data-urlencode 'pick_code=b53gu6z3hvqji8wrm'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------|:--------|:-----------------------------|
|
||||
| state | boolean | 操作结果状态，true：成功；false：失败 |
|
||||
| message | string | 返回信息，成功时为空字符串 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 播放进度数据；没有记录时为空数组 |
|
||||
| data.add_time | int | 记录添加时间，Unix 时间戳 |
|
||||
| data.file_id | string | 文件ID |
|
||||
| data.file_name | string | 文件名称 |
|
||||
| data.hash | string | 文件哈希值 |
|
||||
| data.pick_code | string | 文件提取码 |
|
||||
| data.time | int | 已播放时长，单位为秒 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"add_time": 0,
|
||||
"file_id": "",
|
||||
"file_name": "",
|
||||
"hash": "",
|
||||
"pick_code": "b53gu6z3hvqji8wrm",
|
||||
"time": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 接口只返回当前 `pick_code` 对应的单条播放进度记录。
|
||||
- 视频是否播放完毕可通过文件列表中的 `played_end` 字段查看，`1` 表示已播放完毕。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 通过 `Authorization` 请求头传递，请将请求示例中的占位符替换为实际访问令牌。
|
||||
- `pick_code` 对应的文件不存在或不在有效文件区域时，接口返回失败。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,119 @@
|
||||
## 视频字幕列表
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:--------------------------------|
|
||||
| 接口名称 | 视频字幕列表 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /subtitle |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
获取指定视频的自动载入字幕和可用字幕列表。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/video/subtitle
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:----------|:-----------------|
|
||||
| pick_code | string | 是 | - | 视频文件提取码 | b53gu6z3hvqji8wrm |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://proapi.115.com/open/video/subtitle' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
--data-urlencode 'pick_code=b53gu6z3hvqji8wrm'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:----------------------------|:---------|:----------------------------|
|
||||
| state | boolean | 操作结果状态，true：成功；false：失败 |
|
||||
| message | string | 返回信息，成功时为空字符串 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| data.autoload | object | 默认自动载入的字幕；无可用字幕时为空数组 |
|
||||
| data.autoload.sid | string | 字幕标识 |
|
||||
| data.autoload.language | string | 字幕语言 |
|
||||
| data.autoload.title | string | 字幕标题 |
|
||||
| data.autoload.url | string | 字幕文件地址 |
|
||||
| data.autoload.type | string | 字幕文件类型 |
|
||||
| data.autoload.key | string | 内置字幕键，仅内置字幕返回 |
|
||||
| data.autoload.sha1 | string | 字幕文件哈希值 |
|
||||
| data.autoload.file_id | string | 外挂或内嵌字幕文件ID |
|
||||
| data.autoload.file_name | string | 外挂或内嵌字幕文件名 |
|
||||
| data.autoload.pick_code | string | 外挂或内嵌字幕文件提取码 |
|
||||
| data.autoload.caption_map_id | string | 内嵌字幕映射ID |
|
||||
| data.autoload.is_caption_map | int | 是否为内嵌字幕，0：否；1：是 |
|
||||
| data.autoload.sync_time | float | 字幕同步时间 |
|
||||
| data.autoload.from | int | 记忆字幕来源标识 |
|
||||
| data.autoload.user_sub | int | 是否为用户记忆字幕，1：是 |
|
||||
| data.list | object[] | 字幕列表 |
|
||||
| data.list[].sid | string | 字幕标识 |
|
||||
| data.list[].language | string | 字幕语言 |
|
||||
| data.list[].title | string | 字幕标题 |
|
||||
| data.list[].url | string | 字幕文件地址 |
|
||||
| data.list[].type | string | 字幕文件类型 |
|
||||
| data.list[].key | string | 内置字幕键，仅内置字幕返回 |
|
||||
| data.list[].sha1 | string | 字幕文件哈希值 |
|
||||
| data.list[].file_id | string | 外挂或内嵌字幕文件ID |
|
||||
| data.list[].file_name | string | 外挂或内嵌字幕文件名 |
|
||||
| data.list[].pick_code | string | 外挂或内嵌字幕文件提取码 |
|
||||
| data.list[].caption_map_id | string | 内嵌字幕映射ID |
|
||||
| data.list[].is_caption_map | int | 是否为内嵌字幕，0：否；1：是 |
|
||||
| data.list[].sync_time | float | 字幕同步时间 |
|
||||
| data.list[].from | int | 记忆字幕来源标识 |
|
||||
| data.list[].user_sub | int | 是否为用户记忆字幕，1：是 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": {
|
||||
"autoload": [],
|
||||
"list": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- 用户记忆字幕不在列表中时会被前置；其余字幕按同目录同名外挂字幕、内嵌字幕、内置字幕、其他外挂字幕的顺序组合。
|
||||
- 存在用户记忆字幕时优先将其作为自动载入字幕；否则依次选择内嵌字幕、同名外挂字幕或内置字幕。
|
||||
- 字幕项来源不同，部分来源专属字段可能不返回。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 通过 `Authorization` 请求头传递，请将请求示例中的占位符替换为实际访问令牌。
|
||||
- 字幕文件地址具有时效性，请以本次接口返回值为准。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,89 @@
|
||||
## 记忆视频播放进度
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-------------|:--------------------------------|
|
||||
| 接口名称 | 记忆视频播放进度 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /history |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
记录指定视频的播放进度及是否播放完毕。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://proapi.115.com/open/video/history
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
Authorization: Bearer access_token
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----------|:-------|:---|:----|:-------------------|:-----------------|
|
||||
| pick_code | string | 是 | - | 视频文件提取码 | b53gu6z3hvqji8wrm |
|
||||
| time | int | 否 | 0 | 视频播放进度，单位为秒 | 10 |
|
||||
| watch_end | int | 否 | 0 | 是否播放完毕，0：否；1：是 | 0 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://proapi.115.com/open/video/history' \
|
||||
-H 'Authorization: Bearer <access_token>' \
|
||||
-F 'pick_code=b53gu6z3hvqji8wrm' \
|
||||
-F 'time=10' \
|
||||
-F 'watch_end=0'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:------|:---------|:----------------------|
|
||||
| state | boolean | 操作结果状态，true：成功；false：失败 |
|
||||
| message | string | 返回信息，成功时为空字符串 |
|
||||
| code | int | 错误码 |
|
||||
| data | object[] | 响应数据，成功时为空数组 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": true,
|
||||
"message": "",
|
||||
"code": 0,
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
### 业务规则
|
||||
|
||||
- `time` 和 `watch_end` 均不传时，两个参数均按 `0` 处理，即播放进度为 0 秒且未播放完毕。
|
||||
- 非本人文件不写入播放进度，但接口按操作成功返回。
|
||||
- 同一视频未播放完毕的进度在 5 秒内重复上报时不重复持久化；标记为播放完毕时会立即持久化。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 通过 `Authorization` 请求头传递，请将请求示例中的占位符替换为实际访问令牌。
|
||||
- `pick_code` 必须属于当前授权用户可记录播放进度的视频文件。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,30 @@
|
||||
# 开发须知
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 文档名称 | 开发须知 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
为共同建设开放、共赢的合作生态并保障平台服务的可持续发展，开发者在接入平台服务前，须认真阅读并严格遵循《115生活开放平台开发者协议》的相关要求，确保合规运营、维护平台秩序。
|
||||
|
||||
基于平台与用户权益保护原则，平台会持续监测开发者的服务使用行为。如发现违反平台规范的行为，平台将视情节采取包括但不限于服务限流、接口冻结、资质回收等限制措施，并保留依法追责的权利。
|
||||
|
||||
开发者严禁实施包括但不限于以下行为：
|
||||
|
||||
1. **数据隐私违规行为**：侵害用户数据隐私安全，包括未经用户授权或未明确用途，违规收集、下载、存储、传播、加工用户存储数据等。开发者需要确保用户数据的获取与使用全程透明、可追溯。
|
||||
2. **商业利益侵犯行为**：损害 115 科技的商业利益，包括多人共享开发者账号及会员权益、开展竞争关系业务、未经授权获取平台相关服务运营数据等。
|
||||
3. **不当使用行为**：违规或未按要求使用 API 服务，包括违反国家相关政策法规、侵犯第三方合法权益、调用非公开接口、实际用途与申请信息不符等。
|
||||
|
||||
## 限流说明
|
||||
|
||||
为确保系统安全并保障服务稳定运行，115生活开放平台对所有 API 实施频率控制策略。出于安全防护需要，相关策略细则暂不公开，平台会持续动态优化该机制。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,60 @@
|
||||
# 授权错误码
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 文档名称 | 授权错误码 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
| 错误码 | 描述 | 建议 |
|
||||
|:-------|:------------------------------------|:-------------------------------------------------------------|
|
||||
| 40100000 | 参数缺失 | - |
|
||||
| 40101017 | 用户验证失败 | - |
|
||||
| 40110000 | 请求异常，需要重试 | - |
|
||||
| 40140100 | `client_id` 错误 | - |
|
||||
| 40140101 | `code_challenge` 必填 | - |
|
||||
| 40140102 | `code_challenge_method` 必须是 `sha256`、`sha1`、`md5` 之一 | - |
|
||||
| 40140103 | `sign` 必填 | - |
|
||||
| 40140104 | `sign` 签名失败 | - |
|
||||
| 40140105 | 生成二维码失败 | - |
|
||||
| 40140106 | AppID 无效 | - |
|
||||
| 40140107 | 应用不存在 | - |
|
||||
| 40140108 | 应用未审核通过 | - |
|
||||
| 40140109 | 应用已被停用 | - |
|
||||
| 40140110 | 应用已过期 | - |
|
||||
| 40140111 | AppSecret 错误 | - |
|
||||
| 40140112 | `code_verifier` 长度要求为 43 至 128 位 | - |
|
||||
| 40140113 | `code_verifier` 验证失败 | - |
|
||||
| 40140114 | `refresh_token` 格式错误(防篡改) | - |
|
||||
| 40140115 | `refresh_token` 签名校验失败(防篡改) | - |
|
||||
| 40140116 | `refresh_token` 无效(已解除授权) | 重新授权。终态错误，重试不会成功；继续重试将被标记为永久失效，见 `40140137` |
|
||||
| 40140117 | `access_token` 刷新太频繁 | - |
|
||||
| 40140118 | 开发者认证已过期 | - |
|
||||
| 40140119 | `refresh_token` 已过期 | 重新授权。终态错误，重试不会成功；继续重试将被标记为永久失效，见 `40140137` |
|
||||
| 40140120 | `refresh_token` 检验失败(防篡改) | 调用 `/open/refreshToken` 后会重新生成 `refresh_token`，检查本地是否已更新其值。终态错误，持续用旧值重试将被标记为永久失效，见 `40140137` |
|
||||
| 40140121 | `access_token` 刷新失败 | 重试 |
|
||||
| 40140122 | 超出授权应用数量上限 | - |
|
||||
| 40140123 | `access_token` 格式错误(防篡改) | - |
|
||||
| 40140124 | `access_token` 签名校验失败(防篡改) | - |
|
||||
| 40140125 | `access_token` 无效(已过期、已解除授权或授权缓存不存在) | 调用 `/open/refreshToken` 获取新凭证；若 `refresh_token` 无效或已过期，重新授权 |
|
||||
| 40140126 | `access_token` 与当前授权记录不匹配 | 重新读取刷新后保存的最新凭证，禁止使用原 `access_token` 重试；没有可用新凭证时调用 `/open/refreshToken` |
|
||||
| 40140127 | `response_type` 错误 | - |
|
||||
| 40140128 | `redirect_uri` 缺少协议 | - |
|
||||
| 40140129 | `redirect_uri` 缺少域名 | - |
|
||||
| 40140130 | 没有配置重定向域名 | 到应用管理中配置域名 |
|
||||
| 40140131 | `redirect_uri` 域名不合法 | 需要与应用管理中配置的应用域名一致 |
|
||||
| 40140132 | `grant_type` 错误 | - |
|
||||
| 40140133 | `client_secret` 验证失败 | - |
|
||||
| 40140134 | 授权码 `code` 验证失败 | - |
|
||||
| 40140135 | `client_id` 验证失败 | - |
|
||||
| 40140136 | `redirect_uri` 验证失败(防 MITM 攻击) | - |
|
||||
| 40140137 | `refresh_token` 已失效，请停止重试并重新授权(终态) | 同一 `refresh_token` 连续多次以 `40140116`/`40140119`/`40140120` 失败后被服务端标记为永久失效。收到后必须停止用该令牌重试，引导用户重新授权；重新授权产生的新令牌不受影响 |
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月10日(周一) 10:23:15 | 修正 `40140125`、`40140126` 的原因及处理建议 |
|
||||
| 2026年08月24日(周一) 10:16:52 | 新增终态错误码 `40140137`，补充 `40140116`/`40140119`/`40140120` 的永久失效判定说明 |
|
||||
@@ -0,0 +1,92 @@
|
||||
## 刷新access_token
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 刷新access_token |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /refreshToken |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于通过 `refresh_token` 获取新的 `access_token` 和 `refresh_token`。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://passportapi.115.com/open/refreshToken
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
OAuth 2.0 刷新凭证
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------------|:-------|:---|:----|:---------------------|:----------------------------|
|
||||
| refresh_token | string | 是 | - | 用于刷新访问凭证的刷新凭证 | `REFRESH_TOKEN_PLACEHOLDER` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://passportapi.115.com/open/refreshToken' \
|
||||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'refresh_token=REFRESH_TOKEN_PLACEHOLDER'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------|:-------|:------------------------------------|
|
||||
| state | int | 状态码 |
|
||||
| code | int | 错误码 |
|
||||
| message | string | 响应信息 |
|
||||
| data | object | 响应数据 |
|
||||
| data.access_token | string | 新的 `access_token`，同时刷新有效期 |
|
||||
| data.refresh_token | string | 新的 `refresh_token`，其有效期不延长、不改变 |
|
||||
| data.expires_in | int | `access_token` 有效期，单位为秒 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 1,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"data": {
|
||||
"access_token": "ACCESS_TOKEN_PLACEHOLDER",
|
||||
"refresh_token": "REFRESH_TOKEN_PLACEHOLDER",
|
||||
"expires_in": 7200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `access_token` 有效期为 7200 秒，调用方应以响应中的 `expires_in` 计算刷新时间。
|
||||
- 同一授权在 60 秒内重复刷新会触发频率控制；多进程或多节点调用方应确保同一授权同一时间只有一个刷新请求。
|
||||
- 调用后会同时生成新的 `access_token` 和 `refresh_token`。调用方必须将两者作为一组原子保存，并停止使用刷新前的旧凭证；刷新凭证本身的有效期不延长、不改变。
|
||||
- 收到 `40140125` 或 `40140126` 时，不要使用原 `access_token` 重复重试。应先读取已保存的最新凭证；没有可用新凭证时，再调用本接口刷新。
|
||||
- `40140116`、`40140119`、`40140120` 是终态错误，用同一个 `refresh_token` 重试永远不会成功。同一 `refresh_token` 连续多次以这三种原因失败会被服务端标记为永久失效，之后每次刷新都直接返回 `40140137`。客户端收到这三种错误或 `40140137` 时必须停止重试，引导用户重新授权；后台常驻程序（如 NAS 同步任务）尤其要实现该逻辑，避免长期无效轮询。
|
||||
- `access_token` 和 `refresh_token` 属于敏感凭证，不得写入公开仓库、客户端日志或公开沟通内容。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
| 2026年08月10日(周一) 10:23:15 | 修正 `access_token` 有效期示例，补充凭证轮换及并发刷新说明 |
|
||||
| 2026年08月24日(周一) 10:16:52 | 新增 `refresh_token` 永久失效判定规则与终态错误码 `40140137` 说明 |
|
||||
@@ -0,0 +1,88 @@
|
||||
## 获取access_token
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 获取access_token |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /deviceCodeToToken |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于在用户确认手机扫码授权后，使用设备码和 PKCE 原始校验值换取 `access_token`。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://passportapi.115.com/open/deviceCodeToToken
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
OAuth 2.0 + PKCE
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-----------|:-------|:---|:----|:--------------------------------|:---------------------------------------------------------------|
|
||||
| uid | string | 是 | - | 二维码 ID/设备码 | `DEVICE_CODE_PLACEHOLDER` |
|
||||
| code_verifier | string | 是 | - | 计算 `code_challenge` 时使用的原始随机字符串 | `IGKN6CJanWxCDPDhHZJrhswQdlcPBGLqExkhyujysXaQ4fJKBk_6dlPJo47s` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://passportapi.115.com/open/deviceCodeToToken' \
|
||||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'uid=DEVICE_CODE_PLACEHOLDER' \
|
||||
--data-urlencode 'code_verifier=IGKN6CJanWxCDPDhHZJrhswQdlcPBGLqExkhyujysXaQ4fJKBk_6dlPJo47s'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------|:-------|:--------------------------------|
|
||||
| state | int | 状态码 |
|
||||
| code | int | 错误码 |
|
||||
| message | string | 响应信息 |
|
||||
| data | object | 响应数据 |
|
||||
| data.access_token | string | 访问资源接口的凭证 |
|
||||
| data.refresh_token | string | 刷新 `access_token` 的凭证，有效期 1 年 |
|
||||
| data.expires_in | int | `access_token` 有效期，单位为秒 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 1,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"data": {
|
||||
"access_token": "ACCESS_TOKEN_PLACEHOLDER",
|
||||
"refresh_token": "REFRESH_TOKEN_PLACEHOLDER",
|
||||
"expires_in": 7200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `code_verifier` 必须与生成 `code_challenge` 时使用的原始值一致。
|
||||
- `access_token` 和 `refresh_token` 属于敏感凭证，不得写入公开仓库、客户端日志或公开沟通内容。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,103 @@
|
||||
## 获取设备码和二维码内容
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 获取设备码和二维码内容 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /authDeviceCode |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于 OAuth 2.0 + PKCE 手机扫码授权流程的第一步，获取设备码和二维码内容。此模式适用于无后端服务的第三方客户端，无需提供 AppSecret。
|
||||
|
||||
第三方客户端需要根据响应中的 `data.qrcode` 生成二维码，供 115 客户端扫码授权。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://passportapi.115.com/open/authDeviceCode
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
OAuth 2.0 + PKCE
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:---------------------|:-------|:---|:----|:--------------------------------|:-----------------------------------------------------------|
|
||||
| client_id | string | 是 | - | AppID | `YOUR_APP_ID` |
|
||||
| code_challenge | string | 是 | - | PKCE 挑战码 | `THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw` |
|
||||
| code_challenge_method | string | 是 | - | `code_challenge` 的哈希算法，见下方枚举表格 | `sha256` |
|
||||
|
||||
#### 请求参数中的 code_challenge_method 字段枚举
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
|:-------|:---------------------------|:---|
|
||||
| md5 | 使用 MD5 计算挑战码 | - |
|
||||
| sha1 | 使用 SHA-1 计算挑战码 | - |
|
||||
| sha256 | 使用 SHA-256 计算挑战码，推荐使用 | - |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://passportapi.115.com/open/authDeviceCode' \
|
||||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'client_id=YOUR_APP_ID' \
|
||||
--data-urlencode 'code_challenge=THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw' \
|
||||
--data-urlencode 'code_challenge_method=sha256'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-----------|:-----|:------------------------------------------|
|
||||
| state | int | 状态码 |
|
||||
| code | int | 错误码 |
|
||||
| message | string | 响应信息 |
|
||||
| data | object | 响应数据 |
|
||||
| data.uid | string | 设备码，轮询二维码状态时使用 |
|
||||
| data.time | int | 校验时间戳，轮询二维码状态时使用 |
|
||||
| data.qrcode | string | 二维码内容，第三方客户端需要据此生成设备二维码 |
|
||||
| data.sign | string | 校验签名，轮询二维码状态时使用 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 1,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"data": {
|
||||
"uid": "DEVICE_CODE_PLACEHOLDER",
|
||||
"time": 0,
|
||||
"qrcode": "QRCODE_CONTENT_PLACEHOLDER",
|
||||
"sign": "SIGN_PLACEHOLDER"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `code_verifier` 为长度 43 至 128 位的随机字符串。
|
||||
- `code_challenge` 的计算方式为 `url_safe(base64_encode(hash(code_verifier)))`。哈希结果按二进制数据参与 Base64 编码，算法需要与 `code_challenge_method` 一致。
|
||||
- AppID 等应用凭证请使用实际应用配置，不要在公开仓库或日志中记录敏感凭证。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,89 @@
|
||||
## 轮询二维码状态
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 轮询二维码状态 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /get/status/ |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于长轮询设备二维码的扫码和授权状态。当二维码状态没有变化时，接口不会立即响应，直到请求超时或状态发生变化。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://qrcodeapi.115.com/get/status/
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
设备码参数校验
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:----|:-------|:---|:----|:------------------------------------|:------------------------|
|
||||
| uid | string | 是 | - | 二维码 ID/设备码，从 `/open/authDeviceCode` 的 `data.uid` 获取 | `DEVICE_CODE_PLACEHOLDER` |
|
||||
| time | int | 是 | - | 校验时间戳，从 `/open/authDeviceCode` 的 `data.time` 获取 | `0` |
|
||||
| sign | string | 是 | - | 校验签名，从 `/open/authDeviceCode` 的 `data.sign` 获取 | `SIGN_PLACEHOLDER` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://qrcodeapi.115.com/get/status/' \
|
||||
--data-urlencode 'uid=DEVICE_CODE_PLACEHOLDER' \
|
||||
--data-urlencode 'time=0' \
|
||||
--data-urlencode 'sign=SIGN_PLACEHOLDER'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:------------|:-------|:-------------------------------------------|
|
||||
| state | int | 轮询状态：0-二维码无效，结束轮询；1-继续轮询 |
|
||||
| code | int | 错误码 |
|
||||
| message | string | 响应信息 |
|
||||
| data | object | 响应数据；115 客户端扫码或输入设备码后才有值 |
|
||||
| data.msg | string | 操作提示 |
|
||||
| data.status | int | 二维码状态：1-扫码成功，等待确认；2-确认登录或授权，结束轮询 |
|
||||
| data.version | string | 版本信息 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 1,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"data": {
|
||||
"msg": "OPERATION_MESSAGE_PLACEHOLDER",
|
||||
"status": 1,
|
||||
"version": "VERSION_PLACEHOLDER"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `state=0` 表示二维码无效，应结束轮询；`state=1` 表示继续轮询。
|
||||
- `data.status=1` 表示扫码成功并等待用户确认；`data.status=2` 表示用户已确认登录或授权，应结束轮询并进入换取访问凭证的步骤。
|
||||
- 长轮询超时不等同于授权失败，客户端可以按照自身网络策略重新发起请求。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,95 @@
|
||||
## 用授权码换取access_token
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 用授权码换取access_token |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /authCodeToToken |
|
||||
| 请求方法 | POST |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于通过授权码换取 `access_token`。建议在开发者服务端调用，避免泄露 AppSecret。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://passportapi.115.com/open/authCodeToToken
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
POST
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
OAuth 2.0 授权码模式
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-------------|:-------|:---|:----|:------------------------------------|:------------------------------|
|
||||
| client_id | string | 是 | - | AppID | `YOUR_APP_ID` |
|
||||
| client_secret | string | 是 | - | AppSecret | `YOUR_APP_SECRET` |
|
||||
| code | string | 是 | - | 请求授权接口重定向返回的授权码 | `AUTHORIZATION_CODE_PLACEHOLDER` |
|
||||
| redirect_uri | string | 是 | - | 与请求授权时传入的 `redirect_uri` 一致，用于防止 MITM 和 CSRF 攻击 | `https://foo.com?state=123456` |
|
||||
| grant_type | string | 是 | - | 授权类型，固定为 `authorization_code` | `authorization_code` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl 'https://passportapi.115.com/open/authCodeToToken' \
|
||||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'client_id=YOUR_APP_ID' \
|
||||
--data-urlencode 'client_secret=YOUR_APP_SECRET' \
|
||||
--data-urlencode 'code=AUTHORIZATION_CODE_PLACEHOLDER' \
|
||||
--data-urlencode 'redirect_uri=https://foo.com?state=123456' \
|
||||
--data-urlencode 'grant_type=authorization_code'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:-------------------|:-------|:--------------------------------|
|
||||
| state | int | 状态码：0-失败；1-成功 |
|
||||
| code | int | 错误码 |
|
||||
| message | string | 响应信息 |
|
||||
| data | object | 响应数据 |
|
||||
| data.access_token | string | 访问资源接口的凭证 |
|
||||
| data.refresh_token | string | 刷新 `access_token` 的凭证，有效期 1 年 |
|
||||
| data.expires_in | int | `access_token` 有效期，单位为秒 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 1,
|
||||
"code": 0,
|
||||
"message": "",
|
||||
"data": {
|
||||
"access_token": "ACCESS_TOKEN_PLACEHOLDER",
|
||||
"refresh_token": "REFRESH_TOKEN_PLACEHOLDER",
|
||||
"expires_in": 7200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 必须在服务端安全保存并使用 AppSecret，不得在客户端代码、公开仓库或日志中泄露。
|
||||
- `redirect_uri` 必须与请求授权时传入的值一致。
|
||||
- `access_token` 和 `refresh_token` 属于敏感凭证，应按照敏感数据规范存储。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,87 @@
|
||||
## 请求授权
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 接口名称 | 请求授权 |
|
||||
| 接口版本 | v1.0 |
|
||||
| 接口路径 | /authorize |
|
||||
| 请求方法 | GET |
|
||||
| 接口状态 | 生产环境 |
|
||||
|
||||
### 接口说明
|
||||
|
||||
该接口用于发起 OAuth 2.0 授权码模式授权，建议由开发者服务端参与授权流程。
|
||||
|
||||
用户未登录时，接口会重定向到登录页面；用户已登录时，接口会自动完成授权并重定向到 `redirect_uri` 指定的地址。
|
||||
|
||||
### 接口地址
|
||||
|
||||
```
|
||||
https://passportapi.115.com/open/authorize
|
||||
```
|
||||
|
||||
### 请求方式
|
||||
|
||||
```
|
||||
GET
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
|
||||
```
|
||||
OAuth 2.0 授权码模式
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||||
|:-----------|:-------|:---|:----|:-----------------------------------------------|:---------------------|
|
||||
| client_id | string | 是 | - | AppID | `YOUR_APP_ID` |
|
||||
| redirect_uri | string | 是 | - | 授权完成后的重定向地址；接口会附加授权码 `code`，并原样附加请求中的 `state` | `https://foo.com/bar` |
|
||||
| response_type | string | 是 | - | 授权模式，固定为 `code` | `code` |
|
||||
| state | string | 否 | "" | 防止 CSRF 攻击的随机值，重定向时原样返回 | `123456` |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```shell
|
||||
curl -G 'https://passportapi.115.com/open/authorize' \
|
||||
--data-urlencode 'client_id=YOUR_APP_ID' \
|
||||
--data-urlencode 'redirect_uri=https://foo.com/bar' \
|
||||
--data-urlencode 'response_type=code' \
|
||||
--data-urlencode 'state=123456'
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
接口调用成功时会重定向到 `redirect_uri`，并通过查询参数返回授权码 `code` 和请求中携带的 `state`。接口调用失败时返回以下字段：
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|:--------|:-------|:------------------|
|
||||
| state | int | 状态码：0-失败；1-成功 |
|
||||
| code | int | 错误码 |
|
||||
| data | object | 响应数据 |
|
||||
| message | string | 响应信息 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 0,
|
||||
"code": 40140127,
|
||||
"data": {},
|
||||
"message": "response_type 错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `redirect_uri` 需要先在[115生活开放平台](https://open.115.com/)的应用管理中配置域名，并在请求时进行 URL 编码。
|
||||
- 强烈建议传入随机 `state`，并在换取 `access_token` 前验证重定向返回的 `state` 与请求值一致，以防止 CSRF 攻击。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,57 @@
|
||||
# 接入流程
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 文档名称 | 接入流程 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
## 1. 注册“115生活”账号
|
||||
|
||||
在使用 115 开放平台服务之前，开发者需要先通过[“115生活”官网](https://115.com/)注册“115生活”账号并登录，完成实名认证。
|
||||
|
||||
## 2. 提交入驻申请
|
||||
|
||||
访问[115生活开放平台](https://open.115.com/)，按照页面流程填写相关信息。
|
||||
|
||||
### 2.1 选择开发者身份类型
|
||||
|
||||
开发者可以申请成为“个人开发者”或“企业开发者”。点击页面上方的“切换申请类型”，可以切换身份类型。
|
||||
|
||||
### 2.2 签署协议
|
||||
|
||||
认真阅读并确认相关协议内容；如无异议，勾选“同意”并点击“下一步”。
|
||||
|
||||
### 2.3 填写入驻资料
|
||||
|
||||
按照页面指引填写个人信息、API 对接需求、应用场景等入驻资料，然后点击“下一步”。
|
||||
|
||||
### 2.4 填写认证信息
|
||||
|
||||
根据所选择的开发者身份类型，按照页面指引填写并上传身份认证资料：
|
||||
|
||||
- **个人开发者**：姓名、身份证信息(证件号码、有效期)、证件照片(身份证件正反面照片、本人手持身份证照片)。
|
||||
- **企业开发者**：企业负责人或法人的姓名、联系方式、身份证信息(证件号码、有效期)、证件照片(身份证件正反面照片、加盖公章的营业执照影印件)、统一社会信用代码。
|
||||
|
||||
### 2.5 提交入驻申请
|
||||
|
||||
确认上述信息填写无误后，点击“提交验证”提交入驻申请。平台将在 7 个工作日内完成审核。
|
||||
|
||||
## 3. 创建应用
|
||||
|
||||
入驻申请通过后，进入 115 生活开放平台管理页面，选择“应用管理”，点击“创建应用”，按照页面指引填写应用信息、应用域名、应用描述、接口信息等内容。确认信息填写无误后提交应用申请，平台将在 7 个工作日内完成审核。
|
||||
|
||||
应用审核通过后，开发者可以获取该应用的 AppID、AppKey 和 AppSecret 等接入凭证。请妥善保存这些凭证，不要在客户端代码、公开仓库或沟通内容中泄露。
|
||||
|
||||
## 4. 接口调试
|
||||
|
||||
按照开放平台接口文档完成接入和调用后，即可正式使用开放平台能力。
|
||||
|
||||
开放平台 API 基础域名：`https://proapi.115.com/`
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,23 @@
|
||||
# 更新记录
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 文档名称 | 更新记录 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
## 更新内容
|
||||
|
||||
| 更新模块 | 更新内容 | 更新时间 |
|
||||
|:-----------|:-------------------------|:--------------|
|
||||
| 增值服务产品 | 新增增值服务产品，获得推广收益 | 2025年4月17日周四 |
|
||||
| 视频播放、云下载 | 新增视频播放、云下载接口 | 2025年4月3日周四 |
|
||||
| 接入授权 | 支持 H5 账号密码/短信授权 | 2025年4月2日周三 |
|
||||
| 基本框架 | 新增开放平台文档接口 | 2025年1月22日周三 |
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,30 @@
|
||||
# 概述
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|:-----------|:---------------------------------|
|
||||
| 文档名称 | 概述 |
|
||||
| 文档版本 | v1.0 |
|
||||
|
||||
## 115生活简介
|
||||
|
||||
“115生活”是一款面向个人用户的数字生活平台，提供海量数据的安全存储、多端同步与快速访问。用户不仅可以便捷地管理和使用各类数字资源，还能使用多维社交、生活服务等多元化功能。
|
||||
|
||||
## 115生活开放平台能力说明
|
||||
|
||||
115生活开放平台提供“115生活”数据存储、同步、管理等功能的 API 服务。开发者通过对接 API，可以将“115生活”的存储能力集成到自己的应用中。
|
||||
|
||||
目前已开放以下能力：
|
||||
|
||||
- **用户管理能力**：用户授权与信息查询等。
|
||||
- **文件管理能力**：获取文件列表，查看文件属性，以及文件上传、下载、搜索、移动、删除等。
|
||||
- **视频管理能力**：视频文件的在线转码与播放等。
|
||||
- **云下载服务**：获取云下载任务列表、配额信息，以及添加、删除下载任务等。
|
||||
- **商业价值转化**：开发者参与“推广产品得收益”计划，可基于用户实际购买的产品获取相应推广收益。
|
||||
|
||||
### 修改历史
|
||||
|
||||
| 修改时间 | 修改说明 |
|
||||
|:-----------------------------|:-----|
|
||||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|
||||
@@ -0,0 +1,67 @@
|
||||
# 115 开放平台文档（离线版）
|
||||
|
||||
> 来源：https://open.115.com/doc/ （115生活开放平台开发者文档）
|
||||
> 抓取时间：2026-09-05，共 42 篇 Markdown 文档，目录结构与官网一致。
|
||||
> 目录索引：[tree-index.json](tree-index.json)（官网原始目录树，程序化遍历可用）。
|
||||
|
||||
## 文档目录
|
||||
|
||||
- [概述](115开放平台/简介/概述.md)
|
||||
- [更新记录](115开放平台/简介/更新记录.md)
|
||||
- [接入流程](115开放平台/接入指南/接入流程.md)
|
||||
- [开发须知](115开放平台/接入指南/开发须知.md)
|
||||
- [授权错误码](115开放平台/接入指南/授权错误码.md)
|
||||
- **接入授权/**
|
||||
- **手机扫码授权PKCE模式/**
|
||||
- [获取设备码和二维码内容](115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/获取设备码和二维码内容.md)
|
||||
- [轮询二维码状态](115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/轮询二维码状态.md)
|
||||
- [获取access_token](115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/获取access_token.md)
|
||||
- **授权码模式/**
|
||||
- [请求授权](115开放平台/接入指南/接入授权/授权码模式/请求授权.md)
|
||||
- [用授权码换取access_token](115开放平台/接入指南/接入授权/授权码模式/用授权码换取access_token.md)
|
||||
- [刷新access_token](115开放平台/接入指南/接入授权/刷新access_token.md)
|
||||
- [开发者商业价值转化：推广产品得收益](115开放平台/API列表/开发者商业价值转化：推广产品得收益.md)
|
||||
- **用户管理/**
|
||||
- [用户信息](115开放平台/API列表/用户管理/用户信息.md)
|
||||
- **文件管理/**
|
||||
- **文件上传/**
|
||||
- [上传流程](115开放平台/API列表/文件管理/文件上传/上传流程.md)
|
||||
- [获取上传凭证](115开放平台/API列表/文件管理/文件上传/获取上传凭证.md)
|
||||
- [文件上传](115开放平台/API列表/文件管理/文件上传/文件上传.md)
|
||||
- [断点续传](115开放平台/API列表/文件管理/文件上传/断点续传.md)
|
||||
- [新建文件夹](115开放平台/API列表/文件管理/新建文件夹.md)
|
||||
- [获取文件列表](115开放平台/API列表/文件管理/获取文件列表.md)
|
||||
- **获取文件(夹)详情/**
|
||||
- [按ID获取](115开放平台/API列表/文件管理/获取文件(夹)详情/按ID获取.md)
|
||||
- [按路径获取](115开放平台/API列表/文件管理/获取文件(夹)详情/按路径获取.md)
|
||||
- [文件搜索](115开放平台/API列表/文件管理/文件搜索.md)
|
||||
- [文件复制](115开放平台/API列表/文件管理/文件复制.md)
|
||||
- [文件移动](115开放平台/API列表/文件管理/文件移动.md)
|
||||
- [获取文件下载地址](115开放平台/API列表/文件管理/获取文件下载地址.md)
|
||||
- [文件(夹)更新](115开放平台/API列表/文件管理/文件(夹)更新.md)
|
||||
- [删除文件](115开放平台/API列表/文件管理/删除文件.md)
|
||||
- [回收站列表](115开放平台/API列表/文件管理/回收站列表.md)
|
||||
- [回收站还原](115开放平台/API列表/文件管理/回收站还原.md)
|
||||
- [删除或清空回收站](115开放平台/API列表/文件管理/删除或清空回收站.md)
|
||||
- **视频播放/**
|
||||
- [记忆视频播放进度](115开放平台/API列表/视频播放/记忆视频播放进度.md)
|
||||
- [视频字幕列表](115开放平台/API列表/视频播放/视频字幕列表.md)
|
||||
- [获取视频播放进度](115开放平台/API列表/视频播放/获取视频播放进度.md)
|
||||
- [获取视频在线播放地址](115开放平台/API列表/视频播放/获取视频在线播放地址.md)
|
||||
- [提交视频转码](115开放平台/API列表/视频播放/提交视频转码.md)
|
||||
- **云下载/**
|
||||
- [解析BT种子](115开放平台/API列表/云下载/解析BT种子.md)
|
||||
- [获取用户云下载任务列表](115开放平台/API列表/云下载/获取用户云下载任务列表.md)
|
||||
- [获取云下载配额信息](115开放平台/API列表/云下载/获取云下载配额信息.md)
|
||||
- [清空云下载任务](115开放平台/API列表/云下载/清空云下载任务.md)
|
||||
- [添加云下载链接任务](115开放平台/API列表/云下载/添加云下载链接任务.md)
|
||||
- [删除用户云下载任务](115开放平台/API列表/云下载/删除用户云下载任务.md)
|
||||
- [添加云下载BT任务](115开放平台/API列表/云下载/添加云下载BT任务.md)
|
||||
|
||||
## API 接口速查
|
||||
|
||||
主要 API 域名与认证方式（详见各文档）：
|
||||
|
||||
- 开放 API 基础地址：`https://proapi.115.com/open/...`
|
||||
- 认证方式：`Authorization: Bearer access_token`
|
||||
- OAuth 授权相关文档见 `115开放平台/接入指南/接入授权/`
|
||||
@@ -0,0 +1,308 @@
|
||||
{
|
||||
"name": "doc",
|
||||
"path": "/doc/",
|
||||
"children": [
|
||||
{
|
||||
"name": "115开放平台",
|
||||
"path": "/doc/115开放平台/",
|
||||
"children": [
|
||||
{
|
||||
"name": "简介",
|
||||
"path": "/doc/115开放平台/简介/",
|
||||
"children": [
|
||||
{
|
||||
"name": "概述.md",
|
||||
"path": "/doc/115开放平台/简介/概述.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "更新记录.md",
|
||||
"path": "/doc/115开放平台/简介/更新记录.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "接入指南",
|
||||
"path": "/doc/115开放平台/接入指南/",
|
||||
"children": [
|
||||
{
|
||||
"name": "接入流程.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入流程.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "开发须知.md",
|
||||
"path": "/doc/115开放平台/接入指南/开发须知.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "授权错误码.md",
|
||||
"path": "/doc/115开放平台/接入指南/授权错误码.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "接入授权",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/",
|
||||
"children": [
|
||||
{
|
||||
"name": "手机扫码授权PKCE模式",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/",
|
||||
"children": [
|
||||
{
|
||||
"name": "获取设备码和二维码内容.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/获取设备码和二维码内容.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "轮询二维码状态.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/轮询二维码状态.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取access_token.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/手机扫码授权PKCE模式/获取access_token.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "授权码模式",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/授权码模式/",
|
||||
"children": [
|
||||
{
|
||||
"name": "请求授权.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/授权码模式/请求授权.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "用授权码换取access_token.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/授权码模式/用授权码换取access_token.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "刷新access_token.md",
|
||||
"path": "/doc/115开放平台/接入指南/接入授权/刷新access_token.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "API列表",
|
||||
"path": "/doc/115开放平台/API列表/",
|
||||
"children": [
|
||||
{
|
||||
"name": "开发者商业价值转化：推广产品得收益.md",
|
||||
"path": "/doc/115开放平台/API列表/开发者商业价值转化：推广产品得收益.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "用户管理",
|
||||
"path": "/doc/115开放平台/API列表/用户管理/",
|
||||
"children": [
|
||||
{
|
||||
"name": "用户信息.md",
|
||||
"path": "/doc/115开放平台/API列表/用户管理/用户信息.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "文件管理",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/",
|
||||
"children": [
|
||||
{
|
||||
"name": "文件上传",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件上传/",
|
||||
"children": [
|
||||
{
|
||||
"name": "上传流程.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件上传/上传流程.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取上传凭证.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件上传/获取上传凭证.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "文件上传.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件上传/文件上传.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "断点续传.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件上传/断点续传.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "新建文件夹.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/新建文件夹.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取文件列表.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/获取文件列表.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取文件(夹)详情",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/获取文件(夹)详情/",
|
||||
"children": [
|
||||
{
|
||||
"name": "按ID获取.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/获取文件(夹)详情/按ID获取.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "按路径获取.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/获取文件(夹)详情/按路径获取.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "文件搜索.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件搜索.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "文件复制.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件复制.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "文件移动.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件移动.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取文件下载地址.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/获取文件下载地址.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "文件(夹)更新.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/文件(夹)更新.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "删除文件.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/删除文件.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "回收站列表.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/回收站列表.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "回收站还原.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/回收站还原.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "删除或清空回收站.md",
|
||||
"path": "/doc/115开放平台/API列表/文件管理/删除或清空回收站.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "视频播放",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/",
|
||||
"children": [
|
||||
{
|
||||
"name": "记忆视频播放进度.md",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/记忆视频播放进度.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "视频字幕列表.md",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/视频字幕列表.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取视频播放进度.md",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/获取视频播放进度.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取视频在线播放地址.md",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/获取视频在线播放地址.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "提交视频转码.md",
|
||||
"path": "/doc/115开放平台/API列表/视频播放/提交视频转码.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
},
|
||||
{
|
||||
"name": "云下载",
|
||||
"path": "/doc/115开放平台/API列表/云下载/",
|
||||
"children": [
|
||||
{
|
||||
"name": "解析BT种子.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/解析BT种子.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取用户云下载任务列表.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/获取用户云下载任务列表.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "获取云下载配额信息.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/获取云下载配额信息.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "清空云下载任务.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/清空云下载任务.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "添加云下载链接任务.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/添加云下载链接任务.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "删除用户云下载任务.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/删除用户云下载任务.md",
|
||||
"type": "file"
|
||||
},
|
||||
{
|
||||
"name": "添加云下载BT任务.md",
|
||||
"path": "/doc/115开放平台/API列表/云下载/添加云下载BT任务.md",
|
||||
"type": "file"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
}
|
||||
],
|
||||
"type": "directory"
|
||||
}
|
||||
+2
-1
@@ -23,6 +23,7 @@ import (
|
||||
|
||||
"github.com/truewhile/MeBox/internal/config"
|
||||
"github.com/truewhile/MeBox/internal/database"
|
||||
"github.com/truewhile/MeBox/internal/helper"
|
||||
"github.com/truewhile/MeBox/internal/repository"
|
||||
"github.com/truewhile/MeBox/internal/service"
|
||||
)
|
||||
@@ -121,7 +122,7 @@ func main() {
|
||||
)
|
||||
}
|
||||
}()
|
||||
go services.Boot()
|
||||
helper.Go(logger, "services.boot", services.Boot)
|
||||
|
||||
// Graceful shutdown.
|
||||
stop := make(chan os.Signal, 1)
|
||||
|
||||
@@ -130,26 +130,35 @@ func (m *serverManager) Shutdown(ctx context.Context) error {
|
||||
// desiredPair 根据当前配置计算目标监听形态：nil 表示明文 HTTP，非 nil 表示 TLS。
|
||||
// 证书/私钥按"路径优先、内容兜底"解析，并校验是否匹配。
|
||||
func (m *serverManager) desiredPair() (*tlsPair, error) {
|
||||
if m.cfg == nil || !m.cfg.App.HTTPSEnabled {
|
||||
// 与 ApplyRuntimeSetting 的写锁配对：HTTPS 相关字段可能被运行时设置
|
||||
// 热更新，无锁读存在数据竞争（string 撕裂）。
|
||||
config.RuntimeMu.RLock()
|
||||
httpsEnabled := m.cfg != nil && m.cfg.App.HTTPSEnabled
|
||||
cert := m.cfg.App.SSLCert
|
||||
certPath := m.cfg.App.SSLCertPath
|
||||
key := m.cfg.App.SSLKey
|
||||
keyPath := m.cfg.App.SSLKeyPath
|
||||
config.RuntimeMu.RUnlock()
|
||||
if !httpsEnabled {
|
||||
return nil, nil
|
||||
}
|
||||
certPEM, err := service.ResolveSSLMaterial(m.cfg.App.SSLCert, m.cfg.App.SSLCertPath, "证书")
|
||||
certPEM, err := service.ResolveSSLMaterial(cert, certPath, "证书")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
keyPEM, err := service.ResolveSSLMaterial(m.cfg.App.SSLKey, m.cfg.App.SSLKeyPath, "私钥")
|
||||
keyPEM, err := service.ResolveSSLMaterial(key, keyPath, "私钥")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := service.ValidateSSLKeyPair(certPEM, keyPEM); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
cert, err := tls.X509KeyPair([]byte(certPEM), []byte(keyPEM))
|
||||
pairCert, err := tls.X509KeyPair([]byte(certPEM), []byte(keyPEM))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("SSL 证书/私钥无效：%v", err)
|
||||
}
|
||||
return &tlsPair{
|
||||
cert: cert,
|
||||
cert: pairCert,
|
||||
certPEM: certPEM,
|
||||
keyPEM: keyPEM,
|
||||
version: certPEM + "\x00" + keyPEM,
|
||||
@@ -171,6 +180,8 @@ func (m *serverManager) maybeStartAutoReloadLocked() {
|
||||
|
||||
// pathBased 是否至少有一侧证书/私钥通过文件路径配置。
|
||||
func (m *serverManager) pathBased() bool {
|
||||
config.RuntimeMu.RLock()
|
||||
defer config.RuntimeMu.RUnlock()
|
||||
return strings.TrimSpace(m.cfg.App.SSLCertPath) != "" || strings.TrimSpace(m.cfg.App.SSLKeyPath) != ""
|
||||
}
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ require (
|
||||
github.com/gin-contrib/gzip v1.2.6
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
github.com/glebarez/sqlite v1.11.0
|
||||
github.com/golang-jwt/jwt/v5 v5.2.0
|
||||
github.com/golang-jwt/jwt/v5 v5.2.2
|
||||
github.com/google/uuid v1.6.0
|
||||
github.com/gorilla/websocket v1.5.3
|
||||
github.com/redis/go-redis/v9 v9.7.0
|
||||
|
||||
@@ -52,8 +52,8 @@ github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
|
||||
github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
|
||||
github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
|
||||
github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
|
||||
github.com/golang-jwt/jwt/v5 v5.2.0 h1:d/ix8ftRUorsN+5eMIlF4T6J8CAt9rch3My2winC1Jw=
|
||||
github.com/golang-jwt/jwt/v5 v5.2.0/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
|
||||
github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
|
||||
github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
|
||||
github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
|
||||
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
|
||||
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
|
||||
|
||||
@@ -12,6 +12,7 @@ import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
|
||||
"github.com/spf13/viper"
|
||||
)
|
||||
@@ -19,6 +20,12 @@ import (
|
||||
// EnvPrefix 是所有环境变量驱动的覆盖使用的前缀。
|
||||
const EnvPrefix = "MeBox"
|
||||
|
||||
// RuntimeMu 保护运行时热更新配置字段的并发读写：ApplyRuntimeSetting 在
|
||||
// HTTP goroutine 中写字段，serverManager 的证书轮询等后台协程在无锁读取
|
||||
// 同一批字段。string 是双字结构，无锁并发读写可读到撕裂的 header。
|
||||
// 写方在 ApplyRuntimeSetting 内 Lock，读方（cmd/server）在轮询处 RLock。
|
||||
var RuntimeMu sync.RWMutex
|
||||
|
||||
// Load 从默认值 / 文件 / 环境读取配置。
|
||||
//
|
||||
// 即使没有文件也始终返回可用的 Config。
|
||||
@@ -45,8 +52,13 @@ func Load() (*Config, error) {
|
||||
}
|
||||
s := viper.New()
|
||||
s.SetConfigFile(filepath.Join("config", e.Name()))
|
||||
if err := s.ReadInConfig(); err == nil {
|
||||
_ = v.MergeConfigMap(s.AllSettings())
|
||||
if err := s.ReadInConfig(); err != nil {
|
||||
// 分片解析失败不能静默吞掉：database.yaml 语法错误会让
|
||||
// database.dsn 缺失 → type=auto 静默回退 SQLite，新数据
|
||||
// 全部写进一个空库而用户无感知。
|
||||
fmt.Fprintf(os.Stderr, "warning: parse config/%s failed: %v\n", e.Name(), err)
|
||||
} else {
|
||||
v.MergeConfigMap(s.AllSettings())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -68,8 +68,14 @@ func (c *Config) normalize() error {
|
||||
return fmt.Errorf("generate jwt secret: %w", err)
|
||||
}
|
||||
c.Secrets.JWTSecret = hex.EncodeToString(buf)
|
||||
_ = os.MkdirAll(c.App.DataDir, 0o750)
|
||||
_ = os.WriteFile(path, []byte(c.Secrets.JWTSecret), 0o600)
|
||||
// 持久化失败（DataDir 只读/权限异常）会导致每次重启重新生成
|
||||
// 密钥、全部会话静默失效、多实例各持不同 secret——必须让
|
||||
// 操作员感知。
|
||||
if mkErr := os.MkdirAll(c.App.DataDir, 0o750); mkErr != nil {
|
||||
fmt.Fprintf(os.Stderr, "warning: persist jwt secret failed (mkdir): %v\n", mkErr)
|
||||
} else if wErr := os.WriteFile(path, []byte(c.Secrets.JWTSecret), 0o600); wErr != nil {
|
||||
fmt.Fprintf(os.Stderr, "warning: persist jwt secret failed (write): %v\n", wErr)
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
|
||||
@@ -34,8 +34,15 @@ func SaveDatabaseConfig(dbType, dsn string) error {
|
||||
return fmt.Errorf("marshal config.yaml: %w", err)
|
||||
}
|
||||
|
||||
if err := os.WriteFile(configPath, out, 0644); err != nil {
|
||||
return fmt.Errorf("write config.yaml: %w", err)
|
||||
// 原子写：临时文件 + rename，避免进程崩溃/断电留下截断的 config.yaml
|
||||
// （下次启动会硬失败）；DSN 含数据库密码，权限收窄到 0600。
|
||||
tmp := configPath + ".tmp"
|
||||
if err := os.WriteFile(tmp, out, 0o600); err != nil {
|
||||
return fmt.Errorf("write config.yaml.tmp: %w", err)
|
||||
}
|
||||
if err := os.Rename(tmp, configPath); err != nil {
|
||||
_ = os.Remove(tmp)
|
||||
return fmt.Errorf("replace config.yaml: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -6,6 +6,7 @@ import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/glebarez/sqlite"
|
||||
"go.uber.org/zap"
|
||||
@@ -73,6 +74,14 @@ func configureConnectionPool(db *gorm.DB, cfg *config.Config) error {
|
||||
if cfg.Database.MaxIdleConns > 0 {
|
||||
sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
|
||||
}
|
||||
// 连接生命周期：默认 0 意味着 Postgres 重启/故障切换后的陈旧连接
|
||||
// 永不过期，首次复用才报错，运行期断连恢复慢且可能批量报错。
|
||||
if isPostgres(db) {
|
||||
sqlDB.SetConnMaxLifetime(time.Hour)
|
||||
sqlDB.SetConnMaxIdleTime(10 * time.Minute)
|
||||
} else if isSQLite(db) {
|
||||
sqlDB.SetConnMaxLifetime(24 * time.Hour)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ const mediaSearchIndexSchemaVersion = 2
|
||||
|
||||
func ensureMediaSearchIndex(db *gorm.DB) error {
|
||||
if err := ensureMediaSearchMetaTable(db); err != nil {
|
||||
return nil
|
||||
return err // meta 表创建失败必须上抛，不能静默掩盖
|
||||
}
|
||||
version := currentMediaSearchIndexVersion(db)
|
||||
if version != mediaSearchIndexSchemaVersion {
|
||||
|
||||
@@ -8,6 +8,11 @@ import (
|
||||
|
||||
// AutoMigrate creates tables for every model registered in the model package.
|
||||
func AutoMigrate(db *gorm.DB) error {
|
||||
// 必须先于 AutoMigrate：旧库中可能已有重复的 (user_id, media_id) 历史行，
|
||||
// 不去重会导致唯一索引 uniq_user_history 创建失败。
|
||||
if err := dedupePlaybackHistories(db); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := db.AutoMigrate(model.AllModels()...); err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -37,6 +42,27 @@ func ensureSQLiteQueryOptimizer(db *gorm.DB) error {
|
||||
return db.Exec("ANALYZE").Error
|
||||
}
|
||||
|
||||
// dedupePlaybackHistories removes duplicate (user_id, media_id) rows left by
|
||||
// the former read-then-write upsert, so the uniq_user_history composite unique
|
||||
// index can be created on existing databases. Keeps the most recent row per
|
||||
// pair, preferring live rows over soft-deleted ones.
|
||||
func dedupePlaybackHistories(db *gorm.DB) error {
|
||||
if !db.Migrator().HasTable("playback_histories") {
|
||||
return nil
|
||||
}
|
||||
return db.Exec(`
|
||||
DELETE FROM playback_histories WHERE id IN (
|
||||
SELECT id FROM (
|
||||
SELECT id, ROW_NUMBER() OVER (
|
||||
PARTITION BY user_id, media_id
|
||||
ORDER BY deleted_at IS NULL DESC, watched_at DESC, id DESC
|
||||
) AS rn
|
||||
FROM playback_histories
|
||||
) ranked
|
||||
WHERE ranked.rn > 1
|
||||
)`).Error
|
||||
}
|
||||
|
||||
func ensurePostgresColumnCompatibility(db *gorm.DB) error {
|
||||
if !isPostgres(db) {
|
||||
return nil
|
||||
@@ -106,13 +132,19 @@ func ensureEmbyMountsCompatibility(db *gorm.DB) error {
|
||||
return err
|
||||
}
|
||||
}
|
||||
// 针对已有数据：如果存在多个 sort_order=0/NULL 的记录，按创建时间顺序赋予稳定递增的序号
|
||||
// 针对已有数据：只给 sort_order=0/NULL 的行按创建时间补号（从现有
|
||||
// 最大值之后递增），不能整表重排——此前无条件按 created_at 从 0 重新
|
||||
// 编号，会把用户自定义的顺序覆盖掉。
|
||||
var zeroCount int64
|
||||
if err := db.Model(&model.EmbyMount{}).Where("sort_order = 0 OR sort_order IS NULL").Count(&zeroCount).Error; err == nil && zeroCount > 1 {
|
||||
if err := db.Model(&model.EmbyMount{}).Where("sort_order = 0 OR sort_order IS NULL").Count(&zeroCount).Error; err == nil && zeroCount > 0 {
|
||||
// max 只统计非 0 行：sort_order=0 与 NULL 同样视为“未分配”，
|
||||
// 全部为 0 时从 0 开始编号（与迁移前的初始化语义一致）。
|
||||
var maxOrder int
|
||||
_ = db.Raw("SELECT COALESCE(MAX(sort_order), -1) FROM emby_mounts WHERE sort_order > 0").Scan(&maxOrder).Error
|
||||
var mounts []model.EmbyMount
|
||||
if err := db.Order("created_at asc, id asc").Find(&mounts).Error; err == nil {
|
||||
if err := db.Where("sort_order = 0 OR sort_order IS NULL").Order("created_at asc, id asc").Find(&mounts).Error; err == nil {
|
||||
for i, m := range mounts {
|
||||
_ = db.Exec("UPDATE emby_mounts SET sort_order = ? WHERE id = ?", i, m.ID).Error
|
||||
_ = db.Exec("UPDATE emby_mounts SET sort_order = ? WHERE id = ?", maxOrder+1+i, m.ID).Error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
package database
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/glebarez/sqlite"
|
||||
"gorm.io/gorm"
|
||||
)
|
||||
|
||||
// TestAutoMigrateDedupesPlaybackHistories reproduces the upgrade path: a legacy
|
||||
// database contains duplicate (user_id, media_id) history rows created by the
|
||||
// old read-then-write upsert. AutoMigrate must merge them before creating the
|
||||
// uniq_user_history composite unique index, otherwise the upgrade fails.
|
||||
func TestAutoMigrateDedupesPlaybackHistories(t *testing.T) {
|
||||
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// 旧 schema：无 uniq_user_history 唯一索引。
|
||||
if err := db.Exec(`CREATE TABLE playback_histories (
|
||||
id varchar(36) PRIMARY KEY,
|
||||
created_at datetime,
|
||||
updated_at datetime,
|
||||
deleted_at datetime,
|
||||
user_id varchar(36) NOT NULL,
|
||||
media_id varchar(128) NOT NULL,
|
||||
position_ms integer,
|
||||
duration_ms integer,
|
||||
watched_at datetime,
|
||||
completed numeric
|
||||
)`).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
base := time.Now()
|
||||
rows := []struct {
|
||||
id string
|
||||
position int64
|
||||
watchedAt time.Time
|
||||
}{
|
||||
{"h-old", 1_000, base.Add(-2 * time.Hour)},
|
||||
{"h-mid", 2_000, base.Add(-1 * time.Hour)},
|
||||
{"h-new", 3_000, base},
|
||||
}
|
||||
for _, r := range rows {
|
||||
if err := db.Exec(
|
||||
`INSERT INTO playback_histories (id, user_id, media_id, position_ms, watched_at, created_at, updated_at)
|
||||
VALUES (?, 'u-1', 'm-1', ?, ?, ?, ?)`,
|
||||
r.id, r.position, r.watchedAt, r.watchedAt, r.watchedAt,
|
||||
).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
if err := AutoMigrate(db); err != nil {
|
||||
t.Fatalf("auto migrate with duplicate histories: %v", err)
|
||||
}
|
||||
|
||||
var count int64
|
||||
if err := db.Table("playback_histories").Where("user_id = ? AND media_id = ?", "u-1", "m-1").Count(&count).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if count != 1 {
|
||||
t.Fatalf("expected duplicate rows merged to 1, got %d", count)
|
||||
}
|
||||
var position int64
|
||||
if err := db.Table("playback_histories").
|
||||
Where("user_id = ? AND media_id = ?", "u-1", "m-1").
|
||||
Select("position_ms").Scan(&position).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if position != 3_000 {
|
||||
t.Fatalf("dedupe should keep the most recent row, got position_ms=%d", position)
|
||||
}
|
||||
|
||||
// 唯一索引存在时，重复插入同一 (user_id, media_id) 应触发冲突而非新增行。
|
||||
if err := db.Exec(
|
||||
`INSERT INTO playback_histories (id, user_id, media_id, position_ms, watched_at, created_at, updated_at)
|
||||
VALUES ('h-dup', 'u-1', 'm-1', 4_000, ?, ?, ?)`,
|
||||
base, base, base,
|
||||
).Error; err == nil {
|
||||
t.Fatal("insert violating uniq_user_history should fail")
|
||||
}
|
||||
}
|
||||
@@ -50,28 +50,43 @@ func copyModelTables(src, target *gorm.DB, batchSize int) (map[string]int64, int
|
||||
if modelType.Kind() != reflect.Ptr {
|
||||
return tableCounts, totalCopied, fmt.Errorf("model %T is not a pointer", m)
|
||||
}
|
||||
sliceType := reflect.SliceOf(modelType.Elem())
|
||||
slicePtr := reflect.New(sliceType)
|
||||
if err := src.Unscoped().Find(slicePtr.Interface()).Error; err != nil {
|
||||
return tableCounts, totalCopied, fmt.Errorf("read sqlite table %s: %w", table, err)
|
||||
}
|
||||
filtered := slicePtr.Elem()
|
||||
var primaryKeySet map[string]struct{}
|
||||
if targetCount > 0 {
|
||||
primaryKeySet, err := targetPrimaryKeySet(target, table, primaryColumns)
|
||||
primaryKeySet, err = targetPrimaryKeySet(target, table, primaryColumns)
|
||||
if err != nil {
|
||||
return tableCounts, totalCopied, err
|
||||
}
|
||||
filtered = filterRowsMissingInTarget(target, table, primaryColumns, filtered, primaryKeySet)
|
||||
}
|
||||
if filtered.Len() == 0 {
|
||||
continue
|
||||
// 分页流式读取：此前整表一次性 Find 进内存，media 表几十万行、
|
||||
// 每行含 overview/genres 等长文本时可达数百 MB，迁移过程有 OOM
|
||||
// 风险。源库在迁移期间是静态的，offset 分页安全。
|
||||
const readBatch = 1000
|
||||
copiedForTable := int64(0)
|
||||
for offset := 0; ; offset += readBatch {
|
||||
batchPtr := reflect.New(reflect.SliceOf(modelType.Elem()))
|
||||
if err := src.Unscoped().Limit(readBatch).Offset(offset).Find(batchPtr.Interface()).Error; err != nil {
|
||||
return tableCounts, totalCopied, fmt.Errorf("read sqlite table %s: %w", table, err)
|
||||
}
|
||||
batch := batchPtr.Elem()
|
||||
if batch.Len() == 0 {
|
||||
break
|
||||
}
|
||||
filtered := batch
|
||||
if primaryKeySet != nil {
|
||||
filtered = filterRowsMissingInTarget(target, table, primaryColumns, batch, primaryKeySet)
|
||||
}
|
||||
if filtered.Len() > 0 {
|
||||
filteredPtr := reflect.New(filtered.Type())
|
||||
filteredPtr.Elem().Set(filtered)
|
||||
if err := target.Clauses(clause.OnConflict{DoNothing: true}).CreateInBatches(filteredPtr.Interface(), batchSize).Error; err != nil {
|
||||
return tableCounts, totalCopied, fmt.Errorf("copy sqlite table %s: %w", table, err)
|
||||
}
|
||||
copiedForTable += int64(filtered.Len())
|
||||
}
|
||||
if batch.Len() < readBatch {
|
||||
break
|
||||
}
|
||||
}
|
||||
filteredPtr := reflect.New(filtered.Type())
|
||||
filteredPtr.Elem().Set(filtered)
|
||||
if err := target.Clauses(clause.OnConflict{DoNothing: true}).CreateInBatches(filteredPtr.Interface(), batchSize).Error; err != nil {
|
||||
return tableCounts, totalCopied, fmt.Errorf("copy sqlite table %s: %w", table, err)
|
||||
}
|
||||
copiedForTable := int64(filtered.Len())
|
||||
tableCounts[table] = copiedForTable
|
||||
totalCopied += copiedForTable
|
||||
}
|
||||
|
||||
@@ -5,12 +5,21 @@ import (
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"sync/atomic"
|
||||
"time"
|
||||
|
||||
"gorm.io/gorm"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/config"
|
||||
)
|
||||
|
||||
// sqliteGateHoldLimit 是写闸持有者的最长合法持有时长。语句级写闸在 SQL
|
||||
// 执行 panic 时 After 回调不会运行，令牌会泄漏并让后续所有写入永久等锁；
|
||||
// 超过该时长的持有者按泄漏强制回收（60s 内单条写语句远未到，正常写路径
|
||||
// 不受影响）。
|
||||
const sqliteGateHoldLimit = 60 * time.Second
|
||||
|
||||
func installSQLiteWriteGate(db *gorm.DB) {
|
||||
if db == nil {
|
||||
return
|
||||
@@ -22,15 +31,18 @@ func installSQLiteWriteGate(db *gorm.DB) {
|
||||
if tx.Statement != nil && tx.Statement.Context != nil {
|
||||
ctx = tx.Statement.Context
|
||||
}
|
||||
if err := gate.Lock(ctx); err != nil {
|
||||
holder, err := gate.Lock(ctx)
|
||||
if err != nil {
|
||||
_ = tx.AddError(err)
|
||||
return
|
||||
}
|
||||
tx.InstanceSet(lockedKey, struct{}{})
|
||||
tx.InstanceSet(lockedKey, holder)
|
||||
}
|
||||
unlock := func(tx *gorm.DB) {
|
||||
if _, ok := tx.InstanceGet(lockedKey); ok {
|
||||
gate.Unlock()
|
||||
if holder, ok := tx.InstanceGet(lockedKey); ok {
|
||||
if h, ok := holder.(*sqliteGateHolder); ok {
|
||||
gate.Unlock(h)
|
||||
}
|
||||
}
|
||||
}
|
||||
rawLock := func(tx *gorm.DB) {
|
||||
@@ -64,38 +76,76 @@ func isReadOnlySQL(sql string) bool {
|
||||
return false
|
||||
}
|
||||
|
||||
// sqliteWriteGate serializes in-process SQLite writes while respecting the
|
||||
// statement context, so request cancellation can break out of a queued write.
|
||||
// sqliteWriteGate serializes in-process SQLite writes. 所有权令牌（而非裸
|
||||
// 信号量）保证只有持有者本人能释放；持有超时按泄漏自动回收，避免一次
|
||||
// panic 让进程的 SQLite 写入半永久性瘫痪。
|
||||
type sqliteWriteGate struct {
|
||||
ch chan struct{}
|
||||
mu sync.Mutex
|
||||
cond *sync.Cond
|
||||
owner *sqliteGateHolder
|
||||
}
|
||||
|
||||
type sqliteGateHolder struct {
|
||||
id uint64
|
||||
acquired time.Time
|
||||
}
|
||||
|
||||
var sqliteGateHolderSeq atomic.Uint64
|
||||
|
||||
func newSQLiteWriteGate() *sqliteWriteGate {
|
||||
return &sqliteWriteGate{ch: make(chan struct{}, 1)}
|
||||
g := &sqliteWriteGate{}
|
||||
g.cond = sync.NewCond(&g.mu)
|
||||
return g
|
||||
}
|
||||
|
||||
func (g *sqliteWriteGate) Lock(ctx context.Context) error {
|
||||
select {
|
||||
case g.ch <- struct{}{}:
|
||||
return nil
|
||||
default:
|
||||
}
|
||||
func (g *sqliteWriteGate) Lock(ctx context.Context) (*sqliteGateHolder, error) {
|
||||
g.mu.Lock()
|
||||
defer g.mu.Unlock()
|
||||
if ctx == nil {
|
||||
ctx = context.Background()
|
||||
}
|
||||
select {
|
||||
case g.ch <- struct{}{}:
|
||||
return nil
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
// ctx 取消时唤醒等待者（cond 无法感知 ctx，用旁路 goroutine 广播）。
|
||||
if done := ctx.Done(); done != nil {
|
||||
stop := make(chan struct{})
|
||||
defer close(stop)
|
||||
go func() {
|
||||
select {
|
||||
case <-done:
|
||||
g.cond.Broadcast()
|
||||
case <-stop:
|
||||
}
|
||||
}()
|
||||
}
|
||||
for {
|
||||
if g.owner == nil {
|
||||
holder := &sqliteGateHolder{
|
||||
id: sqliteGateHolderSeq.Add(1),
|
||||
acquired: time.Now(),
|
||||
}
|
||||
g.owner = holder
|
||||
return holder, nil
|
||||
}
|
||||
if ctx.Err() != nil {
|
||||
return nil, ctx.Err()
|
||||
}
|
||||
if time.Since(g.owner.acquired) > sqliteGateHoldLimit {
|
||||
// 持有者疑似 panic 泄漏（After 回调未执行）：强制回收。
|
||||
g.owner = nil
|
||||
g.cond.Broadcast()
|
||||
continue
|
||||
}
|
||||
g.cond.Wait()
|
||||
}
|
||||
}
|
||||
|
||||
func (g *sqliteWriteGate) Unlock() {
|
||||
select {
|
||||
case <-g.ch:
|
||||
default:
|
||||
func (g *sqliteWriteGate) Unlock(h *sqliteGateHolder) {
|
||||
g.mu.Lock()
|
||||
defer g.mu.Unlock()
|
||||
if h == nil || g.owner != h {
|
||||
return
|
||||
}
|
||||
g.owner = nil
|
||||
g.cond.Broadcast()
|
||||
}
|
||||
|
||||
func buildSQLiteDSN(cfg *config.Config) string {
|
||||
@@ -104,7 +154,9 @@ func buildSQLiteDSN(cfg *config.Config) string {
|
||||
// keep as-is to respect user-provided relative paths.
|
||||
dbPath = filepath.Clean(dbPath)
|
||||
}
|
||||
dsn := dbPath + "?_pragma=foreign_keys(1)"
|
||||
// _txlock=immediate：事务以写锁开始。此前 deferred BEGIN 在并发事务
|
||||
// 升级写锁时会绕过 busy_timeout 直接报 SQLITE_BUSY。
|
||||
dsn := dbPath + "?_txlock=immediate&_pragma=foreign_keys(1)"
|
||||
if cfg.Database.WALMode {
|
||||
dsn += "&_pragma=journal_mode(WAL)&_pragma=synchronous(NORMAL)"
|
||||
}
|
||||
|
||||
@@ -10,6 +10,7 @@ import (
|
||||
"github.com/gin-gonic/gin"
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/config"
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
"github.com/truewhile/MeBox/internal/service"
|
||||
)
|
||||
@@ -86,10 +87,19 @@ func applyHTTPSetting(svc *service.Container, key, value string) error {
|
||||
svc.Log.Warn("https setting saved but not applied yet", zap.String("key", key), zap.String("reason", reason))
|
||||
}
|
||||
}
|
||||
|
||||
config.RuntimeMu.RLock()
|
||||
httpsEnabled := svc.Cfg.App.HTTPSEnabled
|
||||
cert := svc.Cfg.App.SSLCert
|
||||
certPath := svc.Cfg.App.SSLCertPath
|
||||
keyMaterial := svc.Cfg.App.SSLKey
|
||||
keyPath := svc.Cfg.App.SSLKeyPath
|
||||
config.RuntimeMu.RUnlock()
|
||||
|
||||
switch key {
|
||||
case "https.enabled":
|
||||
if svc.Cfg.App.HTTPSEnabled {
|
||||
if _, err := service.ResolveSSLKeyPair(svc.Cfg.App.SSLCert, svc.Cfg.App.SSLCertPath, svc.Cfg.App.SSLKey, svc.Cfg.App.SSLKeyPath); err != nil {
|
||||
if httpsEnabled {
|
||||
if _, err := service.ResolveSSLKeyPair(cert, certPath, keyMaterial, keyPath); err != nil {
|
||||
return fmt.Errorf("启用 HTTPS 失败：%v", err)
|
||||
}
|
||||
}
|
||||
@@ -97,7 +107,7 @@ func applyHTTPSetting(svc *service.Container, key, value string) error {
|
||||
if err := validateSSLMaterialSource(key, value); err != nil {
|
||||
return err
|
||||
}
|
||||
if !svc.Cfg.App.HTTPSEnabled {
|
||||
if !httpsEnabled {
|
||||
return nil
|
||||
}
|
||||
if !httpsPairReady(svc) {
|
||||
@@ -144,7 +154,13 @@ func validateSSLMaterialSource(key, value string) error {
|
||||
|
||||
// httpsPairReady 判断基于当前配置解析出的证书/私钥是否完整且匹配。
|
||||
func httpsPairReady(svc *service.Container) bool {
|
||||
_, err := service.ResolveSSLKeyPair(svc.Cfg.App.SSLCert, svc.Cfg.App.SSLCertPath, svc.Cfg.App.SSLKey, svc.Cfg.App.SSLKeyPath)
|
||||
config.RuntimeMu.RLock()
|
||||
cert := svc.Cfg.App.SSLCert
|
||||
certPath := svc.Cfg.App.SSLCertPath
|
||||
keyMaterial := svc.Cfg.App.SSLKey
|
||||
keyPath := svc.Cfg.App.SSLKeyPath
|
||||
config.RuntimeMu.RUnlock()
|
||||
_, err := service.ResolveSSLKeyPair(cert, certPath, keyMaterial, keyPath)
|
||||
return err == nil
|
||||
}
|
||||
|
||||
|
||||
@@ -3,6 +3,8 @@ package handler
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
@@ -33,6 +35,21 @@ func dlnaCastHandler(svc *service.Container) gin.HandlerFunc {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
// SSRF 防护：control_url 必须命中本服务发现到的真实渲染设备，
|
||||
// 防止登录用户借 cast 接口向任意内网地址发起 POST。
|
||||
// 优先用 30s 缓存；未命中时强制重扫一次再校验（设备可能刚上线）。
|
||||
devices, err := svc.DLNA.Discover(c.Request.Context(), false)
|
||||
if err == nil && !dlnaControlURLKnown(devices, req.ControlURL) {
|
||||
devices, err = svc.DLNA.Discover(c.Request.Context(), true)
|
||||
}
|
||||
if err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
if !dlnaControlURLKnown(devices, req.ControlURL) {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": "unknown DLNA device: control_url must come from /api/dlna discovery"})
|
||||
return
|
||||
}
|
||||
if err := svc.DLNA.Cast(c.Request.Context(), req.ControlURL, req.MediaURL); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
@@ -40,3 +57,25 @@ func dlnaCastHandler(svc *service.Container) gin.HandlerFunc {
|
||||
c.Status(http.StatusNoContent)
|
||||
}
|
||||
}
|
||||
|
||||
// dlnaControlURLKnown 判断 control_url 是否属于发现列表中的设备。
|
||||
// 按解析后的 host:port+path 精确比对，容忍大小写与尾斜杠差异。
|
||||
func dlnaControlURLKnown(devices []service.DLNADevice, controlURL string) bool {
|
||||
want, err := url.Parse(strings.TrimSpace(controlURL))
|
||||
if err != nil || want.Host == "" {
|
||||
return false
|
||||
}
|
||||
for _, dev := range devices {
|
||||
for _, candidate := range []string{dev.ControlURL, dev.Location} {
|
||||
u, err := url.Parse(strings.TrimSpace(candidate))
|
||||
if err != nil || u.Host == "" {
|
||||
continue
|
||||
}
|
||||
if strings.EqualFold(u.Host, want.Host) &&
|
||||
strings.EqualFold(strings.TrimRight(u.Path, "/"), strings.TrimRight(want.Path, "/")) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
@@ -132,22 +132,25 @@ func embyMeHandler(svc *service.Container) gin.HandlerFunc {
|
||||
|
||||
func embyGetUserByIDHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
u, err := svc.Emby.FindUser(c.Request.Context(), c.Param("userId"))
|
||||
uid := embyUserID(c)
|
||||
if uid == "" {
|
||||
embyError(c, http.StatusUnauthorized, "not authenticated")
|
||||
return
|
||||
}
|
||||
// 只返回调用者自己的用户对象：客户端误传其他 userId 时回退到
|
||||
// 调用者自身（保留旧行为的兼容语义），但绝不返回他人数据。
|
||||
u, err := svc.Emby.FindUser(c.Request.Context(), uid)
|
||||
if err == nil && u != nil {
|
||||
c.JSON(http.StatusOK, u)
|
||||
return
|
||||
}
|
||||
if authUID := embyUserID(c); authUID != "" && authUID != c.Param("userId") {
|
||||
u, err = svc.Emby.FindUser(c.Request.Context(), authUID)
|
||||
if err == nil && u != nil {
|
||||
c.JSON(http.StatusOK, u)
|
||||
return
|
||||
}
|
||||
}
|
||||
c.JSON(http.StatusOK, embyFallbackUser(c.Param("userId")))
|
||||
c.JSON(http.StatusOK, embyFallbackUser(uid))
|
||||
}
|
||||
}
|
||||
|
||||
// embyFallbackUser 是查库失败时的最后兜底（保持客户端可渲染）。
|
||||
// Policy 必须是最小权限：不声明管理员/删除内容/控制他人等能力，
|
||||
// 实际权限始终由服务端各路由的校验决定。
|
||||
func embyFallbackUser(id string) gin.H {
|
||||
if strings.TrimSpace(id) == "" {
|
||||
id = "mebox-user"
|
||||
@@ -161,10 +164,10 @@ func embyFallbackUser(id string) gin.H {
|
||||
"HasConfiguredEasyPassword": false,
|
||||
"EnableAutoLogin": false,
|
||||
"Policy": gin.H{
|
||||
"IsAdministrator": true,
|
||||
"EnableContentDeletion": true,
|
||||
"EnableRemoteControlOfOtherUsers": true,
|
||||
"EnableSharedDeviceControl": true,
|
||||
"IsAdministrator": false,
|
||||
"EnableContentDeletion": false,
|
||||
"EnableRemoteControlOfOtherUsers": false,
|
||||
"EnableSharedDeviceControl": false,
|
||||
"EnableRemoteAccess": true,
|
||||
"EnableAllDevices": true,
|
||||
"EnableAllChannels": true,
|
||||
|
||||
+80
-33
@@ -11,8 +11,10 @@ import (
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/helper"
|
||||
"github.com/truewhile/MeBox/internal/middleware"
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
"github.com/truewhile/MeBox/internal/repository"
|
||||
"github.com/truewhile/MeBox/internal/service"
|
||||
)
|
||||
|
||||
@@ -58,17 +60,37 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
|
||||
}
|
||||
role, _ := c.Get(middleware.CtxUserRole)
|
||||
includeHidden := role == "admin" && (c.Query("include_hidden") == "1" || c.Query("include_hidden") == "true" || c.Query("all") == "1")
|
||||
if !includeHidden {
|
||||
libs = service.FilterDisplayCloudLibraries(ctx, svc.Repo, libs)
|
||||
visibility := mediaVisibilityForRequest(c, svc)
|
||||
filtered := libs[:0]
|
||||
for _, lib := range libs {
|
||||
if service.LibraryVisibleForUser(ctx, svc.Repo, lib, visibility) {
|
||||
filtered = append(filtered, lib)
|
||||
if !includeHidden {
|
||||
libs = service.FilterDisplayCloudLibraries(ctx, svc.Repo, libs)
|
||||
visibility := mediaVisibilityForRequest(c, svc)
|
||||
filtered := libs[:0]
|
||||
for _, lib := range libs {
|
||||
if service.LibraryVisibleForUser(ctx, svc.Repo, lib, visibility) {
|
||||
filtered = append(filtered, lib)
|
||||
}
|
||||
}
|
||||
libs = filtered
|
||||
}
|
||||
rawIDs := strings.TrimSpace(c.Query("ids"))
|
||||
var targetSet map[string]struct{}
|
||||
if rawIDs != "" {
|
||||
targetSet = make(map[string]struct{})
|
||||
for _, id := range strings.Split(rawIDs, ",") {
|
||||
id = strings.TrimSpace(id)
|
||||
if id != "" {
|
||||
targetSet[id] = struct{}{}
|
||||
}
|
||||
}
|
||||
}
|
||||
libs = filtered
|
||||
}
|
||||
if len(targetSet) > 0 {
|
||||
filtered := libs[:0]
|
||||
for _, lib := range libs {
|
||||
if _, ok := targetSet[lib.ID]; ok {
|
||||
filtered = append(filtered, lib)
|
||||
}
|
||||
}
|
||||
libs = filtered
|
||||
}
|
||||
withPreview := c.Query("with_preview") == "1" || c.Query("with_preview") == "true"
|
||||
limit := 10
|
||||
if withPreview {
|
||||
@@ -89,22 +111,41 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
|
||||
for _, p := range previews {
|
||||
out = append(out, webLibraryPayload{Library: p.Library, Total: p.Total, Cards: p.Cards})
|
||||
}
|
||||
} else {
|
||||
for _, l := range libs {
|
||||
out = append(out, webLibraryPayload{Library: l})
|
||||
} else {
|
||||
visibility := mediaVisibilityForRequest(c, svc)
|
||||
libIDs := make([]string, len(libs))
|
||||
for i, l := range libs {
|
||||
libIDs[i] = l.ID
|
||||
}
|
||||
counts, _ := svc.Repo.Media.CountByLibraries(ctx, libIDs, repository.MediaQueryFilter{
|
||||
IncludeNSFW: visibility.IncludeNSFW,
|
||||
AllowedLibraryIDs: visibility.AllowedLibraryIDs,
|
||||
HiddenLibraryIDs: visibility.HiddenLibraryIDs,
|
||||
})
|
||||
for _, l := range libs {
|
||||
var total int64
|
||||
if counts != nil {
|
||||
total = counts[l.ID]
|
||||
}
|
||||
out = append(out, webLibraryPayload{Library: l, Total: total})
|
||||
}
|
||||
}
|
||||
}
|
||||
// 远程 Emby 挂载库追加在本地库之后（非管理员视图仍受 allowed_library_ids 约束）。
|
||||
if svc.EmbyRemote != nil {
|
||||
if views, err := svc.EmbyRemote.RemoteLibraries(ctx); err == nil {
|
||||
visibility := mediaVisibilityForRequest(c, svc)
|
||||
allowedViews := make([]service.RemoteLibraryView, 0, len(views))
|
||||
for _, v := range views {
|
||||
if !includeHidden && !service.LibraryVisibleForUser(ctx, svc.Repo, v.Library, visibility) {
|
||||
continue
|
||||
visibility := mediaVisibilityForRequest(c, svc)
|
||||
allowedViews := make([]service.RemoteLibraryView, 0, len(views))
|
||||
for _, v := range views {
|
||||
if !includeHidden && !service.LibraryVisibleForUser(ctx, svc.Repo, v.Library, visibility) {
|
||||
continue
|
||||
}
|
||||
if len(targetSet) > 0 {
|
||||
if _, ok := targetSet[v.Library.ID]; !ok {
|
||||
continue
|
||||
}
|
||||
}
|
||||
allowedViews = append(allowedViews, v)
|
||||
}
|
||||
allowedViews = append(allowedViews, v)
|
||||
}
|
||||
remotePayloads := make([]webLibraryPayload, len(allowedViews))
|
||||
for i, v := range allowedViews {
|
||||
remotePayloads[i] = webLibraryPayload{Library: v.Library, IsRemoteEmby: true, RemoteSource: v.AccountName}
|
||||
@@ -124,18 +165,20 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
|
||||
case <-ctx.Done():
|
||||
return
|
||||
}
|
||||
acct := svc.EmbyRemote.AccountByID(ctx, v.AccountID)
|
||||
if acct == nil {
|
||||
return
|
||||
}
|
||||
tmpMount := &model.EmbyMount{Base: model.Base{ID: v.MountID}}
|
||||
itemTypes := remoteLibraryItemTypes(v.CollectionType)
|
||||
if _, total, err := svc.EmbyRemote.RemoteLibraryMedia(ctx, tmpMount, acct, v.RemoteID, itemTypes, 0, 1); err == nil {
|
||||
remotePayloads[i].Total = total
|
||||
}
|
||||
if cards, err := svc.EmbyRemote.RemoteLatestCards(ctx, tmpMount, acct, v.RemoteID, limit); err == nil {
|
||||
remotePayloads[i].Cards = cards
|
||||
}
|
||||
helper.Run(svc.Log, "media.remotePreview", func() {
|
||||
acct := svc.EmbyRemote.AccountByID(ctx, v.AccountID)
|
||||
if acct == nil {
|
||||
return
|
||||
}
|
||||
tmpMount := &model.EmbyMount{Base: model.Base{ID: v.MountID}}
|
||||
itemTypes := remoteLibraryItemTypes(v.CollectionType)
|
||||
if _, total, err := svc.EmbyRemote.RemoteLibraryMedia(ctx, tmpMount, acct, v.RemoteID, itemTypes, 0, 1); err == nil {
|
||||
remotePayloads[i].Total = total
|
||||
}
|
||||
if cards, err := svc.EmbyRemote.RemoteLatestCards(ctx, tmpMount, acct, v.RemoteID, limit); err == nil {
|
||||
remotePayloads[i].Cards = cards
|
||||
}
|
||||
})
|
||||
}()
|
||||
}
|
||||
wg.Wait()
|
||||
@@ -325,7 +368,11 @@ func deleteLibraryHandler(svc *service.Container) gin.HandlerFunc {
|
||||
}
|
||||
uid, _ := c.Get("ctx_user_id")
|
||||
svc.Audit.Record(c.Request.Context(), toString(uid), "library.delete", id, c.ClientIP(), "")
|
||||
go func() { _ = svc.Watcher.Refresh(context.Background()) }()
|
||||
// goroutine 内的 panic 无法被 gin.Recovery 捕获，会直接崩掉进程：
|
||||
// 与其他调用点一致先判空。
|
||||
if svc.Watcher != nil {
|
||||
go func() { _ = svc.Watcher.Refresh(context.Background()) }()
|
||||
}
|
||||
c.Status(http.StatusNoContent)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -7,6 +7,7 @@ import (
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/helper"
|
||||
"github.com/truewhile/MeBox/internal/service"
|
||||
)
|
||||
|
||||
@@ -41,7 +42,11 @@ func scanLibraryHandler(svc *service.Container) gin.HandlerFunc {
|
||||
task := startScanHTTPTask(svc, "手动扫描入库", lib.Name, lib.Path)
|
||||
go func(libraryID string, task *service.TaskHandle, finish func()) {
|
||||
defer finish()
|
||||
res, err := svc.Scan.ScanLibrary(context.Background(), libraryID)
|
||||
var res *service.ScanResult
|
||||
var err error
|
||||
helper.Run(svc.Log, "scan.library", func() {
|
||||
res, err = svc.Scan.ScanLibrary(context.Background(), libraryID)
|
||||
})
|
||||
if err != nil {
|
||||
finishHTTPTask(task, err, "scan", "手动扫描入库失败", scanTaskMetrics(res), scanTaskDetails(res, 20))
|
||||
return
|
||||
@@ -75,7 +80,11 @@ func scanLibraryRootHandler(svc *service.Container) gin.HandlerFunc {
|
||||
task := startScanHTTPTask(svc, "手动扫描媒体库路径", id, rootID)
|
||||
go func(libraryID, libraryRootID string, task *service.TaskHandle, finish func()) {
|
||||
defer finish()
|
||||
res, err := svc.Scan.ScanLibraryRoot(context.Background(), libraryID, libraryRootID)
|
||||
var res *service.ScanResult
|
||||
var err error
|
||||
helper.Run(svc.Log, "scan.libraryRoot", func() {
|
||||
res, err = svc.Scan.ScanLibraryRoot(context.Background(), libraryID, libraryRootID)
|
||||
})
|
||||
if err != nil {
|
||||
finishHTTPTask(task, err, "scan", "手动扫描路径失败", scanTaskMetrics(res), scanTaskDetails(res, 20))
|
||||
return
|
||||
@@ -110,11 +119,13 @@ func queueLibraryRootScan(svc *service.Container, libraryID, rootID string) {
|
||||
}
|
||||
go func() {
|
||||
defer finish()
|
||||
if strings.TrimSpace(rootID) == "" {
|
||||
_, _ = svc.Scan.ScanLibrary(context.Background(), libraryID)
|
||||
return
|
||||
}
|
||||
_, _ = svc.Scan.ScanLibraryRoot(context.Background(), libraryID, rootID)
|
||||
helper.Run(svc.Log, "scan.queuedRoot", func() {
|
||||
if strings.TrimSpace(rootID) == "" {
|
||||
_, _ = svc.Scan.ScanLibrary(context.Background(), libraryID)
|
||||
return
|
||||
}
|
||||
_, _ = svc.Scan.ScanLibraryRoot(context.Background(), libraryID, rootID)
|
||||
})
|
||||
}()
|
||||
}
|
||||
|
||||
|
||||
@@ -104,11 +104,16 @@ func TestListLibrariesHidesAdultDirectoriesUnlessAdminRequestsAll(t *testing.T)
|
||||
t.Fatalf("watching library list should hide adult directories, got %#v", visible)
|
||||
}
|
||||
|
||||
all := requestLibraries(t, svc, viewer.ID, "admin", "/api/libraries?include_hidden=1")
|
||||
if len(all) != 2 {
|
||||
t.Fatalf("admin include_hidden list should keep management access, got %#v", all)
|
||||
all := requestLibraries(t, svc, viewer.ID, "admin", "/api/libraries?include_hidden=1")
|
||||
if len(all) != 2 {
|
||||
t.Fatalf("admin include_hidden list should keep management access, got %#v", all)
|
||||
}
|
||||
|
||||
filtered := requestLibraries(t, svc, viewer.ID, "admin", "/api/libraries?include_hidden=1&ids="+safe.ID)
|
||||
if len(filtered) != 1 || filtered[0].ID != safe.ID {
|
||||
t.Fatalf("ids filter should return only requested library, got %#v", filtered)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestGetLibraryAllowsEmptyLibrary(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
package handler
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"net/http"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"gorm.io/gorm"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/middleware"
|
||||
"github.com/truewhile/MeBox/internal/service"
|
||||
@@ -157,6 +159,25 @@ type playlistItemReq struct {
|
||||
MediaID string `json:"media_id" binding:"required"`
|
||||
}
|
||||
|
||||
// playlistWriteGuard 校验当前用户对播放列表的写权限（属主或 admin）。
|
||||
// 校验失败时已写入错误响应，调用方直接 return。
|
||||
func playlistWriteGuard(c *gin.Context, svc *service.Container, playlistID string) (string, bool, bool) {
|
||||
uid, _ := c.Get(middleware.CtxUserID)
|
||||
role, _ := c.Get(middleware.CtxUserRole)
|
||||
isAdmin := role == "admin"
|
||||
if err := svc.Playback.EnsurePlaylistOwner(c.Request.Context(), playlistID, uid.(string), isAdmin); err != nil {
|
||||
if errors.Is(err, service.ErrPlaylistForbidden) {
|
||||
c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
|
||||
} else if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
c.JSON(http.StatusNotFound, gin.H{"error": "playlist not found"})
|
||||
} else {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
}
|
||||
return "", isAdmin, false
|
||||
}
|
||||
return uid.(string), isAdmin, true
|
||||
}
|
||||
|
||||
func addPlaylistItemHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
var req playlistItemReq
|
||||
@@ -164,8 +185,12 @@ func addPlaylistItemHandler(svc *service.Container) gin.HandlerFunc {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
uid, isAdmin, ok := playlistWriteGuard(c, svc, c.Param("id"))
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
if err := svc.Playback.AddToPlaylist(
|
||||
c.Request.Context(), c.Param("id"), req.MediaID,
|
||||
c.Request.Context(), c.Param("id"), uid, req.MediaID, isAdmin,
|
||||
); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
@@ -176,8 +201,12 @@ func addPlaylistItemHandler(svc *service.Container) gin.HandlerFunc {
|
||||
|
||||
func removePlaylistItemHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
uid, isAdmin, ok := playlistWriteGuard(c, svc, c.Param("id"))
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
if err := svc.Playback.RemoveFromPlaylist(
|
||||
c.Request.Context(), c.Param("id"), c.Param("media_id"),
|
||||
c.Request.Context(), c.Param("id"), uid, c.Param("media_id"), isAdmin,
|
||||
); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
@@ -188,8 +217,12 @@ func removePlaylistItemHandler(svc *service.Container) gin.HandlerFunc {
|
||||
|
||||
func deletePlaylistHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
uid, isAdmin, ok := playlistWriteGuard(c, svc, c.Param("id"))
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
if err := svc.Playback.DeletePlaylist(
|
||||
c.Request.Context(), c.Param("id"),
|
||||
c.Request.Context(), c.Param("id"), uid, isAdmin,
|
||||
); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
|
||||
@@ -27,6 +27,9 @@ func reorderPlaylistHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return
|
||||
}
|
||||
pid := c.Param("id")
|
||||
if _, _, ok := playlistWriteGuard(c, svc, pid); !ok {
|
||||
return
|
||||
}
|
||||
for i, mid := range req.Order {
|
||||
if err := svc.Repo.DB.WithContext(c.Request.Context()).
|
||||
Model(&model.PlaylistItem{}).
|
||||
@@ -44,8 +47,12 @@ func reorderPlaylistHandler(svc *service.Container) gin.HandlerFunc {
|
||||
// /playlists/:id/items/:item_id (vs. the existing /:media_id variant).
|
||||
func deletePlaylistItemByIDHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
pid := c.Param("id")
|
||||
if _, _, ok := playlistWriteGuard(c, svc, pid); !ok {
|
||||
return
|
||||
}
|
||||
if err := svc.Repo.DB.WithContext(c.Request.Context()).
|
||||
Where("playlist_id = ? AND id = ?", c.Param("id"), c.Param("item_id")).
|
||||
Where("playlist_id = ? AND id = ?", pid, c.Param("item_id")).
|
||||
Delete(&model.PlaylistItem{}).Error; err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
return
|
||||
|
||||
@@ -14,9 +14,14 @@ import (
|
||||
)
|
||||
|
||||
// statsUserHandler returns a watch-time summary for one user.
|
||||
// 观看统计是隐私数据：仅允许本人或管理员查询。
|
||||
func statsUserHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
uid := c.Param("id")
|
||||
if !statsCallerAllowed(c, uid) {
|
||||
c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
|
||||
return
|
||||
}
|
||||
var watched int64
|
||||
_ = svc.Repo.DB.Model(&model.PlaybackHistory{}).
|
||||
Where("user_id = ?", uid).
|
||||
@@ -35,8 +40,14 @@ func statsUserHandler(svc *service.Container) gin.HandlerFunc {
|
||||
}
|
||||
|
||||
// statsTopUsersHandler returns the most active users by play count.
|
||||
// 全员排行含用户名与精确时长，仅管理员可查。
|
||||
func statsTopUsersHandler(svc *service.Container) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
role, _ := c.Get(middleware.CtxUserRole)
|
||||
if role != "admin" {
|
||||
c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
|
||||
return
|
||||
}
|
||||
limit, _ := strconv.Atoi(c.DefaultQuery("limit", "10"))
|
||||
if limit <= 0 || limit > 50 {
|
||||
limit = 10
|
||||
@@ -109,3 +120,13 @@ func statsPlayHandler(svc *service.Container) gin.HandlerFunc {
|
||||
c.JSON(http.StatusOK, gin.H{"ok": true})
|
||||
}
|
||||
}
|
||||
|
||||
// statsCallerAllowed 判断当前调用者是否允许查看 uid 的观看统计。
|
||||
func statsCallerAllowed(c *gin.Context, uid string) bool {
|
||||
role, _ := c.Get(middleware.CtxUserRole)
|
||||
if role == "admin" {
|
||||
return true
|
||||
}
|
||||
caller, _ := c.Get(middleware.CtxUserID)
|
||||
return toString(caller) == uid
|
||||
}
|
||||
|
||||
@@ -39,11 +39,16 @@ func listSystemConfigHandler(svc *service.Container) gin.HandlerFunc {
|
||||
}
|
||||
|
||||
func isSecretKey(k string) bool {
|
||||
for _, suffix := range []string{".token", ".secret", ".password", ".api_key", ".cookie"} {
|
||||
for _, suffix := range []string{".token", ".secret", ".password", ".api_key", ".cookie", ".pin"} {
|
||||
if endsWith(k, suffix) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
// 非后缀型敏感键：可触发服务端任意命令的更新命令等。
|
||||
switch k {
|
||||
case "system.update.command":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
|
||||
+17
-4
@@ -9,6 +9,8 @@ package handler
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
@@ -21,10 +23,21 @@ import (
|
||||
var wsUpgrader = websocket.Upgrader{
|
||||
ReadBufferSize: 1024,
|
||||
WriteBufferSize: 1024,
|
||||
// Allow any origin: the AuthRequired middleware already validated the
|
||||
// JWT before we got here, and we never serve sensitive cross-domain
|
||||
// state through the socket.
|
||||
CheckOrigin: func(_ *http.Request) bool { return true },
|
||||
// 同源校验：浏览器跨站页面虽读不到 ?token=，但可能借 cookie 通道
|
||||
// （extractToken 接受 msgo_access_token cookie）发起跨站 WebSocket
|
||||
// 劫持。放行同源与非浏览器客户端（不发 Origin 头的 App/脚本），
|
||||
// 拒绝跨站 Origin。
|
||||
CheckOrigin: func(r *http.Request) bool {
|
||||
origin := strings.TrimSpace(r.Header.Get("Origin"))
|
||||
if origin == "" {
|
||||
return true
|
||||
}
|
||||
u, err := url.Parse(origin)
|
||||
if err != nil || u.Host == "" {
|
||||
return false
|
||||
}
|
||||
return strings.EqualFold(u.Host, r.Host)
|
||||
},
|
||||
}
|
||||
|
||||
func wsHandler(svc *service.Container) gin.HandlerFunc {
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
// Package helper provides shared utilities.
|
||||
package helper
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"runtime/debug"
|
||||
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// Go runs fn in a new goroutine and recovers from panics so that a failure in
|
||||
// a background task (scraper parsing remote responses, cloud-drive sync, ...)
|
||||
// is logged instead of crashing the whole process. log may be nil.
|
||||
func Go(log *zap.Logger, name string, fn func()) {
|
||||
go Run(log, name, fn)
|
||||
}
|
||||
|
||||
// Run executes fn and recovers from panics, logging the task name and stack.
|
||||
// Use it as the first statement inside goroutines spawned elsewhere, or wrap
|
||||
// loop bodies so one bad iteration cannot kill a long-running worker.
|
||||
func Run(log *zap.Logger, name string, fn func()) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
logPanic(log, name, r)
|
||||
}
|
||||
}()
|
||||
fn()
|
||||
}
|
||||
|
||||
// Recover runs fn and converts a panic into an error so callers can run their
|
||||
// own deferred cleanup (releasing locks, updating job state) before unwinding.
|
||||
func Recover(log *zap.Logger, name string, fn func() error) (err error) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
logPanic(log, name, r)
|
||||
err = fmt.Errorf("%s panicked: %v", name, r)
|
||||
}
|
||||
}()
|
||||
return fn()
|
||||
}
|
||||
|
||||
func logPanic(log *zap.Logger, name string, r any) {
|
||||
if log == nil {
|
||||
fmt.Fprintf(os.Stderr, "background task panicked: task=%s panic=%v\n%s\n", name, r, debug.Stack())
|
||||
return
|
||||
}
|
||||
log.Error("background task panicked",
|
||||
zap.String("task", name),
|
||||
zap.Any("panic", r),
|
||||
zap.ByteString("stack", debug.Stack()),
|
||||
)
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
package helper
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"go.uber.org/zap"
|
||||
"go.uber.org/zap/zaptest/observer"
|
||||
)
|
||||
|
||||
func newObservedLogger(t *testing.T) (*zap.Logger, *observer.ObservedLogs) {
|
||||
t.Helper()
|
||||
core, logs := observer.New(zap.ErrorLevel)
|
||||
return zap.New(core), logs
|
||||
}
|
||||
|
||||
func waitForLogs(t *testing.T, logs *observer.ObservedLogs, n int) []observer.LoggedEntry {
|
||||
t.Helper()
|
||||
deadline := time.Now().Add(2 * time.Second)
|
||||
for time.Now().Before(deadline) {
|
||||
if entries := logs.All(); len(entries) >= n {
|
||||
return entries
|
||||
}
|
||||
time.Sleep(5 * time.Millisecond)
|
||||
}
|
||||
t.Fatalf("timed out waiting for %d log entries, got %d", n, logs.Len())
|
||||
return nil
|
||||
}
|
||||
|
||||
func TestRunRecoversPanic(t *testing.T) {
|
||||
log, logs := newObservedLogger(t)
|
||||
ran := false
|
||||
Run(log, "unit.panic", func() {
|
||||
ran = true
|
||||
panic("boom")
|
||||
})
|
||||
if !ran {
|
||||
t.Fatal("fn should have run before panicking")
|
||||
}
|
||||
entries := waitForLogs(t, logs, 1)
|
||||
if entries[0].Message != "background task panicked" {
|
||||
t.Fatalf("unexpected message: %s", entries[0].Message)
|
||||
}
|
||||
found := false
|
||||
for _, f := range entries[0].Context {
|
||||
if f.Key == "task" && f.String == "unit.panic" {
|
||||
found = true
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Fatalf("expected task name in log context: %v", entries[0].Context)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunNoPanicNoLog(t *testing.T) {
|
||||
log, logs := newObservedLogger(t)
|
||||
Run(log, "unit.ok", func() {})
|
||||
time.Sleep(10 * time.Millisecond)
|
||||
if logs.Len() != 0 {
|
||||
t.Fatalf("expected no error log, got %d", logs.Len())
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecoverConvertsPanicToError(t *testing.T) {
|
||||
log, _ := newObservedLogger(t)
|
||||
err := Recover(log, "unit.recover", func() error {
|
||||
panic("kaboom")
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected error from recovered panic")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "kaboom") {
|
||||
t.Fatalf("panic value should be in error: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecoverReturnsFnError(t *testing.T) {
|
||||
sentinel := errors.New("plain failure")
|
||||
err := Recover(nil, "unit.err", func() error { return sentinel })
|
||||
if !errors.Is(err, sentinel) {
|
||||
t.Fatalf("expected fn error, got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunWithNilLoggerDoesNotCrash(t *testing.T) {
|
||||
Run(nil, "unit.nillog", func() { panic("still caught") })
|
||||
}
|
||||
|
||||
func TestGoLogsPanicFromSpawnedGoroutine(t *testing.T) {
|
||||
log, logs := newObservedLogger(t)
|
||||
Go(log, "unit.go", func() { panic("async boom") })
|
||||
waitForLogs(t, logs, 1)
|
||||
}
|
||||
@@ -51,6 +51,19 @@ func EmbyAuthRequired(secret string) gin.HandlerFunc {
|
||||
return
|
||||
}
|
||||
|
||||
// 用途限定令牌（如 external_play，签发给外链播放器且绑定单一
|
||||
// media）只允许走 /api/stream|/hls|/cloud/play，绝不能作为全功能
|
||||
// 凭据访问 Emby 兼容面；否则外链 URL 一旦泄漏，持有者可获得
|
||||
// 该用户最长 24h 的全部 Emby API 权限。
|
||||
if strings.TrimSpace(claims.Purpose) != "" {
|
||||
c.JSON(http.StatusUnauthorized, gin.H{
|
||||
"Code": 40101,
|
||||
"Message": "Invalid token",
|
||||
})
|
||||
c.Abort()
|
||||
return
|
||||
}
|
||||
|
||||
c.Set(EmbyCtxUserID, claims.UserID)
|
||||
c.Set(CtxUserID, claims.UserID)
|
||||
c.Set(CtxUserRole, claims.Role)
|
||||
|
||||
@@ -16,6 +16,8 @@ type RateLimiter struct {
|
||||
window time.Duration
|
||||
max int
|
||||
requests map[string][]time.Time
|
||||
stop chan struct{}
|
||||
stopped sync.Once
|
||||
}
|
||||
|
||||
// NewRateLimiter creates a rate limiter allowing max requests per window
|
||||
@@ -25,14 +27,27 @@ func NewRateLimiter(max int, window time.Duration) *RateLimiter {
|
||||
window: window,
|
||||
max: max,
|
||||
requests: make(map[string][]time.Time),
|
||||
stop: make(chan struct{}),
|
||||
}
|
||||
go rl.cleanup()
|
||||
return rl
|
||||
}
|
||||
|
||||
// Close 停止后台清理 goroutine：清理循环此前无停止机制，每建一个实例
|
||||
// 就永久滞留一条 goroutine（测试场景会随实例创建不断累积）。
|
||||
func (rl *RateLimiter) Close() {
|
||||
rl.stopped.Do(func() { close(rl.stop) })
|
||||
}
|
||||
|
||||
func (rl *RateLimiter) cleanup() {
|
||||
ticker := time.NewTicker(5 * time.Minute)
|
||||
defer ticker.Stop()
|
||||
for {
|
||||
time.Sleep(5 * time.Minute)
|
||||
select {
|
||||
case <-rl.stop:
|
||||
return
|
||||
case <-ticker.C:
|
||||
}
|
||||
rl.mu.Lock()
|
||||
now := time.Now()
|
||||
for ip, times := range rl.requests {
|
||||
|
||||
@@ -5,15 +5,22 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
// ApiConfig 存储第三方 API 密钥和配置信息。
|
||||
// APIKey 字段在 JSON 序列化时隐藏（json:"-"），通过加密存储。
|
||||
type ApiConfig struct {
|
||||
// APIConfig 存储第三方 API 密钥和配置信息。
|
||||
// APIKey 字段在 JSON 序列化时隐藏（json:"-"），通过加密存储（AES-GCM 密文，
|
||||
// base64 后常超 512 字符，因此必须是 text 而非 varchar(512)）。
|
||||
//
|
||||
// NOTE: 历史上曾有 APIConfig / ApiConfig 两个结构体映射到同一张 api_configs
|
||||
// 表，AutoMigrate 每次启动互相改列（provider/api_key 长度来回切换），且
|
||||
// varchar(512) 收窄会让长密文入库后下一次启动迁移直接失败。现已合并为本
|
||||
// 结构体，字段取两者并集，请勿再拆分。
|
||||
type APIConfig struct {
|
||||
Base
|
||||
Provider string `gorm:"size:64;uniqueIndex;not null" json:"provider"`
|
||||
APIKey string `gorm:"size:512" json:"-"`
|
||||
BaseURL string `gorm:"size:512" json:"base_url,omitempty"`
|
||||
Extra string `gorm:"type:text" json:"extra,omitempty"`
|
||||
Enabled bool `gorm:"default:true" json:"enabled"`
|
||||
Provider string `gorm:"uniqueIndex;size:64;not null" json:"provider"`
|
||||
APIKey string `gorm:"type:text" json:"-"` // ciphertext (never serialised)
|
||||
BaseURL string `gorm:"size:512" json:"base_url,omitempty"`
|
||||
Extra string `gorm:"type:text" json:"extra,omitempty"` // free-form JSON
|
||||
Enabled bool `gorm:"default:true" json:"enabled"`
|
||||
|
||||
Description string `gorm:"size:255" json:"description,omitempty"`
|
||||
LastTestedAt *time.Time `json:"last_tested_at,omitempty"`
|
||||
TestResult string `gorm:"size:32" json:"test_result,omitempty"`
|
||||
|
||||
@@ -1,23 +1,8 @@
|
||||
package model
|
||||
|
||||
// APIConfig stores third-party data-source configuration. The api_key
|
||||
// column is encrypted with AES-GCM (see internal/service/crypto.go) so an
|
||||
// SQLite leak does not expose third-party credentials.
|
||||
//
|
||||
// Provider values mirror the original Python project:
|
||||
//
|
||||
// tmdb — themoviedb.org
|
||||
// bangumi — bgm.tv
|
||||
// thetvdb — thetvdb.com
|
||||
// fanart — fanart.tv
|
||||
// douban — douban.com (cookie)
|
||||
// openai — OpenAI / DeepSeek / Qwen / Ollama (compatible)
|
||||
type APIConfig struct {
|
||||
Base
|
||||
Provider string `gorm:"uniqueIndex;size:32;not null" json:"provider"`
|
||||
APIKey string `gorm:"type:text" json:"-"` // ciphertext (never serialised)
|
||||
BaseURL string `gorm:"size:512" json:"base_url,omitempty"`
|
||||
Extra string `gorm:"type:text" json:"extra,omitempty"` // free-form JSON
|
||||
Enabled bool `gorm:"default:true" json:"enabled"`
|
||||
Description string `gorm:"size:255" json:"description,omitempty"`
|
||||
}
|
||||
// NOTE: 原 APIConfig（provider varchar(32) / api_key text）与 api_config.go
|
||||
// 里的 ApiConfig（provider varchar(64) / api_key varchar(512)）映射到同一张
|
||||
// api_configs 表，AutoMigrate 每次启动互相改列；且 api_key 被收窄成
|
||||
// varchar(512) 后，成人区/豆瓣等存的长 AES-GCM Cookie 密文一旦入库，下次
|
||||
// 启动迁移即失败、服务无法启动。两者已合并为 api_config.go 中唯一的
|
||||
// APIConfig 结构体（字段取并集），此处不再定义重复模型。
|
||||
|
||||
@@ -26,7 +26,7 @@ type LibraryRoot struct {
|
||||
// Media 是单个可播放项。剧集链接到 SeriesID；电影 SeriesID == ""。
|
||||
type Media struct {
|
||||
Base
|
||||
LibraryID string `gorm:"index;size:36" json:"library_id"`
|
||||
LibraryID string `gorm:"index;size:36;index:idx_media_library_release,priority:1" json:"library_id"`
|
||||
LibraryRootID string `gorm:"index;size:36" json:"library_root_id,omitempty"`
|
||||
SeriesID string `gorm:"index;size:128" json:"series_id,omitempty"`
|
||||
Title string `gorm:"size:255;not null" json:"title"`
|
||||
@@ -46,7 +46,7 @@ type Media struct {
|
||||
Overview string `gorm:"type:text" json:"overview,omitempty"`
|
||||
Rating float32 `json:"rating"`
|
||||
Year int `json:"year"`
|
||||
ReleaseDate string `gorm:"size:10;index" json:"release_date,omitempty"`
|
||||
ReleaseDate string `gorm:"size:10;index:idx_media_library_release,priority:2" json:"release_date,omitempty"`
|
||||
SeasonNum int `json:"season_num"`
|
||||
EpisodeNum int `json:"episode_num"`
|
||||
ScrapeStatus string `gorm:"size:16;default:pending" json:"scrape_status"`
|
||||
|
||||
@@ -46,7 +46,6 @@ func AllModels() []interface{} {
|
||||
&APIConfig{},
|
||||
&UserPermission{},
|
||||
&RefreshToken{},
|
||||
&ApiConfig{},
|
||||
&PlayProfile{},
|
||||
&RegistrationCode{},
|
||||
&SignIn{},
|
||||
|
||||
@@ -3,10 +3,12 @@ package model
|
||||
import "time"
|
||||
|
||||
// PlaybackHistory 记录当前播放位置以支持续播。
|
||||
// (user_id, media_id) 唯一：播放进度每几秒上报一次，唯一索引保证并发上报
|
||||
// 不会插入重复行（否则续播列表会出现重复卡片），也让 upsert 单语句完成。
|
||||
type PlaybackHistory struct {
|
||||
Base
|
||||
UserID string `gorm:"index;size:36;not null" json:"user_id"`
|
||||
MediaID string `gorm:"index;size:128;not null" json:"media_id"`
|
||||
UserID string `gorm:"index;size:36;not null;uniqueIndex:uniq_user_history" json:"user_id"`
|
||||
MediaID string `gorm:"index;size:128;not null;uniqueIndex:uniq_user_history" json:"media_id"`
|
||||
PositionMs int64 `json:"position_ms"`
|
||||
DurationMs int64 `json:"duration_ms"`
|
||||
WatchedAt time.Time `json:"watched_at"`
|
||||
|
||||
@@ -124,6 +124,7 @@ type StrmUploadTask struct {
|
||||
FileName string `gorm:"size:512" json:"file_name"`
|
||||
LocalPath string `gorm:"size:1024" json:"local_path"` // 本地源文件
|
||||
RemotePath string `gorm:"size:1024" json:"remote_path"` // 远端目标路径
|
||||
RemoteRef string `gorm:"size:1024" json:"remote_ref"` // 远端同名旧文件引用（115 文件 ID；上传覆盖前先删除旧文件，WebDAV/OpenList 直接覆盖无需删除）
|
||||
Size int64 `json:"size"`
|
||||
Status string `gorm:"size:16;index" json:"status"`
|
||||
Error string `gorm:"size:1024" json:"error"`
|
||||
|
||||
@@ -10,17 +10,17 @@ import (
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
)
|
||||
|
||||
// ApiConfigRepository persists model.ApiConfig records.
|
||||
// ApiConfigRepository persists model.APIConfig records.
|
||||
type ApiConfigRepository struct{ db *gorm.DB }
|
||||
|
||||
// Create inserts a new API config record.
|
||||
func (r *ApiConfigRepository) Create(ctx context.Context, c *model.ApiConfig) error {
|
||||
func (r *ApiConfigRepository) Create(ctx context.Context, c *model.APIConfig) error {
|
||||
return r.db.WithContext(ctx).Create(c).Error
|
||||
}
|
||||
|
||||
// FindByProvider returns the API config for a provider, or (nil, nil).
|
||||
func (r *ApiConfigRepository) FindByProvider(ctx context.Context, provider string) (*model.ApiConfig, error) {
|
||||
var c model.ApiConfig
|
||||
func (r *ApiConfigRepository) FindByProvider(ctx context.Context, provider string) (*model.APIConfig, error) {
|
||||
var c model.APIConfig
|
||||
err := r.db.WithContext(ctx).Where("provider = ?", provider).First(&c).Error
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, nil
|
||||
@@ -32,27 +32,40 @@ func (r *ApiConfigRepository) FindByProvider(ctx context.Context, provider strin
|
||||
}
|
||||
|
||||
// List returns all API configs.
|
||||
func (r *ApiConfigRepository) List(ctx context.Context) ([]model.ApiConfig, error) {
|
||||
var rows []model.ApiConfig
|
||||
func (r *ApiConfigRepository) List(ctx context.Context) ([]model.APIConfig, error) {
|
||||
var rows []model.APIConfig
|
||||
err := r.db.WithContext(ctx).Order("provider asc").Find(&rows).Error
|
||||
return rows, err
|
||||
}
|
||||
|
||||
// Upsert creates or updates an API config.
|
||||
func (r *ApiConfigRepository) Upsert(ctx context.Context, c *model.ApiConfig) error {
|
||||
return r.db.WithContext(ctx).Where("provider = ?", c.Provider).
|
||||
Assign(model.ApiConfig{
|
||||
Base: model.Base{UpdatedAt: time.Now()},
|
||||
APIKey: c.APIKey,
|
||||
BaseURL: c.BaseURL,
|
||||
Extra: c.Extra,
|
||||
Enabled: c.Enabled,
|
||||
}).FirstOrCreate(c).Error
|
||||
// 显式 map 更新：Assign(struct) 会跳过零值字段，导致 Enabled=false、
|
||||
// 清空 BaseURL/Extra 等撤销操作静默失效。
|
||||
func (r *ApiConfigRepository) Upsert(ctx context.Context, c *model.APIConfig) error {
|
||||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||||
var existing model.APIConfig
|
||||
err := tx.Where("provider = ?", c.Provider).First(&existing).Error
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return tx.Create(c).Error
|
||||
}
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
c.ID = existing.ID
|
||||
c.CreatedAt = existing.CreatedAt
|
||||
return tx.Model(&existing).Updates(map[string]any{
|
||||
"api_key": c.APIKey,
|
||||
"base_url": c.BaseURL,
|
||||
"extra": c.Extra,
|
||||
"enabled": c.Enabled,
|
||||
"updated_at": time.Now(),
|
||||
}).Error
|
||||
})
|
||||
}
|
||||
|
||||
// Update updates an API config.
|
||||
func (r *ApiConfigRepository) Update(ctx context.Context, c *model.ApiConfig) error {
|
||||
return r.db.WithContext(ctx).Model(&model.ApiConfig{}).
|
||||
func (r *ApiConfigRepository) Update(ctx context.Context, c *model.APIConfig) error {
|
||||
return r.db.WithContext(ctx).Model(&model.APIConfig{}).
|
||||
Where("provider = ?", c.Provider).Updates(map[string]any{
|
||||
"api_key": c.APIKey,
|
||||
"base_url": c.BaseURL,
|
||||
@@ -64,13 +77,13 @@ func (r *ApiConfigRepository) Update(ctx context.Context, c *model.ApiConfig) er
|
||||
|
||||
// Delete 物理删除 API 配置。
|
||||
func (r *ApiConfigRepository) Delete(ctx context.Context, provider string) error {
|
||||
return r.db.WithContext(ctx).Unscoped().Where("provider = ?", provider).Delete(&model.ApiConfig{}).Error
|
||||
return r.db.WithContext(ctx).Unscoped().Where("provider = ?", provider).Delete(&model.APIConfig{}).Error
|
||||
}
|
||||
|
||||
// UpdateTestResult 更新测试结果。
|
||||
func (r *ApiConfigRepository) UpdateTestResult(ctx context.Context, provider, result string) error {
|
||||
now := time.Now()
|
||||
return r.db.WithContext(ctx).Model(&model.ApiConfig{}).
|
||||
return r.db.WithContext(ctx).Model(&model.APIConfig{}).
|
||||
Where("provider = ?", provider).Updates(map[string]any{
|
||||
"test_result": result,
|
||||
"last_tested_at": &now,
|
||||
|
||||
@@ -125,3 +125,16 @@ func (r *EmbyMountRepository) DeleteByAccountID(ctx context.Context, accountID s
|
||||
})
|
||||
return count, err
|
||||
}
|
||||
|
||||
// DeleteOrphans 清理账号已不存在的挂载（老版本删除账号未级联的历史残留）。
|
||||
func (r *EmbyMountRepository) DeleteOrphans(ctx context.Context) (int64, error) {
|
||||
var count int64
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
res := r.db.WithContext(ctx).
|
||||
Where("account_id NOT IN (SELECT id FROM strm_accounts)").
|
||||
Delete(&model.EmbyMount{})
|
||||
count = res.RowsAffected
|
||||
return res.Error
|
||||
})
|
||||
return count, err
|
||||
}
|
||||
|
||||
@@ -2,9 +2,9 @@ package repository
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
|
||||
"gorm.io/gorm"
|
||||
"gorm.io/gorm/clause"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
)
|
||||
@@ -13,25 +13,24 @@ import (
|
||||
// upserts on (UserID, MediaID) so resume always reads the latest position.
|
||||
type HistoryRepository struct{ db *gorm.DB }
|
||||
|
||||
// Upsert atomically inserts/updates the resume position.
|
||||
// Upsert atomically inserts/updates the resume position in a single statement,
|
||||
// relying on the uniq_user_history composite unique index. Concurrent progress
|
||||
// reports for the same (user, media) can no longer double-insert.
|
||||
func (r *HistoryRepository) Upsert(ctx context.Context, h *model.PlaybackHistory) error {
|
||||
var existing model.PlaybackHistory
|
||||
err := r.db.WithContext(ctx).
|
||||
Where("user_id = ? AND media_id = ?", h.UserID, h.MediaID).
|
||||
First(&existing).Error
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return r.db.WithContext(ctx).Create(h).Error
|
||||
}
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
existing.PositionMs = h.PositionMs
|
||||
if h.DurationMs > 0 {
|
||||
existing.DurationMs = h.DurationMs
|
||||
}
|
||||
existing.WatchedAt = h.WatchedAt
|
||||
existing.Completed = h.Completed
|
||||
return r.db.WithContext(ctx).Save(&existing).Error
|
||||
return r.db.WithContext(ctx).Clauses(clause.OnConflict{
|
||||
Columns: []clause.Column{{Name: "user_id"}, {Name: "media_id"}},
|
||||
DoUpdates: clause.Assignments(map[string]any{
|
||||
"position_ms": h.PositionMs,
|
||||
// 沿用旧语义：未知时长（0）不覆盖已记录的时长。
|
||||
"duration_ms": gorm.Expr(
|
||||
"CASE WHEN ? > 0 THEN ? ELSE playback_histories.duration_ms END",
|
||||
h.DurationMs, h.DurationMs,
|
||||
),
|
||||
"watched_at": h.WatchedAt,
|
||||
"completed": h.Completed,
|
||||
"deleted_at": nil,
|
||||
}),
|
||||
}).Create(h).Error
|
||||
}
|
||||
|
||||
// ListByUser returns the most recent history rows for the user.
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
package repository
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/glebarez/sqlite"
|
||||
"gorm.io/gorm"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/database"
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
)
|
||||
|
||||
func TestHistoryUpsertSingleRowPerUserMedia(t *testing.T) {
|
||||
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := database.AutoMigrate(db); err != nil {
|
||||
t.Fatalf("migrate: %v", err)
|
||||
}
|
||||
repos := New(db)
|
||||
ctx := t.Context()
|
||||
watched := time.Now()
|
||||
|
||||
first := &model.PlaybackHistory{UserID: "u-1", MediaID: "m-1", PositionMs: 30_000, DurationMs: 0, WatchedAt: watched, Completed: false}
|
||||
if err := repos.History.Upsert(ctx, first); err != nil {
|
||||
t.Fatalf("first upsert: %v", err)
|
||||
}
|
||||
second := &model.PlaybackHistory{UserID: "u-1", MediaID: "m-1", PositionMs: 90_000, DurationMs: 120_000, WatchedAt: watched.Add(time.Minute), Completed: true}
|
||||
if err := repos.History.Upsert(ctx, second); err != nil {
|
||||
t.Fatalf("second upsert: %v", err)
|
||||
}
|
||||
|
||||
var count int64
|
||||
if err := db.Model(&model.PlaybackHistory{}).Where("user_id = ? AND media_id = ?", "u-1", "m-1").Count(&count).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if count != 1 {
|
||||
t.Fatalf("expected 1 history row after upserts, got %d", count)
|
||||
}
|
||||
var got model.PlaybackHistory
|
||||
if err := db.Where("user_id = ? AND media_id = ?", "u-1", "m-1").First(&got).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got.PositionMs != 90_000 || !got.Completed {
|
||||
t.Fatalf("position/completion not updated: %#v", got)
|
||||
}
|
||||
if got.DurationMs != 120_000 {
|
||||
t.Fatalf("duration should update when known, got %d", got.DurationMs)
|
||||
}
|
||||
}
|
||||
|
||||
func TestHistoryUpsertKeepsDurationWhenUnknown(t *testing.T) {
|
||||
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := database.AutoMigrate(db); err != nil {
|
||||
t.Fatalf("migrate: %v", err)
|
||||
}
|
||||
repos := New(db)
|
||||
ctx := t.Context()
|
||||
watched := time.Now()
|
||||
|
||||
if err := repos.History.Upsert(ctx, &model.PlaybackHistory{UserID: "u-1", MediaID: "m-2", PositionMs: 10, DurationMs: 600_000, WatchedAt: watched}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := repos.History.Upsert(ctx, &model.PlaybackHistory{UserID: "u-1", MediaID: "m-2", PositionMs: 20, DurationMs: 0, WatchedAt: watched.Add(time.Second)}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var got model.PlaybackHistory
|
||||
if err := db.Where("user_id = ? AND media_id = ?", "u-1", "m-2").First(&got).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got.DurationMs != 600_000 {
|
||||
t.Fatalf("duration_ms=0 upsert must not clear stored duration, got %d", got.DurationMs)
|
||||
}
|
||||
}
|
||||
@@ -22,45 +22,93 @@ import (
|
||||
// 显式写入）。这两个问题都让 EnrichLibrary(WHERE scrape_status='pending')
|
||||
// 永远捞不到数据。
|
||||
func (r *MediaRepository) Upsert(ctx context.Context, m *model.Media) error {
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.upsertWithDB(ctx, r.db, m)
|
||||
var indexIDs []string
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
id, uerr := r.upsertWithDB(ctx, r.db, m)
|
||||
if uerr != nil {
|
||||
return uerr
|
||||
}
|
||||
indexIDs = append(indexIDs[:0], id)
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
r.indexByIDBestEffort(ctx, indexIDs)
|
||||
return nil
|
||||
}
|
||||
|
||||
// UpsertBatch 在单个事务里逐条执行 Upsert：扫描一批只提交（fsync）一次，
|
||||
// 而不是每条一个隐式事务。任一条目落库失败不影响批内已成功的条目——
|
||||
// 事务回滚后由调用方退回逐条 Upsert 兜底。
|
||||
//
|
||||
// OpenSearch 索引同步（HTTP，4s 超时）必须在事务提交之后统一执行：放在
|
||||
// 事务内会把 SQLite 写锁挂起在网络 IO 上，且批内用非事务连接回读只能
|
||||
// 拿到提交前的旧版本数据，把陈旧内容写进索引。
|
||||
func (r *MediaRepository) UpsertBatch(ctx context.Context, items []*model.Media) error {
|
||||
if len(items) == 0 {
|
||||
return nil
|
||||
}
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
indexIDs := make([]string, 0, len(items))
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
indexIDs = indexIDs[:0]
|
||||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||||
for _, m := range items {
|
||||
if m == nil {
|
||||
continue
|
||||
}
|
||||
if err := r.upsertWithDB(ctx, tx, m); err != nil {
|
||||
id, err := r.upsertWithDB(ctx, tx, m)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if id != "" {
|
||||
indexIDs = append(indexIDs, id)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *model.Media) error {
|
||||
existing, created, err := r.findOrCreateMediaByPath(ctx, db, m)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
r.indexByIDBestEffort(ctx, indexIDs)
|
||||
return nil
|
||||
}
|
||||
|
||||
// indexByIDBestEffort 在事务提交后按 ID 回读最新行并同步搜索索引。
|
||||
func (r *MediaRepository) indexByIDBestEffort(ctx context.Context, ids []string) {
|
||||
for _, id := range ids {
|
||||
if id == "" {
|
||||
continue
|
||||
}
|
||||
if fresh, err := r.FindByID(ctx, id); err == nil && fresh != nil {
|
||||
r.indexMediaBestEffort(ctx, *fresh)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// upsertWithDB 落库（新建或更新），返回需要重建索引的媒体 ID（无则空串）。
|
||||
func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *model.Media) (string, error) {
|
||||
existing, created, err := r.findOrCreateMediaByPath(ctx, db, m)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if created {
|
||||
r.indexMediaBestEffort(ctx, *m)
|
||||
return nil
|
||||
return m.ID, nil
|
||||
}
|
||||
|
||||
updates := mediaUpsertUpdates(existing, *m)
|
||||
return r.applyMediaUpsertUpdates(ctx, db, m, existing, updates)
|
||||
if len(updates) == 0 {
|
||||
*m = existing
|
||||
return "", nil
|
||||
}
|
||||
if err := db.WithContext(ctx).Unscoped().Model(&model.Media{}).
|
||||
Where("id = ?", existing.ID).Updates(updates).Error; err != nil {
|
||||
return "", err
|
||||
}
|
||||
// 回写 ID / 不可变字段，让 caller 拿到完整的现有行。
|
||||
*m = existing
|
||||
return existing.ID, nil
|
||||
}
|
||||
|
||||
func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.DB, m *model.Media) (model.Media, bool, error) {
|
||||
@@ -75,6 +123,9 @@ func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.
|
||||
return *m, true, nil
|
||||
} else if retryErr := db.WithContext(ctx).Unscoped().Where("path = ?", m.Path).First(&existing).Error; retryErr != nil {
|
||||
return model.Media{}, false, createErr
|
||||
} else {
|
||||
// 并发插入竞态：重查已命中既有行，直接走更新分支。
|
||||
return existing, false, nil
|
||||
}
|
||||
}
|
||||
if err != nil {
|
||||
@@ -259,24 +310,6 @@ func setNonEmptyMediaString(updates map[string]any, key, current, next string) {
|
||||
}
|
||||
}
|
||||
|
||||
func (r *MediaRepository) applyMediaUpsertUpdates(ctx context.Context, db *gorm.DB, m *model.Media, existing model.Media, updates map[string]any) error {
|
||||
if len(updates) == 0 {
|
||||
*m = existing
|
||||
return nil
|
||||
}
|
||||
if err := db.WithContext(ctx).Unscoped().Model(&model.Media{}).
|
||||
Where("id = ?", existing.ID).Updates(updates).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
// 回写 ID / 不可变字段，让 caller 拿到完整的现有行。
|
||||
*m = existing
|
||||
if fresh, err := r.FindByID(ctx, existing.ID); err == nil && fresh != nil {
|
||||
*m = *fresh
|
||||
r.indexMediaBestEffort(ctx, *fresh)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func setIfChanged[T comparable](updates map[string]any, key string, current, next T) {
|
||||
if current != next {
|
||||
updates[key] = next
|
||||
|
||||
@@ -105,11 +105,17 @@ func (r *MediaRepository) searchFilteredLIKE(ctx context.Context, query string,
|
||||
var total int64
|
||||
q := r.db.WithContext(ctx).Model(&model.Media{})
|
||||
q = applyMediaQueryFilter(q, filter)
|
||||
// SQLite 的 LIKE 对 ASCII 不区分大小写；Postgres 的 LIKE 区分大小写，
|
||||
// 需用 ILIKE 保持两端搜索行为一致。
|
||||
likeOp := "LIKE"
|
||||
if r.db.Dialector != nil && r.db.Dialector.Name() == "postgres" {
|
||||
likeOp = "ILIKE"
|
||||
}
|
||||
terms := mediaSearchTerms(query)
|
||||
for _, term := range terms {
|
||||
like := "%" + escapeLike(term) + "%"
|
||||
q = q.Where(
|
||||
"(title LIKE ? ESCAPE '\\' OR original_name LIKE ? ESCAPE '\\' OR path LIKE ? ESCAPE '\\' OR genres LIKE ? ESCAPE '\\')",
|
||||
"(title "+likeOp+" ? ESCAPE '\\' OR original_name "+likeOp+" ? ESCAPE '\\' OR path "+likeOp+" ? ESCAPE '\\' OR genres "+likeOp+" ? ESCAPE '\\')",
|
||||
like, like, like, like,
|
||||
)
|
||||
}
|
||||
@@ -120,7 +126,7 @@ func (r *MediaRepository) searchFilteredLIKE(ctx context.Context, query string,
|
||||
prefix := escapeLike(query) + "%"
|
||||
exact := query
|
||||
q = q.Order(gorm.Expr(
|
||||
"CASE WHEN title = ? THEN 0 WHEN original_name = ? THEN 1 WHEN title LIKE ? ESCAPE '\\' THEN 2 WHEN original_name LIKE ? ESCAPE '\\' THEN 3 ELSE 4 END, created_at desc",
|
||||
"CASE WHEN title = ? THEN 0 WHEN original_name = ? THEN 1 WHEN title "+likeOp+" ? ESCAPE '\\' THEN 2 WHEN original_name "+likeOp+" ? ESCAPE '\\' THEN 3 ELSE 4 END, created_at desc",
|
||||
exact, exact, prefix, prefix,
|
||||
))
|
||||
} else {
|
||||
@@ -259,7 +265,9 @@ func (r *MediaRepository) searchIndexEnabled(ctx context.Context) bool {
|
||||
}
|
||||
r.searchIndexOnce.Do(func() {
|
||||
var count int64
|
||||
err := r.db.WithContext(ctx).
|
||||
// 用 Background 探测：sync.Once 只执行一次，若借用调用方的
|
||||
// ctx 且恰好被取消，FTS 会被永久误判为不可用。
|
||||
err := r.db.WithContext(context.Background()).
|
||||
Raw(`SELECT COUNT(*) FROM sqlite_master WHERE name = 'media_search_fts'`).
|
||||
Scan(&count).Error
|
||||
r.searchIndexAvailable = err == nil && count > 0
|
||||
|
||||
@@ -3,6 +3,7 @@ package repository
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"time"
|
||||
|
||||
"gorm.io/gorm"
|
||||
|
||||
@@ -44,10 +45,43 @@ func (r *PermissionRepository) Update(ctx context.Context, userID string, update
|
||||
}
|
||||
|
||||
// Upsert creates or updates a permission record.
|
||||
// 显式 map 更新：Assign(struct) 会被 GORM 跳过零值字段，导致权限
|
||||
// "撤销"（false）保存后静默失效且无法重置。
|
||||
func (r *PermissionRepository) Upsert(ctx context.Context, p *model.UserPermission) error {
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.db.WithContext(ctx).Where("user_id = ?", p.UserID).
|
||||
Assign(*p).FirstOrCreate(p).Error
|
||||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||||
var existing model.UserPermission
|
||||
err := tx.Where("user_id = ?", p.UserID).First(&existing).Error
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return tx.Create(p).Error
|
||||
}
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
p.ID = existing.ID
|
||||
p.CreatedAt = existing.CreatedAt
|
||||
return tx.Model(&existing).Updates(map[string]any{
|
||||
"can_view_dashboard": p.CanViewDashboard,
|
||||
"can_play_media": p.CanPlayMedia,
|
||||
"can_cast": p.CanCast,
|
||||
"can_external_player": p.CanExternalPlayer,
|
||||
"can_favorite": p.CanFavorite,
|
||||
"can_view_history": p.CanViewHistory,
|
||||
"can_edit_media": p.CanEditMedia,
|
||||
"can_rescrape": p.CanRescrape,
|
||||
"can_use_ai": p.CanUseAI,
|
||||
"can_capture_frames": p.CanCaptureFrames,
|
||||
"can_manage_downloads": p.CanManageDownloads,
|
||||
"can_manage_subscriptions": p.CanManageSubscriptions,
|
||||
"can_manage_sites": p.CanManageSites,
|
||||
"can_use_ai_assistant": p.CanUseAIAssistant,
|
||||
"can_manage_users": p.CanManageUsers,
|
||||
"can_manage_files": p.CanManageFiles,
|
||||
"can_manage_strm": p.CanManageStrm,
|
||||
"can_access_settings": p.CanAccessSettings,
|
||||
"updated_at": time.Now(),
|
||||
}).Error
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
@@ -52,6 +52,40 @@ func (r *ScrapeTaskRepository) FindActiveByMediaID(ctx context.Context, mediaID
|
||||
return &t, err
|
||||
}
|
||||
|
||||
// FindActiveByMediaIDs 批量查询仍处于 pending/running 的任务媒体 ID 集合，
|
||||
// 供整库入队时去重（防止同一媒体被重复入队并被并发双刮）。
|
||||
func (r *ScrapeTaskRepository) FindActiveByMediaIDs(ctx context.Context, mediaIDs []string) (map[string]bool, error) {
|
||||
out := make(map[string]bool, len(mediaIDs))
|
||||
if len(mediaIDs) == 0 {
|
||||
return out, nil
|
||||
}
|
||||
var rows []model.ScrapeTask
|
||||
err := r.db.WithContext(ctx).
|
||||
Select("media_id").
|
||||
Where("media_id IN ? AND status IN ?", mediaIDs, []string{model.ScrapeTaskPending, model.ScrapeTaskRunning}).
|
||||
Find(&rows).Error
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
for _, r := range rows {
|
||||
out[r.MediaID] = true
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ResetRunningToPending 启动自愈：进程中断遗留的 running 任务重置为 pending，
|
||||
// 否则任务永久卡死（ClaimPending 只认 pending，重试按钮也拒绝 running）。
|
||||
func (r *ScrapeTaskRepository) ResetRunningToPending(ctx context.Context) (int64, error) {
|
||||
res := r.db.WithContext(ctx).Model(&model.ScrapeTask{}).
|
||||
Where("status = ?", model.ScrapeTaskRunning).
|
||||
Updates(map[string]any{
|
||||
"status": model.ScrapeTaskPending,
|
||||
"error": "服务重启，任务已重置",
|
||||
"started_at": nil,
|
||||
})
|
||||
return res.RowsAffected, res.Error
|
||||
}
|
||||
|
||||
func (r *ScrapeTaskRepository) List(ctx context.Context, status string, page, pageSize int) ([]model.ScrapeTask, int64, error) {
|
||||
if page < 1 {
|
||||
page = 1
|
||||
|
||||
@@ -302,6 +302,39 @@ func (r *StrmDownloadTaskRepository) Update(ctx context.Context, t *model.StrmDo
|
||||
})
|
||||
}
|
||||
|
||||
// UpdateIfRunning 仅当任务在 DB 中仍为 running 时写入给定字段。
|
||||
// 返回 false 表示任务已被外部改变状态（如用户取消），收尾不得覆盖。
|
||||
func (r *StrmDownloadTaskRepository) UpdateIfRunning(ctx context.Context, id string, updates map[string]any) (bool, error) {
|
||||
var ok bool
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
updates["updated_at"] = time.Now()
|
||||
res := r.db.WithContext(ctx).Model(&model.StrmDownloadTask{}).
|
||||
Where("id = ? AND status = ?", id, model.StrmTaskRunning).Updates(updates)
|
||||
ok = res.RowsAffected > 0
|
||||
return res.Error
|
||||
})
|
||||
return ok, err
|
||||
}
|
||||
|
||||
// ResetRunningToPending 启动自愈：进程中断遗留的 running 任务全部重置为
|
||||
// pending（清空退避时间以便立即可被认领），否则任务永久卡死且会阻塞
|
||||
// 该文件的重复下载。
|
||||
func (r *StrmDownloadTaskRepository) ResetRunningToPending(ctx context.Context) (int64, error) {
|
||||
var n int64
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
res := r.db.WithContext(ctx).Model(&model.StrmDownloadTask{}).
|
||||
Where("status = ?", model.StrmTaskRunning).
|
||||
Updates(map[string]any{
|
||||
"status": model.StrmTaskPending,
|
||||
"error": "服务重启，任务已重置",
|
||||
"started_at": nil,
|
||||
})
|
||||
n = res.RowsAffected
|
||||
return res.Error
|
||||
})
|
||||
return n, err
|
||||
}
|
||||
|
||||
func (r *StrmDownloadTaskRepository) Delete(ctx context.Context, id string) error {
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmDownloadTask{}).Error
|
||||
@@ -620,6 +653,36 @@ func (r *StrmUploadTaskRepository) Update(ctx context.Context, t *model.StrmUplo
|
||||
})
|
||||
}
|
||||
|
||||
// UpdateIfRunning 仅当任务在 DB 中仍为 running 时写入给定字段。
|
||||
func (r *StrmUploadTaskRepository) UpdateIfRunning(ctx context.Context, id string, updates map[string]any) (bool, error) {
|
||||
var ok bool
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
updates["updated_at"] = time.Now()
|
||||
res := r.db.WithContext(ctx).Model(&model.StrmUploadTask{}).
|
||||
Where("id = ? AND status = ?", id, model.StrmTaskRunning).Updates(updates)
|
||||
ok = res.RowsAffected > 0
|
||||
return res.Error
|
||||
})
|
||||
return ok, err
|
||||
}
|
||||
|
||||
// ResetRunningToPending 启动自愈：进程中断遗留的 running 任务全部重置为 pending。
|
||||
func (r *StrmUploadTaskRepository) ResetRunningToPending(ctx context.Context) (int64, error) {
|
||||
var n int64
|
||||
err := withSQLiteBusyRetry(ctx, func() error {
|
||||
res := r.db.WithContext(ctx).Model(&model.StrmUploadTask{}).
|
||||
Where("status = ?", model.StrmTaskRunning).
|
||||
Updates(map[string]any{
|
||||
"status": model.StrmTaskPending,
|
||||
"error": "服务重启，任务已重置",
|
||||
"started_at": nil,
|
||||
})
|
||||
n = res.RowsAffected
|
||||
return res.Error
|
||||
})
|
||||
return n, err
|
||||
}
|
||||
|
||||
func (r *StrmUploadTaskRepository) Delete(ctx context.Context, id string) error {
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmUploadTask{}).Error
|
||||
@@ -838,6 +901,53 @@ func (r *StrmDirCacheRepository) Set(ctx context.Context, syncPathID, dirID, pat
|
||||
})
|
||||
}
|
||||
|
||||
// SetBatch 批量 upsert 目录缓存（dirID → 相对路径）。单个事务内先查出已存在
|
||||
// 行再分流更新/插入，替代同步流程逐目录单条 Set，避免首次全量同步上万目录时
|
||||
// 的 SQLite 写锁竞争。同一 dirID 的重复项以 map 语义取最后一次写入。
|
||||
func (r *StrmDirCacheRepository) SetBatch(ctx context.Context, syncPathID string, paths map[string]string) error {
|
||||
if len(paths) == 0 {
|
||||
return nil
|
||||
}
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||||
ids := make([]string, 0, len(paths))
|
||||
for dirID := range paths {
|
||||
ids = append(ids, dirID)
|
||||
}
|
||||
var existing []model.StrmDirCache
|
||||
if err := tx.Where("sync_path_id = ? AND dir_id IN ?", syncPathID, ids).Find(&existing).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
existingRowID := make(map[string]string, len(existing))
|
||||
for _, row := range existing {
|
||||
existingRowID[row.DirID] = row.ID
|
||||
}
|
||||
now := time.Now()
|
||||
var creates []model.StrmDirCache
|
||||
for dirID, path := range paths {
|
||||
if rowID, ok := existingRowID[dirID]; ok {
|
||||
if err := tx.Model(&model.StrmDirCache{}).Where("id = ?", rowID).Updates(map[string]any{
|
||||
"path": path,
|
||||
"updated_at": now,
|
||||
}).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
continue
|
||||
}
|
||||
creates = append(creates, model.StrmDirCache{
|
||||
SyncPathID: syncPathID,
|
||||
DirID: dirID,
|
||||
Path: path,
|
||||
})
|
||||
}
|
||||
if len(creates) > 0 {
|
||||
return tx.CreateInBatches(creates, 100).Error
|
||||
}
|
||||
return nil
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
func (r *StrmDirCacheRepository) DeleteBySyncPathID(ctx context.Context, syncPathID string) error {
|
||||
return withSQLiteBusyRetry(ctx, func() error {
|
||||
return r.db.WithContext(ctx).Unscoped().Where("sync_path_id = ?", syncPathID).Delete(&model.StrmDirCache{}).Error
|
||||
|
||||
@@ -20,7 +20,7 @@ func TestAdultProviderRouting(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatalf("failed to open sqlite: %v", err)
|
||||
}
|
||||
_ = db.AutoMigrate(&model.Setting{}, &model.ApiConfig{})
|
||||
_ = db.AutoMigrate(&model.Setting{}, &model.APIConfig{})
|
||||
|
||||
repos := repository.New(db)
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ func (s *ApiConfigService) TestConnection(ctx context.Context, provider string)
|
||||
}
|
||||
|
||||
// testTMDb 测试 TMDb API 连接。
|
||||
func (s *ApiConfigService) testTMDb(cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testTMDb(cfg *model.APIConfig) (string, error) {
|
||||
if cfg.APIKey == "" {
|
||||
return "error", errors.New("API key is required")
|
||||
}
|
||||
@@ -74,7 +74,7 @@ func (s *ApiConfigService) testTMDb(cfg *model.ApiConfig) (string, error) {
|
||||
}
|
||||
|
||||
// testOpenAI 测试 OpenAI API 连接。
|
||||
func (s *ApiConfigService) testOpenAI(cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testOpenAI(cfg *model.APIConfig) (string, error) {
|
||||
if cfg.APIKey == "" {
|
||||
return "error", errors.New("API key is required")
|
||||
}
|
||||
@@ -108,7 +108,7 @@ func (s *ApiConfigService) testOpenAI(cfg *model.ApiConfig) (string, error) {
|
||||
}
|
||||
|
||||
// testDeepSeek 测试 DeepSeek API 连接。
|
||||
func (s *ApiConfigService) testDeepSeek(cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testDeepSeek(cfg *model.APIConfig) (string, error) {
|
||||
if cfg.APIKey == "" {
|
||||
return "error", errors.New("API key is required")
|
||||
}
|
||||
@@ -142,7 +142,7 @@ func (s *ApiConfigService) testDeepSeek(cfg *model.ApiConfig) (string, error) {
|
||||
}
|
||||
|
||||
// testSiliconFlow 测试 SiliconFlow API 连接。
|
||||
func (s *ApiConfigService) testSiliconFlow(cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testSiliconFlow(cfg *model.APIConfig) (string, error) {
|
||||
if cfg.APIKey == "" {
|
||||
return "error", errors.New("API key is required")
|
||||
}
|
||||
@@ -176,7 +176,7 @@ func (s *ApiConfigService) testSiliconFlow(cfg *model.ApiConfig) (string, error)
|
||||
}
|
||||
|
||||
// testAdult 测试 Adult (JavDB/JavBus) 刮削数据源连接与年龄验证。
|
||||
func (s *ApiConfigService) testAdult(ctx context.Context, cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testAdult(ctx context.Context, cfg *model.APIConfig) (string, error) {
|
||||
bases := []string{}
|
||||
if cfg.BaseURL != "" {
|
||||
bases = append(bases, adultConfiguredBases(cfg.BaseURL)...)
|
||||
@@ -245,7 +245,7 @@ func (s *ApiConfigService) testAdult(ctx context.Context, cfg *model.ApiConfig)
|
||||
}
|
||||
|
||||
// testMetaTube 测试 MetaTube Server 连接与 Token。
|
||||
func (s *ApiConfigService) testMetaTube(ctx context.Context, cfg *model.ApiConfig) (string, error) {
|
||||
func (s *ApiConfigService) testMetaTube(ctx context.Context, cfg *model.APIConfig) (string, error) {
|
||||
serverURL := strings.TrimRight(strings.TrimSpace(cfg.BaseURL), "/")
|
||||
if serverURL == "" {
|
||||
serverURL = "http://127.0.0.1:7700"
|
||||
|
||||
@@ -9,7 +9,7 @@ import (
|
||||
)
|
||||
|
||||
// GetEffectiveConfig 获取生效的 API 配置（数据库配置优先于配置文件）。
|
||||
func (s *ApiConfigService) GetEffectiveConfig(ctx context.Context, provider string) (*model.ApiConfig, error) {
|
||||
func (s *ApiConfigService) GetEffectiveConfig(ctx context.Context, provider string) (*model.APIConfig, error) {
|
||||
// 首先尝试从数据库获取
|
||||
cfg, err := s.GetByProvider(ctx, provider)
|
||||
if err == nil && cfg != nil {
|
||||
@@ -21,7 +21,7 @@ func (s *ApiConfigService) GetEffectiveConfig(ctx context.Context, provider stri
|
||||
}
|
||||
|
||||
// getConfigFromFile 从配置文件获取 API 配置。
|
||||
func (s *ApiConfigService) getConfigFromFile(provider string) (*model.ApiConfig, error) {
|
||||
func (s *ApiConfigService) getConfigFromFile(provider string) (*model.APIConfig, error) {
|
||||
var apiKey string
|
||||
var hasKey bool
|
||||
|
||||
@@ -44,7 +44,7 @@ func (s *ApiConfigService) getConfigFromFile(provider string) (*model.ApiConfig,
|
||||
return nil, ErrApiConfigNotFound
|
||||
}
|
||||
|
||||
return &model.ApiConfig{
|
||||
return &model.APIConfig{
|
||||
Provider: provider,
|
||||
APIKey: apiKey,
|
||||
Enabled: true,
|
||||
|
||||
@@ -33,7 +33,7 @@ var (
|
||||
)
|
||||
|
||||
// GetByProvider 获取指定提供者的 API 配置。
|
||||
func (s *ApiConfigService) GetByProvider(ctx context.Context, provider string) (*model.ApiConfig, error) {
|
||||
func (s *ApiConfigService) GetByProvider(ctx context.Context, provider string) (*model.APIConfig, error) {
|
||||
cfg, err := s.repo.ApiConfig.FindByProvider(ctx, provider)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
@@ -49,7 +49,7 @@ func (s *ApiConfigService) GetByProvider(ctx context.Context, provider string) (
|
||||
}
|
||||
|
||||
// List 返回所有 API 配置。
|
||||
func (s *ApiConfigService) List(ctx context.Context) ([]model.ApiConfig, error) {
|
||||
func (s *ApiConfigService) List(ctx context.Context) ([]model.APIConfig, error) {
|
||||
configs, err := s.repo.ApiConfig.List(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
@@ -69,7 +69,7 @@ func (s *ApiConfigService) GetProviders() []model.ApiProvider {
|
||||
}
|
||||
|
||||
// Upsert 创建或更新 API 配置，自动加密敏感字段。
|
||||
func (s *ApiConfigService) Upsert(ctx context.Context, provider string, apiKey, baseURL, extra string, enabled bool) (*model.ApiConfig, error) {
|
||||
func (s *ApiConfigService) Upsert(ctx context.Context, provider string, apiKey, baseURL, extra string, enabled bool) (*model.APIConfig, error) {
|
||||
// 验证提供者是否有效
|
||||
if !s.isValidProvider(provider) {
|
||||
return nil, ErrInvalidProvider
|
||||
@@ -81,7 +81,7 @@ func (s *ApiConfigService) Upsert(ctx context.Context, provider string, apiKey,
|
||||
encryptedKey = s.crypto.Encrypt(apiKey)
|
||||
}
|
||||
|
||||
cfg := &model.ApiConfig{
|
||||
cfg := &model.APIConfig{
|
||||
Provider: provider,
|
||||
APIKey: encryptedKey,
|
||||
BaseURL: baseURL,
|
||||
@@ -112,7 +112,7 @@ func (s *ApiConfigService) Update(ctx context.Context, provider string, apiKey,
|
||||
encryptedKey = s.crypto.Encrypt(apiKey)
|
||||
}
|
||||
|
||||
cfg := &model.ApiConfig{
|
||||
cfg := &model.APIConfig{
|
||||
Provider: provider,
|
||||
APIKey: encryptedKey,
|
||||
BaseURL: baseURL,
|
||||
|
||||
@@ -12,6 +12,7 @@ import (
|
||||
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/helper"
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
"github.com/truewhile/MeBox/internal/repository"
|
||||
)
|
||||
@@ -50,6 +51,8 @@ func (a *AuditService) RecordBestEffort(userID, action, target, ip, detail strin
|
||||
go func() {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
|
||||
defer cancel()
|
||||
a.Record(ctx, userID, action, target, ip, detail)
|
||||
helper.Run(a.log, "audit.record", func() {
|
||||
a.Record(ctx, userID, action, target, ip, detail)
|
||||
})
|
||||
}()
|
||||
}
|
||||
|
||||
@@ -13,6 +13,7 @@ import (
|
||||
"golang.org/x/crypto/bcrypt"
|
||||
|
||||
"github.com/truewhile/MeBox/internal/config"
|
||||
"github.com/truewhile/MeBox/internal/helper"
|
||||
"github.com/truewhile/MeBox/internal/model"
|
||||
"github.com/truewhile/MeBox/internal/repository"
|
||||
)
|
||||
@@ -176,9 +177,11 @@ func (s *AuthService) touchLoginBestEffort(userID string) {
|
||||
go func() {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
|
||||
defer cancel()
|
||||
if err := s.repo.User.TouchLogin(ctx, userID); err != nil && s.log != nil {
|
||||
s.log.Debug("touch login delayed", zap.String("user_id", userID), zap.Error(err))
|
||||
}
|
||||
helper.Run(s.log, "auth.touchLogin", func() {
|
||||
if err := s.repo.User.TouchLogin(ctx, userID); err != nil && s.log != nil {
|
||||
s.log.Debug("touch login delayed", zap.String("user_id", userID), zap.Error(err))
|
||||
}
|
||||
})
|
||||
}()
|
||||
}
|
||||
|
||||
|
||||
@@ -45,6 +45,9 @@ type FileEntry struct {
|
||||
MTime int64 `json:"mtime,omitempty"`
|
||||
// PickCode is 115-specific; other providers use ID directly.
|
||||
PickCode string `json:"pick_code,omitempty"`
|
||||
// Sha1 is 115-specific content hash（大写 hex，目录/未完成文件可能为空或占位符）。
|
||||
// 其他网盘不提供，留空时调用方退回大小比对。用于元数据"是否同一文件"的精确判定。
|
||||
Sha1 string `json:"sha1,omitempty"`
|
||||
}
|
||||
|
||||
// DirectLink is a resolved playback target.
|
||||
@@ -72,6 +75,15 @@ type Provider interface {
|
||||
Resolve(ctx context.Context, fileRef string) (*DirectLink, error)
|
||||
}
|
||||
|
||||
// BatchResolver is implemented by providers that can resolve several file
|
||||
// references in fewer API calls（115 的 downurl 接口支持逗号分隔多个 pick_code，
|
||||
// 批量换取可显著降低下载队列的换链请求量）。返回以原始引用为键的直链 map；
|
||||
// 解析失败的引用不在结果中，err 汇报批量机制本身的失败，调用方应据此对缺失
|
||||
// 项回退到逐个 Resolve。
|
||||
type BatchResolver interface {
|
||||
ResolveBatch(ctx context.Context, fileRefs []string) (map[string]*DirectLink, error)
|
||||
}
|
||||
|
||||
// MutableProvider is implemented by cloud bridges that support safe folder
|
||||
// management through their official API or standard WebDAV methods.
|
||||
type MutableProvider interface {
|
||||
|
||||
@@ -81,7 +81,12 @@ func Test115OpenAPIListPaginates(t *testing.T) {
|
||||
t.Fatalf("unexpected path %s", r.URL.Path)
|
||||
}
|
||||
offset, _ := strconv.Atoi(r.URL.Query().Get("offset"))
|
||||
count := 100
|
||||
limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
|
||||
if limit <= 0 {
|
||||
limit = 100
|
||||
}
|
||||
// 首页返回满页，之后返回 1 条：驱动按 offset/limit 翻页直到短页
|
||||
count := limit
|
||||
if offset > 0 {
|
||||
count = 1
|
||||
}
|
||||
@@ -97,11 +102,12 @@ func Test115OpenAPIListPaginates(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatalf("list: %v", err)
|
||||
}
|
||||
if len(entries) != 101 {
|
||||
t.Fatalf("entries = %d, want 101", len(entries))
|
||||
// List 使用文档上限 limit=1150：首页 1150 条 + 短页 1 条
|
||||
if len(entries) != 1151 {
|
||||
t.Fatalf("entries = %d, want 1151", len(entries))
|
||||
}
|
||||
if entries[100].ID != "100" || entries[100].PickCode != "pick100" {
|
||||
t.Fatalf("last entry wrong: %#v", entries[100])
|
||||
if entries[1150].ID != "1150" || entries[1150].PickCode != "pick1150" {
|
||||
t.Fatalf("last entry wrong: %#v", entries[1150])
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ import (
|
||||
"net/url"
|
||||
"path"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// cloudDrive2Provider bridges CloudDrive2 through its WebDAV endpoint.
|
||||
@@ -22,11 +24,18 @@ type cloudDrive2Provider struct {
|
||||
base *url.URL
|
||||
username string
|
||||
password string
|
||||
token string
|
||||
token string // 配置的静态令牌（构造后只读）
|
||||
ua string
|
||||
apiBase *url.URL
|
||||
client *http.Client
|
||||
proxy bool
|
||||
|
||||
// tokenMu / loginToken / loginTokenSeen 保护 OpenList 用户名密码登录的
|
||||
// token 缓存：多 worker 并发时单飞登录，缓存有效期内直接复用，
|
||||
// 401 时清缓存重登（见 clouddrive2_openlist.go 的 openListAPIToken）。
|
||||
tokenMu sync.Mutex
|
||||
loginToken string
|
||||
loginTokenSeen time.Time
|
||||
}
|
||||
|
||||
func newCloudDrive2(cfg map[string]any, client *http.Client) *cloudDrive2Provider {
|
||||
|
||||
@@ -36,9 +36,10 @@ func (p *cloudDrive2Provider) List(ctx context.Context, dir string) ([]FileEntry
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return nil, p.decorateDAVStatusError(resp, target)
|
||||
}
|
||||
body, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
|
||||
// 流式解码：超大目录（如上万条目的网盘目录）响应可能远超旧 4MB 截断上限，
|
||||
// 直接 xml.Unmarshal 会截断报错；这里用 LimitReader(64MB) + Decoder 边读边解
|
||||
var multi cloudDAVMultiStatus
|
||||
if err := xml.Unmarshal(body, &multi); err != nil {
|
||||
if err := xml.NewDecoder(io.LimitReader(resp.Body, 64<<20)).Decode(&multi); err != nil {
|
||||
return nil, fmt.Errorf("%s: decode webdav: %w", p.name, err)
|
||||
}
|
||||
basePath := strings.TrimRight(p.base.EscapedPath(), "/")
|
||||
|
||||
@@ -131,10 +131,13 @@ func (p *cloudDrive2Provider) openListAPIMove(ctx context.Context, source, targe
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) openListAPIPost(ctx context.Context, apiPath string, payload any, action string) error {
|
||||
token, err := p.openListAPIToken(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
_, err := doWithOpenListAPIToken(ctx, p, func(token string) (struct{}, error) {
|
||||
return struct{}{}, p.openListAPIPostWithToken(ctx, apiPath, payload, action, token)
|
||||
})
|
||||
return err
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) openListAPIPostWithToken(ctx context.Context, apiPath string, payload any, action, token string) error {
|
||||
body, _ := json.Marshal(payload)
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.openListAPIURL(apiPath), bytes.NewReader(body))
|
||||
if err != nil {
|
||||
@@ -151,6 +154,9 @@ func (p *cloudDrive2Provider) openListAPIPost(ctx context.Context, apiPath strin
|
||||
return decorateDAVTransportError(p.name, p.openListAPIURL(apiPath), err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusUnauthorized {
|
||||
return errOpenListAPITokenExpired
|
||||
}
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return fmt.Errorf("%s: api %s returned http %d", p.name, action, resp.StatusCode)
|
||||
}
|
||||
@@ -200,27 +206,43 @@ func (p *cloudDrive2Provider) PutFile(ctx context.Context, remotePath string, r
|
||||
}
|
||||
|
||||
// openListAPIPutFile 通过 OpenList /api/fs/form 上传（QMediaSync 同款契约：
|
||||
// PUT + multipart + File-Path 头）。
|
||||
// PUT + multipart + File-Path 头）。使用 io.Pipe + multipart.Writer 边写边发，
|
||||
// 避免把整个文件读进内存。
|
||||
func (p *cloudDrive2Provider) openListAPIPutFile(ctx context.Context, remotePath string, r io.Reader) error {
|
||||
token, err := p.openListAPIToken(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
encodedPath := openListPathEscape(remotePath)
|
||||
body := &bytes.Buffer{}
|
||||
writer := multipart.NewWriter(body)
|
||||
formFile, err := writer.CreateFormFile("file", path.Base(remotePath))
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if _, err := io.Copy(formFile, r); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := writer.Close(); err != nil {
|
||||
return err
|
||||
}
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPut, p.openListAPIURL("/api/fs/form"), body)
|
||||
|
||||
pr, pw := io.Pipe()
|
||||
writer := multipart.NewWriter(pw)
|
||||
go func() {
|
||||
var writeErr error
|
||||
defer func() {
|
||||
// 读源失败必须传给 pipe 写端，让 HTTP 请求以失败收场而不是静默截断
|
||||
if writeErr != nil {
|
||||
_ = pw.CloseWithError(writeErr)
|
||||
return
|
||||
}
|
||||
_ = pw.Close()
|
||||
}()
|
||||
formFile, err := writer.CreateFormFile("file", path.Base(remotePath))
|
||||
if err != nil {
|
||||
writeErr = err
|
||||
return
|
||||
}
|
||||
if _, err := io.Copy(formFile, r); err != nil {
|
||||
writeErr = err
|
||||
return
|
||||
}
|
||||
writeErr = writer.Close()
|
||||
}()
|
||||
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPut, p.openListAPIURL("/api/fs/form"), pr)
|
||||
if err != nil {
|
||||
// 关闭读端以释放仍在等待写入的后台 goroutine（其 Write 会立即失败返回）
|
||||
_ = pr.Close()
|
||||
return err
|
||||
}
|
||||
req.Header.Set("Authorization", token)
|
||||
@@ -230,9 +252,15 @@ func (p *cloudDrive2Provider) openListAPIPutFile(ctx context.Context, remotePath
|
||||
req.Header.Set("Overwrite", "true")
|
||||
resp, err := p.client.Do(req)
|
||||
if err != nil {
|
||||
// 传输层失败（含提前断开）时 net/http 会关闭请求 body，解除后台 goroutine 阻塞
|
||||
return decorateDAVTransportError(p.name, p.openListAPIURL("/api/fs/form"), err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusUnauthorized {
|
||||
// 流式 body 无法重放，不能自动重试：清除登录 token 缓存让下次上传重新登录，
|
||||
// 本次返回明确错误交由调用方重试
|
||||
p.invalidateOpenListAPIToken()
|
||||
}
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return p.openListAPIStatusError("upload", remotePath, resp.StatusCode)
|
||||
}
|
||||
|
||||
@@ -4,18 +4,50 @@ import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
func (p *cloudDrive2Provider) listOpenListAPI(ctx context.Context, dir string) ([]FileEntry, error) {
|
||||
// errOpenListAPITokenExpired 标记 OpenList 返回 401（登录 token 已失效）：
|
||||
// 调用方收到后应清缓存重登一次再重试原请求。
|
||||
var errOpenListAPITokenExpired = errors.New("openlist api token expired")
|
||||
|
||||
// openListAPITokenCacheTTL 登录 token 缓存有效期（OpenList 默认签发 48h JWT，
|
||||
// 这里保守取 30 分钟，过期自动重新登录）。
|
||||
const openListAPITokenCacheTTL = 30 * time.Minute
|
||||
|
||||
// doWithOpenListAPIToken 获取 OpenList API token 后执行 fn；若请求命中 401
|
||||
// （登录 token 失效）则清缓存重登一次并重试，避免一次 token 轮换导致整批请求失败。
|
||||
func doWithOpenListAPIToken[T any](ctx context.Context, p *cloudDrive2Provider, fn func(token string) (T, error)) (T, error) {
|
||||
var zero T
|
||||
token, err := p.openListAPIToken(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
return zero, err
|
||||
}
|
||||
result, err := fn(token)
|
||||
if err == nil || !errors.Is(err, errOpenListAPITokenExpired) {
|
||||
return result, err
|
||||
}
|
||||
p.invalidateOpenListAPIToken()
|
||||
token, err = p.openListAPIToken(ctx)
|
||||
if err != nil {
|
||||
return zero, err
|
||||
}
|
||||
return fn(token)
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) listOpenListAPI(ctx context.Context, dir string) ([]FileEntry, error) {
|
||||
return doWithOpenListAPIToken(ctx, p, func(token string) ([]FileEntry, error) {
|
||||
return p.listOpenListAPIWithToken(ctx, dir, token)
|
||||
})
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) listOpenListAPIWithToken(ctx context.Context, dir, token string) ([]FileEntry, error) {
|
||||
const pageSize = 500
|
||||
target := normalizeCloudDAVPath(dir)
|
||||
out := make([]FileEntry, 0, pageSize)
|
||||
@@ -45,6 +77,9 @@ func (p *cloudDrive2Provider) listOpenListAPI(ctx context.Context, dir string) (
|
||||
var decoded openListListResponse
|
||||
decodeErr := json.NewDecoder(io.LimitReader(resp.Body, 32<<20)).Decode(&decoded)
|
||||
resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusUnauthorized {
|
||||
return nil, errOpenListAPITokenExpired
|
||||
}
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return nil, p.openListAPIStatusError("list", target, resp.StatusCode)
|
||||
}
|
||||
@@ -85,10 +120,12 @@ func (p *cloudDrive2Provider) listOpenListAPI(ctx context.Context, dir string) (
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) resolveOpenListAPIDirect(ctx context.Context, fileRef string) (*DirectLink, error) {
|
||||
token, err := p.openListAPIToken(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return doWithOpenListAPIToken(ctx, p, func(token string) (*DirectLink, error) {
|
||||
return p.resolveOpenListAPIDirectWithToken(ctx, fileRef, token)
|
||||
})
|
||||
}
|
||||
|
||||
func (p *cloudDrive2Provider) resolveOpenListAPIDirectWithToken(ctx context.Context, fileRef, token string) (*DirectLink, error) {
|
||||
payload, _ := json.Marshal(map[string]string{"path": normalizeCloudDAVPath(fileRef), "password": ""})
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.openListAPIURL("/api/fs/get"), bytes.NewReader(payload))
|
||||
if err != nil {
|
||||
@@ -105,6 +142,9 @@ func (p *cloudDrive2Provider) resolveOpenListAPIDirect(ctx context.Context, file
|
||||
return nil, decorateDAVTransportError(p.name, p.openListAPIURL("/api/fs/get"), err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusUnauthorized {
|
||||
return nil, errOpenListAPITokenExpired
|
||||
}
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return nil, p.openListAPIStatusError("get", fileRef, resp.StatusCode)
|
||||
}
|
||||
@@ -163,6 +203,10 @@ func (p *cloudDrive2Provider) hasOpenListAPICredentials() bool {
|
||||
return strings.TrimSpace(p.token) != "" || (strings.TrimSpace(p.username) != "" && p.password != "")
|
||||
}
|
||||
|
||||
// openListAPIToken 返回 OpenList API 访问令牌：
|
||||
// - 配置了静态 token 时直接使用（构造后只读，无并发问题）；
|
||||
// - 否则用用户名密码登录，并在缓存有效期内单飞复用——8 个同步 worker 并发时
|
||||
// 只会有一个 goroutine 真正执行登录，避免登录风暴；登录 token 的写入受 tokenMu 保护。
|
||||
func (p *cloudDrive2Provider) openListAPIToken(ctx context.Context) (string, error) {
|
||||
if token := strings.TrimSpace(p.token); token != "" {
|
||||
return token, nil
|
||||
@@ -170,6 +214,30 @@ func (p *cloudDrive2Provider) openListAPIToken(ctx context.Context) (string, err
|
||||
if strings.TrimSpace(p.username) == "" || p.password == "" {
|
||||
return "", nil
|
||||
}
|
||||
p.tokenMu.Lock()
|
||||
defer p.tokenMu.Unlock()
|
||||
if p.loginToken != "" && time.Since(p.loginTokenSeen) < openListAPITokenCacheTTL {
|
||||
return p.loginToken, nil
|
||||
}
|
||||
token, err := p.openListAPILogin(ctx)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
p.loginToken = token
|
||||
p.loginTokenSeen = time.Now()
|
||||
return token, nil
|
||||
}
|
||||
|
||||
// invalidateOpenListAPIToken 清除登录 token 缓存（收到 401 时调用，下次请求重新登录）。
|
||||
func (p *cloudDrive2Provider) invalidateOpenListAPIToken() {
|
||||
p.tokenMu.Lock()
|
||||
p.loginToken = ""
|
||||
p.loginTokenSeen = time.Time{}
|
||||
p.tokenMu.Unlock()
|
||||
}
|
||||
|
||||
// openListAPILogin 调用 OpenList /api/auth/login 换取登录 token。
|
||||
func (p *cloudDrive2Provider) openListAPILogin(ctx context.Context) (string, error) {
|
||||
payload, _ := json.Marshal(map[string]string{
|
||||
"username": p.username,
|
||||
"password": p.password,
|
||||
@@ -204,7 +272,6 @@ func (p *cloudDrive2Provider) openListAPIToken(ctx context.Context) (string, err
|
||||
if token == "" {
|
||||
return "", fmt.Errorf("%s: api login returned empty token", p.name)
|
||||
}
|
||||
p.token = token
|
||||
return token, nil
|
||||
}
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user