Path: 宝塔面板 API 参考 › 文件管理

`POST /files`

这个请求地址通过 action 区分具体功能。下方列出每个 action 的参数、约束和调用示例。

## Request body

_Required._

One of:

- `ActionTask`
- `CheckExistsFiles`
- `Close_Recycle_bin`
- `CreateLink`
- `DeleteDir`
- `GetDir`
- `GetDirNew`
- `GetFileAccess`
- `GetFileHistory`
- `Get_Recycle_bin`
- `Re_Recycle_bin`
- `Recycle_bin`
- `RemoveTask`
- `SaveFileBody`
- `UploadFile`
- `dir_webshell_check`
- `file_history_list`
- `file_webshell_check`
- `get_bt_sync_status`
- `get_composer_version`
- `get_files_store`
- `get_path_size`
- `get_videos`
- `install_rar`
- `list_backups`
- `mutil_unzip`
- `remove_download_url`
- `send_baota`
- `test_path`
- `update_composer`
- `upload_files_exists`

## Example request

```text
{
  "request_time": "string",
  "request_token": "string",
  "action": "ActionTask"
}
```

## Code samples

### cURL（填写面板地址与签名）

```curl
curl --request POST \
  --url "https://your-panel.example.com:8888/files" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "request_time=<Unix时间戳>" \
  --data-urlencode "request_token=<按 API 概览生成的签名>" \
  --data-urlencode "action=ActionTask"
```

## Responses

### default

响应因 action 而异，见下方各 action 的详细说明。


## ActionTask

激活后台任务队列，使积压的文件操作任务开始执行。

- **路由**：`POST /files`
- **action**：`ActionTask`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `ActionTask` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 激活成功 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=ActionTask
```

### 响应

```json
{"status": true, "msg": "任务队列已激活"}
```


## CheckExistsFiles

检查源文件是否与目标路径下已有文件重名，用于上传/复制前确认。

- **路由**：`POST /files`
- **action**：`CheckExistsFiles`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `CheckExistsFiles` |
| dfile | 是 | String | 目标目录路径 |
| filename | 否 | String | 要检查的单个文件名。不传则检查 session 中勾选的全部文件 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 已存在的文件名列表，空数组 `[]` 表示无冲突 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=CheckExistsFiles&dfile=/www/wwwroot&filename=index.html
```

### 响应

```json
[]
```


## Close_Recycle_bin

清空所有回收站目录，永久删除已放入回收站的文件。

- **路由**：`POST /files`
- **action**：`Close_Recycle_bin`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `Close_Recycle_bin` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 清空成功 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=Close_Recycle_bin
```

### 响应

```json
{"status": true, "msg": "已清空回收站!"}
```


## CopyFile

## CopyFile / MvFile

复制或移动文件/目录。

- **路由**：`POST /files`

## CopyFile

复制文件或目录。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `CopyFile` |
| sfile | 是 | String | 源文件路径 |
| dfile | 是 | String | 目标文件路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | 请求结果，`true` 表示成功 |
| msg | String | 提示信息 |

```json
{"status": true, "msg": "文件复制成功!"}
```

## MvFile

移动（重命名）文件或目录。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `MvFile` |
| sfile | 是 | String | 源文件路径 |
| dfile | 是 | String | 目标文件路径 |

```json
{"status": true, "msg": "移动文件或目录成功!"}
```


## CreateFile

## CreateFile / CreateDir / DeleteFile / DeleteDir

文件和目录的基本 CRUD 操作。

- **路由**：`POST /files`

## CreateFile

创建空文件。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `CreateFile` |
| path | 是 | String | 文件完整路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | 请求结果，`true` 表示成功 |
| msg | String | 提示信息 |

```json
{"status": true, "msg": "文件创建成功!"}
```

## CreateDir

创建目录。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `CreateDir` |
| path | 是 | String | 目录路径 |

```json
{"status": true, "msg": "目录创建成功!"}
```

## DeleteFile

删除文件（移入回收站）。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `DeleteFile` |
| path | 是 | String | 文件路径 |

## DeleteDir

删除目录（移入回收站）。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `DeleteDir` |
| path | 是 | String | 目录路径 |


## CreateLink

为文件或目录创建软链接（符号链接 symlink）。

- **路由**：`POST /files`
- **action**：`CreateLink`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `CreateLink` |
| sfile | 是 | String | 源文件或目录的绝对路径 |
| dfile | 是 | String | 软链接目标路径（绝对路径），文件名仅允许 `[\w\-\.]+` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 创建成功 |
| msg | String | `软链文件创建成功!` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=CreateLink&sfile=/www/wwwroot/testapi.bt.local&dfile=/tmp/bt_link_test
```

