版本：latest

宝塔 MCP 工具说明

共 98 个工具。标题即 MCP 调用时的 tool name；入参表来自各工具的 input_schema。

通用约定

返回结构：所有工具统一返回 {"status": bool, "msg": string, ...}；status=false 为失败（msg 说明原因），成功时按需附加 data、task_id 等字段。
风险等级：low 只读/安全；medium 有副作用；high 高危（删除/覆盖/执行命令），调用前须二次确认。
基础工具：标记「基础工具」者仅对非本机部署（nginx/public）的客户端开放。
必填：是=必填，否=可选。

基础

Read

读取文件 · 分类 基础 · 风险 low · 基础工具

读取文本文件；查看文件或读取 Grep 命中位置附近内容时使用。只读。

data 返回 lines 和 next_offset；结果达到约 40KB 时会提前分页。lines 包含 number 和 content，单行最多返回 1000 字符，超出时追加 ...；无效 UTF-8 字节会替换。next_offset 非空时传回 offset 继续读取。

入参

参数名	类型	必填	说明
`file_path`	`string`	是	允许范围内的绝对路径。
`offset`	`integer`	否	起始行，默认 1。
`limit`	`integer`	否	行数，默认及上限 2000。

调用示例

{
  "file_path": "示例",
  "offset": 1,
  "limit": 2000
}

Edit

精确修改文件 · 分类 基础 · 风险 high · 基础工具

精确修改已有 UTF-8 文本文件；先用 Read 获取原文，再进行小范围替换。高风险：调用前必须向用户确认。

修改前后的文件上限均为 4MB。匹配多处时请增加上下文，或设置 replace_all=true 全部替换。成功时仅返回 replacements。

入参

参数名	类型	必填	说明
`file_path`	`string`	是	允许范围内的绝对路径。
`old_string`	`string`	是	必须与原文完全一致。
`new_string`	`string`	是	替换后的文本。
`replace_all`	`boolean`	否	true 时全部替换，默认 false 只替换第一处。

调用示例

{
  "file_path": "示例",
  "old_string": "示例",
  "new_string": "示例",
  "replace_all": false
}

Write

写入文件 · 分类 基础 · 风险 high · 基础工具

创建或完整覆盖 UTF-8 文本文件；局部修改请使用 Edit。高风险：调用前必须向用户确认。

父目录不存在时自动创建。覆盖已有文件前先用 Read 确认原文。成功时仅返回 bytes。

入参

参数名	类型	必填	说明
`file_path`	`string`	是	允许范围内的绝对路径。
`content`	`string`	是	文件完整内容，不支持追加。

调用示例

{
  "file_path": "示例",
  "content": "示例"
}

Glob

查找文件 · 分类 基础 · 风险 low · 基础工具

按名称或扩展名查找文件；不知道文件准确路径时使用。只读。

默认跳过 .git、node_modules、venv、dist 等目录。files 是按修改时间倒序排列的绝对路径； next_offset 非空时传回 offset 继续。匹配超过 2000 个文件时请缩小范围。

入参

参数名	类型	必填	说明
`pattern`	`string`	是	相对 glob 模式，如 */.py。
`path`	`string`	否	允许范围内的绝对目录，留空使用当前目录。
`offset`	`integer`	否	默认 0。
`limit`	`integer`	否	默认及上限 50。

调用示例

{
  "pattern": "示例",
  "path": "",
  "offset": 0,
  "limit": 50
}

Grep

搜索文件内容 · 分类 基础 · 风险 low · 基础工具

在文件或目录中搜索内容；找代码、配置或日志信息时优先使用，无需先读取整个文件。只读。

目录搜索默认跳过常见缓存、依赖和构建目录，并最多扫描 2000 个文件。 matches 返回匹配行、绝对路径和行号；单行最多搜索前 65536 个字符、返回前 1000 字符。next_offset 非空时传回 offset 继续。忽略大小写可在 pattern 前加 (?i)，查看上下文请用返回的路径和行号调用 Read。

入参

参数名	类型	必填	说明
`pattern`	`string`	是	Python 正则。
`path`	`string`	否	允许范围内的绝对文件或目录，留空搜索当前目录。
`glob`	`string`	否	文件模式过滤，如 */.py。
`offset`	`integer`	否	默认 0。
`limit`	`integer`	否	默认及上限 50。

调用示例

{
  "pattern": "示例",
  "path": "",
  "glob": "",
  "offset": 0,
  "limit": 50
}

LS

列出目录 · 分类 基础 · 风险 low · 基础工具

列出目录的直接子项；浏览目录或确认路径时使用。只读。

目录排在文件前；entry 包含 name、绝对路径 path 和 is_dir；敏感项不会返回。 next_offset 非空时传回 offset 继续。项目超过 2000 个时请改用 Glob。

入参

参数名	类型	必填	说明
`path`	`string`	否	绝对目录，留空使用当前目录。
`offset`	`integer`	否	默认 0。
`limit`	`integer`	否	默认及上限 50。

调用示例

{
  "path": "",
  "offset": 0,
  "limit": 50
}

Bash

执行命令 · 分类 基础 · 风险 high · 基础工具

执行 shell 命令（sh -c）。high 风险，需 Key 显式授权。

前台最多等 20s（低于工具全局超时），未完成自动转后台并返回 task_id；用 BashStatus 查询结果，用 BashStop 停止。后台最长 30 分钟，超则强杀。run_in_background=true 立即后台。输出受 50KB 上限（头+尾截断）。极少数灾难命令（rm -rf 关键路径 / mkfs / dd 覆写块设备 / 关机重启 / fork 炸弹）被拦拒绝。

入参

参数名	类型	必填	说明
`command`	`string`	是	shell 命令串，必填。
`description`	`string`	否	命令用途说明，仅进审计日志，不影响执行。
`timeout`	`integer`	否	前台愿意等待的秒数上限，默认 20，服务端封顶 20。
`run_in_background`	`boolean`	否	true 时跳过前台等待，立即后台返回 task_id。

调用示例

{
  "command": "示例",
  "description": "",
  "timeout": 20,
  "run_in_background": false
}

BashStatus

查询命令状态 · 分类 基础 · 风险 low · 基础工具

查询后台任务的状态、输出与最终结果。low 只读。

task_id 由接入统一后台任务管理器的工具返回；此处只读其状态，绝不新起进程。 wait=true 时最多等 timeout 秒（默认上限 20s）再返回；任务完成时返回完整输出并清理。运行中返回当前已捕获输出；未知 task_id 返回错误。

入参

参数名	类型	必填	说明
`task_id`	`string`	是	后台任务标识，必填。
`wait`	`boolean`	否	true 时阻塞等待任务结束（受前台 20s 上限）。
`timeout`	`integer`	否	wait=true 时的等待秒数，0 表示用默认上限。

调用示例

{
  "task_id": "示例",
  "wait": false,
  "timeout": 0
}

BashStop

终止后台任务 · 分类 基础 · 风险 medium · 基础工具

终止或停止追踪后台任务。medium 风险。

适用于所有统一 task_id 的后台任务。子进程任务会被真实终止；函数线程任务无法强杀，仅标记为 stopped，后台操作仍可能执行完成。未知 task_id 幂等返回 stopped。

入参

参数名	类型	必填	说明
`task_id`	`string`	是	后台任务标识，必填。

调用示例

{
  "task_id": "示例"
}

网站

SiteList

获取网站列表 · 分类 网站 · 风险 low

获取宝塔面板管理的网站列表。只读，仅面板原生站点。

data.sites 每项含 name、domains、ports、status、ps、project_type、path、php_version、ssl； php_version 仅对 PHP 类站点（PHP/phpmod/wp2）有值，其他语言恒为空串； ssl 为证书状态（enabled、days_left、not_after、issuer、san_domains，未部署时 enabled 为 False）。 name 是站点唯一标识，作为其他网站工具的站点参数。

入参

参数名	类型	必填	说明
`search`	`string`	否	按站点名模糊搜索。
`page`	`integer`	否	页码，从 1 开始。
`page_size`	`integer`	否	每页数量，默认 20、最大 50。

调用示例

{
  "search": "",
  "page": 1,
  "page_size": 20
}

SiteGetConfig

获取网站配置 · 分类 网站 · 风险 low

获取指定网站当前生效的 webserver 配置文件内容。只读。

data 含 webserver（nginx/apache）、config_path、content（配置全文）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。

调用示例

{
  "site_name": "示例"
}

SiteLogs

获取网站访问日志 · 分类 网站 · 风险 low

获取指定网站的访问日志（原始文本，末尾片段）。只读。网站打不开/报错/502/500 等排查先看本工具。

已对 URL 中的凭据参数（token/key/password 等）脱敏。仅访问日志；错误日志需另查 webserver 的 error log。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。

调用示例

{
  "site_name": "示例"
}

SiteTraffic

获取网站流量 · 分类 网站 · 风险 low

获取指定网站的访问流量统计（UV/PV、请求数、流量趋势等）。只读。

返回单站流量数据；全站排名与总览用 TrafficAnalysis。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。

调用示例

{
  "site_name": "示例"
}

SiteCreate

创建网站 · 分类 网站 · 风险 medium

创建网站并绑定 PHP 版本。中风险，有副作用。

php_version 为空时自动绑定已装版本（面板默认优先）。成功时 data 含 site_id、path、php_version、nginx_config。

入参

参数名	类型	必填	说明
`domain`	`string`	是	域名或 IP，不含端口。
`site_path`	`string`	是	网站目录绝对路径。
`port`	`string`	否	站点端口，默认 80。
`php_version`	`string`	否	PHP 版本号（如 "82"），留空自动绑定。

调用示例

{
  "domain": "示例",
  "site_path": "示例",
  "port": "80",
  "php_version": ""
}

SiteDelete

删除网站 · 分类 网站 · 风险 high

删除宝塔面板中的网站。高风险、不可逆，调用前必须向用户确认。删前用 SiteList 核对避免误删。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`delete_path`	`boolean`	否	True 连网站目录一并删（默认），False 仅删站点记录保留文件。
`ftp`	`boolean`	否	True 同时删除关联 FTP（默认 False）。
`database`	`boolean`	否	True 同时删除关联数据库（默认 False）。
`confirm`	`boolean`	否	首次调用必须为 false，仅建立确认记录且不会执行。收到 waiting_confirm 后必须停止并询问用户。只有收到一条后续用户消息明确同意，才可使用完全相同的业务参数设置为 true。

调用示例

