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

`POST /ftp`

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

## Request body

_Required._

One of:

- `AddUser`
- `BatchSetUserPassword`
- `DeleteUser`
- `ModifyFtpUserAccess`
- `SetStatus`
- `SetUserPassword`
- `find_ftp`
- `get_action_logs`
- `get_login_logs`
- `setPort`
- `set_ftp_logs`
- `view_ftp_types`

## Example request

```text
{
  "request_time": "string",
  "request_token": "string",
  "action": "AddUser",
  "ftp_username": "string",
  "ftp_password": "string",
  "path": "string",
  "ps": "string"
}
```

## Code samples

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

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

## Responses

### default

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


## AddUser

创建新的 FTP 用户。

- **路由**：`POST /ftp`
- **action**：`AddUser`
- **前置条件**：面板已安装 Pure-FTPd

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `AddUser` |
| ftp_username | 是 | String | FTP 用户名（不含空格） |
| ftp_password | 是 | String | FTP 密码（不少于 6 位） |
| path | 是 | String | 用户主目录，如 `/www/wwwroot/testapi.bt.local` |
| ps | 否 | String | 备注信息 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 添加成功 |
| msg | String | `添加成功` |

## 示例

```json
{"status": true, "msg": "添加成功"}
```

## 相关接口

- [DeleteUser](/api/ftp/deleteuser)
- [SetUserPassword](/api/ftp/setuserpassword)
- [SetStatus](/api/ftp/setstatus)


## BatchSetUserPassword

批量修改多个 FTP 用户的密码。需同时传入用户 ID 和用户名。

- **路由**：`POST /ftp`
- **action**：`BatchSetUserPassword`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `BatchSetUserPassword` |
| data | 是 | String | JSON 数组，每项格式 `{"id":1,"ftp_username":"user1","new_password":"newpass"}` |

> 注意：`new_password` 长度不能少于 6 位。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array&lt;Object&gt; | 操作结果，每项含 `ftp_username` 和 `status` |

## 示例

### 请求

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

action=BatchSetUserPassword&data=[{"id":5,"ftp_username":"batch_test1","new_password":"NewPass1@"},{"id":6,"ftp_username":"batch_test2","new_password":"NewPass2@"}]
```

### 响应

```json
[{"ftp_username": "batch_test1", "status": true}, {"ftp_username": "batch_test2", "status": true}]
```


## DeleteUser

删除 FTP 用户。

- **路由**：`POST /ftp`
- **action**：`DeleteUser`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `DeleteUser` |
| id | 是 | Integer | FTP 用户在 `ftps` 表中的 ID |
| username | 是 | String | FTP 用户名 |

### 获取 FTP 用户 ID

通过 `/data` 接口查询：

```
action=getData&table=ftps&type=-1
```

## 示例

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

action=DeleteUser&id=3&username=api_ftp_doc
```

## 输出参数

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

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


## ModifyFtpUserAccess

修改指定 FTP 用户的下载带宽、上传带宽和最大存储空间限制。

- **路由**：`POST /ftp`
- **action**：`ModifyFtpUserAccess`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `ModifyFtpUserAccess` |
| username | 是 | String | FTP 用户名 |
| download_bandwidth | 否 | String | 下载带宽限制，如 `100KB`、`1MB`，默认 `0KB` |
| upload_bandwidth | 否 | String | 上传带宽限制，默认 `0KB` |
| max_size | 否 | String | 最大存储空间，如 `100MB`、`1GB`，默认 `0MB` |

## 输出参数

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

## 示例

### 请求

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

action=ModifyFtpUserAccess&username=err_test&download_bandwidth=100KB&upload_bandwidth=50KB&max_size=100MB
```

### 响应

```json
{"status": true, "msg": "修改成功"}
```


## SetStatus

启用或暂停指定的 FTP 用户。

- **路由**：`POST /ftp`
- **action**：`SetStatus`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `SetStatus` |
| id | 是 | Integer | FTP 用户 ID（从 `ftps` 表获取） |
| username | 是 | String | FTP 用户名 |
| status | 是 | String | `1` = 启用，`0` = 暂停 |

## 示例

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

action=SetStatus&id=3&username=api_ftp_doc&status=0
```

## 输出参数

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

```json
{"status": true, "msg": "操作成功"}
```


## SetUserPassword

修改指定 FTP 用户的密码。

- **路由**：`POST /ftp`
- **action**：`SetUserPassword`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `SetUserPassword` |
| id | 是 | Integer | FTP 用户 ID |
| ftp_username | 是 | String | FTP 用户名 |
| new_password | 是 | String | 新密码（不少于 6 位） |

## 示例

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

action=SetUserPassword&id=3&ftp_username=api_ftp_doc&new_password=NewPass@2024
```

## 输出参数

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

```json
{"status": true, "msg": "修改成功"}
```

---

## SetStatus

启用或暂停 FTP 用户。

- **路由**：`POST /ftp`
- **action**：`SetStatus`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `SetStatus` |
| id | 是 | Integer | FTP 用户 ID |
| username | 是 | String | FTP 用户名（**非** ftp_username） |
| status | 是 | String | `1` = 启用，`0` = 暂停 |

> 注意：`AddUser` 用 `ftp_username`，但 `DeleteUser`/`SetStatus` 用 `username`。这是面板设计不一致。

## 示例

```
action=SetStatus&id=3&username=api_ftp_doc&status=0
```

```json
{"status": true, "msg": "操作成功"}
```


## find_ftp

根据 FTP 用户 ID 查找用户详情。

- **路由**：`POST /ftp`
- **action**：`find_ftp`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `find_ftp` |
| id | 是 | Integer | FTP 用户 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` |
| msg | Array | 用户信息列表 |

## 示例

```json
{"status": true, "msg": []}
```


## get_action_logs

获取指定 FTP 用户的操作行为日志，包括上传、下载、重命名、删除等操作记录。

- **路由**：`POST /ftp`
- **action**：`get_action_logs`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_action_logs` |
| user_name | 是 | String | FTP 用户名 |
| p | 否 | Integer | 页码 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| page | String | 分页 HTML |
| data | Object | 含 `upload`/`download`/`rename`/`delete` 四个数组 |

## 示例

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


## get_login_logs

获取指定 FTP 用户的登录历史记录。

- **路由**：`POST /ftp`
- **action**：`get_login_logs`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_login_logs` |
| user_name | 是 | String | FTP 用户名 |
| p | 否 | Integer | 页码，默认 `1` |
| limit | 否 | Integer | 每页条数 |

## 输出参数

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

## 示例

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


## setPort

修改 Pure-FTPd 的监听端口，并自动更新防火墙规则。

- **路由**：`POST /ftp`
- **action**：`setPort`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `setPort` |
| port | 是 | Integer | 新端口号 |

## 示例

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

action=setPort&port=21
```

## 输出参数

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

```json
{"status": true, "msg": "修改成功"}
```


## set_ftp_logs

控制 FTP 操作日志的记录状态。

- **路由**：`POST /ftp`
- **action**：`set_ftp_logs`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `set_ftp_logs` |
| exec_name | 是 | String | `getlog` 查询状态 / 其他值切换状态 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | String | `stop` 已停止 / 其他值表示已开启 |

## 示例

```
stop
```


## view_ftp_types

获取 FTP 用户的自定义分类列表。

- **路由**：`POST /ftp`
- **action**：`view_ftp_types`

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` |
| msg | Array | 分类列表 |

## 示例

```json
{"status": true, "msg": []}
```