### 响应

```json
{"status": true, "msg": "软链文件创建成功!"}
```


## DeleteDir

将指定文件或目录移入面板回收站，不直接永久删除。

- **路由**：`POST /files`
- **action**：`DeleteDir`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `DeleteDir` |
| path | 是 | String | 要删除的文件或目录的绝对路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 删除成功 |
| msg | String | `删除目录成功!` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=DeleteDir&path=/tmp/bt_doc_test_dir
```

### 响应

```json
{"status": true, "msg": "删除目录成功!"}
```


## GetDir

获取指定路径下的目录和文件列表，支持分页、排序、搜索。返回每项的详细信息（大小、权限、修改时间等）。

- **路由**：`POST /files`
- **action**：`GetDir`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `GetDir` |
| path | 是 | String | 目录路径，如 `/www/wwwroot/testapi.bt.local` |
| p | 否 | Integer | 页码，默认 `1` |
| search | 否 | String | 搜索关键词 |
| sort | 否 | String | 排序字段：`name`/`size`/`mtime`/`permission`/`owner` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| PATH | String | 当前路径 |
| DIR | Array | 子目录列表，每项格式：`name;size;mtime;permission;owner;...` |
| FILES | Array | 文件列表，格式同上 |
| PAGE | String | 分页 HTML |
| STORE | Array | 收藏的路径列表 |
| FILE_RECYCLE | Boolean | 是否开启回收站 |

## 示例

### 请求

```
POST /files HTTP/1.1
Content-Type: application/x-www-form-urlencoded

request_time=1700000000&request_token=xxx&action=GetDir&path=/www/wwwroot/testapi.bt.local&p=1
```

### 响应

```json
{
    "PATH": "/www/wwwroot/testapi.bt.local",
    "DIR": [],
    "FILES": ["404.html;138;1779435866;644;www;;0;0;0;0;;0", "index.html;917;...;644;www;..."],
    "PAGE": "<div>分页</div>",
    "STORE": [],
    "FILE_RECYCLE": false
}
```


## GetDirNew

浏览服务器文件系统，查看指定目录下的文件和子目录列表，支持分页和搜索。

- **路由**：`POST /files`
- **action**：`GetDirNew`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `GetDirNew` |
| path | 否 | String | 目录路径，默认 `/www/wwwroot` |
| search | 否 | String | 搜索关键词，匹配文件名 |
| all | 否 | String | 传任意值触发全量搜索模式 |
| p | 否 | Integer | 页码，默认 `1` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| path | String | 当前路径 |
| dir | Array&lt;Object&gt; | 子目录列表，每项含 `nm`(名称)、`sz`(大小)、`mt`(修改时间戳)、`acc`(权限)、`user`(属主) |
| page | String | 分页 HTML 片段 |
| store | Array | 收藏夹目录列表 |
| file_recycle | Boolean | 回收站状态 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=GetDirNew&path=/www/wwwroot
```

### 响应

```json
{
  "store": [],
  "file_recycle": false,
  "page": "<div><span class='Pcurrent'>1</span><span class='Pnumber'>1/1</span><span class='Pline'>从1-3条</span><span class='Pcount'>共3条</span></div>",
  "path": "/www/wwwroot",
  "dir": [
    {"nm": "api-demo.bt.local", "sz": 4096, "mt": 1779451143, "acc": "755", "user": "www", "lnk": "", "durl": "", "cmp": 0, "fav": "0", "rmk": "", "top": 0, "sn": "api-demo.bt.local"},
    {"nm": "default", "sz": 4096, "mt": 1779433215, "acc": "755", "user": "root", "lnk": "", "durl": "", "cmp": 0, "fav": "0", "rmk": "", "top": 0, "sn": "default"}
  ]
}
```


## GetFileAccess

获取文件的权限（chmod）、所有者（chown）及系统用户列表。

- **路由**：`POST /files`
- **action**：`GetFileAccess`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `GetFileAccess` |
| filename | 是 | String | 文件路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| chmod | String | 权限位，如 `644` |
| chown | String | 所有者，如 `www` |
| users | Array | 系统可用用户列表 |

## 示例

```json
{"chmod": "644", "chown": "www", "users": ["www", "root", "mysql", "nobody"]}
```


## GetFileBody