{
  "site_name": "示例",
  "delete_path": true,
  "ftp": false,
  "database": false,
  "confirm": false
}

OneClickDeploy

一键部署应用 · 分类 网站 · 风险 medium

一键部署 CMS 应用。中风险，有副作用。需先用 SiteCreate 建站。

WordPress 自动补全：绑定 PHP、建库、生成 wp-config.php 并模拟安装向导。可重入：已安装时跳过。成功时 data 含 admin_username、admin_password、success_url、db_name、db_user、db_password、auto_installed。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`app`	`string`	是	应用标识，如 wordpress、discuz、discuzx、typecho、dedecms。

调用示例

{
  "site_name": "示例",
  "app": "示例"
}

TrafficAnalysis

获取全站流量分析 · 分类 网站 · 风险 low

获取全部网站的流量分析聚合数据。只读。返回全站聚合：三日总览、当日 Top5 站点（按流量降序）、近 7 日趋势；各段含流量/请求数/UV/PV。字段以实际返回为准。单站明细用 SiteStats。

入参

无入参，调用时传空对象 {}。

调用示例

{}

SiteCertList

获取证书库列表 · 分类 网站 · 风险 low

获取面板证书库中的证书列表（本地导入 + Let's Encrypt + 云证书）。只读。

data.certs 每项含 id、hash、subject、dns（覆盖域名）、not_after、endtime（剩余天数）、 cloud_id（-1 为本地证书）、use_for_site（已部署到的站点 id 列表）。

入参

参数名	类型	必填	说明
`search`	`string`	否	按证书名称(subject)模糊搜索。
`status_filter`	`string`	否	all/valid/expiring/expired/expired_long 之一：全部/未过期/15天内到期/已过期/过期1年以上。
`force_refresh`	`boolean`	否	是否强制刷新证书库（与宝塔云端同步），默认 false。

调用示例

{
  "search": "",
  "status_filter": "all",
  "force_refresh": false
}

SiteSSLDeploy

部署SSL证书 · 分类 网站 · 风险 medium

部署证书到网站：将证书库中已有证书（ssl_hash）或直接提供的证书（PEM 内容/文件）部署到指定网站。

中风险：写入站点证书目录并更新 webserver 配置。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`ssl_hash`	`string`	否	证书库中的证书 hash（SiteCertList 查询），与证书内容/文件来源互斥。
`certificate`	`string`	否	PEM 证书内容（含证书链），与 private_key 成对提供。
`private_key`	`string`	否	PEM 私钥内容。
`cert_file`	`string`	否	证书文件绝对路径（服务器本地），与 key_file 成对提供。
`key_file`	`string`	否	私钥文件绝对路径。

调用示例

{
  "site_name": "示例",
  "ssl_hash": "",
  "certificate": "",
  "private_key": "",
  "cert_file": "",
  "key_file": ""
}

SiteSSLApply

申请SSL证书 · 分类 网站 · 风险 medium

为站点配置/启用 HTTPS：申请并部署 SSL 证书（Let's Encrypt）。中风险：会写站点目录并重载 web 服务。

同步执行，耗时几十秒到数分钟。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList。
`domains`	`array<string, integer, number, boolean>`	是	要签发的域名列表。
`validation`	`string`	否	验证方式，仅支持 http。

调用示例

{
  "site_name": "示例",
  "domains": [],
  "validation": "http"
}

DomainManage

网站域名管理 · 分类 网站 · 风险 high

管理网站绑定域名：添加或删除。高风险，删除不可逆，调用前须向用户确认。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`operation`	`string`	是	add 或 remove。
`domains`	`string`	是	域名列表，逗号分隔，单个可带 :port（不带端口默认 80）；remove 支持批量删除。

调用示例

{
  "site_name": "示例",
  "operation": "示例",
  "domains": "示例"
}

SiteConfig

配置网站 · 分类 网站 · 风险 medium

配置网站：切换 PHP 版本 / 设置运行目录 / 配置默认首页 / 配置伪静态 / 重载配置。中风险，有副作用。

action 说明：

php_version: value 填版本号（如 "82"），已安装版本用 SoftwareList 查询，当前版本见 SiteList 的 php_version；
run_path: value 填相对路径（如 "/public"），空串表示站点根目录；
index: value 填逗号分隔的默认文档（如 "index.php,index.html"）；
rewrite: value 填伪静态规则全文；
reload: value 忽略，重载 webserver 配置（php_version/run_path/index 修改后面板已自动重载，本 action 用于手动改配置文件后）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`action`	`string`	是	配置项，php_version/run_path/index/rewrite/reload 之一。
`value`	`string`	否	配置值，reload 时忽略。

调用示例

{
  "site_name": "示例",
  "action": "示例",
  "value": ""
}

SiteControl

启停网站 · 分类 网站 · 风险 medium

启动/停止网站。中风险，有副作用（修改 webserver 配置并重载服务）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。
`action`	`string`	是	start/stop 之一。

调用示例

{
  "site_name": "示例",
  "action": "示例"
}

SiteBackup

备份网站 · 分类 网站 · 风险 medium

备份站点（含文件、配置、SSL、关联数据库）。中风险：占用磁盘与 IO。

该操作可能进入后台并返回 task_id；用 BashStatus 查询状态与结果，用 BashStop 停止任务。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	站点名，取自 SiteList 返回的 name。

调用示例

{
  "site_name": "示例"
}

网络

WebFetch

抓取网页 · 分类 网络 · 风险 low · 基础工具

获取公开网页内容，供客户端依据 prompt 阅读、提取或分析。只读，不提交表单、不携带认证信息，也不执行网页脚本。

返回受限 Markdown 和 prompt，由调用方完成分析。响应超过 32KB 时拒绝返回。

入参

参数名	类型	必填	说明
`url`	`string`	是	完整 http 或 https 地址。
`prompt`	`string`	是	描述希望从网页中得到的信息。

调用示例

{
  "url": "示例",
  "prompt": "示例"
}

ServerIP

获取服务器IP · 分类 网络 · 风险 low

获取服务器的内网与公网 IP。只读。 data.internal 为内网 IPv4 列表（各网卡，已排除 loopback，多网卡时含多个）； data.external 为公网 IP，查询失败时为 None。

入参

无入参，调用时传空对象 {}。

调用示例

{}

Upload

上传 · 分类 网络 · 风险 medium

上传客户端本地文件；调用方必须能在客户端本机执行 curl，否则无法用本工具上传。

首次调用传 file_name，执行返回的 next_action 中对应平台命令，只替换 <LOCAL_FILE>。命令已固定服务器公钥，应原样执行。命令失败或结果不确定时，按返回的 on_failure 处理，不要重跑旧命令。不要自行获取 offset、分片或构造 PUT/PATCH。ready=true 表示完成；成功后将返回文件绝对路径，可直接使用 path。仅上传已经生成完毕且不再写入的本地文件。

入参

参数名	类型	必填	说明
`file_name`	`string`	否	首次调用时传本地文件名，不传路径或文件内容。
`size`	`integer`	否	可选文件字节数，用于大小校验。
`sha256`	`string`	否	可选的预期 SHA256；传入时校验完整内容，未传时只返回实际摘要，expected_sha256_matched=null。
`file_id`	`string`	否	恢复上传时传首次调用返回的值。

调用示例

{
  "file_name": "",
  "size": null,
  "sha256": "",
  "file_id": ""
}

数据库

DatabaseList

获取数据库列表 · 分类 数据库 · 风险 low

获取面板管理的 MySQL 数据库列表。只读。

data.databases 每项含 name、username、accept（允许连接的来源 IP）、type。不返回密码；连接密码须向用户索取。查库列表用本工具，不要用 SQL。

入参

参数名	类型	必填	说明
`search`	`string`	否	按库名模糊搜索。

调用示例

{
  "search": ""
}

DatabaseCreate

创建数据库 · 分类 数据库 · 风险 medium

创建 MySQL 数据库（本地实例）并创建访问用户。中风险。

password 留空时自动生成强密码并在返回中给出。成功时 data 含 name、username、address。

入参

参数名	类型	必填	说明
`name`	`string`	是	库名，必填。
`db_user`	`string`	是	用户名，必填。
`password`	`string`	否	密码，留空自动生成。
`codeing`	`string`	否	字符集，默认 utf8mb4（仅 utf8/utf8mb4/gbk/big5）。
`address`	`string`	否	访问权限，默认 127.0.0.1（仅本机），远程传 % 或具体 IP。
`ps`	`string`	否	备注。

调用示例

{
  "name": "示例",
  "db_user": "示例",
  "password": "",
  "codeing": "utf8mb4",
  "address": "127.0.0.1",
  "ps": ""
}

DatabaseDelete

删除数据库 · 分类 数据库 · 风险 high

删除指定 MySQL 数据库。高风险：调用前必须向用户确认。删前用 DatabaseList 核对避免误删。

面板启用数据库回收站时，删除的库进回收站（可恢复）；否则真删、不可逆。

入参

参数名	类型	必填	说明
`name`	`string`	是	库名，取自 DatabaseList 返回的 name。

调用示例

{
  "name": "示例"
}

DatabaseBackup

备份数据库 · 分类 数据库 · 风险 medium

备份指定 MySQL 数据库（全库，存入面板备份目录）。中风险：占用磁盘与 IO。

该操作可能进入后台并返回 task_id；用 BashStatus 查询状态与结果，用 BashStop 停止任务。

入参

参数名	类型	必填	说明
`name`	`string`	是	库名，取自 DatabaseList 返回的 name。

调用示例

{
  "name": "示例"
}

MysqlQuery

MySql查询 · 分类 数据库 · 风险 low

对 MySQL 执行只读 SQL 并返回结果行。只读，不修改任何数据。

仅允许 SELECT/SHOW/DESCRIBE/DESC/EXPLAIN/WITH/TABLE；写关键字、系统库表与敏感列（password/authentication_string）一律拒绝。SQL 含 %s 占位符时必须以 params 提供绑定值，禁止字符串拼接。表结构类查询直接传 SHOW CREATE TABLE/DESCRIBE 等。

入参

参数名	类型	必填	说明
`sql`	`string`	是	单条只读 SQL，必填。
`database`	`string`	否	目标库名，留空连实例级（可查 SHOW DATABASES 等）。
`params`	`array<string, integer, number, boolean>`	否	%s 占位符的绑定值列表，sql 含 %s 时必填。
`limit`	`integer`	否	最多返回行数，默认 100，上限 200；超出截断并以 truncated 标记。

调用示例

