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

`POST /system`

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

## Request body

_Required._

One of:

- `ClearSystem`
- `GetAllInfo`
- `GetConcifInfo`
- `GetCpuInfo`
- `GetDiskInfo`
- `GetLoadAverage`
- `GetMemInfo`
- `GetNetWork`
- `GetNetWorkApi`
- `GetSystemTotal`
- `ReMemory`
- `ReWeb`
- `ServiceAdmin`
- `get_io_info`
- `get_upgrade_log`
- `reload_task`
- `set_rname`
- `upgrade_env`
- `upgrade_env_log`

## Example request

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

## Code samples

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

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

## Responses

### default

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


## ClearSystem

清理系统垃圾文件和临时数据。

- **路由**：`POST /system`
- **action**：`ClearSystem`

## 输入参数

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

## 输出参数

返回数组 `[清理文件数量, 清理字节数]`。

## 示例

### 响应

```json
[0, 0]
```


## GetAllInfo

聚合返回系统全部信息概览。

- **路由**：`POST /system`
- **action**：`GetAllInfo`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| load_average | Object | 负载信息（同 GetLoadAverage） |
| title | String | 面板标题 |
| network | Object | 网络流量（同 GetNetWorkApi） |
| cpu | Array | CPU 信息（同 GetCpuInfo） |
| time | String | 系统运行时间 |
| system | String | 操作系统版本 |
| mem | Object | 内存信息（同 GetMemInfo） |
| version | String | 面板版本 |
| iostat | Object | 磁盘 IO 信息 |
| disk | Array | 磁盘分区信息 |

## 示例

### 响应

```json
{
    "load_average": {"one": 0.15, "five": 0.08, "fifteen": 0.02, "max": 4, "limit": 4, "safe": 3.0},
    "title": "宝塔面板",
    "network": {"upTotal": 1000000, "downTotal": 5000000, "up": 10.5, "down": 50.2},
    "cpu": [12.5, 2, [15.0, 10.0], "Intel...", 1, 1],
    "time": "0分钟",
    "system": "Debian GNU/Linux 13 x86_64(Py3.7.16)",
    "mem": {"memTotal": 3901, "memFree": 2918, "memRealUsed": 623},
    "version": "11.7.0"
}
```


## GetConcifInfo

获取面板完整环境配置信息，包括所有已安装组件的版本和运行状态。

- **路由**：`POST /system`
- **action**：`GetConcifInfo`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| webserver | String | Web 服务器类型：`nginx` / `apache` / `openlitespeed` |
| sites_path | String | 网站根目录路径 |
| backup_path | String | 备份目录路径 |
| status | String | 面板状态 |
| mysql_root | String | MySQL root 密码 |
| php | Array | PHP 版本列表，每项含 `version`、`name`、`setup`、`max`、`maxTime`、`pathinfo`、`status` |
| web | Object | Web 服务器详情：`type`、`version`、`setup`、`status` |
| mysql | Object | MySQL 详情：`setup`、`version`、`status` |
| redis | Object | Redis 详情 |
| memcached | Object | Memcached 详情 |
| pure-ftpd | Object | Pure-FTPd 详情 |
| phpmyadmin | Object/Boolean | phpMyAdmin 详情，未安装为 `false` |
| tomcat | Object/Boolean | Tomcat 详情，未安装为 `false` |
| panel | Object | 面板配置：`ip`、`port`、`domain`、`limitip`、`limitarea` 等 |
| systemdate | String | 系统时间 |
| email | String | 管理员邮箱 |

## 示例

### 响应

```json
{
    "webserver": "nginx",
    "sites_path": "/www/wwwroot",
    "backup_path": "/www/backup",
    "status": "ok",
    "mysql_root": "xxxx",
    "php": [{"version": "85", "name": "PHP-85", "setup": true, "max": "50", "maxTime": "60", "pathinfo": true, "status": true}],
    "mysql": {"setup": true, "version": "5.7.44", "status": true},
    "redis": {"setup": false, "status": false},
    "pure-ftpd": {"setup": true, "version": "1.0.49", "status": true},
    "panel": {"ip": "10.0.12.10", "port": "114.132.47.153", "domain": "", "limitip": ""},
    "systemdate": "2026-05-22 08:15:01 CST +0800"
}
```