## GetFileBody / SaveFileBody

读取或保存文件内容，用于面板在线编辑器。

- **路由**：`POST /files`

## GetFileBody

读取文件内容，自动检测编码。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `GetFileBody` |
| path | 是 | String | 文件路径 |

### 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` |
| data | String | 文件内容 |
| encoding | String | 检测到的编码（如 `utf-8`） |
| size | Integer | 文件大小（字节） |
| only_read | Boolean | 是否只读 |

### 示例

```json
{"status": true, "only_read": false, "size": 917, "encoding": "utf-8", "data": "<!doctype html>..."}
```

## SaveFileBody

保存编辑后的内容到文件。

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `SaveFileBody` |
| path | 是 | String | 文件路径（必须已存在） |
| data | 是 | String | 新内容 |
| encoding | 是 | String | 编码，如 `utf-8` |

> 文件必须已存在且面板有写入权限。


## GetFileHistory

查询面板文件管理的操作历史记录，支持分页和关键词搜索。

- **路由**：`POST /files`
- **action**：`GetFileHistory`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `GetFileHistory` |
| p | 否 | Integer | 页码，默认 `1` |
| limit | 否 | Integer | 每页条数，默认 `20` |
| content | 否 | String | 搜索关键词，匹配时间和日志内容 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| page | String | 分页 HTML |
| data | Array | 操作日志列表 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=GetFileHistory&p=1&limit=10
```

### 响应

```json
{"page": "<div>...</div>", "data": []}
```


## Get_Recycle_bin

查看面板回收站中的文件和目录列表，支持分页。

- **路由**：`POST /files`
- **action**：`Get_Recycle_bin`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `Get_Recycle_bin` |
| p | 否 | Integer | 页码，默认 `1` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| list | Array | 回收站文件列表 |
| status | Boolean | 文件回收站开关状态 |
| status_db | Boolean | 数据库回收站开关状态 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=Get_Recycle_bin&p=1
```

### 响应

```json
{"list": [], "status": true, "status_db": false}
```


## Re_Recycle_bin

将回收站中的文件或目录恢复到其原始位置。

先通过 [Get_Recycle_bin](/api/files/get_recycle_bin) 获取回收站列表，取目标项的 `rname` 字段作为 `path` 参数传入。

- **路由**：`POST /files`
- **action**：`Re_Recycle_bin`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `Re_Recycle_bin` |
| path | 是 | String | 回收站中的文件名（`rname`），如 `_bt_tmp_bt_test.txt_t_1234567890.123` |
| rpath | 否 | String | 恢复到指定目录（不填则恢复到原始路径） |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 恢复成功 |
| msg | String | `恢复成功!` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=Re_Recycle_bin&path=_bt_tmp_bt_bt_recycle_test.txt_t_1779504311
```

### 响应

```json
{"status": true, "msg": "恢复成功!"}
```

## 相关接口

- [Get_Recycle_bin](/api/files/get_recycle_bin) — 查看回收站列表
- [DeleteDir](/api/files/deletedir) — 删除文件到回收站


## Recycle_bin

切换文件回收站功能的开启/关闭状态。若回收站关闭，删除的文件将被直接永久删除。

- **路由**：`POST /files`
- **action**：`Recycle_bin`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `Recycle_bin` |
| db | 否 | String | 传任意值则操作数据库回收站而非文件回收站 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 操作成功 |
| msg | String | `FILE_ON_RECYCLE_BIN`（已开启）或 `FILE_OFF_RECYCLE_BIN`（已关闭） |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=Recycle_bin
```

### 响应

```json
{"status": true, "msg": "已关闭回收站功能!"}
```


## RemoveTask

删除指定 ID 的后台任务。若任务正在运行（状态 `-1`）则同时终止相关进程。

- **路由**：`POST /files`
- **action**：`RemoveTask`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `RemoveTask` |
| id | 是 | Integer | 任务 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 删除成功 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=RemoveTask&id=999
```

### 响应

```json
{"status": true, "msg": "任务已删除"}
```


## SaveFileBody

保存文本内容到指定文件，用于在线编辑代码或配置文件。

- **路由**：`POST /files`
- **action**：`SaveFileBody`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `SaveFileBody` |
| path | 是 | String | 文件绝对路径 |
| data | 是 | String | 要写入的文件内容 |
| encoding | 是 | String | 文件编码：`utf-8` / `ascii` / `ansi` / `GBK` / `BIG5` |

> **重要**：`encoding` 参数必须传入，否则会报 `FILE_SAVE_ERR` 错误。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 保存成功 |
| msg | String | `文件已保存!` |
| historys | Array | 历史版本 ID 列表 |
| st_mtime | String | 修改时间戳 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=SaveFileBody&path=/tmp/test.txt&data=hello world&encoding=utf-8
```