{
  "sql": "示例",
  "database": "",
  "params": null,
  "limit": 100
}

MysqlExecute

MySql写操作 · 分类 数据库 · 风险 high

对 MySQL 执行单条写 SQL（DML/表级 DDL）。高风险，在执行前要求用户确认。系统库写入与库级/用户级 DDL 拒绝。

入参

参数名	类型	必填	说明
`sql`	`string`	是	单条写 SQL，含 %s 占位符时必须以 params 提供绑定值。
`database`	`string`	是	目标库名，必填。
`params`	`array<string, integer, number, boolean>`	否	%s 占位符的绑定值列表，sql 含 %s 时必填。
`confirm`	`boolean`	否	首次调用必须为 false，仅建立确认记录且不会执行。收到 waiting_confirm 后必须停止并询问用户。只有收到一条后续用户消息明确同意，才可使用完全相同的业务参数设置为 true。

调用示例

{
  "sql": "示例",
  "database": "示例",
  "params": null,
  "confirm": false
}

服务

ServiceStatus

获取服务状态 · 分类 服务 · 风险 low

查询服务的安装与运行状态。只读，不改变系统状态。

不传时返回所有支持的服务（nginx、apache、mysql、redis、pure-ftpd、memcached、mongodb + 已装 php-fpm 版本）。支持别名（httpd/apache2→apache、mysqld/mariadb/mariadbd→mysql）；yum/apt 安装的服务同样可识别。未安装返回 status=not_installed，不误报 stopped；传入不支持的名称返回错误并列出支持范围。

入参

参数名	类型	必填	说明
`service_names`	`array<string, integer, number, boolean>`	否	服务名列表（如 ["nginx","mysql"]），留空返回全部。支持别名，自动去重。

调用示例

{
  "service_names": null
}

ServiceControl

启停服务 · 分类 服务 · 风险 medium

启动/停止指定服务。中风险：会短暂影响该服务现有连接，调用前须向用户确认。

未安装的服务跳过（status=not_installed）。成功时 data.results 每项含 service、operated、running、status。重启场景由模型自行组合：先 stop 再 start。

入参

参数名	类型	必填	说明
`service_names`	`array<string, integer, number, boolean>`	是	服务名列表，别名同 ServiceStatus。
`action`	`string`	是	start/stop 之一。

调用示例

{
  "service_names": [],
  "action": "示例"
}

Docker

ContainerList

容器列表 · 分类 Docker · 风险 low

获取容器列表（状态、IP、端口映射）。只读，不改变任何状态。

未安装或未运行时 data.installed=false 且 data.service_status 说明原因。 data.container_list 每项含 id、name（面板显示名）、status、image、ip、ports、cpu_usage。

入参

无入参，调用时传空对象 {}。

调用示例

{}

ContainerLogs

容器日志 · 分类 Docker · 风险 low

获取容器日志（尾部 lines 行）。只读。

入参

参数名	类型	必填	说明
`container`	`string`	是	容器名（面板显示名/真实名/ID）。
`lines`	`integer`	否	取尾部行数，上限 1000。

调用示例

{
  "container": "示例",
  "lines": 200
}

ContainerInspect

容器详情 · 分类 Docker · 风险 low

查看容器详情（状态、镜像、重启策略、挂载、端口、网络）。只读。

用于排查异常：挂载是否在、端口映射、重启策略、健康状态等。环境变量可能含密码等敏感值，刻意不返回。

入参

参数名	类型	必填	说明
`container`	`string`	是	容器名（面板显示名/真实名/ID）。

调用示例

{
  "container": "示例"
}

ComposeList

编排项目列表 · 分类 Docker · 风险 low

获取 docker-compose 项目列表（含模板与运行状态）。只读。

data.project_list 每项含 id、name、remark、status、path、containers。

入参

无入参，调用时传空对象 {}。

调用示例

{}

ImageList

镜像列表 · 分类 Docker · 风险 low

获取镜像列表（名称/标签/大小）。只读。

data.images_list 每项含 id、name、tags、size（字节）；installed/service_status 说明 Docker 状态。

入参

无入参，调用时传空对象 {}。

调用示例

{}

VolumeList

存储卷列表 · 分类 Docker · 风险 low

获取存储卷列表（名称、驱动、挂载点、使用容器）。只读。

data.volume 每项含 Name、Driver、Mountpoint、container（使用该卷的容器名）。

入参

无入参，调用时传空对象 {}。

调用示例

{}

NetworkList

网络列表 · 分类 Docker · 风险 low

获取 docker 网络列表（名称、驱动、子网、网关）。只读。

data.network 每项含 id、name、driver、subnet、gateway。

入参

无入参，调用时传空对象 {}。

调用示例

{}

ContainerControl

容器启停 · 分类 Docker · 风险 medium

启动/停止/重启容器。中风险：会改变容器运行状态，调用前须向用户确认。返回操作后的容器状态。

入参

参数名	类型	必填	说明
`container`	`string`	是	容器名（面板显示名/真实名/ID）。
`action`	`string`	是	操作，仅支持 start/stop/restart。

调用示例

{
  "container": "示例",
  "action": "示例"
}

ContainerDelete

删除容器 · 分类 Docker · 风险 high

删除容器（强制，同步清理宝塔 name_map 与监控统计）。高风险：容器及数据不可恢复，调用前必须确认。

入参

参数名	类型	必填	说明
`container`	`string`	是	容器名（面板显示名/真实名/ID）。

调用示例

{
  "container": "示例"
}

ImagePull

拉取镜像 · 分类 Docker · 风险 medium

拉取镜像。中风险。

该操作可能进入后台并返回 task_id；用 BashStatus 查询状态与结果，用 BashStop 停止任务。

入参

参数名	类型	必填	说明
`image`	`string`	是	镜像名，如 nginx:latest，可带仓库地址（如 registry.example.com/ns/img:tag）。
`registry`	`string`	否	私有仓库地址，默认空即 Docker Hub。
`username`	`string`	否	私有仓库用户名，与 password 成对填写。
`password`	`string`	否	私有仓库密码，仅经 stdin 传入，不进审计。

调用示例

{
  "image": "示例",
  "registry": "",
  "username": "",
  "password": ""
}

系统

SystemInfo

获取系统信息 · 分类 系统 · 风险 low

获取服务器系统资源概况。只读。返回 CPU（核数/使用率）、内存（总量/已用/使用率）、根分区磁盘（总量/已用/使用率）、系统负载（1/5/15 分钟）、运行时长（秒）、系统版本。

入参

无入参，调用时传空对象 {}。

调用示例

{}

软件

SoftwareList

获取软件列表 · 分类 软件 · 风险 low

获取宝塔软件商店清单及安装状态。只读。

data.software 每项含 name、title、version(当前已装版本，未装为空)、ps、setup、task(安装任务状态)、 versions(可选版本)。total 取自分页信息，未知时为 None。

入参

参数名	类型	必填	说明
`search`	`string`	否	按名称搜索。
`page`	`integer`	否	页码，从 1 起。
`page_size`	`integer`	否	每页数量，默认 20、最大 100。

调用示例

{
  "search": "",
  "page": 1,
  "page_size": 20
}

SoftwareInstall

安装软件 · 分类 软件 · 风险 medium

提交软件安装（异步）。中风险。立即返回，用 SoftwareList 查看安装进度。

入参

参数名	类型	必填	说明
`name`	`string`	是	软件名（nginx、mysql、php-7.4 等）。
`version`	`string`	否	安装版本，留空时取 SoftwareList 返回的第一个版本（稳定版）。
`type`	`string`	否	安装方式，默认 1。

调用示例

{
  "name": "示例",
  "version": "",
  "type": "1"
}

SoftwareUninstall

卸载软件 · 分类 软件 · 风险 high

提交软件卸载（面板同步执行）。高风险：移除已装软件，调用前必须确认。

入参

参数名	类型	必填	说明
`name`	`string`	是	软件名，同 SoftwareInstall。
`version`	`string`	否	卸载版本，同 SoftwareInstall。
`type`	`string`	否	保留兼容，卸载方式由面板内部确定。

调用示例

{
  "name": "示例",
  "version": "",
  "type": "0"
}

防火墙

FirewallStatus

获取防火墙状态 · 分类 防火墙 · 风险 low

获取系统防火墙状态。只读。

返回 data：running 是否启用、type 类型(ufw/firewalld/iptables)、port_count 端口规则数、ping 是否响应 Ping。

入参

无入参，调用时传空对象 {}。

调用示例

{}

FirewallPortList

获取端口规则列表 · 分类 防火墙 · 风险 low

获取防火墙端口规则列表。只读，防火墙未启用时返回错误。

返回面板分页结构，规则项含 Port、Protocol、Address(来源)、Strategy(accept/drop)、Chain、brief。

入参

参数名	类型	必填	说明
`chain`	`string`	否	ALL/INPUT/OUTPUT。
`search`	`string`	否	按端口或备注模糊匹配。
`page`	`integer`	否	页码，从 1 起。
`page_size`	`integer`	否	每页数量，上限 100。

调用示例

{
  "chain": "ALL",
  "search": "",
  "page": 1,
  "page_size": 20
}

FirewallIpList

获取IP规则列表 · 分类 防火墙 · 风险 low

获取防火墙 IP 规则列表(放行或屏蔽的 IP)。只读，防火墙未启用时返回错误。

返回面板分页结构，规则项含 Address(IP/CIDR)、Strategy(accept/drop)、Chain、Family、brief。

入参

参数名	类型	必填	说明
`chain`	`string`	否	ALL/INPUT/OUTPUT。
`search`	`string`	否	按 IP 或备注模糊匹配。
`page`	`integer`	否	页码，从 1 起。
`page_size`	`integer`	否	每页数量，上限 100。

调用示例

{
  "chain": "ALL",
  "search": "",
  "page": 1,
  "page_size": 20
}

FirewallPortSet

设置端口规则 · 分类 防火墙 · 风险 high

添加或删除防火墙端口规则。高风险，调用前须向用户确认；防火墙未启用时返回错误。

删除时 protocol/address/strategy/chain 须与添加时一致，建议先 FirewallPortList 查询。

入参

参数名	类型	必填	说明
`operation`	`string`	是	add 或 remove。
`port`	`string`	是	端口或范围，如 80、8080-8090。
`protocol`	`string`	否	tcp/udp/tcp/udp，默认 tcp/udp。
`address`	`string`	否	来源 IP，默认 all。
`strategy`	`string`	否	accept 或 drop。
`chain`	`string`	否	INPUT 或 OUTPUT。
`brief`	`string`	否	备注。