## GetCpuInfo

获取 CPU 详细信息。调用 `psutil.cpu_percent(percpu=True, interval=interval)` 采样。

- **路由**：`POST /system`
- **action**：`GetCpuInfo`

## 输入参数

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

> 采样间隔固定为 1 秒，不可通过 API 修改。

## 输出参数

返回数组 `[使用率%, 逻辑核心数, [各核使用率...], CPU名称, 物理核心数, 物理CPU数]`。

| 索引 | 类型 | 描述 |
|------|------|------|
| 0 | Float | 整体 CPU 使用率（%） |
| 1 | Integer | 逻辑核心数 |
| 2 | Array[Float] | 各核心使用率数组 |
| 3 | String | CPU 型号名称 |
| 4 | Integer | 物理核心数 |
| 5 | Integer | 物理 CPU 数 |

## 示例

### 请求

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

request_time=1700000000&request_token=xxx&action=GetCpuInfo
```

### 响应

```json
[12.5, 2, [15.0, 10.0], "Intel Core Processor (Skylake, IBRS)", 1, 1]
```


## GetDiskInfo

获取服务器磁盘分区信息。自动过滤 `/boot`、`/dev/shm`、`/proc`、Docker overlay、snap 等非核心分区。

- **路由**：`POST /system`
- **action**：`GetDiskInfo`

## 输入参数

除公共参数外无需额外参数。

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

## 输出参数

返回磁盘分区数组，每项包含：

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| path | String | 挂载路径，如 `/`、`/www` |
| size | Array\[String\] | `[总大小, 已用, 可用, 使用率%, 已用(inode), 剩余]` |
| filesystem | String | 设备名，如 `/dev/sda1` |
| type | String | 文件系统类型，如 `ext4`、`xfs` |
| inodes | Array\[String\] | `[总inode数, 已用, 剩余, 使用率%]` |
| byte_size | Array\[Integer\] | `[总字节, 已用字节, 剩余字节]` |
| d_size | String | 物理磁盘大小，云环境可能为 `None` |

## 示例

### 请求

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

request_time=1700000000&request_token=xxx&action=GetDiskInfo
```

### 响应

```json
[{
    "path": "/",
    "size": ["19.5 GB", "4.8 GB", "13.8 GB", "26.00%", "859.4 MB", "4.8"],
    "filesystem": "/dev/sda1",
    "type": "ext4",
    "inodes": [1302528, 107216, 1195312, "8.23 %"],
    "byte_size": [20922114048, 5204590592, 14816325632],
    "d_size": "None"
}]
```


## GetLoadAverage

获取系统负载平均值，基于 `/proc/loadavg`。

- **路由**：`POST /system`
- **action**：`GetLoadAverage`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| one | Float | 1 分钟平均负载 |
| five | Float | 5 分钟平均负载 |
| fifteen | Float | 15 分钟平均负载 |
| max | Integer | 最大负载阈值（CPU核心数 × 2） |
| limit | Integer | 同 max |
| safe | Float | 安全阈值（max × 0.75） |

## 示例

### 响应

```json
{
    "one": 0.15,
    "five": 0.08,
    "fifteen": 0.02,
    "max": 4,
    "limit": 4,
    "safe": 3.0
}
```


## GetMemInfo

获取服务器内存详细信息，包含物理内存和虚拟内存。结果会被缓存 60 秒。

- **路由**：`POST /system`
- **action**：`GetMemInfo`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| memTotal | Integer | 总内存（MB） |
| memFree | Integer | 空闲内存（MB） |
| memBuffers | Integer | 缓冲区（MB） |
| memCached | Integer | 缓存（MB） |
| memAvailable | Integer | 可用内存（MB），含可回收的 buffer/cache |
| memRealUsed | Integer | 实际已用（MB）= memTotal - memFree - memBuffers - memCached |

## 示例

### 请求

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