### 响应

```json
{"status": true, "msg": "文件已保存!", "historys": ["1779514192"], "st_mtime": "1779514192"}
```

## 相关接口

- [GetFileBody](/api/files/getfilebody) — 读取文件
- [CreateFile](/api/files/createfile) — 创建文件


## UploadFile

上传文件到指定目录。与面板其他接口不同，本接口使用 `multipart/form-data` 格式。

- **路由**：`POST /files`
- **action**：`UploadFile`
- **Content-Type**：`multipart/form-data`（非 form-urlencoded）

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `UploadFile`（FormData 字段） |
| path | 是 | String | 目标目录路径 |
| zunfile | 是 | File | 上传的文件（FormData 文件字段） |
| request_time | 是 | String | 认证时间戳（FormData 字段） |
| request_token | 是 | String | 认证令牌（FormData 字段） |

> 注意：认证参数 `request_time` 和 `request_token` 也要以 FormData 字段方式传递，不能放在 URL query 中。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 上传成功 |
| msg | String | `上传成功!` |

## 示例

### Python

```python
import requests

url = 'http://192.168.168.213:8888/files'
data = {
    'action': 'UploadFile',
    'path': '/www/wwwroot/testapi.bt.local',
    'request_time': str(int(time.time())),
    'request_token': token,
}
files = {'zunfile': ('test.txt', 'Hello World', 'text/plain')}
r = requests.post(url, data=data, files=files)
```

### cURL

```bash
curl -F 'action=UploadFile' \
     -F 'path=/www/wwwroot/testapi.bt.local' \
     -F 'request_time=1700000000' \
     -F 'request_token=xxx' \
     -F 'zunfile=@local_file.txt' \
     http://192.168.168.213:8888/files
```

### 响应

```json
{"status": true, "msg": "上传成功!"}
```


## dir_webshell_check

对指定目录发起 Webshell 木马扫描任务，结果写入面板安全日志。

- **路由**：`POST /files`
- **action**：`dir_webshell_check`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `dir_webshell_check` |
| path | 是 | String | 要扫描的目录绝对路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 扫描任务已启动 |
| msg | String | 提示信息 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=dir_webshell_check&path=/www/wwwroot
```

### 响应

```json
{"status": true, "msg": "正在启动木马查杀进程。详细信息会在面板安全日志中"}
```


## file_history_list

列出所有有编辑历史记录的文件及其历史版本信息。

- **路由**：`POST /files`
- **action**：`file_history_list`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `file_history_list` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 文件历史列表，每项含 `filepath` 和 `historys` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=file_history_list
```

### 响应

```json
[]
```


## file_webshell_check

对指定文件进行 Webshell（木马）检测。

- **路由**：`POST /files`
- **action**：`file_webshell_check`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `file_webshell_check` |
| filename | 是 | String | 要检测的文件绝对路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 无风险，`false` 检测到风险 |
| msg | String | `无风险` 或包含告警信息 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=file_webshell_check&filename=/www/wwwroot/test.php
```

### 响应

```json
{"status": true, "msg": "无风险"}
```


## get_bt_sync_status

检查服务器上文件同步工具（rsync/lsyncd）的安装和配置状态。

- **路由**：`POST /files`
- **action**：`get_bt_sync_status`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_bt_sync_status` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| have_sync | Boolean | 是否有同步任务 |
| data | Array | 同步任务数据列表 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=get_bt_sync_status
```

### 响应

```json
{"have_sync": false, "data": []}
```


## get_composer_version

获取当前服务器已安装的 Composer 版本号。

- **路由**：`POST /files`
- **action**：`get_composer_version`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_composer_version` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | String | Composer 版本号，如 `2.9.8` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=get_composer_version
```

### 响应

```
2.9.8
```


## get_files_store

获取用户收藏/标记的目录列表。

- **路由**：`POST /files`
- **action**：`get_files_store`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_files_store` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 收藏目录列表，每项含 `path`、`name`、`type` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=get_files_store
```

### 响应

```json
[]
```


## get_path_size

获取指定路径的磁盘占用大小。

- **路由**：`POST /files`
- **action**：`get_path_size`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_path_size` |
| path | 是 | String | 目标路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| path | String | 传入的路径 |
| size | Integer | 路径占用磁盘大小（字节） |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=get_path_size&path=/www/wwwroot
```

### 响应

```json
{"path": "/www/wwwroot", "size": 245760}
```


## get_videos

列出指定路径下的视频文件。

- **路由**：`POST /files`
- **action**：`get_videos`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_videos` |
| path | 是 | String | 目录路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 视频文件名列表，无视频时为空数组 `[]` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=get_videos&path=/www/wwwroot
```

### 响应

```json
[]
```


## install_rar

检查并安装 RAR 格式支持工具（rar/unrar）。若已安装则直接返回 `True`，否则自动安装。

- **路由**：`POST /files`
- **action**：`install_rar`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `install_rar` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Boolean | `True` 表示 RAR 支持就绪 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=install_rar
```