调用示例

{
  "operation": "示例",
  "port": "示例",
  "protocol": "tcp/udp",
  "address": "all",
  "strategy": "accept",
  "chain": "INPUT",
  "brief": ""
}

FirewallIpSet

设置IP规则 · 分类 防火墙 · 风险 high

添加或删除防火墙 IP 规则(放行或屏蔽某 IP 全部访问)。高风险，调用前须向用户确认；防火墙未启用时返回错误。

删除时 strategy/chain/family 须与添加时一致，建议先 FirewallIpList 查询。

入参

参数名	类型	必填	说明
`operation`	`string`	是	add 或 remove。
`address`	`string`	是	目标 IP/CIDR（如 1.2.3.4），不支持 all。
`strategy`	`string`	否	accept 或 drop，默认 drop。
`chain`	`string`	否	INPUT 或 OUTPUT。
`family`	`string`	否	ipv4 或 ipv6。
`brief`	`string`	否	备注。

调用示例

{
  "operation": "示例",
  "address": "示例",
  "strategy": "drop",
  "chain": "INPUT",
  "family": "ipv4",
  "brief": ""
}

Java

JavaJdk

管理JDK · 分类 Java · 风险 medium

管理本机 JDK（中风险：install/add_local 有副作用，list 只读）。

action=list 返回 data.jdks（每项 name/path/operation/is_current； operation: 0 未装 / 1 已装 / 2 系统自带 / 3 安装中）。 action=install 异步安装指定版本（提交面板任务队列），用 list 轮询 operation 3→1 确认完成。 action=add_local 登记本机已有但未被面板收录的 JDK 路径。

入参

参数名	类型	必填	说明
`action`	`string`	否	list/install/add_local，默认 list。
`version`	`string`	否	install 的版本号（如 jdk-17.0.8，可先用 list 确认）。
`jdk_path`	`string`	否	add_local 的 JDK 可执行文件路径（如 .../bin/java）。

调用示例

{
  "action": "list",
  "version": "",
  "jdk_path": ""
}

JavaProjectCreate

分析并创建Java项目 · 分类 Java · 风险 medium

把本机 jar 部署成面板可管理 Java 项目（中风险：创建即注册并自动启动）。

analyze_only=true 只读分析（端口/生效配置/隐患），不创建；创建时复用分析补全缺失参数。传 domains 时自动建 Nginx 反代（best-effort，失败 data.proxy_created=false，用 JavaProjectModify add_proxy 补，否则域名 403）。缺省：port=jar 分析值、jdk_path=已装 JDK、project_cmd 自动拼装。成功 data 含上述参数 + analysis。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名（面板内唯一），必填。
`jar_path`	`string`	否	jar 绝对路径，必填。
`jdk_path`	`string`	否	JDK 根路径，可带 /bin/java；缺省自动选。
`port`	`integer`	否	应用端口，缺省用 jar 分析值。
`run_user`	`string`	否	运行用户，默认 www。
`project_cmd`	`string`	否	完整启动命令，缺省自动拼装。
`domains`	`array<string, integer, number, boolean>`	否	域名列表，'域名' 或 '域名:端口'。
`ps`	`string`	否	备注。
`analyze_only`	`boolean`	否	true 只分析。
`release_firewall`	`boolean`	否	是否放行端口防火墙。
`proxy_path`	`string`	否	反代路由前缀，默认 '/'；置空只绑域名。

调用示例

{
  "project_name": "",
  "jar_path": "",
  "jdk_path": "",
  "port": 0,
  "run_user": "www",
  "project_cmd": "",
  "domains": null,
  "ps": "",
  "analyze_only": false,
  "release_firewall": false,
  "proxy_path": "/"
}

JavaProjectInfo

查看Java项目 · 分类 Java · 风险 low

查看面板管理的 Java 项目。只读。

project_name 留空返回全部项目列表（含运行态 pid/listen）；给出时返回单项目详情： project_config（jar/JDK/启动命令/日志/域名/绑定状态）、pid、监听端口、ssl、log_files （应用日志 + nginx 访问/错误日志路径，供文件读取工具查看）。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名，留空返回列表。

调用示例

{
  "project_name": ""
}

JavaProjectControl

控制Java项目进程 · 分类 Java · 风险 medium

启动/停止/重启 Java 项目进程（中风险：会中断或拉起服务，执行前说明影响）。

已运行时启动/未运行时停止按面板语义返回（不视为错误）。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（取自 JavaProjectInfo）。
`action`	`string`	否	start/stop/restart，默认 restart。

调用示例

{
  "project_name": "示例",
  "action": "restart"
}

JavaProjectModify

修改Java项目 · 分类 Java · 风险 medium

修改 Java 项目配置与域名（中风险：config 改后不会自动重启，下次重启才生效）。

action=config 改运行用户/JDK/jar/启动命令/守护状态（未传字段保留现值；改端口=改 project_cmd 的 --server.port=）。 add_domain/remove_domain 绑/删域名（至少保留一个）；bind_extranet/unbind_extranet 开关外网映射（只开外网不建反代，需再 add_proxy 才转发到应用）；add_proxy 新增反代（proxy_port 必填，代理到 127.0.0.1:<proxy_port>，proxy_dir 默认 '/'）；remove_proxy 按 proxy_id 删；proxy_list 只读列反代。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名，必填。
`action`	`string`	否	config/add_domain/remove_domain/bind_extranet/unbind_extranet/ add_proxy/remove_proxy/proxy_list，默认 config。
`run_user`	`string`	否	config 改运行用户。
`project_jdk`	`string`	否	config 改 JDK 路径。
`project_jar`	`string`	否	config 改 jar 路径（须与 project_cmd 一致）。
`project_cmd`	`string`	否	config 改启动命令。
`daemon_status`	`boolean`	否	config 开关守护（崩溃自动拉起）。
`ps`	`string`	否	config 改备注（缺省保留现值）。
`domains`	`array<string, integer, number, boolean>`	否	add_domain/remove_domain 的域名列表。
`proxy_port`	`integer`	否	add_proxy 目标端口（应用端口）。
`proxy_dir`	`string`	否	add_proxy 路由前缀，默认 '/'。
`proxy_id`	`string`	否	remove_proxy 要删的反代 id（proxy_list 获取）。

调用示例

{
  "project_name": "示例",
  "action": "config",
  "run_user": "",
  "project_jdk": "",
  "project_jar": "",
  "project_cmd": "",
  "daemon_status": null,
  "ps": "",
  "domains": null,
  "proxy_port": 0,
  "proxy_dir": "/",
  "proxy_id": ""
}

JavaProjectDelete

删除Java项目 · 分类 Java · 风险 high

删除 Java 项目（高风险、不可逆，调用前必须确认）。

停止并移除守护进程、清理 pid/启动脚本/环境变量/日志、删面板项目与域名记录、移除 Nginx 反代；jar 源文件保留。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（先用 JavaProjectInfo 核对）。

调用示例

{
  "project_name": "示例"
}

NodeJS

NodeVersion

管理Node版本 · 分类 NodeJS · 风险 medium

检测/浏览/安装 Node 版本与全局模块（中风险：install/module 有副作用，list/online 只读）。

action=list 返回 data.versions（已装版本 + 各版本 npm/yarn/pnpm/pm2 是否存在）、 data.plugin_installed（插件是否已装，缺则无法在线安装）与 data.default_version。 action=online 返回可安装版本（data.total 本地分页；每项含 version/lts/security/installed (setup==1 已装)/is_default；lts_only=true 只看稳定版；从新到旧排序），选好后用于 install。 action=install 装指定版本（如 v20.15.0），install_pm2/install_yarn 可顺带补全局模块（pm2 类型需要）。 action=module 给已装版本全局装 npm 模块（modules 逐个）。pm2 类型项目启动依赖该版本已全局装 pm2。

入参

参数名	类型	必填	说明
`action`	`string`	否	list/online/install/module，默认 list。
`version`	`string`	否	install/module 的版本号（如 v20.15.0）。
`install_pm2`	`boolean`	否	install 顺带装该版本 pm2。
`install_yarn`	`boolean`	否	install 顺带装该版本 yarn。
`lts_only`	`boolean`	否	online 只看稳定版（LTS）。
`page`	`integer`	否	online 页码，从 1 起。
`page_size`	`integer`	否	online 每页条数，默认 20，上限 100。
`modules`	`array<string, integer, number, boolean>`	否	module 要装的模块名列表（如 ['pm2']）。

调用示例

{
  "action": "list",
  "version": "",
  "install_pm2": false,
  "install_yarn": false,
  "lts_only": false,
  "page": 1,
  "page_size": 20,
  "modules": null
}

NodeProjectCreate

分析并创建Node项目 · 分类 NodeJS · 风险 medium

把本机 Node 项目目录部署成面板可管理项目（nodejs/general/pm2，中风险：创建即注册并自动启动）。

analyze_only=true 只读分析（scripts/engines/依赖/node_modules/端口启发），不创建。 nodejs_version 三类型均必填（须已安装）；绑外网（domains）必须给 port；install_deps=true 先装依赖。 pm2 类型自动确保该版本已全局装 pm2（缺则调插件装，data.pm2_auto_installed 标记）。 nodejs 类型 env 注入面板有缺陷（存了不生效），要环境变量用 general。成功 data.project 含 run/listen。参数按类型：nodejs 用 project_script；general 用 project_file+project_args；pm2 用 project_file+cluster/watch/max_memory_limit。

入参

参数名	类型	必填	说明
`project_type`	`string`	否	nodejs/general/pm2，默认 nodejs。
`project_name`	`string`	否	项目名，必填。
`project_cwd`	`string`	否	项目目录，必填。
`project_script`	`string`	否	nodejs 类型启动脚本。
`project_file`	`string`	否	general/pm2 启动文件路径。
`project_args`	`string`	否	general/pm2 启动参数。
`nodejs_version`	`string`	否	node 版本（如 v20.15.0），三类型必填。
`pkg_manager`	`string`	否	npm/yarn/pnpm，默认 npm。
`run_user`	`string`	否	运行用户，默认 www。
`port`	`integer`	否	端口，绑外网必给。
`domains`	`array<string, integer, number, boolean>`	否	'域名' 或 '域名:端口'。
`env`	`string`	否	每行 key=value；nodejs 注入缺陷用 general。
`cluster`	`integer`	否	pm2 实例数，默认 1。
`watch`	`boolean`	否	pm2 自动重载。
`max_memory_limit`	`integer`	否	内存上限 MB，0 用默认。
`install_deps`	`boolean`	否	先装依赖。
`release_firewall`	`boolean`	否	放行端口防火墙。
`is_power_on`	`boolean`	否	开机自启，默认 true。
`ps`	`string`	否	备注。
`analyze_only`	`boolean`	否	true 只分析。

