---
title: "宝塔 MCP 工具说明"
description: "宝塔 MCP 提供的 98 个工具参考，包含功能说明、风险等级、入参定义和调用示例。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bt.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 宝塔 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。 |

**调用示例**

```json
{
  "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 只替换第一处。 |

**调用示例**

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

### Write

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

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

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

**入参**

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

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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 表示用默认上限。 |

**调用示例**

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

### BashStop

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

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

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

**入参**

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

**调用示例**

```json
{
  "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。 |

**调用示例**

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

### SiteGetConfig

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

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

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

**入参**

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

**调用示例**

```json
{
  "site_name": "示例"
}
```

### SiteLogs

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

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

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

**入参**

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

**调用示例**

```json
{
  "site_name": "示例"
}
```

### SiteTraffic

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

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

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

**入参**

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

**调用示例**

```json
{
  "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"），留空自动绑定。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

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

### TrafficAnalysis

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

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

**入参**

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

**调用示例**

```json
{}
```

### 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。 |

**调用示例**

```json
{
  "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` | 否 | 私钥文件绝对路径。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

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

### DomainManage

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

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

**入参**

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

**调用示例**

```json
{
  "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 时忽略。 |

**调用示例**

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

### SiteControl

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

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

**入参**

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

**调用示例**

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

### SiteBackup

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

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

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

**入参**

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

**调用示例**

```json
{
  "site_name": "示例"
}
```

## 网络

### WebFetch

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

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

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

**入参**

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

**调用示例**

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

### ServerIP

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

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

**入参**

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

**调用示例**

```json
{}
```

### 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` | 否 | 恢复上传时传首次调用返回的值。 |

**调用示例**

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

## 数据库

### DatabaseList

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

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

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

**入参**

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

**调用示例**

```json
{
  "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` | 否 | 备注。 |

**调用示例**

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

### DatabaseDelete

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

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

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

**入参**

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

**调用示例**

```json
{
  "name": "示例"
}
```

### DatabaseBackup

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

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

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

**入参**

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

**调用示例**

```json
{
  "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 标记。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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"]），留空返回全部。支持别名，自动去重。 |

**调用示例**

```json
{
  "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 之一。 |

**调用示例**

```json
{
  "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。

**入参**

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

**调用示例**

```json
{}
```

### ContainerLogs

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

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

**入参**

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

**调用示例**

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

### ContainerInspect

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

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

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

**入参**

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

**调用示例**

```json
{
  "container": "示例"
}
```

### ComposeList

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

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

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

**入参**

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

**调用示例**

```json
{}
```

### ImageList

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

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

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

**入参**

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

**调用示例**

```json
{}
```

### VolumeList

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

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

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

**入参**

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

**调用示例**

```json
{}
```

### NetworkList

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

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

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

**入参**

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

**调用示例**

```json
{}
```

### ContainerControl

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

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

**入参**

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

**调用示例**

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

### ContainerDelete

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

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

**入参**

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

**调用示例**

```json
{
  "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 传入，不进审计。 |

**调用示例**

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

## 系统

### SystemInfo

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

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

**入参**

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

**调用示例**

```json
{}
```

## 软件

### SoftwareList

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

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

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

**入参**

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

**调用示例**

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

### SoftwareInstall

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

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

**入参**

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

**调用示例**

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

### SoftwareUninstall

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

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

**入参**

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

**调用示例**

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

## 防火墙

### FirewallStatus

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

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

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

**入参**

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

**调用示例**

```json
{}
```

### FirewallPortList

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

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

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

**入参**

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

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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` | 否 | 备注。 |

**调用示例**

```json
{
  "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` | 否 | 备注。 |

**调用示例**

```json
{
  "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）。 |

**调用示例**

```json
{
  "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` | 否 | 反代路由前缀，默认 '/'；置空只绑域名。 |

**调用示例**

```json
{
  "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` | 否 | 项目名，留空返回列表。 |

**调用示例**

```json
{
  "project_name": ""
}
```

### JavaProjectControl

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

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

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

**入参**

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

**调用示例**

```json
{
  "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 获取）。 |

**调用示例**

```json
{
  "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 核对）。 |

**调用示例**

```json
{
  "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']）。 |

**调用示例**

```json
{
  "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 只分析。 |

**调用示例**

```json
{
  "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` | 否 | 项目名，留空返回列表。 |

**调用示例**

```json
{
  "project_name": ""
}
```

### NodeProjectControl

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

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

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

**入参**

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

**调用示例**

```json
{
  "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 的域名列表。 |

**调用示例**

```json
{
  "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 核对）。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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（可选，默认阿里云镜像）。 |

**调用示例**

```json
{
  "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 只分析。 |

**调用示例**

```json
{
  "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` | 否 | 详情是否附带已装包列表。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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 后端端口，必填。 |

**调用示例**

```json
{
  "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 核对）。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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` | 否 | 是否放行端口防火墙。 |

**调用示例**

```json
{
  "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` | 否 | 项目名，留空返回列表。 |

**调用示例**

```json
{
  "project_name": ""
}
```

### GoProjectControl

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

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

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

**入参**

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

**调用示例**

```json
{
  "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 的域名列表。 |

**调用示例**

```json
{
  "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 核对）。 |

**调用示例**

```json
{
  "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` | 否 | 备注。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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 配置文件内容（覆盖保存），必填。 |

**调用示例**

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

### ProxyProjectDelete

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

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

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

**入参**

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

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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。 |

**调用示例**

```json
{
  "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）。 |

**调用示例**

```json
{
  "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 核对）。 |

**调用示例**

```json
{
  "site_name": "示例"
}
```

## SSH

### SSHInfo

**查看SSH · 分类 `SSH` · 风险 `low`**

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

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

**入参**

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

**调用示例**

```json
{}
```

### 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 时需要）。 |

**调用示例**

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

### SSHIntrusion

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

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

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

**入参**

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

**调用示例**

```json
{}
```

## 安全

### SecurityCheck

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

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

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

**入参**

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

**调用示例**

```json
{}
```

## 计划任务

### GetCrontab

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

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

**入参**

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

**调用示例**

```json
{
  "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` | 否 | 备份/日志对象（站点/目录/库名），备份日志类必填 |

**调用示例**

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

## 通知

### GetChannel

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

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

**入参**

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

**调用示例**

```json
{
  "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个） |

**调用示例**

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

### SendMessage

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

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

**入参**

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

**调用示例**

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

Source: https://docs.bt.cn/ai-ops/mcp/tools-reference/index.mdx