Skip to content
宝塔面板官方文档

FTP 管理：按 action 选择功能

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

POST
https://your-panel.example.com:8888/ftp
查看 Markdown

Request bodyX-WWW-FORM-URLENCODEDrequired

One of the following:

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

Returns

default

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

各操作详细说明

AddUseraction=AddUser添加 FTP 用户

创建新的 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 添加成功

示例

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

相关接口

BatchSetUserPasswordaction=BatchSetUserPassword批量修改 FTP 用户密码

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

  • 路由：POST /ftp
  • action：BatchSetUserPassword

输入参数

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

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

输出参数

参数名称 类型 描述
- Array<Object> 操作结果，每项含 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@"}]

响应

[{"ftp_username": "batch_test1", "status": true}, {"ftp_username": "batch_test2", "status": true}]
DeleteUseraction=DeleteUser删除 FTP 用户

删除 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 提示信息 
{"status": true, "msg": "删除成功"}
ModifyFtpUserAccessaction=ModifyFtpUserAccess修改 FTP 用户的带宽和存储限制

修改指定 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

响应

{"status": true, "msg": "修改成功"}
SetStatusaction=SetStatus启用或暂停 FTP 用户

启用或暂停指定的 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 提示信息 
{"status": true, "msg": "操作成功"}
SetUserPasswordaction=SetUserPassword修改 FTP 用户密码

修改指定 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 提示信息 
{"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

{"status": true, "msg": "操作成功"}
find_ftpaction=find_ftp按 ID 查找 FTP 用户信息

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

  • 路由：POST /ftp
  • action：find_ftp

输入参数

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

输出参数

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

示例

{"status": true, "msg": []}
get_action_logsaction=get_action_logs获取 FTP 用户的操作日志（上传/下载/重命名/删除）

获取指定 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 四个数组

示例

{"page": "<div>...</div>", "data": []}
get_login_logsaction=get_login_logs获取 FTP 用户的登录日志

获取指定 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 登录日志列表

示例

{"page": "<div>...</div>", "data": []}
setPortaction=setPort修改 FTP 服务监听端口

修改 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 提示信息 
{"status": true, "msg": "修改成功"}
set_ftp_logsaction=set_ftp_logs控制 FTP 日志记录的启停

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

  • 路由：POST /ftp
  • action：set_ftp_logs

输入参数

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

输出参数

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

示例

stop
view_ftp_typesaction=view_ftp_types获取 FTP 账户的分类列表

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

  • 路由：POST /ftp
  • action：view_ftp_types

输出参数

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

示例

{"status": true, "msg": []}
Navigation

Type to search…

↑↓ navigate↵ selectEsc close