调用示例

{
  "project_type": "nodejs",
  "project_name": "",
  "project_cwd": "",
  "project_script": "",
  "project_file": "",
  "project_args": "",
  "nodejs_version": "",
  "pkg_manager": "npm",
  "run_user": "www",
  "port": 0,
  "domains": null,
  "env": "",
  "cluster": 1,
  "watch": false,
  "max_memory_limit": 0,
  "install_deps": false,
  "release_firewall": false,
  "is_power_on": true,
  "ps": "",
  "analyze_only": false
}

NodeProjectInfo

查看Node项目 · 分类 NodeJS · 风险 low

查看面板管理的 Node 项目。只读。

project_name 留空返回全部项目列表（含运行态 run/listen）；给出时返回单项目详情： project_config（类型/目录/脚本/node 版本/端口/域名/绑定状态）、run/pid、listen、ssl、 log_files（应用 + pm2 + nginx 日志路径，供文件读取工具查看）。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名，留空返回列表。

调用示例

{
  "project_name": ""
}

NodeProjectControl

控制Node项目进程 · 分类 NodeJS · 风险 medium

启动/停止/重启 Node 项目进程（中风险：会中断或拉起服务，执行前说明影响）。

自动识别项目类型（nodejs/general/pm2）分发到对应子模型；已运行时启动/未运行时停止按面板语义返回。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（取自 NodeProjectInfo）。
`action`	`string`	否	start/stop/restart，默认 restart。

调用示例

{
  "project_name": "示例",
  "action": "restart"
}

NodeProjectModify

修改Node项目 · 分类 NodeJS · 风险 medium

修改 Node 项目配置与域名（中风险：config 改后自动重启生效，pm2 重建 ecosystem）。

action=config 改启动脚本/文件/参数/node 版本/包管理器/端口/环境变量/运行用户/内存/开机自启/备注（未传字段保留现值；改端口后已绑域名自动重写反代）。 action=add_domain/remove_domain 绑/删域名（至少保留一个）。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名，必填。
`action`	`string`	否	config/add_domain/remove_domain，默认 config。
`project_script`	`string`	否	config 改 nodejs 类型启动脚本。
`project_file`	`string`	否	config 改 general/pm2 类型启动文件。
`project_args`	`string`	否	config 改启动参数。
`nodejs_version`	`string`	否	config 切换 node 版本（须已安装）。
`pkg_manager`	`string`	否	config 改 npm/yarn/pnpm。
`port`	`integer`	否	config 改端口（0 不修改）。
`env`	`string`	否	config 改环境变量（每行 key=value；nodejs 注入缺陷见创建工具）。
`run_user`	`string`	否	config 改运行用户。
`max_memory_limit`	`integer`	否	config 改内存上限 MB（0 不修改）。
`is_power_on`	`boolean`	否	config 改开机自启。
`ps`	`string`	否	config 改备注。
`watch`	`boolean`	否	config 改 pm2 自动重载。
`cluster`	`integer`	否	config 改 pm2 实例数（0 不修改）。
`domains`	`array<string, integer, number, boolean>`	否	add_domain/remove_domain 的域名列表。

调用示例

{
  "project_name": "示例",
  "action": "config",
  "project_script": "",
  "project_file": "",
  "project_args": "",
  "nodejs_version": "",
  "pkg_manager": "",
  "port": 0,
  "env": "",
  "run_user": "",
  "max_memory_limit": 0,
  "is_power_on": null,
  "ps": "",
  "watch": null,
  "cluster": 0,
  "domains": null
}

NodeProjectDelete

删除Node项目 · 分类 NodeJS · 风险 high

删除 Node 项目（高风险、不可逆，调用前必须确认）。

停止进程（pm2 先 pm2 delete）、清理 pid/启动脚本/日志、删面板项目与域名记录、移除 Nginx 反代；项目目录与源码保留。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（先用 NodeProjectInfo 核对）。

调用示例

{
  "project_name": "示例"
}

Python

PythonVersion

管理Python版本 · 分类 Python · 风险 medium

查看/浏览/移除本机 Python 解释器版本（中风险：remove 有副作用，list/online 只读）。

action=list 返回 data.sdk（all/streamline/pypy，每项 version/type/installed/install_command）、 data.installed 已装版本与 data.default_python。 action=online 返回云端可安装版本（data.versions 本地分页 data.total；is_all=false 只留每小版本最新 streamline；is_pypy=true 看 PyPy；每项 install_command 可直接交 Bash 后台执行）。 action=remove 移除已装版本（multi_remove_env，被项目占用会拒绝）。 安装勿用本工具：优先预编译（下载解压即用，快），无预编译包/特殊参数回落源码编译（慢）。用 Bash 后台执行 install_command（run_in_background=true）→ BashStatus 轮询 → 完成后 PythonEnv list 确认。

入参

参数名	类型	必填	说明
`action`	`string`	否	list/online/remove，默认 list。
`version`	`string`	否	remove 的版本号（如 3.12.3）。
`refresh`	`boolean`	否	list/online 强制刷新云端版本缓存。
`is_all`	`boolean`	否	online 显示全部版本（含同小版本多个补丁版）。
`is_pypy`	`boolean`	否	online 查 PyPy 版本。
`page`	`integer`	否	online 页码，从 1 起。
`page_size`	`integer`	否	online 每页条数，默认 20，上限 100。

调用示例

{
  "action": "list",
  "version": "",
  "refresh": false,
  "is_all": false,
  "is_pypy": false,
  "page": 1,
  "page_size": 20
}

PythonEnv

管理虚拟环境与包 · 分类 Python · 风险 medium

管理面板 Python 虚拟环境与包（pip）（中风险：create/remove/set_default/package 有副作用）。

action=list 返回 data.env_list（每项 bin_path/version/env_type/source/can_create/can_remove/projects 占用项目）与 data.default_python、data.source_priority。 action=create 基于系统(system)型 Python 建虚拟环境（venv_name+python_bin），落 /www/server/pyporject_evn/<name>。 源优先级（list 返回 source/source_priority）：① panel_installed 面板安装版本（推荐）→② system 系统 Python→③ panel_pyenv 面板自带 pyenv（精简打包，不适合普通用户，会被拒绝）。已规避面板 create_venv_sync 假成功缺陷（走 create_venv + 磁盘校验，不传 call_log）。 action=remove 移除虚拟环境（被项目使用/conda/非面板路径会拒绝）；set_default 设置命令行默认 Python （path=python_bin；空串关闭）；package 在虚拟环境做 pip 管理（python_bin+package_action install/uninstall/list；install 可带 package_version/pip_source；list 返回已装包）。慢，日志尾部回传。建 Python 项目前必须先有可用虚拟环境（Create 要求 can_use_directly）。

入参

参数名	类型	必填	说明
`action`	`string`	否	list/create/remove/set_default/package，默认 list。
`venv_name`	`string`	否	create 的虚拟环境名（唯一）。
`python_bin`	`string`	否	create 源环境 / package 目标环境的 python 路径。
`ps`	`string`	否	create 的环境备注。
`path`	`string`	否	remove/set_default 的 python_bin。
`package_action`	`string`	否	package 的 install/uninstall/list，默认 install。
`package_name`	`string`	否	package install/uninstall 的包名。
`package_version`	`string`	否	package install 的版本约束（可选）。
`pip_source`	`string`	否	package install 的 pip 源 URL（可选，默认阿里云镜像）。

调用示例

{
  "action": "list",
  "venv_name": "",
  "python_bin": "",
  "ps": "",
  "path": "",
  "package_action": "install",
  "package_name": "",
  "package_version": "",
  "pip_source": ""
}

PythonProjectCreate

分析并创建Python项目 · 分类 Python · 风险 medium

把本机 Python 项目目录部署成面板可管理项目（中风险：创建即注册并进入环境准备）。

analyze_only=true 只读分析（framework/runfile/xsgi/call_app/requirement/端口启发），不创建。创建 = 面板 CreateProject 注册 → 后台异步环境准备（装托管依赖+requirements+生成启动脚本+尝试启动） → 立即返回。创建返回≠启动成功：必须 PythonProjectInfo 轮询 prep_status 到 complete，再验 run/listen/日志。前置：project_path 须已有可用虚拟环境 python_bin（can_use_directly，PythonEnv 建）；创建前先 analyze_only。 stype 仅 uwsgi/gunicorn/command（python 直跑用 command：project_cmd 支持占位符 {python_bin}/{rfile}/{path}/{parm}）。 uwsgi/gunicorn 需 rfile+call_app+port；command 需 project_cmd（port 可留 0）。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名，必填。
`project_path`	`string`	否	项目目录（须已存在、不含空格），必填。
`python_bin`	`string`	否	虚拟环境 python 路径，必填。
`stype`	`string`	否	uwsgi/gunicorn/command，默认 uwsgi。
`port`	`integer`	否	端口，uwsgi/gunicorn 必填；command 可留 0。
`xsgi`	`string`	否	wsgi/asgi，默认 wsgi。
`rfile`	`string`	否	uwsgi/gunicorn 启动文件绝对路径。
`call_app`	`string`	否	可调用对象名，默认 app。
`framework`	`string`	否	框架，默认 python。
`project_cmd`	`string`	否	command 启动命令，占位符由工具替换，如 `"{python_bin} -u {rfile}"`。
`user`	`string`	否	运行用户，默认 root。
`env_list`	`array<object>`	否	环境变量列表，每项 `{"k","v"}`（如 `[{"k":"PORT","v":"9000"}]`；`"K=V"` 会被 schema 拒）。
`env_file`	`string`	否	环境变量文件路径（可选）。
`requirement_path`	`string`	否	requirements 文件路径（可选，准备阶段自动装）。
`initialize`	`string`	否	环境准备阶段的初始化命令（可选）。
`auto_run`	`boolean`	否	开机自启，默认 false。
`processes`	`integer`	否	进程数，默认 4。
`threads`	`integer`	否	线程数，默认 2。
`release_firewall`	`boolean`	否	放行端口防火墙，默认 false。
`analyze_only`	`boolean`	否	true 只分析。

调用示例