request_time={timestamp}&request_token={token}&action=GetMemInfo
```

### 响应

```json
{
    "memTotal": 3901,
    "memFree": 2918,
    "memBuffers": 22,
    "memCached": 338,
    "memAvailable": 3056,
    "memRealUsed": 623
}
```


## GetNetWork

## GetNetWork / GetNetWorkApi

获取实时网络流量及综合系统数据（CPU、内存、负载、磁盘、IO）。

- **路由**：`POST /system`
- **action**：`GetNetWork` 或 `GetNetWorkApi`（两者行为相同）

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | `GetNetWork` 或 `GetNetWorkApi` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| network | Object | 各网卡流量，key 为网卡名，值为 `{upTotal, downTotal, up, down, upPackets, downPackets}` |
| upTotal | Integer | 总上传字节数 |
| downTotal | Integer | 总下载字节数 |
| up | Float | 当前上传速率（KB/s） |
| down | Float | 当前下载速率（KB/s） |
| cpu | Array | CPU 信息 |
| load | Object | 负载信息 |
| mem | Object | 内存信息 |
| disk | Array | 磁盘信息 |
| iostat | Object | 磁盘 IO 统计 |
| time | String | 系统运行时间 |
| system | String | 操作系统版本 |
| site_total | Integer | 网站数量 |
| ftp_total | Integer | FTP 用户数量 |
| database_total | Integer | 数据库数量 |

## 示例

### 响应

```json
{
    "network": {"eth0": {"upTotal": 1000000, "downTotal": 5000000, "up": 10.5, "down": 50.2}},
    "upTotal": 1000000,
    "downTotal": 5000000,
    "up": 10.5,
    "down": 50.2,
    "cpu": [12.5, 2, [15.0, 10.0], "Intel...", 1, 1],
    "load": {"one": 0.15, "five": 0.08, "fifteen": 0.02},
    "mem": {"memTotal": 3901, "memFree": 2918, "memRealUsed": 623},
    "disk": [...],
    "site_total": 1,
    "ftp_total": 0,
    "database_total": 1
}
```


## GetNetWorkApi

与 [GetNetWork](/api/system/getnetwork) 行为相同，获取实时网络流量和综合系统数据。

- **路由**：`POST /system`
- **action**：`GetNetWorkApi`

## 输入参数

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

## 输出

返回 `network`、`upTotal`、`downTotal`、`up`、`down` 等字段。详见 [GetNetWork](/api/system/getnetwork)。

## 输出参数

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


## GetSystemTotal

获取系统统计信息，包含内存、CPU、运行时间、系统版本等综合数据。

- **路由**：`POST /system`
- **action**：`GetSystemTotal`

## 输入参数

除公共参数外无需额外参数。

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| memTotal | Integer | 总内存（MB） |
| memFree | Integer | 空闲内存（MB） |
| memBuffers | Integer | 缓冲区内存（MB） |
| memCached | Integer | 缓存内存（MB） |
| memAvailable | Integer | 可用内存（MB） |
| memRealUsed | Integer | 实际已用内存（MB），不含 buffer/cache |
| cpuNum | Integer | CPU 逻辑核心数 |
| cpuRealUsed | Float | CPU 实时使用率（%） |
| time | String | 系统已运行时间，如 `10天`、`5小时`、`30分钟` |
| system | String | 操作系统版本，如 `Debian GNU/Linux 13 x86_64(Py3.7.16)` |
| isuser | Integer | 是否存在 admin 用户，`1` 为存在 |
| isport | Boolean | 面板端口是否为默认 8888 |
| version | String | 面板版本号，如 `11.7.0` |

## 示例

### 请求

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

request_time=1700000000&request_token=xxx&action=GetSystemTotal
```

### 响应

```json
{
    "memTotal": 3901,
    "memFree": 2918,
    "memBuffers": 22,
    "memCached": 338,
    "memAvailable": 3056,
    "memRealUsed": 623,
    "cpuNum": 2,
    "cpuRealUsed": 12.5,
    "time": "0分钟",
    "system": "Debian GNU/Linux 13 x86_64(Py3.7.16)",
    "isuser": 1,
    "isport": false,
    "version": "11.7.0"
}
```


## ReMemory

执行内存释放操作（sync + drop caches），释放后返回当前内存状态。

- **路由**：`POST /system`
- **action**：`ReMemory`

> **注意**：操作可能耗时较长，建议设置较长的 HTTP 超时（>15s）。


## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| memTotal | Integer | 总内存（MB） |
| memFree | Integer | 空闲内存（MB） |
| memRealUsed | Integer | 实际使用内存（MB） |
| memNewTotalList | Array | 总内存 `["3.8", "GB"]` |
| memNewRealUsedList | Array | 实际使用内存 `["402.0", "MB"]` |

## 示例

```json
{"memTotal": 3901, "memFree": 3295, "memRealUsed": 402, "memNewTotalList": ["3.8", "GB"], "memNewRealUsedList": ["402.0", "MB"]}
```


## ReWeb

重启宝塔面板服务。

> **注意**：调用后面板服务会短暂中断（约 2~5 秒），API 请求将不可用。


- **路由**：`POST /system`
- **action**：`ReWeb`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 表示重启指令已发出 |
| msg | String | 提示信息 |

## 示例

### 响应

```json
{"status": true, "msg": "面板已重启"}
```


## ServiceAdmin

管理服务器上各类服务的启动、停止、重启和重载。

- **路由**：`POST /system`
- **action**：`ServiceAdmin`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `ServiceAdmin` |
| name | 是 | String | 服务名称 |
| type | 是 | String | 操作类型 |

### name 取值

| 值 | 服务 |
|----|------|
| `nginx` | Nginx |
| `httpd` / `apache` | Apache |
| `mysqld` | MySQL / MariaDB |
| `pure-ftpd` | Pure-FTPd |
| `redis` | Redis |
| `memcached` | Memcached |
| `phpmyadmin` | phpMyAdmin |
| `openlitespeed` | OpenLiteSpeed |
| `tomcat` | Tomcat |
| `webserver` | 自动识别当前 Web 服务器 |

### type 取值

| 值 | 操作 |
|----|------|
| `start` | 启动 |
| `stop` | 停止 |
| `restart` | 重启 |
| `reload` | 重载配置（不中断服务） |
| `test` | 测试配置文件 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 表示操作成功 |
| msg | String | 执行结果描述，如 `执行成功!` |

## 示例

### 重启 Nginx

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

request_time=1700000000&request_token=xxx&action=ServiceAdmin&name=nginx&type=restart
```

### 响应

```json
{"status": true, "msg": "执行成功!"}
```

### 启动 MySQL

```
action=ServiceAdmin&name=mysqld&type=start
```


## get_io_info

获取当前磁盘 IO 读写速率（KB/s）。

- **路由**：`POST /system`
- **action**：`get_io_info`

## 输入参数

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

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| write | Integer | 磁盘写入速率（KB/s） |
| read | Integer | 磁盘读取速率（KB/s） |

## 示例

### 响应

```json
{"write": 0, "read": 0}
```


## get_upgrade_log

获取面板最近一次升级的日志内容。

- **路由**：`POST /system`
- **action**：`get_upgrade_log`

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` |
| msg | String | 升级日志内容，无升级时为空 |

## 示例

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


## reload_task

重启面板的后台任务处理进程。

- **路由**：`POST /system`
- **action**：`reload_task`

## 示例

```json
{"status": true, "msg": "后台进程已重启完毕"}
```


## set_rname

为指定路径的磁盘分区设置自定义备注名称。

- **路由**：`POST /system`
- **action**：`set_rname`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `set_rname` |
| path | 是 | String | 磁盘挂载路径，如 `/`、`/www` |
| name | 是 | String | 备注名称 |

## 示例

```json
{"status": true, "msg": "设置成功！"}
```


## upgrade_env

启动面板 Python 运行环境的升级任务（异步执行）。

- **路由**：`POST /system`
- **action**：`upgrade_env`

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 任务已启动 |
| msg | String | `环境升级任务已启动...` |

## 示例

```json
{"status": true, "msg": "环境升级任务已启动...", "data": null}
```

## 相关接口

- [upgrade_env_log](/api/system/upgrade_env_log) — 查看升级日志


## upgrade_env_log

获取面板 Python 运行环境升级的实时日志和执行状态。

- **路由**：`POST /system`
- **action**：`upgrade_env_log`

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` |
| msg | String | 升级状态描述 |
| data.env_update_running | Boolean | 是否正在升级中 |
| data.log | String | 升级日志内容 |

## 示例

```json
{"status": true, "msg": "环境升级已结束", "data": {"env_update_running": false, "log": "已存在python3.13环境, 退出"}}
```