### 响应

```
true
```


## list_backups

列出已配置的云存储备份方案，包括本地和各类云存储。

- **路由**：`POST /files`
- **action**：`list_backups`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `list_backups` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 备份配置列表，每项含 `name`(类型名称)、`path`(路径) 等 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=list_backups
```

### 响应

```json
[]
```


## mutil_unzip

批量解压多个压缩文件到指定目录，支持 zip/tar.gz 等格式。

- **路由**：`POST /files`
- **action**：`mutil_unzip`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `mutil_unzip` |
| sfile_list | 是 | String | JSON 数组，要解压的文件路径列表 |
| dfile | 是 | String | 解压目标目录 |
| coding | 是 | String | 编码，如 `utf-8` |
| type1 | 是 | String | 压缩类型：`zip` / `tar` / `gz` 等 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 全部解压成功 |
| msg | String | 结果消息 |
| success | Array | 成功的文件列表 |
| fail | Array | 失败的文件列表 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=mutil_unzip&sfile_list=["/tmp/test.zip"]&dfile=/tmp/extract&coding=utf-8&type1=zip
```

### 响应

```json
{"status": true, "msg": "全部解压完成!", "success": [], "fail": []}
```


## remove_download_url

删除指定 ID 的分享下载链接。

- **路由**：`POST /files`
- **action**：`remove_download_url`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `remove_download_url` |
| id | 是 | Integer | 下载链接 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 删除成功 |
| msg | String | `删除成功!` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=remove_download_url&id=1
```

### 响应

```json
{"status": true, "msg": "删除成功!"}
```


## send_baota

将误报的 Webshell 文件内容提交到宝塔官方服务器，用于改善木马检测准确性。

需要面板已绑定宝塔账号。

- **路由**：`POST /files`
- **action**：`send_baota`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `send_baota` |
| filename | 是 | String | 被误报的文件路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 提交成功 |
| msg | String | `提交误报完成` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=send_baota&filename=/www/wwwroot/test.php
```

### 响应

```json
{"status": true, "msg": "提交误报完成"}
```


## test_path

检测指定路径是否存在，返回路径、类型（目录/文件）和存在状态。

- **路由**：`POST /files`
- **action**：`test_path`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `test_path` |
| path | 是 | String | 要检测的路径 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| path | String | 路径 |
| is_dir | Boolean | `true` 为目录，`false` 为文件，`null` 为不存在 |
| exists | Boolean | 路径是否存在 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=test_path&path=/www/wwwroot
```

### 响应

```json
{"path": "/www/wwwroot", "is_dir": true, "exists": true}
```


## update_composer

将服务器上已安装的 Composer 更新到最新版本。

- **路由**：`POST /files`
- **action**：`update_composer`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `update_composer` |

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 更新成功 |
| msg | String | 结果消息，如 `当前已经是最新版本，无需升级!` |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=update_composer
```

### 响应

```json
{"status": true, "msg": "当前已经是最新版本，无需升级!"}
```


## upload_files_exists

上传文件前批量检查目标路径下是否已有同名文件，返回已存在的文件列表。

- **路由**：`POST /files`
- **action**：`upload_files_exists`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `upload_files_exists` |
| files | 是 | String | 待检查的文件路径列表，多个用 `\n` 分隔 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array | 已存在的文件路径列表，空数组 `[]` 表示无冲突 |

## 示例

### 请求

```
POST /files HTTP/1.1
Host: 192.168.168.213:8888
Content-Type: application/x-www-form-urlencoded

action=upload_files_exists&files=/www/wwwroot/index.html
```

### 响应

```json
[]
```