{
  "project_name": "",
  "project_path": "",
  "python_bin": "",
  "stype": "uwsgi",
  "port": 0,
  "xsgi": "wsgi",
  "rfile": "",
  "call_app": "app",
  "framework": "python",
  "project_cmd": "",
  "user": "root",
  "env_list": null,
  "env_file": "",
  "requirement_path": "",
  "initialize": "",
  "auto_run": false,
  "processes": 4,
  "threads": 2,
  "release_firewall": false,
  "analyze_only": false
}

PythonProjectInfo

查看Python项目 · 分类 Python · 风险 low

查看面板管理的 Python 项目。只读。

project_name 留空返回全部项目列表（含运行态 run/listen）；给出时返回单项目详情： project_config（stype/目录/python_bin/端口/域名/env）、prep_status（环境准备 running/complete/failure）、 run/pids/listen/cpu/mem、python_bin/python_version、services（关联服务 pid/ports）、log_files （应用日志 + 环境准备日志 + 关联服务日志目录）；include_packages=true 附虚拟环境已装包。排错：prep_status=failure 读环境准备日志；run=false 读 stype 对应应用日志。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名，留空返回列表。
`include_packages`	`boolean`	否	详情是否附带已装包列表。

调用示例

{
  "project_name": "",
  "include_packages": false
}

PythonProjectControl

控制Python项目进程 · 分类 Python · 风险 medium

启动/停止/重启 Python 项目（中风险：会中断或拉起服务，执行前说明影响）。

action=start/stop/restart 走面板 StartProject/StopProject/RestartProject（主服务+关联进程一起启停），返回"指令已执行"，需再用 PythonProjectInfo 核验实际状态；action=start_main/stop_main 只启/停主服务（同步返回实际结果）。注意：环境准备中（prep_status=running）面板会拒绝启停。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（取自 PythonProjectInfo）。
`action`	`string`	否	start/stop/restart/start_main/stop_main，默认 restart。

调用示例

{
  "project_name": "示例",
  "action": "restart"
}

PythonProjectService

管理项目关联进程 · 分类 Python · 风险 medium

管理 Python 项目关联进程（如 celery worker）。中风险：启停会中断进程。

关联进程存于 project_config.services（每条 {sid,name,command,level,log_type}），主服务是隐式 sid='main' （用 PythonProjectControl 启停）。命令以 celery 开头自动按 CeleryService 匹配 PID。 action=list 返回全部服务（含主服务）pid/ports；add 注册（name 唯一+command 唯一，name 不能含空白/$/^/反引号）； start/stop/restart 按 sid 启停；remove 停止并删除（面板 remove_service 本身不停进程，本工具先 stop 再删，避免孤儿进程）；log 查看服务日志（data.log）。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名，必填。
`action`	`string`	否	list/add/start/stop/restart/remove/log，默认 list。
`sid`	`string`	否	start/stop/restart/remove/log 的服务 id（list 返回）。
`name`	`string`	否	add 的服务名。
`command`	`string`	否	add 的启动命令（如 "celery -A demo worker"）。
`level`	`integer`	否	add 的启动顺序优先级，默认 11（主服务为 10）。
`log_type`	`string`	否	add 的日志模式 append/error/off，默认 append。

调用示例

{
  "project_name": "示例",
  "action": "list",
  "sid": "",
  "name": "",
  "command": "",
  "level": 11,
  "log_type": "append"
}

PythonProjectModify

修改Python项目 · 分类 Python · 风险 medium

修改 Python 项目配置、域名与反代（中风险：config 改后停止并重启项目）。

action=config 改 stype/xsgi/rfile/call_app/project_cmd/parm、端口/用户/进程线程/开机自启/日志/环境变量（未传字段保留现值，改后自动重启生效）。 action=add_domain 绑域名（面板对已存在域返回"已存在"=实际已绑定、非失败，本工具按逐域如实上报）。 action=remove_domain 删域名（至少保留一个）。注意：面板移除域名会连带停止项目服务（主+协同，与是否剩最后一个无关，已实证），本工具不自动恢复，移除后须 PythonProjectInfo 复核并在需要时手动重启。 action=bind_extranet/unbind_extranet 开关外网映射（反代 add_proxy 需先开外网映射）。 action=add_proxy 更新/新增 path→port 反代（proxy_path+proxy_port，写 proxy_info 并重写 nginx）。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名，必填。
`action`	`string`	否	config/add_domain/remove_domain/bind_extranet/unbind_extranet/add_proxy，默认 config。
`stype`	`string`	否	config 改 uwsgi/gunicorn/python/command。
`xsgi`	`string`	否	config 改 wsgi/asgi。
`rfile`	`string`	否	config 改启动文件（须在项目目录下）。
`call_app`	`string`	否	config 改可调用对象名。
`project_cmd`	`string`	否	config 改 command 启动命令（占位符由工具替换，如 `"{python_bin} -u {rfile}"`）。
`parm`	`string`	否	config 改 python 直跑附加参数。
`port`	`integer`	否	config 改端口（0 不修改）。
`user`	`string`	否	config 改运行用户。
`processes`	`integer`	否	config 改进程数（0 不修改）。
`threads`	`integer`	否	config 改线程数（0 不修改）。
`auto_run`	`boolean`	否	config 改开机自启。
`logpath`	`string`	否	config 改日志目录。
`loglevel`	`string`	否	config 改日志等级（gunicorn）。
`is_http`	`boolean`	否	config 改 uwsgi 是否走 http。
`env_list`	`array<object>`	否	config 替换环境变量列表（每项 `{"k","v"}`；传 `[]` 清空；`"K=V"` 会被 schema 拒）。
`env_file`	`string`	否	config 改环境变量文件。
`domains`	`array<string, integer, number, boolean>`	否	add_domain/remove_domain 的域名列表。
`proxy_path`	`string`	否	add_proxy 路由前缀，默认 /。
`proxy_port`	`integer`	否	add_proxy 后端端口，必填。

调用示例

{
  "project_name": "示例",
  "action": "config",
  "stype": "",
  "xsgi": "",
  "rfile": "",
  "call_app": "",
  "project_cmd": "",
  "parm": "",
  "port": 0,
  "user": "",
  "processes": 0,
  "threads": 0,
  "auto_run": null,
  "logpath": "",
  "loglevel": "",
  "is_http": null,
  "env_list": null,
  "env_file": "",
  "domains": null,
  "proxy_path": "/",
  "proxy_port": 0
}

PythonProjectDelete

删除Python项目 · 分类 Python · 风险 high

删除 Python 项目（高风险、不可逆，调用前必须确认）。

停止进程（含关联进程）、清理 pid/启动脚本/日志/nginx conf/反代、删面板项目与域名记录；项目目录与源码保留。 删除不删除虚拟环境：venv 与项目非强绑定（可复用/共享），面板接口逻辑即如此；如需移除用 PythonEnv(action='remove', path=<python_bin>)。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（先用 PythonProjectInfo 核对）。

调用示例

{
  "project_name": "示例"
}

Go

GoVersion

管理Go环境 · 分类 Go · 风险 medium

管理本机 Go SDK（中风险：install/use/uninstall/goproxy 有副作用，list 只读）。

action=list 返回 data.installed（已装版本）、data.available（可安装版本，分页：data.total/page/ page_size；每项含 install_command）、data.used（当前使用版本）与 data.goproxy（现状 + 常用源列表）。 stable_only=true 只看每个小版本最新的稳定版（忽略历史/补丁版，列表更短）；page/page_size 翻页（page_size 上限 100）。可用版本较多，分页取数，避免结果超限。 action=install 不同步安装：校验版本在可装列表后返回 install_command + install_hint， 需用 Bash 后台执行防超时（Bash(command=install_command, run_in_background=true) → BashStatus 轮询；一次只装一个版本）。 action=use 切换当前使用版本（软链 /usr/local/btgo）；action=uninstall 卸载指定版本； action=goproxy 设置 GOPROXY（如 https://goproxy.cn,direct）。

入参

参数名	类型	必填	说明
`action`	`string`	否	list/install/use/uninstall/goproxy，默认 list。
`version`	`string`	否	install/use/uninstall 的版本号（如 go1.22.4，可省 'go' 前缀）。
`goproxy`	`string`	否	goproxy 时要设置的代理地址（list 的 data.goproxy.list 有常用源）。
`stable_only`	`boolean`	否	list 只看每小版本最新稳定版（默认 false 看全部）。
`page`	`integer`	否	list 页码，从 1 起。
`page_size`	`integer`	否	list 每页条数，默认 20，上限 100。

调用示例

{
  "action": "list",
  "version": "",
  "goproxy": "",
  "stable_only": false,
  "page": 1,
  "page_size": 20
}

GoProjectCreate

创建Go项目 · 分类 Go · 风险 medium

把编译好的 Go 二进制部署成面板可管理项目（中风险：创建即注册并自动启动）。

Go 是编译产物，无源码分析步骤：给二进制路径 + 端口 + 启动命令（缺省=二进制本身）直接注册。创建即同步启动（nohup 脚本 + pid 文件，无 systemd/pm2）；成功后用 GoProjectInfo 核验 run/listen。传 domains 自动开启外网映射（bind_extranet=1）；项目目录与二进制文件不会被删除。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名（字母/数字/下划线，面板内唯一），必填。
`project_exe`	`string`	否	Go 可执行文件绝对路径，必填。
`port`	`integer`	否	应用监听端口（10-65535），必填。
`project_cmd`	`string`	否	启动命令，缺省=project_exe。
`run_user`	`string`	否	运行用户，默认 www。
`domains`	`array<string, integer, number, boolean>`	否	绑定域名列表，'域名' 或 '域名:端口'（给则开启外网映射）。
`env_list`	`array<object>`	否	环境变量列表，每项 `{"k","v"}`（如 `[{"k":"PORT","v":"9000"}]`；`"K=V"` 会被 schema 拒）。
`env_file`	`string`	否	环境变量文件绝对路径（可选）。
`is_power_on`	`boolean`	否	开机自启，默认 true。
`ps`	`string`	否	备注。
`release_firewall`	`boolean`	否	是否放行端口防火墙。

调用示例

{
  "project_name": "",
  "project_exe": "",
  "port": 0,
  "project_cmd": "",
  "run_user": "www",
  "domains": null,
  "env_list": null,
  "env_file": "",
  "is_power_on": true,
  "ps": "",
  "release_firewall": false
}

GoProjectInfo

查看Go项目 · 分类 Go · 风险 low

查看面板管理的 Go 项目。只读。

project_name 留空返回全部项目列表（含运行态 run/listen）；给出时返回单项目详情： project_config（exe/启动命令/端口/运行用户/域名/环境变量）、run/listen/ssl、log_files （应用日志 + nginx 访问/错误日志路径，供文件读取工具查看）。

入参

参数名	类型	必填	说明
`project_name`	`string`	否	项目名，留空返回列表。

调用示例

{
  "project_name": ""
}

GoProjectControl

控制Go项目进程 · 分类 Go · 风险 medium

启动/停止/重启 Go 项目进程（中风险：会中断或拉起服务，执行前说明影响）。

Go 进程为 nohup 脚本 + pid 文件管理（无守护）；未启动时 stop/restart 面板返回"项目未启动"，如实上报。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（取自 GoProjectInfo）。
`action`	`string`	否	start/stop/restart，默认 restart。

调用示例

{
  "project_name": "示例",
  "action": "restart"
}

GoProjectModify

修改Go项目 · 分类 Go · 风险 medium

修改 Go 项目配置与域名（中风险：config 改后自动重启生效）。

action=config 改可执行文件/启动命令/端口/运行用户/开机自启/环境变量/备注（未传字段保留现值）。 面板 modify_project 无条件读 project_exe 与 project_ps——本工具始终带上现值，不会漏传。 action=add_domain/remove_domain 绑/删域名（面板保证至少保留一个域名）。 action=bind_extranet/unbind_extranet 开关外网映射（需先有域名）。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名，必填。
`action`	`string`	否	config/add_domain/remove_domain/bind_extranet/unbind_extranet，默认 config。
`project_exe`	`string`	否	config 改可执行文件绝对路径。
`project_cmd`	`string`	否	config 改启动命令。
`port`	`integer`	否	config 改端口（0 不修改）。
`run_user`	`string`	否	config 改运行用户。
`is_power_on`	`boolean`	否	config 改开机自启。
`env_list`	`array<object>`	否	config 替换环境变量列表（每项 `{"k","v"}`；面板仅在非空时生效）。
`env_file`	`string`	否	config 改环境变量文件。
`ps`	`string`	否	config 改备注。
`domains`	`array<string, integer, number, boolean>`	否	add_domain/remove_domain 的域名列表。

调用示例

{
  "project_name": "示例",
  "action": "config",
  "project_exe": "",
  "project_cmd": "",
  "port": 0,
  "run_user": "",
  "is_power_on": null,
  "env_list": null,
  "env_file": "",
  "ps": "",
  "domains": null
}

GoProjectDelete

删除Go项目 · 分类 Go · 风险 high

删除 Go 项目（高风险、不可逆，调用前必须确认）。

停止进程、清理 pid/启动脚本/日志、删面板项目与域名记录、移除 Nginx 反代；项目目录与二进制文件保留。

入参

参数名	类型	必填	说明
`project_name`	`string`	是	项目名（先用 GoProjectInfo 核对）。

调用示例

{
  "project_name": "示例"
}

反向代理

ProxyProjectCreate

创建反代项目 · 分类 反向代理 · 风险 medium

创建反向代理项目（中风险：写入 nginx 配置、放行防火墙端口并重载服务）。

一个反代项目 = 一个面板站点（project_type=proxy），按主域名生成站点名，可带多域名与端口（域名形如 'example.com' 或 'example.com:8080'，非 80 端口会成为监听端口）。proxy_pass 为目标上游（http/https 或 unix socket），proxy_path 为前缀（默认 /）。创建即生效，成功后用 ProxyProjectInfo 确认站点名。

安全提示：若 proxy_pass 指向本机 bt_agent_mcp 服务自身端口（127.0.0.1:<resolve_port()>，默认 8765），返回 data.warning 会给出风险说明（可能把 MCP 暴露给该反代域名并绕过来源 IP 白名单）。确需经反代暴露 MCP 时，请在该反代 conf 设置 proxy_set_header X-Real-IP $remote_addr; 并把真实客户端 IP 加入白名单。

入参

参数名	类型	必填	说明
`domains`	`array<string, integer, number, boolean>`	否	域名列表（可带 :port），必填。
`proxy_pass`	`string`	否	代理目标，如 `http://127.0.0.1:8080`、`https://api.example.com` 或 `/tmp/app.sock`，必填。
`proxy_path`	`string`	否	代理前缀，默认 /。
`proxy_host`	`string`	否	转发 Host 头，默认 $http_host。
`proxy_type`	`string`	否	http 或 unix，默认 http。
`remark`	`string`	否	备注。

调用示例

{
  "domains": null,
  "proxy_pass": "",
  "proxy_path": "/",
  "proxy_host": "$http_host",
  "proxy_type": "http",
  "remark": ""
}

ProxyProjectInfo

查看反代项目 · 分类 反向代理 · 风险 low

查看反向代理项目。只读。

site_name 留空返回全部项目列表（data.sites 每项含 name/path/status/ps/ssl 天数/proxy_pass/healthy，支持 search 模糊搜索 + 分页）；给出时返回单项目详情：站点字段 + 配置摘要（域名列表/监听端口/HTTPS 端口/SSL 与强制 HTTPS 状态/IP 黑白名单/URL 规则 proxy_info 精简：proxy_path/proxy_pass/proxy_host/ websocket/超时/备注）+ nginx 配置与日志文件路径（config_file/proxy_config_file/log_files）—— 配置文件内容用文件读取工具按路径自行查看。若某条 URL 规则指向本机 bt_agent_mcp 自身端口，返回 data.warning 会给出风险提示（来源 IP 白名单可能被绕过，仅剩 API Key 鉴权）。

入参

参数名	类型	必填	说明
`site_name`	`string`	否	反代项目站点名，留空返回列表。
`search`	`string`	否	列表模式按站点名模糊搜索。
`page`	`integer`	否	列表模式页码，从 1 开始。
`page_size`	`integer`	否	列表模式每页数量，默认 20、最大 100。

调用示例

{
  "site_name": "",
  "search": "",
  "page": 1,
  "page_size": 20
}

ProxyProjectModify

修改反代项目 · 分类 反向代理 · 风险 medium

修改反代项目（中风险：有副作用）。

action 说明：

remark: 改项目备注（remark）。
start/stop: 启用/停止反代站点（停止后返回停机页）。
add_domain: 增加绑定域名（domains，可带 :port；面板会同步 nginx 配置与反代 JSON）。
remove_domain: 删除绑定域名（domains，至少保留一个）。
force_https: 开启/关闭强制 HTTPS 跳转（force_https true=开、false=关）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	反代项目站点名，必填。
`action`	`string`	否	remark/start/stop/add_domain/remove_domain/force_https，默认 remark。
`remark`	`string`	否	remark 时的备注。
`domains`	`array<string, integer, number, boolean>`	否	add_domain/remove_domain 的域名列表。
`force_https`	`boolean`	否	force_https 时是否开启强制 HTTPS。

调用示例

{
  "site_name": "示例",
  "action": "remark",
  "remark": "",
  "domains": null,
  "force_https": null
}

ProxyWriteConfig

修改反代配置 · 分类 反向代理 · 风险 medium

直接编辑反代项目的 nginx 配置文件（中风险：改错可能导致站点异常，保存后请用 Bash nginx -t 验证）。

编辑起点：先用 ProxyProjectInfo 拿 config_file 路径，用文件读取工具 Read 当前配置，修改后把完整 conf 全文回传本工具。面板写 conf 后会解析并自动同步反向代理 JSON（proxy_info/域名/端口等）。若配置有误导致站点异常，可用面板历史版本回滚或 Read 基线恢复后重新保存。

安全提示：若 conf 里某条 proxy_pass 指向本机 bt_agent_mcp 服务自身端口（127.0.0.1:<resolve_port()>，默认 8765），返回 data.warning 会给出风险说明（可能把 MCP 暴露给该反代域名并绕过来源 IP 白名单）；确需如此请在对应 location 设置 proxy_set_header X-Real-IP $remote_addr; 并把真实客户端 IP 加入白名单。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	反代项目站点名，必填。
`conf_data`	`string`	否	完整 nginx 配置文件内容（覆盖保存），必填。

调用示例

{
  "site_name": "示例",
  "conf_data": ""
}

ProxyProjectDelete

删除反代项目 · 分类 反向代理 · 风险 high

删除反向代理项目（高风险、不可逆，调用前必须确认）。

删除 nginx 配置/日志/反代 JSON 目录与面板站点/域名记录；remove_path=true 时连同 /www/wwwroot/<name> 站点目录一并删除。反代 JSON 与 nginx 配置删除后不可恢复。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	反代项目站点名（先用 ProxyProjectInfo 核对）。
`remove_path`	`boolean`	否	是否同时删除站点根目录，默认 false。

调用示例

{
  "site_name": "示例",
  "remove_path": false
}

HTML

HtmlProjectInfo

查看HTML项目 · 分类 HTML · 风险 low

查看面板管理的 Html(静态)项目。只读。

site_name 留空返回全部项目列表（data.sites 每项含 name/path/status/ps/type_id/ssl 剩余天数，支持 search 按站点名/备注模糊搜索 + 分页）；给出时返回单项目详情：站点字段 + 域名列表 + SSL 状态 + 运行目录 + nginx/apache/rewrite 配置文件与日志文件路径（config_file/apache_config_file/rewrite_file/ log_files）——配置文件内容用文件读取工具按路径自行查看。

入参

参数名	类型	必填	说明
`site_name`	`string`	否	项目站点名（主域名），留空返回列表。
`search`	`string`	否	列表模式按站点名/备注模糊搜索。
`page`	`integer`	否	列表模式页码，从 1 开始。
`page_size`	`integer`	否	列表模式每页数量，默认 20、最大 100。

调用示例

{
  "site_name": "",
  "search": "",
  "page": 1,
  "page_size": 20
}

HtmlProjectCreate

创建HTML项目 · 分类 HTML · 风险 medium

创建 Html(静态)项目（中风险：写入 nginx/apache 配置、非 80 端口放行防火墙并重载服务）。

一个 Html 项目 = 一个面板站点（project_type=html），按主域名生成站点名，可带多域名与端口（域名形如 'example.com' 或 'example.com:8080'，非 80 端口会成为监听端口）。path 为网站根目录绝对路径（可指向已有前端目录，目录不存在会自动创建）。创建即生效，成功后用 HtmlProjectInfo 确认站点名。

入参

参数名	类型	必填	说明
`domains`	`array<string, integer, number, boolean>`	否	域名列表（可带 :port），首项为主域名，必填。
`path`	`string`	否	网站根目录绝对路径（如 /www/wwwroot/demo.example.com），必填。
`ps`	`string`	否	项目备注。
`type_id`	`integer`	否	项目分类 ID，默认 0。

调用示例

{
  "domains": null,
  "path": "",
  "ps": "",
  "type_id": 0
}

HtmlProjectModify

修改HTML项目 · 分类 HTML · 风险 medium

修改 Html(静态)项目（中风险：有副作用）。

action 说明：

remark: 改项目备注（remark）。
start/stop: 启用/停止站点（静态站无重启概念）。
add_domain: 增加绑定域名（domains 列表，可带 :port；面板同步 nginx/apache 配置与 domain 表）。
remove_domain: 删除绑定域名（domain，可带 :port；至少保留一个）。
change_path: 修改网站根目录（path 绝对路径，目标目录必须已存在）。
set_run_path: 设置运行目录（run_path 为根目录下的相对子目录，如 /dist，'/' 或空=根目录）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	项目站点名，必填。
`action`	`string`	否	remark/start/stop/add_domain/remove_domain/change_path/set_run_path，默认 remark。
`remark`	`string`	否	remark 时的备注。
`domains`	`array<string, integer, number, boolean>`	否	add_domain 的域名列表。
`domain`	`string`	否	remove_domain 的域名（可带 :port）。
`path`	`string`	否	change_path 的目标网站根目录（绝对路径，须已存在）。
`run_path`	`string`	否	set_run_path 的相对子目录（如 /dist）。

调用示例

{
  "site_name": "示例",
  "action": "remark",
  "remark": "",
  "domains": null,
  "domain": "",
  "path": "",
  "run_path": ""
}

HtmlProjectDelete

删除HTML项目 · 分类 HTML · 风险 high

删除 Html(静态)项目（高风险、不可逆，调用前必须确认）。

删除 nginx/apache/rewrite 配置、放行记录与面板站点/域名记录；不删除 /www/wwwroot 站点目录 （如需删除目录请用文件系统工具另行处理）。

入参

参数名	类型	必填	说明
`site_name`	`string`	是	项目站点名（先用 HtmlProjectInfo 核对）。

调用示例

{
  "site_name": "示例"
}

SSH

SSHInfo

查看SSH · 分类 SSH · 风险 low

查看 SSH 服务状态与登录配置。只读。

data 含 sshd_status 与 config（root 登录方式、密码/密钥登录开关、密钥类型）。

入参

无入参，调用时传空对象 {}。

调用示例

{}

SSHConfig

配置SSH · 分类 SSH · 风险 high

管理 SSH 密钥认证或重启 sshd。中风险：生成密钥时保留密码认证（双通道），关闭密钥时自动恢复密码。

action 说明：

key: value 填密钥类型（ed25519/ecdsa/rsa），生成密钥对并启用密钥认证，保留密码认证；
key_off: value 忽略，关闭密钥认证并恢复密码认证；
restart: value 忽略，重启 sshd。

入参

参数名	类型	必填	说明
`action`	`string`	是	key/key_off/restart 之一。
`value`	`string`	否	密钥类型（仅 key 时需要）。

调用示例

{
  "action": "示例",
  "value": ""
}

SSHIntrusion

查看异常登录 · 分类 SSH · 风险 low

查看 SSH 异常登录统计（爆破情况）。只读。

data.intrusion 含累计与今日的登录失败/成功次数，用于判断是否遭受爆破攻击。

入参

无入参，调用时传空对象 {}。

调用示例

{}

安全

SecurityCheck

安全检查 · 分类 安全 · 风险 low

检查服务器安全状态：安全评分、10 项安全检查项（含状态与修复建议）、SSH 危险命令历史。只读。

安全检查项包括 SSH 端口、密码策略、登录告警、面板 SSL 等，每项含 status（是否通过）、suggest（修复建议）。修复操作须用 Bash 执行（高风险操作须向用户确认）。

入参

无入参，调用时传空对象 {}。

调用示例

{}

计划任务

GetCrontab

获取计划任务列表 · 分类 计划任务 · 风险 low

获取面板计划任务列表。只读。

入参

参数名	类型	必填	说明
`search`	`string`	否	按任务名/脚本内容模糊搜索。
`category`	`string`	否	过滤：system(系统)/enabled(启用)/disabled(停用)/分类 id，空=全部。
`page`	`integer`	否	页码，默认 1。
`page_size`	`integer`	否	每页条数，默认 0=全部。

调用示例

{
  "search": "",
  "category": "",
  "page": 1,
  "page_size": 0
}

ManageCrontab

计划任务管理 · 分类 计划任务 · 风险 high

管理计划任务：add 创建 / del 删除。高风险。

入参

参数名	类型	必填	说明
`action`	`string`	是	add创建 / del删除
`id`	`integer`	否	任务id，del必填，取自GetCrontab
`name`	`string`	否	任务名，add必填
`schedule.type`	`string`	否	周期类型：minute-n每N分/hour每小时/hour-n每N时/day每天/day-n每N天/week每周/month每月/second-n每N秒；各类型需填字段：minute-n→interval, hour→minute, hour-n→interval+minute, day→hour+minute, day-n→interval+hour+minute, week→weekday+hour+minute, month→interval+hour+minute, second-n→interval
`task.type`	`string`	否	任务类型：shell执行命令/site备份网站/path备份目录/database备份数据库/logs日志切割/log_cleanup日志清理；target填对象：site→站点名, path→目录路径, database→库名, logs/log_cleanup→站点或目录
`task.command`	`string`	否	命令/脚本，shell必填
`task.target`	`string`	否	备份/日志对象（站点/目录/库名），备份日志类必填

调用示例

{
  "action": "add",
  "id": 0,
  "name": "示例",
  "schedule": {
    "type": "minute-n"
  },
  "task": {
    "type": "shell"
  }
}

通知

GetChannel

获取通知通道列表 · 分类 通知 · 风险 low

获取面板已配置的通知通道列表。只读。返回通道 id/type/used/title。

入参

参数名	类型	必填	说明
`refresh`	`boolean`	否	强制刷新配置，默认 false。

调用示例

{
  "refresh": false
}

ManageChannel

通知通道管理 · 分类 通知 · 风险 high

管理通知通道：add 添加 / del 删除 / status 启停 / test 发测试消息。高风险。

入参

参数名	类型	必填	说明
`action`	`string`	是	add/del/status/test
`id`	`string`	否	通道id，del/status/test必填，取自GetChannel
`type`	`string`	否	通道类型：weixin(企业微信,webhook URL)/mail/feishu/dingding 可添加；wx_account(个人微信/公众号) 需面板扫码绑定；sms(短信)/webhook(自定义) 不支持
`title`	`string`	否	备注名，add必填，≤15字
`data.url`	`string`	否	机器人webhook地址（weixin/feishu/dingding）
`data.send`	`object`	否	SMTP 配置 `{qq_mail,qq_stmp_pwd,hosts,port}`，mail 必填。
`data.receive`	`array<string>`	否	收件人邮箱，mail必填（至少1个）

调用示例

{
  "action": "add",
  "id": "示例",
  "type": "weixin",
  "title": "示例",
  "data": {
    "url": "示例"
  }
}

SendMessage

发送消息 · 分类 通知 · 风险 medium

通过指定通知通道发送一条自由消息。通道不存在/停用时返回 available.channels。

入参

参数名	类型	必填	说明
`channel_id`	`string`	是	目标通道 id，取自 GetChannel。
`content`	`string`	是	消息内容。
`title`	`string`	否	消息标题，默认宝塔面板消息推送。

调用示例

{
  "channel_id": "示例",
  "content": "示例",
  "title": ""
}

通用约定​

基础​

Read​

Edit​

Write​

Glob​

Grep​

LS​

Bash​

BashStatus​

BashStop​

网站​

SiteList​

SiteGetConfig​

SiteLogs​

SiteTraffic​

SiteCreate​

SiteDelete​

OneClickDeploy​

TrafficAnalysis​

SiteCertList​

SiteSSLDeploy​

SiteSSLApply​

DomainManage​

SiteConfig​

SiteControl​

SiteBackup​

网络​

WebFetch​

ServerIP​

Upload​

数据库​

DatabaseList​

DatabaseCreate​

DatabaseDelete​

DatabaseBackup​

MysqlQuery​

MysqlExecute​

服务​

ServiceStatus​

ServiceControl​

Docker​

ContainerList​

ContainerLogs​

ContainerInspect​

ComposeList​

ImageList​

VolumeList​

NetworkList​

ContainerControl​

ContainerDelete​

ImagePull​

系统​

SystemInfo​

软件​

SoftwareList​

SoftwareInstall​

SoftwareUninstall​

防火墙​

FirewallStatus​

FirewallPortList​

FirewallIpList​

FirewallPortSet​

FirewallIpSet​

Java​

JavaJdk​

JavaProjectCreate​

JavaProjectInfo​

JavaProjectControl​

JavaProjectModify​

JavaProjectDelete​

NodeJS​

NodeVersion​

NodeProjectCreate​

NodeProjectInfo​

NodeProjectControl​

NodeProjectModify​

NodeProjectDelete​

Python​

PythonVersion​

通用约定

基础

Read

Edit

Write

Glob

Grep

LS

Bash

BashStatus

BashStop

网站

SiteList

SiteGetConfig

SiteLogs

SiteTraffic

SiteCreate

SiteDelete

OneClickDeploy

TrafficAnalysis

SiteCertList

SiteSSLDeploy

SiteSSLApply

DomainManage

SiteConfig

SiteControl

SiteBackup

网络

WebFetch

ServerIP

Upload

数据库

DatabaseList

DatabaseCreate

DatabaseDelete

DatabaseBackup

MysqlQuery

MysqlExecute

服务

ServiceStatus

ServiceControl

Docker

ContainerList

ContainerLogs

ContainerInspect

ComposeList

ImageList

VolumeList

NetworkList

ContainerControl

ContainerDelete

ImagePull

系统

SystemInfo

软件

SoftwareList

SoftwareInstall

SoftwareUninstall

防火墙

FirewallStatus

FirewallPortList

FirewallIpList

FirewallPortSet

FirewallIpSet

Java

JavaJdk

JavaProjectCreate

JavaProjectInfo

JavaProjectControl

JavaProjectModify

JavaProjectDelete

NodeJS

NodeVersion

NodeProjectCreate

NodeProjectInfo

NodeProjectControl

NodeProjectModify

NodeProjectDelete

Python

PythonVersion