Skill: breadbot86/1panel-api (version 1.0.0)

--- name: 1panel-api description: 1Panel 开源面板 API Skill。提供网站管理、容器管理、数据库管理、文件管理等 23+ 个模块的完整 API 接口文档。 --- # 1Panel API Skills 🎯 **一键管理你的 1Panel 服务器** ## 快速开始 ### 首次配置 首次使用本 Skill 时，请提供以下信息： | 信息 | 说明 | 示例 | |------|------|------| | 1Panel 地址 | 服务器 IP 或域名 + 端口 | `http://192.168.1.100:8888` | | API Key | 在面板「设置」→「API 密钥」中生成 | 你的密钥 | ### 获取 API Key 1. 登录 1Panel 面板 2. 进入「设置」→「API 密钥」 3. 点击「创建」生成新密钥 4. 复制生成的密钥 ## 功能模块 | 模块 | 说明 | |------|------| | [Apps](./docs/SKILL-apps.md) | 应用商店、已安装应用管理 | | [Websites](./docs/SKILL-websites.md) | 网站创建、配置、反向代理、SSL | | [Containers](./docs/SKILL-containers.md) | Docker 容器管理 | | [Databases](./docs/SKILL-databases.md) | MySQL、PostgreSQL、Redis、MongoDB | | [Files](./docs/SKILL-files.md) | 文件上传、下载、压缩、解压 | | [Backups](./docs/SKILL-backups.md) | 备份与恢复 | | [Cronjobs](./docs/SKILL-cronjobs.md) | 定时任务 | | [Runtimes](./docs/SKILL-runtimes.md) | PHP、Node、Python、Go、Java 运行环境 | | [Hosts](./docs/SKILL-hosts.md) | 主机监控、防火墙、SSH、磁盘管理 | | [Settings](./docs/SKILL-settings.md) | 系统配置、用户管理 | ## 认证方式 ```bash # Token 计算方式 [REDACTED_SECRET]" timestamp=$(date +%s) [REDACTED_SECRET] -n "1panel${api_key}${timestamp}" | openssl md5 | awk '{print $2}') # 请求示例 curl -X GET "http://你的地址:8888/api/v2/containers/list" \ -H "1Panel-[REDACTED_SECRET]" \ -H "1Panel-Timestamp: $timestamp" \ -H "Content-Type: application/json" ``` ## 了解更多 - 📖 完整 API 文档：见 [docs](./docs/) 目录 - ❓ 常见问题：见 [README.md](./README.md) - 🔧 1Panel 官网：https://1panel.cn/

path: INDEX.md
content: # 1Panel Skills 索引

- [Ai](./SKILL-ai.md) - 47 个接口
- [Alert](./SKILL-alert.md) - 13 个接口
- [Apps](./SKILL-apps.md) - 31 个接口
- [Containers](./SKILL-containers.md) - 66 个接口
- [Cronjobs](./SKILL-cronjobs.md) - 15 个接口
- [Dashboard](./SKILL-dashboard.md) - 12 个接口
- [Databases](./SKILL-databases.md) - 42 个接口
- [Files](./SKILL-files.md) - 41 个接口
- [Groups](./SKILL-groups.md) - 3 个接口
- [Hosts](./SKILL-hosts.md) - 48 个接口
- [Logs](./SKILL-logs.md) - 3 个接口
- [Openresty](./SKILL-openresty.md) - 9 个接口
- [Process](./SKILL-process.md) - 4 个接口
- [Runtimes](./SKILL-runtimes.md) - 30 个接口
- [Settings](./SKILL-settings.md) - 20 个接口
- [Toolbox](./SKILL-toolbox.md) - 39 个接口
- [Websites](./SKILL-websites.md) - 64 个接口
- [Websites/Acme](./SKILL-websites_acme.md) - 3 个接口
- [Websites/Ca](./SKILL-websites_ca.md) - 6 个接口
- [Websites/Dns](./SKILL-websites_dns.md) - 3 个接口
- [Websites/Ssl](./SKILL-websites_ssl.md) - 12 个接口

**总计**: 21 模块, 511 接口

path: README.md
content: # 1Panel API Skills

🎯 **OpenClaw Skill - 1Panel 服务器管理面板 API 接口文档**

[English](./README_en.md) | 中文

## 简介

本 Skill 提供 1Panel 开源服务器管理面板的完整 API 接口文档，包含 **23+ 个模块**，**500+ 个 API 接口**。

## 1Panel 是什么？

[1Panel](https://1panel.cn/) 是一个现代化、开源的 Linux 服务器运维管理面板，由 Go + Gin + Vue 开发。

## 功能特性

- 🌐 **网站管理** - 创建网站、配置 Nginx、反向代理、SSL 证书
- 🐳 **容器管理** - Docker 容器、镜像、网络、卷管理
- 💾 **数据库** - MySQL、PostgreSQL、Redis、MongoDB
- 📁 **文件管理** - 上传、下载、压缩、解压、在线编辑
- ⏰ **定时任务** - 备份、清理、脚本执行
- 📊 **系统监控** - CPU、内存、磁盘、网络监控
- 🔒 **安全防护** - 防火墙 Fail2ban ClamAV

## 快速开始

### 1. 安装 Skill

```bash
# 方式一：从 ClawHub 安装
openclaw skill install 1panel-api

# 方式二：手动复制到 skills 目录
cp -r 1Panel-Skills ~/.openclaw/workspace/skills/
```

### 2. 配置连接

首次使用需要配置 1Panel 服务器连接信息：

| 配置项 | 说明 | 获取方式 |
|--------|------|----------|
| 面板地址 | 1Panel 面板访问地址 | 浏览器访问你的服务器 IP:8888 |
| API Key | 接口访问密钥 | 面板 → 设置 → API 密钥 → 创建 |

### 3. 开始使用

```bash
# 示例：获取容器列表
# 具体 API 调用请参考各模块文档
```

## 模块列表

| 模块 | 文件 | 说明 |
|------|------|------|
| AI | [SKILL-ai.md](./docs/SKILL-ai.md) | Ollama、MCP Server、TensorRT LLM |
| Apps | [SKILL-apps.md](./docs/SKILL-apps.md) | 应用商店、已安装应用 |
| Auth | [SKILL-auth.md](./docs/SKILL-auth.md) | 登录认证、验证码、MFA |
| Backups | [SKILL-backups.md](./docs/SKILL-backups.md) | 备份与恢复 |
| Containers | [SKILL-containers.md](./docs/SKILL-containers.md) | Docker 容器管理 |
| Cronjobs | [SKILL-cronjobs.md](./docs/SKILL-cronjobs.md) | 定时任务 |
| Dashboard | [SKILL-dashboard.md](./docs/SKILL-dashboard.md) | 系统仪表盘 |
| Databases | [SKILL-databases.md](./docs/SKILL-databases.md) | 数据库管理 |
| Files | [SKILL-files.md](./docs/SKILL-files.md) | 文件管理 |
| Groups | [SKILL-groups.md](./docs/SKILL-groups.md) | 分组管理 |
| Hosts | [SKILL-hosts.md](./docs/SKILL-hosts.md) | 主机监控、防火墙、SSH |
| Logs | [SKILL-logs.md](./docs/SKILL-logs.md) | 日志管理 |
| OpenResty | [SKILL-openresty.md](./docs/SKILL-openresty.md) | OpenResty 管理 |
| Process | [SKILL-process.md](./docs/SKILL-process.md) | 进程管理 |
| Runtimes | [SKILL-runtimes.md](./docs/SKILL-runtimes.md) | 运行环境 |
| Script | [SKILL-script.md](./docs/SKILL-script.md) | 脚本库 |
| Settings | [SKILL-settings.md](./docs/SKILL-settings.md) | 系统设置 |
| Toolbox | [SKILL-toolbox.md](./docs/SKILL-toolbox.md) | 工具箱 |
| Websites | [SKILL-websites.md](./docs/SKILL-websites.md) | 网站管理 |
| Websites SSL | [SKILL-websites_ssl.md](./docs/SKILL-websites_ssl.md) | SSL 证书 |
| Websites CA | [SKILL-websites_ca.md](./docs/SKILL-websites_ca.md) | 自建 CA |
| Websites ACME | [SKILL-websites_acme.md](./docs/SKILL-websites_acme.md) | ACME 账户 |
| Websites DNS | [SKILL-websites_dns.md](./docs/SKILL-websites_dns.md) | DNS 账户 |

## 认证方式

### 请求头

| Header | 说明 | 示例 |
|--------|------|------|
| 1Panel-Token | 认证 Token | `md5("1panel" + APIKey + Timestamp)` |
| 1Panel-Timestamp | Unix 时间戳 | `1709548800` |
| Content-Type | 请求类型 | `application/json` |

### Token 计算

```bash
# Shell 计算方式
[REDACTED_SECRET]"
timestamp=$(date +%s)
[REDACTED_SECRET] -n "1panel${api_key}${timestamp}" | openssl md5 | awk '{print $2}')

# Python 计算方式
import hashlib
[REDACTED_SECRET]"1panel{api_key}{timestamp}".encode()).hexdigest()
```

### 请求示例

```bash
# 获取容器列表
curl -X GET "http://192.168.1.100:8888/api/v2/containers/list" \
  -H "1Panel-[REDACTED_SECRET]" \
  -H "1Panel-Timestamp: 1709548800" \
  -H "Content-Type: application/json"

# 创建网站
curl -X POST "http://192.168.1.100:8888/api/v2/websites" \
  -H "1Panel-[REDACTED_SECRET]" \
  -H "1Panel-Timestamp: 1709548800" \
  -H "Content-Type: application/json" \
  -d '{"type":"static","alias":"mywebsite","websiteGroupID":1}'
```

## 文件路径说明

1Panel 各类文件的存储路径：

| 类型 | 路径 |
|------|------|
| 网站根目录 | `/opt/1panel/www/sites/{网站名}/index` |
| 应用目录 | `/opt/1panel/apps/{应用Key}/{应用名}` |
| 备份目录 | `/opt/1panel/backup/` |
| 日志目录 | `/opt/1panel/logs/` |
| 数据库 | `/opt/1panel/mysql/{数据库名}` |

## 常见问题

### Q: 如何获取 API Key？
A: 登录 1Panel → 设置 → API 密钥 → 创建新密钥

### Q: API 请求失败怎么办？
A: 检查以下几点：
1. 面板地址是否正确
2. API Key 是否有效
3. 时间戳是否与服务器同步
4. Token 计算是否正确

### Q: 支持 HTTPS 吗？
A: 支持，只需将地址改为 `https://` 开头

### Q: 可以管理多台服务器吗？
A: 当前 Skill 配置单服务器，如需管理多台，可以配置多个 Skill 实例

## 源码结构

```
1Panel-Skills/
├── SKILL.md              # Skill 入口文件
├── README.md             # 本文档
├── INDEX.md              # 模块索引（可选）
└── docs/                 # 详细 API 文档
    ├── SKILL-ai.md
    ├── SKILL-apps.md
    ├── SKILL-containers.md
    └── ...
```

## 相关链接

- 🌐 [1Panel 官网](https://1panel.cn/)
- 📚 [1Panel 文档](https://1panel.cn/docs/)
- 💻 [GitHub](https://github.com/1Panel-dev/1Panel)
- 🐳 [Docker Hub](https://hub.docker.com/r/1panel/1panel)

## 贡献

欢迎提交 Issue 和 PR！

## License

本项目基于 MIT License。


path: docs/SKILL-ai.md
content: # AI, McpServer, TensorRT, Agents - 1Panel API

## 模块说明
AI, McpServer, TensorRT, Agents 模块接口，提供 Ollama 模型管理、MCP 服务器、TensorRT LLM 以及 AI Agents 的完整 API。

---

## 一、Ollama 模型接口

### GET /ai/gpu/load
**功能**: 获取 GPU/XPU 信息

**参数**: 无

**返回示例**:
```json
{
  "gpuInfo": {
    "name": "NVIDIA GeForce RTX 3080",
    "memoryTotal": "10GB",
    "memoryUsed": "2GB",
    "utilization": "30%"
  }
}
```

---

### POST /ai/ollama/model/sync
**功能**: 同步 Ollama 模型列表

**参数**: 无

**返回示例**:
```json
[
  { "id": 1, "name": "llama2" },
  { "id": 2, "name": "codellama" }
]
```

---

### POST /ai/ollama/model/search
**功能**: 分页查询 Ollama 模型列表

**参数 (SearchWithPage)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| info | string | 否 | 搜索关键词 | - |

---

### POST /ai/ollama/model
**功能**: 创建 Ollama 模型

**参数 (OllamaModelName)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 模型名称 | 有效的 Ollama 模型名，如 llama2, codellama, mistral 等 |
| taskID | string | 否 | 任务ID | - |

---

### POST /ai/ollama/model/recreate
**功能**: 重新创建 Ollama 模型（重试失败的任务）

**参数 (OllamaModelName)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 模型名称 | 有效的 Ollama 模型名 |
| taskID | string | 否 | 任务ID | - |

---

### POST /ai/ollama/model/load
**功能**: 获取 Ollama 模型详情

**参数 (OllamaModelName)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 模型名称 | 有效的 Ollama 模型名 |
| taskID | string | 否 | 任务ID | - |

**返回示例**:
```json
{
  "id": 1,
  "name": "llama2",
  "size": "3.8GB",
  "from": "ollama",
  "status": "running",
  "message": ""
}
```

---

### POST /ai/ollama/close
**功能**: 关闭 Ollama 模型连接

**参数 (OllamaModelName)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 模型名称 | 有效的 Ollama 模型名 |
| taskID | string | 否 | 任务ID | - |

---

### POST /ai/ollama/model/del
**功能**: 删除 Ollama 模型

**参数 (ForceDelete)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| ids | []uint | 是 | 模型ID列表 | - |
| forceDelete | bool | 否 | 是否强制删除 | true/false |

---

## 二、Ollama 域名绑定接口

### POST /ai/domain/bind
**功能**: 绑定域名到 Ollama 服务

**参数 (OllamaBindDomain)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| domain | string | 是 | 域名 | 有效的域名，如 ollama.example.com |
| appInstallID | uint | 是 | 应用安装ID | - |
| sslID | uint | 否 | SSL证书ID | - |
| websiteID | uint | 否 | 网站ID | - |
| ipList | string | 否 | IP白名单 | 逗号分隔的IP列表，如 "192.168.1.1,10.0.0.1" |

---

### POST /ai/domain/get
**功能**: 获取绑定的域名信息

**参数 (OllamaBindDomainReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| appInstallID | uint | 是 | 应用安装ID | - |

**返回示例 (OllamaBindDomainRes)**:
```json
{
  "domain": "ollama.example.com",
  "sslID": 1,
  "allowIPs": ["192.168.1.1"],
  "websiteID": 1,
  "connUrl": "https://ollama.example.com",
  "acmeAccountID": 1
}
```

---

### POST /ai/domain/update
**功能**: 更新绑定的域名信息

**参数 (OllamaBindDomain)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| domain | string | 是 | 域名 | 有效的域名 |
| appInstallID | uint | 是 | 应用安装ID | - |
| sslID | uint | 否 | SSL证书ID | - |
| websiteID | uint | 否 | 网站ID | - |
| ipList | string | 否 | IP白名单 | 逗号分隔的IP列表 |

---

## 三、MCP 服务器接口

### POST /ai/mcp/search
**功能**: 分页查询 MCP 服务器列表

**参数 (McpServerSearch)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| name | string | 否 | 服务器名称搜索 | - |
| sync | bool | 否 | 是否同步 | true/false |

---

### POST /ai/mcp/server
**功能**: 创建 MCP 服务器

**参数 (McpServerCreate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 服务器名称 | - |
| command | string | 是 | 启动命令 | 如 npx, python 等 |
| environments | []Environment | 否 | 环境变量列表 | - |
| volumes | []Volume | 否 | 卷挂载列表 | - |
| port | int | 是 | 端口号 | 1024-65535 |
| containerName | string | 否 | 容器名称 | - |
| baseUrl | string | 否 | 基础URL | - |
| ssePath | string | 否 | SSE 路径 | - |
| hostIP | string | 否 | 主机IP | - |
| streamableHttpPath | string | 否 | Streamable HTTP 路径 | - |
| outputTransport | string | 是 | 输出传输方式 | stdio, sse, streamable-http |
| type | string | 是 | 服务器类型 | mcp |

**Environment 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 环境变量名 |
| value | string | 是 | 环境变量值 |

**Volume 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| source | string | 是 | 主机路径 |
| target | string | 是 | 容器路径 |

---

### POST /ai/mcp/server/update
**功能**: 更新 MCP 服务器

**参数 (McpServerUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 服务器ID | - |
| name | string | 是 | 服务器名称 | - |
| command | string | 是 | 启动命令 | - |
| environments | []Environment | 否 | 环境变量列表 | - |
| volumes | []Volume | 否 | 卷挂载列表 | - |
| port | int | 是 | 端口号 | 1024-65535 |
| containerName | string | 否 | 容器名称 | - |
| baseUrl | string | 否 | 基础URL | - |
| ssePath | string | 否 | SSE 路径 | - |
| hostIP | string | 否 | 主机IP | - |
| streamableHttpPath | string | 否 | Streamable HTTP 路径 | - |
| outputTransport | string | 是 | 输出传输方式 | stdio, sse, streamable-http |
| type | string | 是 | 服务器类型 | mcp |

---

### POST /ai/mcp/server/del
**功能**: 删除 MCP 服务器

**参数 (McpServerDelete)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 服务器ID | - |

---

### POST /ai/mcp/server/op
**功能**: 操作 MCP 服务器（启动/停止/重启）

**参数 (McpServerOperate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 服务器ID | - |
| operate | string | 是 | 操作类型 | start, stop, restart |

---

### GET /ai/mcp/domain/get
**功能**: 获取 MCP 服务器绑定的域名

**参数**: 无

**返回示例**:
```json
{
  "domain": "mcp.example.com",
  "sslID": 1,
  "allowIPs": ["192.168.1.1"],
  "websiteID": 1
}
```

---

### POST /ai/mcp/domain/bind
**功能**: 绑定域名到 MCP 服务器

**参数 (McpBindDomain)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| domain | string | 是 | 域名 | 有效的域名 |
| sslID | uint | 否 | SSL证书ID | - |
| ipList | string | 否 | IP白名单 | 逗号分隔的IP列表 |

---

### POST /ai/mcp/domain/update
**功能**: 更新 MCP 服务器绑定的域名

**参数 (McpBindDomainUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| websiteID | uint | 是 | 网站ID | - |
| sslID | uint | 否 | SSL证书ID | - |
| ipList | string | 否 | IP白名单 | 逗号分隔的IP列表 |

---

## 四、TensorRT LLM 接口

### POST /ai/tensorrt/search
**功能**: 分页查询 TensorRT LLM 列表

**参数 (TensorRTLLMSearch)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| name | string | 否 | 模型名称搜索 | - |

---

### POST /ai/tensorrt/create
**功能**: 创建 TensorRT LLM

**参数 (TensorRTLLMCreate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 模型名称 | - |
| containerName | string | 是 | 容器名称 | - |
| version | string | 是 | TensorRT-LLM 版本 | 如 v0.13.0 |
| modelDir | string | 是 | 模型目录路径 | - |
| image | string | 是 | Docker 镜像 | 如 nvcr.io/nvidia/trt_llm:latest |
| command | string | 是 | 启动命令 | - |
| modelType | string | 否 | 模型类型 | llama, chatglm, etc. |
| modelSpeedup | bool | 否 | 是否启用加速 | true/false |
| exposedPorts | []ExposedPort | 否 | 暴露端口列表 | - |
| environments | []Environment | 否 | 环境变量列表 | - |
| volumes | []Volume | 否 | 卷挂载列表 | - |

---

### POST /ai/tensorrt/update
**功能**: 更新 TensorRT LLM

**参数 (TensorRTLLMUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 模型ID | - |
| name | string | 是 | 模型名称 | - |
| containerName | string | 是 | 容器名称 | - |
| version | string | 是 | TensorRT-LLM 版本 | - |
| modelDir | string | 是 | 模型目录路径 | - |
| image | string | 是 | Docker 镜像 | - |
| command | string | 是 | 启动命令 | - |
| modelType | string | 否 | 模型类型 | - |
| modelSpeedup | bool | 否 | 是否启用加速 | - |
| exposedPorts | []ExposedPort | 否 | 暴露端口列表 | - |
| environments | []Environment | 否 | 环境变量列表 | - |
| volumes | []Volume | 否 | 卷挂载列表 | - |

---

### POST /ai/tensorrt/delete
**功能**: 删除 TensorRT LLM

**参数 (TensorRTLLMDelete)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 模型ID | - |

---

### POST /ai/tensorrt/operate
**功能**: 操作 TensorRT LLM（启动/停止/重启）

**参数 (TensorRTLLMOperate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 模型ID | - |
| operate | string | 是 | 操作类型 | start, stop, restart |

---

## 五、Agents 接口

### POST /ai/agents
**功能**: 创建 Agent

**参数 (AgentCreateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | Agent 名称 | - |
| appVersion | string | 是 | 应用版本 | - |
| webUIPort | int | 是 | WebUI 端口 | 1024-65535 |
| bridgePort | int | 否 | 桥接端口 | - |
| agentType | string | 否 | Agent 类型 | - |
| provider | string | 否 | 模型提供商 | openai, anthropic, local, etc. |
| model | string | 否 | 模型名称 | - |
| apiType | string | 否 | API 类型 | - |
| maxTokens | int | 否 | 最大 token 数 | - |
| contextWindow | int | 否 | 上下文窗口大小 | - |
| accountID | uint | 否 | 账户ID | - |
| apiKey | string | 否 | API Key | - |
| baseURL | string | 否 | 基础 URL | - |
| token | string | 否 | Agent Token | - |
| advanced | bool | 否 | 是否启用高级配置 | - |
| containerName | string | 否 | 容器名称 | - |
| allowPort | bool | 否 | 是否允许自动分配端口 | - |
| specifyIP | string | 否 | 指定IP | - |
| restartPolicy | string | 否 | 重启策略 | always, on-failure, unless-stopped |
| cpuQuota | float64 | 否 | CPU 配额 | - |
| memoryLimit | float64 | 否 | 内存限制 | - |
| memoryUnit | string | 否 | 内存单位 | MB, GB |
| pullImage | bool | 否 | 是否拉取镜像 | - |
| editCompose | bool | 否 | 是否编辑 Compose | - |
| dockerCompose | string | 否 | Docker Compose 配置 | - |

---

### POST /ai/agents/search
**功能**: 分页查询 Agent 列表

**参数 (SearchWithPage)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| info | string | 否 | 搜索关键词 | - |

---

### POST /ai/agents/delete
**功能**: 删除 Agent

**参数 (AgentDeleteReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | Agent ID | - |
| taskID | string | 否 | 任务ID | - |
| forceDelete | bool | 否 | 是否强制删除 | - |

---

### POST /ai/agents/token/reset
**功能**: 重置 Agent Token

**参数 (AgentTokenResetReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | Agent ID | - |

---

### POST /ai/agents/model/update
**功能**: 更新 Agent 模型配置

**参数 (AgentModelConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| accountID | uint | 是 | 账户ID | - |
| model | string | 是 | 模型名称 | - |

---

### GET /ai/agents/providers
**功能**: 获取支持的模型提供商列表

**参数**: 无

**返回示例**:
```json
[
  {
    "provider": "openai",
    "displayName": "OpenAI",
    "baseURL": "https://api.openai.com/v1",
    "models": [
      { "id": "gpt-4", "name": "GPT-4" },
      { "id": "gpt-3.5-turbo", "name": "GPT-3.5 Turbo" }
    ]
  }
]
```

---

### POST /ai/agents/accounts
**功能**: 创建 Agent 账户

**参数 (AgentAccountCreateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| provider | string | 是 | 模型提供商 | openai, anthropic, etc. |
| name | string | 是 | 账户名称 | - |
| apiKey | string | 是 | API Key | - |
| rememberAPIKey | bool | 否 | 是否记住 API Key | - |
| baseURL | string | 否 | 基础 URL | - |
| model | string | 否 | 默认模型 | - |
| apiType | string | 否 | API 类型 | - |
| maxTokens | int | 否 | 最大 token 数 | - |
| contextWindow | int | 否 | 上下文窗口大小 | - |
| remark | string | 否 | 备注 | - |

---

### POST /ai/agents/accounts/update
**功能**: 更新 Agent 账户

**参数 (AgentAccountUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 账户ID | - |
| name | string | 是 | 账户名称 | - |
| apiKey | string | 是 | API Key | - |
| rememberAPIKey | bool | 否 | 是否记住 API Key | - |
| baseURL | string | 否 | 基础 URL | - |
| model | string | 否 | 默认模型 | - |
| apiType | string | 否 | API 类型 | - |
| maxTokens | int | 否 | 最大 token 数 | - |
| contextWindow | int | 否 | 上下文窗口大小 | - |
| remark | string | 否 | 备注 | - |
| syncAgents | bool | 否 | 是否同步到 Agent | - |

---

### POST /ai/agents/accounts/search
**功能**: 分页查询 Agent 账户列表

**参数 (AgentAccountSearch)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| provider | string | 否 | 提供商筛选 | - |
| name | string | 否 | 账户名称搜索 | - |

---

### POST /ai/agents/accounts/verify
**功能**: 验证 Agent 账户

**参数 (AgentAccountVerifyReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| provider | string | 是 | 模型提供商 | - |
| apiKey | string | 是 | API Key | - |
| baseURL | string | 否 | 基础 URL | - |

---

### POST /ai/agents/accounts/delete
**功能**: 删除 Agent 账户

**参数 (AgentAccountDeleteReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 账户ID | - |

---

### POST /ai/agents/channel/feishu/get
**功能**: 获取飞书频道配置

**参数 (AgentFeishuConfigReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |

---

### POST /ai/agents/channel/feishu/update
**功能**: 更新飞书频道配置

**参数 (AgentFeishuConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| botName | string | 是 | 机器人名称 | - |
| appID | string | 是 | App ID | - |
| appSecret | string | 是 | App Secret | - |
| enabled | bool | 否 | 是否启用 | - |
| dmPolicy | string | 是 | 私信策略 | all, approved, none |

---

### POST /ai/agents/channel/feishu/approve
**功能**: 批准飞书配对

**参数 (AgentFeishuPairingApproveReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| pairingCode | string | 是 | 配对码 | - |

---

### POST /ai/agents/channel/telegram/get
**功能**: 获取 Telegram 频道配置

**参数 (AgentTelegramConfigReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |

---

### POST /ai/agents/channel/telegram/update
**功能**: 更新 Telegram 频道配置

**参数 (AgentTelegramConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| enabled | bool | 否 | 是否启用 | - |
| dmPolicy | string | 是 | 私信策略 | all, approved, none |
| botToken | string | 是 | Bot Token | - |
| proxy | string | 否 | 代理地址 | - |

---

### POST /ai/agents/channel/discord/get
**功能**: 获取 Discord 频道配置

**参数 (AgentDiscordConfigReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |

---

### POST /ai/agents/channel/discord/update
**功能**: 更新 Discord 频道配置

**参数 (AgentDiscordConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| enabled | bool | 否 | 是否启用 | - |
| dmPolicy | string | 是 | 私信策略 | all, approved, none |
| groupPolicy | string | 是 | 群组策略 | open, allowlist, disabled |
| token | string | 是 | Bot Token | - |
| proxy | string | 否 | 代理地址 | - |

---

### POST /ai/agents/browser/get
**功能**: 获取浏览器配置

**参数 (AgentBrowserConfigReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |

---

### POST /ai/agents/browser/update
**功能**: 更新浏览器配置

**参数 (AgentBrowserConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| enabled | bool | 否 | 是否启用 | - |
| headless | bool | 否 | 是否无头模式 | - |
| noSandbox | bool | 否 | 是否禁用沙箱 | - |
| defaultProfile | string | 是 | 默认浏览器配置 | - |

---

### POST /ai/agents/other/get
**功能**: 获取其他配置

**参数 (AgentOtherConfigReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |

---

### POST /ai/agents/other/update
**功能**: 更新其他配置

**参数 (AgentOtherConfigUpdateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| userTimezone | string | 是 | 用户时区 | 如 Asia/Shanghai, America/New_York |

---

### POST /ai/agents/channel/pairing/approve
**功能**: 批准频道配对

**参数 (AgentChannelPairingApproveReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| agentID | uint | 是 | Agent ID | - |
| type | string | 是 | 频道类型 | feishu, telegram, discord |
| pairingCode | string | 是 | 配对码 | - |

---

## 通用结构说明

### PageInfo
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |

### Environment
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 环境变量名 |
| value | string | 是 | 环境变量值 |

### Volume
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| source | string | 是 | 主机路径 |
| target | string | 是 | 容器路径 |

### ExposedPort
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| hostPort | int | 是 | 主机端口 |
| containerPort | int | 是 | 容器端口 |
| hostIP | string | 否 | 主机IP |


path: docs/SKILL-alert.md
content: # Alert - 1Panel API

## 模块说明
alert 模块接口，包含告警管理、ClamAV 病毒扫描、Fail2ban 防护三大功能。

## 接口列表

---

### 一、Alert 告警模块

#### POST /api/v1/alert

**Handler**: `baseApi.CreateAlert`  
**功能**: 创建告警规则  
**说明**: 创建一个新的告警监控规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| type | string | 是 | 告警类型 | - |
| cycle | uint | 否 | 监控周期(分钟) | - |
| count | uint | 否 | 触发告警的次数阈值 | - |
| method | string | 是 | 告警通知方式 | - |
| title | string | 否 | 告警标题 | - |
| project | string | 否 | 关联项目 | - |
| status | string | 否 | 状态 | - |
| sendCount | uint | 否 | 已发送次数 | - |
| advancedParams | string | 否 | 高级参数(JSON字符串) | - |

**返回**: `无`

---

#### POST /api/v1/alert/update

**Handler**: `baseApi.UpdateAlert`  
**功能**: 更新告警规则  
**说明**: 更新已有的告警监控规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 告警规则ID | - |
| type | string | 否 | 告警类型 | - |
| cycle | uint | 否 | 监控周期(分钟) | - |
| count | uint | 否 | 触发告警的次数阈值 | - |
| method | string | 否 | 告警通知方式 | - |
| title | string | 否 | 告警标题 | - |
| project | string | 否 | 关联项目 | - |
| status | string | 否 | 状态 | - |
| sendCount | uint | 否 | 已发送次数 | - |
| advancedParams | string | 否 | 高级参数(JSON字符串) | - |

**返回**: `无`

---

#### POST /api/v1/alert/search

**Handler**: `baseApi.PageAlert`  
**功能**: 分页查询告警规则  
**说明**: 获取告警规则列表，支持分页和过滤

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| orderBy | string | 是 | 排序字段 | `created_at` |
| order | string | 是 | 排序方式 | `null`, `ascending`, `descending` |
| type | string | 否 | 告警类型过滤 | - |
| status | string | 否 | 状态过滤 | - |
| method | string | 否 | 通知方式过滤 | - |

**返回**: `PageResult{Total, Items}`

---

#### POST /api/v1/alert/status

**Handler**: `baseApi.UpdateAlertStatus`  
**功能**: 更新告警规则状态  
**说明**: 启用或禁用告警规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 告警规则ID | - |
| status | string | 是 | 状态 | - |

**返回**: `无`

---

#### POST /api/v1/alert/del

**Handler**: `baseApi.DeleteAlert`  
**功能**: 删除告警规则  
**说明**: 删除指定的告警规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 告警规则ID | - |

**返回**: `无`

---

#### GET /api/v1/alert/disks/list

**Handler**: `baseApi.GetDisks`  
**功能**: 获取磁盘列表  
**说明**: 获取所有可用的磁盘分区信息

**参数**: (无)

**返回**: `DiskDTO[]`

---

#### POST /api/v1/alert/logs/search

**Handler**: `baseApi.PageAlertLogs`  
**功能**: 分页查询告警日志  
**说明**: 获取告警记录日志，支持分页

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| count | uint | 否 | 告警次数 | - |
| status | string | 否 | 状态 | - |

**返回**: `PageResult{Total, Items}`

---

#### POST /api/v1/alert/logs/clean

**Handler**: `baseApi.CleanAlertLogs`  
**功能**: 清理告警日志  
**说明**: 清空所有告警日志记录

**参数**: (无)

**返回**: `无`

---

#### GET /api/v1/alert/clams/list

**Handler**: `baseApi.GetClams`  
**功能**: 获取Clam扫描规则列表  
**说明**: 获取所有已配置的ClamAV扫描规则

**参数**: (无)

**返回**: `ClamDTO[]`

---

#### POST /api/v1/alert/cronjob/list

**Handler**: `baseApi.GetCronJobs`  
**功能**: 获取定时任务列表  
**说明**: 获取可关联的定时任务列表

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 否 | 任务名称 | - |
| status | string | 否 | 任务状态 | - |
| type | string | 否 | 任务类型 | - |

**返回**: `CronJobDTO[]`

---

#### POST /api/v1/alert/config/update

**Handler**: `baseApi.UpdateAlertConfig`  
**功能**: 更新告警配置  
**说明**: 更新告警通道配置信息

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 配置ID | - |
| type | string | 否 | 配置类型 | - |
| title | string | 否 | 配置标题 | - |
| status | string | 否 | 状态 | - |
| config | string | 否 | 配置内容(JSON字符串) | - |

**返回**: `无`

---

#### POST /api/v1/alert/config/info

**Handler**: `baseApi.GetAlertConfig`  
**功能**: 获取告警配置  
**说明**: 获取当前告警通道配置信息

**参数**: (无)

**返回**: `AlertConfig`

---

#### POST /api/v1/alert/config/del

**Handler**: `baseApi.DeleteAlertConfig`  
**功能**: 删除告警配置  
**说明**: 删除指定的告警通道配置

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 配置ID | - |

**返回**: `无`

---

#### POST /api/v1/alert/config/test

**Handler**: `baseApi.TestAlertConfig`  
**功能**: 测试告警配置  
**说明**: 测试告警通道配置是否可用

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| host | string | 是 | 邮件服务器地址 | - |
| port | int | 是 | 端口号 | - |
| sender | string | 是 | 发件人邮箱 | - |
| userName | string | 是 | 用户名 | - |
| password | string | 是 | 密码 | - |
| displayName | string | 否 | 显示名称 | - |
| encryption | string | 是 | 加密方式 | `ssl`, `tls`, `none` |
| recipient | string | 是 | 收件人邮箱 | - |

**返回**: `bool` (测试是否成功)

---

### 二、ClamAV 病毒扫描模块

#### POST /api/v1/toolbox/clam

**Handler**: `baseApi.CreateClam`  
**功能**: 创建扫描规则  
**说明**: 创建新的ClamAV定时扫描规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 规则名称 | - |
| status | string | 否 | 状态 | - |
| path | string | 是 | 扫描路径 | - |
| infectedStrategy | string | 否 | 感染文件处理策略 | - |
| infectedDir | string | 否 | 隔离目录 | - |
| spec | string | 否 | Cron表达式 | - |
| timeout | uint | 否 | 超时时间(秒) | - |
| description | string | 否 | 描述 | - |
| alertCount | uint | 否 | 告警次数阈值 | - |
| alertTitle | string | 否 | 告警标题 | - |
| alertMethod | string | 否 | 告警方式 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/update

**Handler**: `baseApi.UpdateClam`  
**功能**: 更新扫描规则  
**说明**: 更新已有的ClamAV扫描规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 规则ID | - |
| name | string | 否 | 规则名称 | - |
| path | string | 否 | 扫描路径 | - |
| infectedStrategy | string | 否 | 感染文件处理策略 | - |
| infectedDir | string | 否 | 隔离目录 | - |
| spec | string | 否 | Cron表达式 | - |
| timeout | uint | 否 | 超时时间(秒) | - |
| description | string | 否 | 描述 | - |
| alertCount | uint | 否 | 告警次数阈值 | - |
| alertTitle | string | 否 | 告警标题 | - |
| alertMethod | string | 否 | 告警方式 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/status/update

**Handler**: `baseApi.UpdateClamStatus`  
**功能**: 更新扫描规则状态  
**说明**: 启用或禁用扫描规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 规则ID | - |
| status | string | 是 | 状态 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/search

**Handler**: `baseApi.SearchClam`  
**功能**: 分页查询扫描规则  
**说明**: 获取ClamAV扫描规则列表

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |
| orderBy | string | 是 | 排序字段 | `name`, `status`, `createdAt` |
| order | string | 是 | 排序方式 | `null`, `ascending`, `descending` |

**返回**: `PageResult{Total, Items}`

---

#### POST /api/v1/toolbox/clam/base

**Handler**: `baseApi.LoadClamBaseInfo`  
**功能**: 获取ClamAV基础信息  
**说明**: 获取ClamAV服务的基本状态信息

**参数**: (无)

**返回**: `ClamBaseInfo`

---

#### POST /api/v1/toolbox/clam/operate

**Handler**: `baseApi.OperateClam`  
**功能**: ClamAV服务操作  
**说明**: 启动、停止、重启ClamAV服务

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| operation | string | 是 | 操作类型 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/record/clean

**Handler**: `baseApi.CleanClamRecord`  
**功能**: 清理扫描记录  
**说明**: 清空指定扫描规则的记录

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 规则ID | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/record/search

**Handler**: `baseApi.SearchClamRecord`  
**功能**: 分页查询扫描记录  
**说明**: 获取ClamAV扫描历史记录

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| clamID | uint | 否 | 扫描规则ID | - |
| status | string | 否 | 扫描状态 | - |
| startTime | time.Time | 否 | 开始时间 | - |
| endTime | time.Time | 否 | 结束时间 | - |

**返回**: `PageResult{Total, Items}`

---

#### POST /api/v1/toolbox/clam/file/search

**Handler**: `baseApi.SearchClamFile`  
**功能**: 加载扫描日志文件  
**说明**: 读取ClamAV扫描日志内容

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| tail | string | 否 | 尾部行数 | - |
| name | string | 是 | 规则名称 | - |

**返回**: `string` (日志内容)

---

#### POST /api/v1/toolbox/clam/file/update

**Handler**: `baseApi.UpdateFile`  
**功能**: 更新扫描配置文件  
**说明**: 更新ClamAV配置文件内容

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 配置文件名 | - |
| file | string | 是 | 文件内容 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/del

**Handler**: `baseApi.DeleteClam`  
**功能**: 删除扫描规则  
**说明**: 删除指定的ClamAV扫描规则

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| removeInfected | bool | 否 | 是否删除感染文件 | - |
| ids | []uint | 是 | 规则ID列表 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/clam/handle

**Handler**: `baseApi.HandleClamScan`  
**功能**: 执行病毒扫描  
**说明**: 手动触发一次病毒扫描

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 规则ID | - |

**返回**: `无`

---

### 三、Fail2ban 防护模块

#### GET /api/v1/toolbox/fail2ban/base

**Handler**: `baseApi.LoadFail2BanBaseInfo`  
**功能**: 获取Fail2ban基础信息  
**说明**: 获取Fail2ban服务的基本状态和配置信息

**参数**: (无)

**返回**: `Fail2BanBaseInfo`

---

#### POST /api/v1/toolbox/fail2ban/search

**Handler**: `baseApi.SearchFail2Ban`  
**功能**: 查询IP封禁列表  
**说明**: 查询当前被封禁或忽略的IP列表

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| status | string | 是 | 查询类型 | `banned`(已封禁), `ignore`(已忽略) |

**返回**: `string[]` (IP列表)

---

#### POST /api/v1/toolbox/fail2ban/operate

**Handler**: `baseApi.OperateFail2Ban`  
**功能**: Fail2ban服务操作  
**说明**: 启动、停止、重启Fail2ban服务

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| operation | string | 是 | 操作类型 | - |

**返回**: `无`

---

#### POST /api/v1/toolbox/fail2ban/operate/sshd

**Handler**: `baseApi.OperateSSHD`  
**功能**: SSH防护操作  
**说明**: 对SSH服务进行封禁/解封IP操作

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| ips | []string | 否 | IP地址列表 | - |
| operate | string | 是 | 操作类型 | `banned`(封禁), `ignore`(解封) |

**返回**: `无`

---

#### POST /api/v1/toolbox/fail2ban/update

**Handler**: `baseApi.UpdateFail2BanConf`  
**功能**: 更新Fail2ban配置  
**说明**: 更新Fail2ban单个配置项

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| key | string | 是 | 配置键 | `port`, `bantime`, `findtime`, `maxretry`, `banaction`, `logpath` |
| value | string | 是 | 配置值 | - |

**返回**: `无`

---

#### GET /api/v1/toolbox/fail2ban/load/conf

**Handler**: `baseApi.LoadFail2BanConf`  
**功能**: 加载Fail2ban配置文件  
**说明**: 读取/etc/fail2ban/jail.local配置文件内容

**参数**: (无)

**返回**: `string` (配置文件内容)

---

#### POST /api/v1/toolbox/fail2ban/update/byconf

**Handler**: `baseApi.UpdateFail2BanConfByFile`  
**功能**: 通过配置文件更新  
**说明**: 使用完整配置文件内容更新Fail2ban配置

**参数**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| file | string | 是 | 配置文件内容 | - |

**返回**: `无`

---

## 使用说明

- 基础 URL: `http://<1panel-host>:10086/api/v1`
- 认证方式: API Key + Timestamp
- 请求 Content-Type: application/json


path: docs/SKILL-apps.md
content: # App - 1Panel API

## 模块说明
App 模块接口，提供应用商店和已安装应用的管理功能。

## 文件路径说明

### 已安装应用目录结构

1Panel 安装的应用会创建以下文件和目录：

| 路径类型 | 说明 | 计算方式 |
|----------|------|----------|
| **应用根目录** | 已安装应用的主目录 | `GetAppPath()` = `{应用安装目录}/{应用Key}/{应用名称}` |
| **网站根目录** | 网站静态文件存放目录 | `/opt/1panel/www/sites/{网站名称}/index` |
| **docker-compose.yml** | Docker Compose 配置文件 | `GetComposePath()` = `{应用根目录}/docker-compose.yml` |
| **.env** | 环境变量文件 | `GetEnvPath()` = `{应用根目录}/.env` |

### 源码中的路径计算方法

```go
// 获取应用根目录
func (i *AppInstall) GetAppPath() string {
    if i.App.Resource == "local" {
        // 本地应用
        return path.Join(本地应用安装目录, strings.TrimPrefix(i.App.Key, "local"))
    } else {
        // 远程/自定义应用
        return path.Join(应用安装目录, i.App.Key)
    }
}

// 获取 docker-compose.yml 路径
func (i *AppInstall) GetComposePath() string {
    return path.Join(i.GetAppPath(), i.Name, "docker-compose.yml")
}

// 获取 .env 文件路径
func (i *AppInstall) GetEnvPath() string {
    return path.Join(i.GetAppPath(), i.Name, ".env")
}
```

### 应用目录变量说明

| 变量 | 说明 |
|------|------|
| `应用安装目录` | 1Panel 配置的应用安装根目录（默认为 `/opt/1panel/apps/`） |
| `本地应用安装目录` | 1Panel 本地应用安装目录（默认为 `/opt/1panel/apps/local/`） |
| `应用Key` | 应用的唯一标识，如 `openresty`、`mysql`、`redis` 等 |
| `应用名称` | 用户安装时指定的名称 |

### 常见应用路径示例

| 应用 | Key | 安装名称 | 路径 |
|------|-----|----------|------|
| OpenResty | openresty | openresty | `/opt/1panel/apps/openresty/openresty` |
| 网站 | static | mywebsite | `/opt/1panel/www/sites/mywebsite/index` |
| MySQL | mysql | mysql | `/opt/1panel/apps/mysql/mysql` |
| Redis | redis | redis-cache | `/opt/1panel/apps/redis/redis-cache` |

### AppInstall 模型关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| Name | string | 应用安装名称（用户指定） |
| AppId | uint | 应用 ID |
| AppDetailId | uint | 应用详情 ID |
| Version | string | 安装版本 |
| ContainerName | string | 容器名称 |
| ServiceName | string | 服务名称 |
| HttpPort | int | HTTP 端口 |
| HttpsPort | int | HTTPS 端口 |
| Status | string | 运行状态 |

## 接口列表 (33 个)

---

### GET /apps/search
**功能**: 分页搜索应用列表
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| name | string | 否 | 应用名称（模糊搜索） | - |
| tags | []string | 否 | 标签列表 | - |
| type | string | 否 | 应用类型 | - |
| recommend | bool | 否 | 仅推荐应用 | - |
| resource | string | 否 | 资源类型 | - |
| showCurrentArch | bool | 否 | 显示当前架构支持 | - |

---

### GET /apps/sync/remote
**功能**: 同步远程应用商店列表
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| taskID | string | 否 | 异步任务 ID | - |

---

### GET /apps/sync/local
**功能**: 同步本地应用列表
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| taskID | string | 否 | 异步任务 ID | - |

---

### GET /apps/:key
**功能**: 根据 key 获取应用信息
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 应用唯一标识 key |

---

### GET /apps/tags
**功能**: 获取应用商店所有标签

---

### GET /apps/checkupdate
**功能**: 检查应用商店更新
**返回**: 应用商店是否有可用更新

---

### GET /apps/detail/:appId/:version/:type
**功能**: 根据应用 ID、版本和类型获取应用详情
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appId | int | 是 | 应用 ID |
| version | string | 是 | 应用版本 |
| type | string | 是 | 应用类型 |

---

### GET /apps/detail/node/:appKey/:version
**功能**: 根据应用 key 和版本获取应用详情（节点专用）
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appKey | string | 是 | 应用 key |
| version | string | 是 | 应用版本 |

---

### GET /apps/details/:id
**功能**: 根据应用详情 ID 获取应用详情
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 应用详情 ID |

---

### GET /apps/icon/:key
**功能**: 获取应用图标
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 应用 key |

---

### POST /apps/install
**功能**: 安装应用
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| appDetailId | uint | 是 | 应用详情 ID | > 0 |
| name | string | 是 | 安装名称 | - |
| params | map[string]interface{} | 否 | 应用参数 | - |
| services | map[string]string | 否 | 服务映射 | - |
| taskID | string | 否 | 任务 ID | - |
| advanced | bool | 否 | 高级选项 | - |
| cpuQuota | float64 | 否 | CPU 配额 (%) | 0-100 |
| memoryLimit | float64 | 否 | 内存限制 | > 0 |
| memoryUnit | string | 否 | 内存单位 | MB/GB |
| containerName | string | 否 | 容器名称 | - |
| allowPort | bool | 否 | 允许自动开放端口 | - |
| editCompose | bool | 否 | 编辑 Docker Compose | - |
| dockerCompose | string | 否 | Docker Compose 内容 | - |
| hostMode | bool | 否 | 主机网络模式 | - |
| pullImage | bool | 否 | 强制拉取镜像 | - |
| gpuConfig | bool | 否 | GPU 配置 | - |
| webUI | string | 否 | Web UI 地址 | - |
| type | string | 否 | 应用类型 | - |
| specifyIP | string | 否 | 指定出口 IP | - |
| restartPolicy | string | 否 | 重启策略 | always/unless-stopped/no/on-failure |
| nodes | []string | 否 | 节点列表 | - |
| pushNode | bool | 否 | 推送到节点 | - |
| appKey | string | 否 | 应用 key | - |
| version | string | 否 | 版本 | - |

---

### GET /apps/installed/search
**功能**: 分页搜索已安装应用
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | 1-100 |
| type | string | 否 | 应用类型 | - |
| name | string | 否 | 应用名称 | - |
| tags | []string | 否 | 标签列表 | - |
| update | bool | 否 | 检查更新 | - |
| unused | bool | 否 | 仅未使用 | - |
| all | bool | 否 | 返回所有（不分页） | - |
| sync | bool | 否 | 同步应用 | - |
| checkUpdate | bool | 否 | 检查更新状态 | - |

---

### GET /apps/installed/list
**功能**: 获取所有已安装应用列表

---

### POST /apps/installed/check
**功能**: 检查应用是否已安装
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 应用 key |
| name | string | 否 | 应用名称 |

---

### POST /apps/installed/loadport
**功能**: 获取应用端口
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | 名称 |
| type | string | 是 | 类型 |

---

### POST /apps/installed/conninfo
**功能**: 获取应用数据库连接信息
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | 名称 |
| type | string | 是 | 类型 |

---

### GET /apps/installed/delete/check/:appInstallId
**功能**: 删除前检查应用依赖
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appInstallId | int | 是 | 已安装应用 ID |

---

### POST /apps/installed/sync
**功能**: 同步已安装应用列表

---

### POST /apps/installed/op
**功能**: 操作已安装应用
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| installId | uint | 是 | 已安装应用 ID | > 0 |
| operate | string | 是 | 操作类型 | start/stop/restart/delete/sync/backup/update/rebuild/upgrade/reload/favorite |
| backupId | uint | 否 | 备份 ID | - |
| detailId | uint | 否 | 详情 ID | - |
| forceDelete | bool | 否 | 强制删除 | - |
| deleteBackup | bool | 否 | 删除关联备份 | - |
| deleteDB | bool | 否 | 删除关联数据库 | - |
| backup | bool | 否 | 操作前备份 | - |
| pullImage | bool | 否 | 强制拉取镜像 | - |
| dockerCompose | string | 否 | Docker Compose | - |
| taskID | string | 否 | 任务 ID | - |
| deleteImage | bool | 否 | 删除容器镜像 | - |
| favorite | bool | 否 | 收藏/取消收藏 | - |

---

### GET /apps/services/:key
**功能**: 获取应用关联服务
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 应用 key |

---

### POST /apps/installed/port/change
**功能**: 修改应用端口
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 否 | 应用 key |
| name | string | 否 | 应用名称 |
| port | int64 | 是 | 新端口 |

---

### POST /apps/installed/conf
**功能**: 获取应用默认配置
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | 名称 |
| type | string | 是 | 类型 |

---

### GET /apps/installed/params/:appInstallId
**功能**: 获取已安装应用的当前参数
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appInstallId | int | 是 | 已安装应用 ID |

---

### POST /apps/installed/params/update
**功能**: 修改已安装应用参数
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| installId | uint | 是 | 已安装应用 ID | > 0 |
| params | map[string]interface{} | 是 | 参数映射 | - |
| advanced | bool | 否 | 高级选项 | - |
| cpuQuota | float64 | 否 | CPU 配额 (%) | 0-100 |
| memoryLimit | float64 | 否 | 内存限制 | > 0 |
| memoryUnit | string | 否 | 内存单位 | MB/GB |
| containerName | string | 否 | 容器名称 | - |
| allowPort | bool | 否 | 允许开放端口 | - |
| editCompose | bool | 否 | 编辑 Compose | - |
| dockerCompose | string | 否 | Docker Compose | - |
| hostMode | bool | 否 | 主机模式 | - |
| pullImage | bool | 否 | 拉取镜像 | - |
| gpuConfig | bool | 否 | GPU 配置 | - |
| webUI | string | 否 | Web UI | - |
| type | string | 否 | 类型 | - |
| specifyIP | string | 否 | 指定 IP | - |
| restartPolicy | string | 否 | 重启策略 | always/unless-stopped/no/on-failure |

---

### POST /apps/installed/update/versions
**功能**: 获取应用可升级版本列表
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appInstallID | uint | 是 | 已安装应用 ID |
| updateVersion | string | 否 | 指定版本 |

---

### POST /apps/installed/config/update
**功能**: 更新应用配置（如 Web UI 地址）
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| installID | uint | 是 | 已安装应用 ID |
| webUI | string | 否 | Web UI 地址 |

---

### GET /apps/installed/info/:appInstallId
**功能**: 获取已安装应用详细信息
**参数 (Path)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appInstallId | int | 是 | 已安装应用 ID |

---

### POST /apps/installed/sort/update
**功能**: 更新已安装应用排序
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | []AppInstallSortItem | 是 | 排序项列表 |

**AppInstallSortItem**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| installID | uint | 是 | 已安装应用 ID |
| sortOrder | int | 是 | 排序顺序 |

---

### GET /apps/ignored/detail
**功能**: 获取忽略升级的应用列表

---

### POST /apps/installed/ignore
**功能**: 忽略应用升级
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| appID | uint | 是 | 应用 ID | > 0 |
| appDetailID | uint | 否 | 应用详情 ID | - |
| scope | string | 是 | 忽略范围 | all/version |

---

### POST /apps/ignored/cancel
**功能**: 取消忽略应用升级
**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 记录 ID |

---

## 枚举值参考

### AppOperate (应用操作类型)
| 值 | 说明 |
|-----|------|
| start | 启动 |
| stop | 停止 |
| restart | 重启 |
| delete | 删除 |
| sync | 同步 |
| backup | 备份 |
| update | 更新 |
| rebuild | 重建 |
| upgrade | 升级 |
| reload | 重载 |
| favorite | 收藏 |

### RestartPolicy (容器重启策略)
| 值 | 说明 |
|-----|------|
| always | 始终重启 |
| unless-stopped | 除非停止 |
| no | 不重启 |
| on-failure | 失败时重启 |

### Scope (忽略升级范围)
| 值 | 说明 |
|-----|------|
| all | 忽略所有版本 |
| version | 仅忽略当前版本 |


path: docs/SKILL-auth.md
content: # Auth - 1Panel API

## 模块说明
Auth 模块接口，包含验证码、用户登录、MFA 登录、Passkey 登录等功能。

## 接口列表 (7 个)

---

### GET /core/auth/captcha
**功能**: Load captcha - 获取验证码图片

**请求参数**: 无

**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| captchaID | string | 验证码 ID |
| imagePath | string | 验证码图片路径 |

---

### GET /core/auth/setting
**功能**: Get Setting For Login - 获取登录设置信息

**请求参数**: 无

**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| isDemo | boolean | 是否演示模式 |
| isIntl | boolean | 是否国际版 |
| isOffLine | boolean | 是否离线模式 |
| isFxplay | boolean | 是否 fxplay |
| language | string | 语言设置 |
| menuTabs | string | 菜单标签设置 |
| panelName | string | 面板名称 |
| theme | string | 主题 |
| needCaptcha | boolean | 是否需要验证码 |
| passkeySetting | boolean | Passkey 是否已配置 |

---

### POST /core/auth/login
**功能**: User login - 用户登录

**请求头参数**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| EntranceCode | string | 否 | 安全入口 base64 加密串 |

**请求体参数** (dto.Login):
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| name | string | 是 | 用户名 | validate:"required" |
| password | string | 是 | 密码 | validate:"required" |
| captcha | string | 否 | 验证码 (需要验证码时必填) | - |
| captchaID | string | 否 | 验证码 ID (需要验证码时必填) | - |
| language | string | 是 | 语言 | validate:"required,oneof=zh en 'zh-Hant' ko ja ru ms 'pt-BR' tr 'es-ES'" |

**返回参数** (dto.UserLoginInfo):
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 用户名 |
| token | string | 访问令牌 |
| mfaStatus | string | MFA 状态 (enable/disable) |

**语言取值范围**: `zh`, `en`, `zh-Hant`, `ko`, `ja`, `ru`, `ms`, `pt-BR`, `tr`, `es-ES`

---

### POST /core/auth/logout
**功能**: User logout - 用户登出

**请求参数**: 无 (需要登录认证)

**返回参数**: 无 (返回 200 表示成功)

---

### POST /core/auth/mfalogin
**功能**: User login with mfa - MFA 两步验证登录

**请求头参数**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| EntranceCode | string | 否 | 安全入口 base64 加密串 |

**请求体参数** (dto.MFALogin):
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| name | string | 是 | 用户名 | validate:"required" |
| password | string | 是 | 密码 | validate:"required" |
| code | string | 是 | MFA 验证码 | validate:"required" |

**返回参数** (dto.UserLoginInfo):
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 用户名 |
| token | string | 访问令牌 |
| mfaStatus | string | MFA 状态 |

---

### POST /core/auth/passkey/begin
**功能**: User login with passkey - Passkey 登录开始

**请求参数**: 无

**返回参数** (dto.PasskeyBeginResponse):
| 字段 | 类型 | 说明 |
|------|------|------|
| sessionId | string | Passkey 会话 ID |
| publicKey | object | Passkey 公钥对象 |

---

### POST /core/auth/passkey/finish
**功能**: User login with passkey - Passkey 登录完成

**请求头参数**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Passkey-Session | string | 是 | Passkey 会话 ID |

**请求参数**: 无 (使用 Passkey 凭证完成登录)

**返回参数** (dto.UserLoginInfo):
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 用户名 |
| token | string | 访问令牌 |
| mfaStatus | string | MFA 状态 |

---

## 相关 DTO 结构

### dto.CaptchaResponse
```go
type CaptchaResponse struct {
    CaptchaID string `json:"captchaID"`
    ImagePath string `json:"imagePath"`
}
```

### dto.UserLoginInfo
```go
type UserLoginInfo struct {
    Name      string `json:"name"`
    Token     string `json:"token"`
    MfaStatus string `json:"mfaStatus"`
}
```

### dto.Login
```go
type Login struct {
    Name      string `json:"name" validate:"required"`
    Password  string `json:"password" validate:"required"`
    Captcha   string `json:"captcha"`
    CaptchaID string `json:"captchaID"`
    Language  string `json:"language" validate:"required,oneof=zh en 'zh-Hant' ko ja ru ms 'pt-BR' tr 'es-ES'"`
}
```

### dto.MFALogin
```go
type MFALogin struct {
    Name     string `json:"name" validate:"required"`
    Password string `json:"password" validate:"required"`
    Code     string `json:"code" validate:"required"`
}
```

### dto.LoginSetting
```go
type LoginSetting struct {
    IsDemo         bool   `json:"isDemo"`
    IsIntl         bool   `json:"isIntl"`
    IsOffLine      bool   `json:"isOffLine"`
    IsFxplay       bool   `json:"isFxplay"`
    Language       string `json:"language"`
    MenuTabs       string `json:"menuTabs"`
    PanelName      string `json:"panelName"`
    Theme          string `json:"theme"`
    NeedCaptcha    bool   `json:"needCaptcha"`
    PasskeySetting bool   `json:"passkeySetting"`
}
```

### dto.PasskeyBeginResponse
```go
type PasskeyBeginResponse struct {
    SessionID string      `json:"sessionId"`
    PublicKey interface{} `json:"publicKey"`
}
```


path: docs/SKILL-backups.md
content: # Backup Account - 1Panel API

## 模块说明
Backup Account 模块接口，提供备份账号管理、备份/恢复操作、备份记录查询等功能。

## 接口列表 (25 个)

---

### GET /backups/local
**功能**: 获取本地备份目录

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| (string) | string | 本地备份目录路径 |

---

### GET /backups/options
**功能**: 加载备份账号选项列表

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | uint | 备份账号ID |
| name | string | 备份账号名称 |
| type | string | 备份类型 |
| isPublic | bool | 是否公开 |

---

### GET /backups/check/:name
**功能**: 检查备份账号是否被使用

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | ✓ | 备份账号名称 |

---

### POST /backups
**功能**: 创建备份账号

**请求参数** (BackupOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✓ | 备份存储类型 | S3, OSS, AWS-S3, Azure-blob, Google-GCS, Tencent-COS, Huawei-OBS, Kingsoft-KS3, Baidu-BOS, QingStor, MinIO, FTP, SFTP |
| name | string | - | 备份账号名称 | |
| isPublic | bool | - | 是否为公共存储 | true/false |
| bucket | string | - | 存储桶名称 | |
| accessKey | string | - | 访问密钥 | |
| credential | string | - | 访问凭证/密码 | |
| backupPath | string | - | 备份路径 | |
| vars | string | ✓ | 额外变量配置(JSON格式) | |
| rememberAuth | bool | - | 是否记住认证信息 | true/false |

---

### POSTbackup
**功能 /backups/**: 备份系统数据

**请求参数** (CommonBackup):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✓ | 备份数据类型 | app, mysql, mariadb, redis, website, postgresql, mysql-cluster, postgresql-cluster, redis-cluster |
| name | string | - | 备份名称 | |
| detailName | string | - | 详细名称(如应用名称/数据库名/网站名) | |
| secret | string | - | 解密密码 | |
| taskID | string | - | 任务ID | |
| fileName | string | - | 自定义文件名 | |
| args | []string | - | 额外参数 | |
| description | string | - | 备份描述 | |

---

### POST /backups/buckets
**功能**: 获取存储桶列表

**请求参数** (ForBuckets):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | ✓ | 存储类型 |
| accessKey | string | - | 访问密钥 |
| credential | string | ✓ | 访问凭证 |
| vars | string | ✓ | 额外变量配置 |

---

### POST /backups/check
**功能**: 检查备份账号连接

**请求参数** (BackupOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✓ | 备份存储类型 | S3, OSS, AWS-S3, Azure-blob, Google-GCS, Tencent-COS, Huawei-OBS, Kingsoft-KS3, Baidu-BOS, QingStor, MinIO, FTP, SFTP |
| name | string | - | 备份账号名称 | |
| isPublic | bool | - | 是否为公共存储 | true/false |
| bucket | string | - | 存储桶名称 | |
| accessKey | string | - | 访问密钥 | |
| credential | string | - | 访问凭证/密码 | |
| backupPath | string | - | 备份路径 | |
| vars | string | ✓ | 额外变量配置 | |
| rememberAuth | bool | - | 是否记住认证信息 | true/false |

**返回参数** (BackupCheckRes):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| isOk | bool | 连接是否成功 |
| msg | string | 检查消息 |
| token | string | 访问令牌 |

---

### POST /backups/del
**功能**: 删除备份账号

**请求参数** (OperateByID):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | ✓ | 备份账号ID |

---

### POST /backups/record/del
**功能**: 删除备份记录

**请求参数** (BatchDeleteReq):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | []uint | ✓ | 备份记录ID列表 |

---

### POST /backups/record/description/update
**功能**: 更新备份记录描述

**请求参数** (UpdateDescription):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | ✓ | 备份记录ID | |
| description | string | ✓ | 描述内容 | 最大256字符 |

---

### POST /backups/record/download
**功能**: 下载备份记录

**请求参数** (DownloadRecord):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| downloadAccountID | uint | ✓ | 下载账号ID |
| fileDir | string | ✓ | 文件目录 |
| fileName | string | ✓ | 文件名 |

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| (string) | string | 文件下载后的本地路径 |

---

### POST /backups/record/search
**功能**: 分页查询备份记录

**请求参数** (RecordSearch):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | ✓ | 页码 | |
| pageSize | int | ✓ | 每页数量 | |
| type | string | ✓ | 备份数据类型 | app, mysql, mariadb, redis, website, postgresql, mysql-cluster, postgresql-cluster, redis-cluster |
| name | string | - | 备份名称 | |
| detailName | string | - | 详细名称 | |

**返回参数** (BackupRecords):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | uint | 记录ID |
| createdAt | time.Time | 创建时间 |
| accountType | string | 账号类型 |
| accountName | string | 账号名称 |
| downloadAccountID | uint | 下载账号ID |
| fileDir | string | 文件目录 |
| fileName | string | 文件名 |
| taskID | string | 任务ID |
| status | string | 状态 |
| message | string | 消息 |
| description | string | 描述 |

---

### POST /backups/record/search/bycronjob
**功能**: 按定时任务查询备份记录

**请求参数** (RecordSearchByCronjob):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | ✓ | 页码 |
| pageSize | int | ✓ | 每页数量 |
| cronjobID | uint | ✓ | 定时任务ID |

**返回参数**: 同 POST /backups/record/search

---

### POST /backups/record/size
**功能**: 获取备份记录大小

**请求参数** (SearchForSize):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | ✓ | 页码 | |
| pageSize | int | ✓ | 每页数量 | |
| type | string | ✓ | 备份数据类型 | app, mysql, mariadb, redis, website, postgresql, mysql-cluster, postgresql-cluster, redis-cluster |
| name | string | - | 备份名称 | |
| detailName | string | - | 详细名称 | |
| info | string | - | 额外信息 | |
| cronjobID | uint | - | 定时任务ID | |
| orderBy | string | - | 排序字段 | |
| order | string | - | 排序方式 | asc/desc |

**返回参数** (RecordFileSize):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | uint | 记录ID |
| name | string | 文件名 |
| size | int64 | 文件大小(字节) |

---

### POST /backups/recover
**功能**: 恢复系统数据

**请求参数** (CommonRecover):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| downloadAccountID | uint | ✓ | 下载账号ID | |
| type | string | ✓ | 数据类型 | app, mysql, mariadb, redis, website, postgresql, mysql-cluster, postgresql-cluster, redis-cluster |
| name | string | - | 备份名称 | |
| detailName | string | - | 详细名称 | |
| file | string | - | 备份文件路径 | |
| secret | string | - | 解密密码 | |
| taskID | string | - | 任务ID | |
| backupRecordID | uint | - | 备份记录ID | |
| timeout | int | - | 超时时间(秒) | |

---

### POST /backups/recover/byupload
**功能**: 通过上传文件恢复数据

**请求参数** (CommonRecover):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| downloadAccountID | uint | ✓ | 下载账号ID | |
| type | string | ✓ | 数据类型 | app, mysql, mariadb, redis, website, postgresql, mysql-cluster, postgresql-cluster, redis-cluster |
| name | string | - | 备份名称 | |
| detailName | string | - | 详细名称 | |
| file | string | - | 备份文件路径 | |
| secret | string | - | 解密密码 | |
| taskID | string | - | 任务ID | |
| backupRecordID | uint | - | 备份记录ID | |
| timeout | int | - | 超时时间(秒) | |

---

### POST /backups/refresh/token
**功能**: 刷新存储访问令牌

**请求参数** (OperateByID):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | ✓ | 备份账号ID |

---

### POST /backups/search
**功能**: 分页查询备份账号

**请求参数** (SearchPageWithType):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | ✓ | 页码 |
| pageSize | int | ✓ | 每页数量 |
| info | string | - | 搜索关键词 |
| type | string | - | 备份账号类型 |

---

### POST /backups/search/files
**功能**: 从备份账号获取文件列表

**请求参数** (OperateByID):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | ✓ | 备份账号ID |

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| []string | []string | 文件路径列表 |

---

### POST /backups/update
**功能**: 更新备份账号

**请求参数** (BackupOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | - | 备份账号ID | |
| type | string | ✓ | 备份存储类型 | S3, OSS, AWS-S3, Azure-blob, Google-GCS, Tencent-COS, Huawei-OBS, Kingsoft-KS3, Baidu-BOS, QingStor, MinIO, FTP, SFTP |
| name | string | - | 备份账号名称 | |
| isPublic | bool | - | 是否为公共存储 | true/false |
| bucket | string | - | 存储桶名称 | |
| accessKey | string | - | 访问密钥 | |
| credential | string | - | 访问凭证/密码 | |
| backupPath | string | - | 备份路径 | |
| vars | string | ✓ | 额外变量配置 | |
| rememberAuth | bool | - | 是否记住认证信息 | true/false |

---

### POST /backups/upload
**功能**: 上传文件用于恢复

**请求参数** (UploadForRecover):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| filePath | string | - | 文件路径 |
| targetDir | string | - | 目标目录 |

---

### GET /core/backups/client/:clientType
**功能**: 加载备份账号基础信息

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| clientType | string | ✓ | 客户端类型 |

---

### POST /core/backups
**功能**: 创建备份账号 (Core)

---

### POST /core/backups/del
**功能**: 删除备份账号 (Core)

---

### POST /core/backups/refresh/token
**功能**: 刷新令牌 (Core)

---

### POST /core/backups/update
**功能**: 更新备份账号 (Core)

---

## 通用数据结构

### PageInfo
分页信息
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | ✓ | 页码 |
| pageSize | int | ✓ | 每页数量 |

### OperateByID
根据ID操作
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | ✓ | 记录ID |

### BatchDeleteReq
批量删除
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | []uint | ✓ | 记录ID列表 |

### UpdateDescription
更新描述
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | ✓ | 记录ID | |
| description | string | ✓ | 描述内容 | 最大256字符 |


path: docs/SKILL-containers.md
content: # Container, Container Compose, Container Compose-template, Container Docker, Container Image, Container Image-repo, Container Network, Container Volume - 1Panel API

## 模块说明
Container, Container Compose, Container Compose-template, Container Docker, Container Image, Container Image-repo, Container Network, Container Volume 模块接口

## 接口列表 (62 个)

---

### GET /containers/daemonjson
**功能**: Load docker daemon.json (获取 Docker 守护进程配置)

---

### GET /containers/daemonjson/file
**功能**: Load docker daemon.json file (获取 Docker 守护进程配置文件)

---

### GET /containers/docker/status
**功能**: Load docker status (获取 Docker 状态)
**参数**: 无

---

### GET /containers/image
**功能**: load images options (获取镜像选项列表)

---

### GET /containers/image/all
**功能**: List all images (列出所有镜像)

---

### GET /containers/network
**功能**: List networks (获取网络列表)

---

### GET /containers/repo
**功能**: List image repos (获取镜像仓库列表)

---

### GET /containers/search/log
**功能**: Container logs (获取容器日志 - 流式)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| container | string | 是 | 容器名称或ID | - |
| since | string | 否 | 时间筛选（Unix 时间戳） | - |
| follow | string | 否 | 是否追踪日志实时输出 | true/false |
| tail | string | 否 | 显示最后 N 行 | 数字，如 "100" |
| timestamp | string | 否 | 是否显示时间戳 | true/false |

---

### GET /containers/stats/:id
**功能**: Container stats (获取容器实时统计信息)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | string | 是 | 容器 ID（路径参数） | - |

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| cpuPercent | float64 | CPU 使用百分比 |
| memory | float64 | 内存使用量（字节） |
| cache | float64 | 缓存使用量（字节） |
| ioRead | float64 | 磁盘读取速度（字节/秒） |
| ioWrite | float64 | 磁盘写入速度（字节/秒） |
| networkRX | float64 | 网络接收速率（字节/秒） |
| networkTX | float64 | 网络发送速率（字节/秒） |
| shotTime | time | 统计时间 |

---

### GET /containers/status
**功能**: Load containers status (获取容器状态统计)

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| created | int | 已创建容器数量 |
| running | int | 运行中容器数量 |
| paused | int | 暂停容器数量 |
| restarting | int | 重启中容器数量 |
| removing | int | 删除中容器数量 |
| exited | int | 已退出容器数量 |
| dead | int | 死亡容器数量 |
| containerCount | int | 容器总数 |
| composeCount | int | Compose 项目数量 |
| composeTemplateCount | int | Compose 模板数量 |
| imageCount | int | 镜像数量 |
| networkCount | int | 网络数量 |
| volumeCount | int | 卷数量 |
| repoCount | int | 镜像仓库数量 |

---

### GET /containers/template
**功能**: List compose templates (获取 Compose 模板列表)

---

### GET /containers/volume
**功能**: List volumes (获取卷列表)

---

### GET /containers/limit
**功能**: Load container limits (获取容器资源限制)

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| cpu | int | CPU 核心数限制 |
| memory | uint64 | 内存限制（字节） |

---

### GET /containers/list/stats
**功能**: Load container stats list (获取容器统计列表)

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| []ContainerListStats | array | 容器统计列表 |

**ContainerListStats 结构**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| containerID | string | 容器 ID |
| cpuTotalUsage | uint64 | CPU 总使用量 |
| systemUsage | uint64 | 系统 CPU 使用量 |
| cpuPercent | float64 | CPU 使用百分比 |
| percpuUsage | int | 每 CPU 使用量 |
| memoryCache | uint64 | 内存缓存 |
| memoryUsage | uint64 | 内存使用量 |
| memoryLimit | uint64 | 内存限制 |
| memoryPercent | float64 | 内存使用百分比 |

---

### GET /containers/network
**功能**: List networks (获取网络列表)

---

### GET /containers/image/all
**功能**: List all images (获取所有镜像列表)

---

### GET /containers/repo
**功能**: List image repos (获取镜像仓库列表)

---

### POST /containers
**功能**: Create container (创建容器)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID（异步任务） | - |
| name | string | 是 | 容器名称 | - |
| image | string | 是 | 镜像名称 | - |
| hostname | string | 否 | 主机名 | - |
| domainName | string | 否 | 域名 | - |
| dns | []string | 否 | DNS 服务器列表 | - |
| networks | []ContainerNetwork | 否 | 网络配置 | - |
| publishAllPorts | bool | 否 | 发布所有端口 | true/false |
| exposedPorts | []PortHelper | 否 | 暴露端口列表 | - |
| tty | bool | 否 | 分配伪终端 | true/false |
| openStdin | bool | 否 | 打开标准输入 | true/false |
| workingDir | string | 否 | 工作目录 | - |
| user | string | 否 | 用户名/UID | - |
| cmd | []string | 否 | 启动命令 | - |
| entrypoint | []string | 否 | 入口点 | - |
| cpuShares | int64 | 否 | CPU 权重 | - |
| nanoCPUs | float64 | 否 | CPU 核心数 | - |
| memory | float64 | 否 | 内存限制（字节） | - |
| privileged | bool | 否 | 特权模式 | true/false |
| autoRemove | bool | 否 | 容器退出时自动删除 | true/false |
| volumes | []VolumeHelper | 否 | 卷挂载配置 | - |
| labels | []string | 否 | 标签列表 | - |
| env | []string | 否 | 环境变量 | - |
| restartPolicy | string | 否 | 重启策略 | no, always, on-failure, unless-stopped |

**ContainerNetwork 结构**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| network | string | 是 | 网络名称 | - |
| ipv4 | string | 否 | IPv4 地址 | - |
| ipv6 | string | 否 | IPv6 地址 | - |
| macAddr | string | 否 | MAC 地址 | - |

**VolumeHelper 结构**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 卷类型 | bind, volume |
| sourceDir | string | 否 | 主机目录（bind 类型） | - |
| containerDir | string | 是 | 容器内目录 | - |
| mode | string | 否 | 挂载模式 | ro, rw |
| shared | string | 否 | 共享模式 | - |

**PortHelper 结构**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| hostIP | string | 否 | 主机 IP | - |
| hostPort | string | 是 | 主机端口 | - |
| containerPort | string | 是 | 容器端口 | - |
| protocol | string | 否 | 协议 | tcp, udp |

---

### POST /containers/update
**功能**: Update container (更新容器配置)
**参数**: 同 POST /containers（创建容器参数）

---

### POST /containers/upgrade
**功能**: Upgrade container (升级容器镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| names | []string | 是 | 容器名称列表 | - |
| image | string | 是 | 新镜像名称 | - |
| forcePull | bool | 否 | 强制拉取镜像 | true/false |

---

### POST /containers/search
**功能**: Page containers (分页查询容器)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| name | string | 否 | 容器名称筛选 | - |
| state | string | 否 | 容器状态筛选 | all, created, running, paused, restarting, removing, exited, dead |
| orderBy | string | 是 | 排序字段 | name, createdAt, state |
| order | string | 是 | 排序方式 | null, ascending, descending |
| filters | string | 否 | 筛选条件 | - |
| excludeAppStore | bool | 否 | 排除应用商店容器 | true/false |

---

### POST /containers/list
**功能**: List containers (获取容器列表)

---

### POST /containers/list/byimage
**功能**: List containers by image (根据镜像获取容器列表)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 镜像名称 | - |

---

### POST /containers/info
**功能**: Load container info (获取容器详细信息)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 容器名称 | - |

---

### POST /containers/inspect
**功能**: Container inspect (容器深度检查)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | string | 是 | 容器 ID 或名称 | - |
| type | string | 是 | 检查类型 | - |
| detail | string | 否 | 详情 | - |

---

### POST /containers/operate
**功能**: Operate Container (容器操作：启动/停止/重启/删除等)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| names | []string | 是 | 容器名称列表 | - |
| operation | string | 是 | 操作类型 | up, start, stop, restart, kill, pause, unpause, remove |

---

### POST /containers/prune
**功能**: Clean container (清理容器/镜像/卷/网络)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| pruneType | string | 是 | 清理类型 | container, image, volume, network, buildcache |
| withTagAll | bool | 否 | 是否清理所有标签的镜像 | true/false |

---

### POST /containers/rename
**功能**: Rename Container (重命名容器)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 当前容器名称 | - |
| newName | string | 是 | 新容器名称 | - |

---

### POST /containers/commit
**功能**: Commit Container (将容器提交为镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| containerID | string | 是 | 容器 ID | - |
| containerName | string | 否 | 容器名称 | - |
| newImageName | string | 否 | 新镜像名称 | - |
| comment | string | 否 | 镜像注释 | - |
| author | string | 否 | 作者 | - |
| pause | bool | 否 | 提交前是否暂停容器 | true/false |
| taskID | string | 否 | 任务 ID | - |

---

### POST /containers/clean/log
**功能**: Clean container log (清理容器日志)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 容器名称 | - |

---

### POST /containers/download/log
**功能**: Download container logs (下载容器日志)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| container | string | 是 | 容器名称 | - |
| since | string | 否 | 时间筛选（Unix 时间戳） | - |
| tail | uint | 否 | 显示最后 N 行 | - |
| timestamp | bool | 否 | 是否包含时间戳 | true/false |
| containerType | string | 否 | 容器类型 | - |

---

### POST /containers/users
**功能**: Load container users (获取容器用户列表)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 容器名称 | - |

---

### POST /containers/item/stats
**功能**: Load container stats size (获取容器存储统计)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 容器名称 | - |

**返回参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| sizeRw | int64 | 读写层大小 |
| sizeRootFs | int64 | 根文件系统大小 |
| containerUsage | int64 | 容器使用空间 |
| containerReclaimable | int64 | 容器可回收空间 |
| imageUsage | int64 | 镜像使用空间 |
| imageReclaimable | int64 | 镜像可回收空间 |
| volumeUsage | int64 | 卷使用空间 |
| volumeReclaimable | int64 | 卷可回收空间 |
| buildCacheUsage | int64 | 构建缓存使用空间 |
| buildCacheReclaimable | int64 | 构建缓存可回收空间 |

---

### POST /containers/network/search
**功能**: Page networks (分页查询网络)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

---

### POST /containers/network
**功能**: Create network (创建网络)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 网络名称 | - |
| driver | string | 是 | 网络驱动 | bridge, host, overlay, macvlan 等 |
| options | []string | 否 | 网络选项 | - |
| ipv4 | bool | 否 | 是否启用 IPv4 | true/false |
| subnet | string | 否 | IPv4 子网（如 172.17.0.0/16） | - |
| gateway | string | 否 | IPv4 网关 | - |
| ipRange | string | 否 | IPv4 地址范围 | - |
| auxAddress | []SettingUpdate | 否 | 辅助地址 | - |
| ipv6 | bool | 否 | 是否启用 IPv6 | true/false |
| subnetV6 | string | 否 | IPv6 子网 | - |
| gatewayV6 | string | 否 | IPv6 网关 | - |
| ipRangeV6 | string | 否 | IPv6 地址范围 | - |
| auxAddressV6 | []SettingUpdate | 否 | IPv6 辅助地址 | - |
| labels | []string | 否 | 标签 | - |

**SettingUpdate 结构**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | 是 | 键 | - |
| value | string | 是 | 值 | - |

---

### POST /containers/network/del
**功能**: Delete network (删除网络)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| force | bool | 否 | 强制删除 | true/false |
| names | []string | 是 | 网络名称列表 | - |

---

### POST /containers/volume/search
**功能**: Page volumes (分页查询卷)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

---

### POST /containers/volume
**功能**: Create volume (创建卷)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 卷名称 | - |
| driver | string | 是 | 卷驱动 | local, etc. |
| options | []string | 否 | 卷选项 | - |
| labels | []string | 否 | 标签 | - |

---

### POST /containers/volume/del
**功能**: Delete volume (删除卷)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| force | bool | 否 | 强制删除 | true/false |
| names | []string | 是 | 卷名称列表 | - |

---

### POST /containers/image/search
**功能**: Page images (分页查询镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| name | string | 否 | 镜像名称筛选 | - |
| orderBy | string | 是 | 排序字段 | size, tags, createdAt, isUsed |
| order | string | 是 | 排序方式 | null, ascending, descending |

---

### POST /containers/image/pull
**功能**: Pull image (拉取镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| repoID | uint | 否 | 仓库 ID | - |
| imageName | []string | 是 | 镜像名称列表 | - |

---

### POST /containers/image/push
**功能**: Push image (推送镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| repoID | uint | 是 | 目标仓库 ID | - |
| tagName | string | 是 | 镜像标签 | - |
| name | string | 是 | 镜像名称 | - |

---

### POST /containers/image/remove
**功能**: Delete image (删除镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| names | []string | 是 | 镜像名称/ID 列表 | - |

---

### POST /containers/image/tag
**功能**: Tag image (标记镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| sourceID | string | 是 | 源镜像 ID | - |
| tags | []string | 是 | 新标签列表 | - |

---

### POST /containers/image/build
**功能**: Build image (构建镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| from | string | 是 | 基础镜像 | - |
| name | string | 是 | 镜像名称 | - |
| dockerfile | string | 是 | Dockerfile 内容 | - |
| tags | []string | 否 | 镜像标签 | - |
| args | []string | 否 | 构建参数 | - |

---

### POST /containers/image/save
**功能**: Save image (导出镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| tagName | string | 是 | 镜像标签 | - |
| path | string | 是 | 保存路径 | - |
| name | string | 是 | 镜像名称 | - |

---

### POST /containers/image/load
**功能**: Load image (导入镜像)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| paths | []string | 是 | 镜像文件路径列表 | - |

---

### POST /containers/compose/search
**功能**: Page composes (分页查询 Compose 项目)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

---

### POST /containers/compose
**功能**: Create compose (创建 Compose 项目)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| name | string | 是 | 项目名称 | - |
| from | string | 是 | 来源类型 | edit, path, template |
| file | string | 否 | Compose 文件内容 | - |
| path | string | 否 | Compose 文件路径 | - |
| template | uint | 否 | 模板 ID | - |
| env | string | 否 | 环境变量内容 | - |
| forcePull | bool | 否 | 强制拉取镜像 | true/false |

---

### POST /containers/compose/test
**功能**: Test compose (测试 Compose 配置)
**参数**: 同 POST /containers/compose

---

### POST /containers/compose/operate
**功能**: Operate compose (Compose 项目操作)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 项目名称 | - |
| path | string | 否 | 项目路径 | - |
| operation | string | 是 | 操作类型 | up, start, restart, stop, down, delete |
| withFile | bool | 否 | 是否使用 .env 文件 | true/false |
| force | bool | 否 | 强制操作 | true/false |

---

### POST /containers/compose/update
**功能**: Update compose (更新 Compose 项目)
**参数**:
| 参数名 | 类型 | 必填 |说明 | 取值范围 |
|--------|------|------|------|----------|
| taskID | string | 否 | 任务 ID | - |
| name | string | 是 | 项目名称 | - |
| path | string | 是 | 项目路径 | - |
| detailPath | string | 否 | 详情路径 | - |
| content | string | 是 | Compose 文件内容 | - |
| env | string | 否 | 环境变量内容 | - |
| forcePull | bool | 否 | 强制拉取镜像 | true/false |

---

### POST /containers/compose/env
**功能**: Load compose environment variables (加载 Compose 环境变量)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | Compose 项目路径 | - |

---

### POST /containers/compose/clean/log
**功能**: Clean compose log (清理 Compose 日志)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 项目名称 | - |
| path | string | 是 | 项目路径 | - |
| detailPath | string | 否 | 详情路径 | - |

---

### POST /containers/template/search
**功能**: Page compose templates (分页查询 Compose 模板)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

---

### POST /containers/template
**功能**: Create compose template (创建 Compose 模板)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 模板名称 | - |
| description | string | 否 | 模板描述 | - |
| content | string | 否 | 模板内容 | - |

---

### POST /containers/template/update
**功能**: Update compose template (更新 Compose 模板)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 模板 ID | - |
| description | string | 否 | 模板描述 | - |
| content | string | 否 | 模板内容 | - |

---

### POST /containers/template/del
**功能**: Delete compose template (删除 Compose 模板)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| ids | []uint | 是 | 模板 ID 列表 | - |

---

### POST /containers/template/batch
**功能**: Batch compose template (批量创建模板)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| templates | []ComposeTemplateCreate | 是 | 模板列表 | - |

**ComposeTemplateCreate 结构**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 模板名称 | - |
| description | string | 否 | 模板描述 | - |
| content | string | 否 | 模板内容 | - |

---

### POST /containers/repo/search
**功能**: Page image repos (分页查询镜像仓库)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

---

### POST /containers/repo
**功能**: Create image repo (创建镜像仓库)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 仓库名称 | - |
| downloadUrl | string | 否 | 下载 URL | - |
| protocol | string | 否 | 协议 | http, https |
| username | string | 否 | 用户名 | - |
| password | string | 否 | 密码 | - |
| auth | bool | 否 | 是否启用认证 | true/false |

---

### POST /containers/repo/update
**功能**: Update image repo (更新镜像仓库)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 仓库 ID | - |
| downloadUrl | string | 否 | 下载 URL | - |
| protocol | string | 否 | 协议 | http, https |
| username | string | 否 | 用户名 | - |
| password | string | 否 | 密码 | - |
| auth | bool | 否 | 是否启用认证 | true/false |

---

### POST /containers/repo/del
**功能**: Delete image repo (删除镜像仓库)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| ids | []uint | 是 | 仓库 ID 列表 | - |

---

### POST /containers/repo/status
**功能**: Load repo status (获取仓库状态)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 仓库 ID | - |

---

### POST /containers/docker/operate
**功能**: Operate docker (操作 Docker 服务)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | 是 | 操作类型 | start, restart, stop |

---

### POST /containers/daemonjson/update
**功能**: Update docker daemon.json (更新 Docker 守护进程配置)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| isSwarm | bool | 否 | 是否启用 Swarm | true/false |
| version | string | 否 | Docker 版本 | - |
| registryMirrors | []string | 否 | 镜像加速器列表 | - |
| insecureRegistries | []string | 否 | 非安全仓库列表 | - |
| liveRestore | bool | 否 | 容器退出时保持运行 | true/false |
| iptables | bool | 否 | 是否启用 iptables | true/false |
| cgroupDriver | string | 否 | Cgroup 驱动 | cgroupfs, systemd |
| ipv6 | bool | 否 | 是否启用 IPv6 | true/false |
| fixedCidrV6 | string | 否 | IPv6 固定 CIDR | - |
| ip6Tables | bool | 否 | 是否启用 ip6tables | true/false |
| experimental | bool | 否 | 是否启用实验特性 | true/false |
| logMaxSize | string | 否 | 日志最大大小 | - |
| logMaxFile | string | 否 | 日志最大文件数 | - |

---

### POST /containers/daemonjson/update/byfile
**功能**: Update docker daemon.json by upload file (通过文件更新 Docker 配置)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| file | string | 是 | 配置文件内容 | - |

---

### POST /containers/logoption/update
**功能**: Update docker daemon.json log option (更新 Docker 日志配置)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| logMaxSize | string | 否 | 单个日志文件最大大小 | - |
| logMaxFile | string | 否 | 最多保留的日志文件数 | - |

---

### POST /containers/ipv6option/update
**功能**: Update docker daemon.json ipv6 option (更新 Docker IPv6 配置)
**参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| fixedCidrV6 | string | 否 | IPv6 固定 CIDR | - |
| ip6Tables | bool | 是 | 是否启用 ip6tables | true/false |
| experimental | bool | 否 | 是否启用实验特性 | true/false |

---

### GET /containers/exec
**功能**: Container SSH WebSocket (容器 SSH WebSocket 连接)
**参数**: 通过 WebSocket 协议

---



path: docs/SKILL-cronjobs.md
content: # Cronjob - 1Panel API

## 模块说明
Cronjob 模块接口，用于管理定时任务（计划任务）

## 接口列表 (16 个)

---

### GET /cronjobs/script/options
**功能**: 获取脚本选项列表  
**说明**: 获取所有可用的脚本名称和 ID，用于创建定时任务时选择脚本  
**参数**: 无

**返回示例**:
```json
[
  {"id": 1, "name": "backup-script"},
  {"id": 2, "name": "cleanup-script"}
]
```

---

### POST /cronjobs
**功能**: 创建定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | 定时任务名称 | 最大 256 字符 |
| type | string | 是 | 定时任务类型 | 参见下方类型说明 |
| groupID | uint | 否 | 分组 ID | |
| specCustom | bool | 否 | 是否自定义执行时间 | true/false |
| spec | string | 是 | 执行时间规则 | cron 表达式 |
| executor | string | 否 | 执行器类型 | shell/php/python/node |
| scriptMode | string | 否 | 脚本模式 | script/scriptUrl |
| script | string | 否 | 脚本内容 | |
| command | string | 否 | 执行命令 | |
| containerName | string | 否 | 容器名称 | 用于容器执行 |
| user | string | 否 | 执行用户 | |
| scriptID | uint | 否 | 脚本 ID | 关联脚本市场中的脚本 |
| appID | string | 否 | 应用 ID | 用于应用备份 |
| website | string | 否 | 网站名称 | 用于网站备份 |
| exclusionRules | string | 否 | 排除规则 | JSON 格式的排除规则 |
| dbType | string | 否 | 数据库类型 | mysql/postgres/mongodb/redis/mariadb |
| dbName | string | 否 | 数据库名称 | |
| url | string | 否 | URL 地址 | 用于 HTTP 请求任务 |
| isDir | bool | 否 | 是否目录 | |
| sourceDir | string | 否 | 源目录 | |
| withImage | bool | 否 | 是否包含镜像 | 快照规则 |
| ignoreAppIDs | []uint | 否 | 忽略的应用 ID | 快照规则 |
| sourceAccountIDs | string | 否 | 源账户 IDs | 多个用逗号分隔 |
| downloadAccountID | uint | 否 | 下载账户 ID | |
| retainCopies | int | 否 | 保留副本数 | 最小 1 |
| retryTimes | int | 否 | 重试次数 | 最小 0 |
| timeout | uint | 否 | 超时时间(秒) | 最小 1 |
| ignoreErr | bool | 否 | 是否忽略错误 | |
| secret | string | 否 | 密钥 | |
| args | string | 否 | 额外参数 | |
| alertCount | uint | 否 | 告警次数 | |
| alertTitle | string | 否 | 告警标题 | |
| alertMethod | string | 否 | 告警方式 | |
| scopes | []string | 否 | 清理日志范围 | |

**定时任务类型 (type)**:
- `backup` - 备份任务
- `restore` - 恢复任务
- `shell` - Shell 脚本
- `website` - 网站任务
- `database` - 数据库任务
- `directory` - 目录任务
- `log` - 日志清理
- `docker` - Docker 任务
- `snapshot` - 快照任务
- `image` - 镜像任务
- `httptest` - HTTP 测试
- `record` - 录制任务

---

### POST /cronjobs/next
**功能**: 计算下次执行时间  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| spec | string | 是 | cron 表达式 | 标准 cron 格式 |

**返回示例**:
```json
["2024-01-15 10:00:00", "2024-01-15 11:00:00"]
```

---

### POST /cronjobs/import
**功能**: 导入定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cronjobs | []CronjobTrans | 是 | 定时任务列表 |

**CronjobTrans 结构**:

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 任务名称 |
| type | string | 任务类型 |
| groupID | uint | 分组 ID |
| specCustom | bool | 是否自定义时间 |
| spec | string | 执行规则 |
| executor | string | 执行器 |
| scriptMode | string | 脚本模式 |
| script | string | 脚本内容 |
| command | string | 执行命令 |
| containerName | string | 容器名称 |
| user | string | 执行用户 |
| url | string | URL |
| scriptName | string | 脚本名称 |
| apps | []TransHelper | 应用列表 |
| websites | []string | 网站列表 |
| dbType | string | 数据库类型 |
| dbNames | []TransHelper | 数据库名称列表 |
| exclusionRules | string | 排除规则 |
| isDir | bool | 是否目录 |
| sourceDir | string | 源目录 |
| retainCopies | uint64 | 保留副本数 |
| retryTimes | uint | 重试次数 |
| timeout | uint | 超时时间 |
| ignoreErr | bool | 忽略错误 |
| snapshotRule | SnapshotTransHelper | 快照规则 |
| secret | string | 密钥 |
| args | string | 额外参数 |
| sourceAccounts | []string | 源账户 |
| downloadAccount | string | 下载账户 |
| alertCount | uint | 告警次数 |
| alertTitle | string | 告警标题 |
| alertMethod | string | 告警方式 |

---

### POST /cronjobs/export
**功能**: 导出定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | []uint | 是 | 要导出的定时任务 ID 列表 |

**返回**: JSON 格式的定时任务列表（文件下载）

---

### POST /cronjobs/load/info
**功能**: 获取定时任务详情  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 定时任务 ID |

**返回**: CronjobInfo 对象，包含任务完整配置信息

---

### POST /cronjobs/del
**功能**: 删除定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | []uint | 是 | 要删除的定时任务 ID 列表 |
| cleanData | bool | 否 | 是否清理关联数据 |
| cleanRemoteData | bool | 否 | 是否清理远程数据 |

---

### POST /cronjobs/stop
**功能**: 停止正在执行的定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 定时任务 ID |

---

### POST /cronjobs/update
**功能**: 更新定时任务  
**参数 (body)**: 同创建接口 (POST /cronjobs)，需额外提供 id 字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 定时任务 ID |

**其他字段**: 同创建接口

---

### POST /cronjobs/group/update
**功能**: 更新定时任务分组  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 定时任务 ID |
| groupID | uint | 是 | 新的分组 ID |

---

### POST /cronjobs/status
**功能**: 更新定时任务状态  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 定时任务 ID | |
| status | string | 是 | 任务状态 | running/stopped |

---

### POST /cronjobs/handle
**功能**: 手动执行一次定时任务  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 定时任务 ID |

---

### POST /cronjobs/search
**功能**: 分页查询定时任务列表  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | |
| pageSize | int | 是 | 每页数量 | |
| info | string | 否 | 搜索关键词 | |
| groupIDs | []uint | 否 | 分组 ID 列表 | |
| orderBy | string | 否 | 排序字段 | name/status/createdAt |
| order | string | 否 | 排序方向 | null/ascending/descending |

**返回**: 分页结果，包含 Items (任务列表) 和 Total (总数)

---

### POST /cronjobs/search/records
**功能**: 分页查询执行记录  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 是 | 页码 |
| pageSize | int | 是 | 每页数量 |
| cronjobID | int | 否 | 定时任务 ID |
| startTime | time | 否 | 开始时间 |
| endTime | time | 否 | 结束时间 |
| status | string | 否 | 执行状态 |

**返回**: 分页结果，包含执行记录列表

---

### POST /cronjobs/records/log
**功能**: 获取执行记录日志  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 执行记录 ID |

**返回**: 日志内容 (string)

---

### POST /cronjobs/records/clean
**功能**: 清理执行记录  
**参数 (body)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cronjobID | uint | 是 | 定时任务 ID |
| isDelete | bool | 否 | 是否删除记录 |
| cleanData | bool | 否 | 是否清理数据 |
| cleanRemoteData | bool | 否 | 是否清理远程数据 |

---

## 数据结构参考

### SnapshotRule (快照规则)
```json
{
  "withImage": true,
  "ignoreAppIDs": [1, 2, 3]
}
```

### CleanLogConfig (日志清理配置)
```json
{
  "scopes": ["log", "backup"]
}
```

### CronjobInfo 返回字段
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 任务 ID |
| name | string | 任务名称 |
| type | string | 任务类型 |
| groupID | uint | 分组 ID |
| specCustom | bool | 是否自定义 |
| spec | string | 执行规则 |
| executor | string | 执行器 |
| scriptMode | string | 脚本模式 |
| script | string | 脚本内容 |
| command | string | 执行命令 |
| containerName | string | 容器名称 |
| user | string | 执行用户 |
| scriptID | uint | 脚本 ID |
| appID | string | 应用 ID |
| website | string | 网站名称 |
| exclusionRules | string | 排除规则 |
| dbType | string | 数据库类型 |
| dbName | string | 数据库名称 |
| url | string | URL 地址 |
| isDir | bool | 是否目录 |
| sourceDir | string | 源目录 |
| retainCopies | int | 保留副本 |
| retryTimes | int | 重试次数 |
| timeout | uint | 超时时间 |
| ignoreErr | bool | 忽略错误 |
| sourceAccounts | []string | 源账户列表 |
| downloadAccount | string | 下载账户 |
| lastRecordStatus | string | 上次执行状态 |
| lastRecordTime | string | 上次执行时间 |
| status | string | 当前状态 |
| secret | string | 密钥 |
| args | string | 额外参数 |
| alertCount | uint | 告警次数 |

### Record 执行记录字段
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 记录 ID |
| taskID | string | 任务 ID |
| startTime | string | 开始时间 |
| records | string | 记录内容 |
| status | string | 执行状态 |
| message | string | 消息 |
| targetPath | string | 目标路径 |
| interval | int | 间隔 |
| file | string | 文件 |


path: docs/SKILL-dashboard.md
content: # Dashboard - 1Panel API

## 模块说明
Dashboard 模块提供系统仪表盘相关功能，包括系统信息加载、应用启动器管理、快速跳转配置、实时监控数据获取等。

## 接口列表 (12 个)

---

### GET /dashboard/base/os
**功能**: Load OS information (获取操作系统基本信息)

**请求参数**: 无

**返回参数** (`OsInfo`):
| 字段 | 类型 | 说明 |
|------|------|------|
| OS | string | 操作系统名称 |
| platform | string | 平台 |
| platformFamily | string | 平台家族 |
| kernelArch | string | 内核架构 |
| kernelVersion | string | 内核版本 |
| prettyDistro | string | 发行版名称 |
| diskSize | int64 | 磁盘大小(字节) |

---

### GET /dashboard/quick/option
**功能**: Load quick jump options (获取快速跳转选项列表)

**请求参数**: 无

**返回参数** (`QuickJump[]`):
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 跳转项ID |
| name | string | 名称 |
| alias | string | 别名 |
| title | string | 显示标题 |
| detail | string | 详情描述 |
| recommend | int | 推荐级别 |
| isShow | bool | 是否显示 |
| router | string | 路由地址 |

---

### POST /dashboard/quick/change
**功能**: Update quick jump (更新快速跳转配置)

**请求参数** (`ChangeQuicks`):
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| quicks | []QuickJump | 是 | 快速跳转项列表 |

**QuickJump 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 跳转项ID |
| name | string | 名称 |
| alias | string | 别名 |
| title | string | 显示标题 |
| detail | string | 详情描述 |
| recommend | int | 推荐级别 (0=不推荐, 1=推荐) |
| isShow | bool | 是否显示 |
| router | string | 路由地址 |

**返回**: 操作成功返回 200

---

### GET /dashboard/app/launcher
**功能**: Load app launcher (获取应用启动器列表)

**请求参数**: 无

**返回参数** (`AppLauncher[]`):
| 字段 | 类型 | 说明 |
|------|------|------|
| key | string | 启动器唯一标识 |
| type | string | 类型 |
| name | string | 名称 |
| icon | string | 图标路径 |
| limit | int | 限制数量 |
| description | string | 描述 |
| recommend | int | 推荐级别 |
| isInstall | bool | 是否已安装 |
| isRecommend | bool | 是否推荐 |
| detail | []InstallDetail | 详细信息列表 |

**InstallDetail 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| installID | uint | 安装ID |
| detailID | uint | 详情ID |
| name | string | 名称 |
| version | string | 版本 |
| path | string | 安装路径 |
| status | string | 状态 |
| webUI | string | Web界面地址 |
| httpPort | int | HTTP端口 |
| httpsPort | int | HTTPS端口 |

---

### POST /dashboard/app/launcher/show
**功能**: Update app Launcher (更新应用启动器显示配置)

**请求参数** (`SettingUpdate`):
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 设置键 (如: "app_launcher_xxx") |
| value | string | 否 | 设置值 (如: "true"/"false") |

**返回**: 操作成功返回 200

**日志记录**: 记录 key 和 value 的变更

---

### POST /dashboard/app/launcher/option
**功能**: Load app launcher options (获取应用启动器选项列表)

**请求参数** (`SearchByFilter`):
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| filter | string | 否 | 过滤条件 |

**返回参数** (`LauncherOption[]`):
| 字段 | 类型 | 说明 |
|------|------|------|
| key | string | 启动器标识 |
| isShow | bool | 是否显示 |

---

### GET /dashboard/base/:ioOption/:netOption
**功能**: Load dashboard base info (获取仪表盘基础信息)

**路径参数**:
| 参数 | 类型 | 必填 | 说明 | 取值示例 |
|------|------|------|------|----------|
| ioOption | string | 是 | IO选项，指定磁盘 | "sda", "sdb", "all" |
| netOption | string | 是 | 网络选项，指定网卡 | "eth0", "ens33", "all" |

**返回参数** (`DashboardBase`):
| 字段 | 类型 | 说明 |
|------|------|------|
| websiteNumber | int | 网站数量 |
| databaseNumber | int | 数据库数量 |
| cronjobNumber | int | 定时任务数量 |
| appInstalledNumber | int | 已安装应用数量 |
| hostname | string | 主机名 |
| os | string | 操作系统 |
| platform | string | 平台 |
| platformFamily | string | 平台家族 |
| platformVersion | string | 平台版本 |
| prettyDistro | string | 发行版名称 |
| kernelArch | string | 内核架构 |
| kernelVersion | string | 内核版本 |
| virtualizationSystem | string | 虚拟化系统 |
| ipV4Addr | string | IPv4地址 |
| systemProxy | string | 系统代理 |
| cpuCores | int | CPU物理核心数 |
| cpuLogicalCores | int | CPU逻辑核心数 |
| cpuModelName | string | CPU型号 |
| cpuMhz | float64 | CPU主频(MHz) |
| quickJumps | []QuickJump | 快速跳转列表 |
| currentInfo | DashboardCurrent | 当前监控信息 |

---

### GET /dashboard/current/node
**功能**: Load dashboard current info for node (获取节点当前信息)

**请求参数**: 无

**返回参数** (`NodeCurrent`):
| 字段 | 类型 | 说明 |
|------|------|------|
| load1 | float64 | 1分钟负载 |
| load5 | float64 | 5分钟负载 |
| load15 | float64 | 15分钟负载 |
| loadUsagePercent | float64 | 负载使用百分比 |
| cpuUsedPercent | float64 | CPU使用百分比 |
| cpuUsed | float64 | CPU已使用 |
| cpuTotal | int | CPU总核心数 |
| cpuDetailedPercent | []float64 | CPU详细使用率 |
| memoryTotal | uint64 | 内存总量(字节) |
| memoryAvailable | uint64 | 可用内存(字节) |
| memoryUsed | uint64 | 已用内存(字节) |
| memoryUsedPercent | float64 | 内存使用百分比 |
| swapMemoryTotal | uint64 | 交换空间总量 |
| swapMemoryAvailable | uint64 | 可用交换空间 |
| swapMemoryUsed | uint64 | 已用交换空间 |
| swapMemoryUsedPercent | float64 | 交换空间使用百分比 |

---

### GET /dashboard/current/:ioOption/:netOption
**功能**: Load dashboard current info (获取仪表盘当前监控信息)

**路径参数**:
| 参数 | 类型 | 必填 | 说明 | 取值示例 |
|------|------|------|------|----------|
| ioOption | string | 是 | IO选项 | "sda", "all" |
| netOption | string | 是 | 网络选项 | "eth0", "all" |

**返回参数** (`DashboardCurrent`):
| 字段 | 类型 | 说明 |
|------|------|------|
| uptime | uint64 | 运行时间(秒) |
| timeSinceUptime | string | 运行时间描述 |
| procs | uint64 | 进程数 |
| load1 | float64 | 1分钟负载 |
| load5 | float64 | 5分钟负载 |
| load15 | float64 | 15分钟负载 |
| loadUsagePercent | float64 | 负载使用百分比 |
| cpuPercent | []float64 | CPU使用率数组 |
| cpuUsedPercent | float64 | CPU使用百分比 |
| cpuUsed | float64 | CPU已使用 |
| cpuTotal | int | CPU总核心数 |
| cpuDetailedPercent | []float64 | CPU各核心使用率 |
| memoryTotal | uint64 | 内存总量 |
| memoryUsed | uint64 | 已用内存 |
| memoryFree | uint64 | 空闲内存 |
| memoryShard | uint64 | 共享内存 |
| memoryCache | uint64 | 缓存内存 |
| memoryAvailable | uint64 | 可用内存 |
| memoryUsedPercent | float64 | 内存使用百分比 |
| swapMemoryTotal | uint64 | 交换空间总量 |
| swapMemoryAvailable | uint64 | 可用交换空间 |
| swapMemoryUsed | uint64 | 已用交换空间 |
| swapMemoryUsedPercent | float64 | 交换空间使用百分比 |
| ioReadBytes | uint64 | IO读取字节数 |
| ioWriteBytes | uint64 | IO写入字节数 |
| ioCount | uint64 | IO操作次数 |
| ioReadTime | uint64 | IO读取时间 |
| ioWriteTime | uint64 | IO写入时间 |
| diskData | []DiskInfo | 磁盘信息列表 |
| netBytesSent | uint64 | 网络发送字节 |
| netBytesRecv | uint64 | 网络接收字节 |
| gpuData | []GPUInfo | GPU信息列表 |
| xpuData | []XPUInfo | XPU信息列表 |
| topCPUItems | []Process | CPU占用最高的进程 |
| topMemItems | []Process | 内存占用最高的进程 |
| shotTime | time.Time | 快照时间 |

**DiskInfo 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| path | string | 挂载路径 |
| type | string | 文件系统类型 |
| device | string | 设备名 |
| total | uint64 | 总容量 |
| free | uint64 | 可用空间 |
| used | uint64 | 已用空间 |
| usedPercent | float64 | 使用百分比 |
| inodesTotal | uint64 | inode总数 |
| inodesUsed | uint64 | 已用inode |
| inodesFree | uint64 | 可用inode |
| inodesUsedPercent | float64 | inode使用百分比 |

**GPUInfo 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| index | uint | GPU索引 |
| productName | string | 产品名称 |
| gpuUtil | string | GPU利用率 |
| temperature | string | 温度 |
| performanceState | string | 性能状态 |
| powerUsage | string | 电源使用 |
| powerDraw | string | 电源消耗 |
| maxPowerLimit | string | 最大功率限制 |
| memoryUsage | string | 内存使用率 |
| memUsed | string | 已用显存 |
| memTotal | string | 总显存 |
| fanSpeed | string | 风扇速度 |

**XPUInfo 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| deviceID | int | 设备ID |
| deviceName | string | 设备名称 |
| memory | string | 内存信息 |
| temperature | string | 温度 |
| memoryUsed | string | 已用内存 |
| power | string | 功耗 |
| memoryUtil | string | 内存利用率 |

**Process 详情**:
| 字段 | 类型 | 说明 |
|------|------|------|
| pid | int | 进程ID |
| name | string | 进程名称 |
| cpu | float64 | CPU占用率 |
| mem | float64 | 内存占用率 |
| command | string | 命令 |

---

### GET /dashboard/current/top/cpu
**功能**: Load top cpu processes (获取CPU占用最高的进程列表)

**请求参数**: 无

**返回参数** (`Process[]`):
| 字段 | 类型 | 说明 |
|------|------|------|
| pid | int | 进程ID |
| name | string | 进程名称 |
| cpu | float64 | CPU占用百分比 |
| mem | float64 | 内存占用百分比 |
| command | string | 进程命令 |

---

### GET /dashboard/current/top/mem
**功能**: Load top memory processes (获取内存占用最高的进程列表)

**请求参数**: 无

**返回参数** (`Process[]`):
| 字段 | 类型 | 说明 |
|------|------|------|
| pid | int | 进程ID |
| name | string | 进程名称 |
| cpu | float64 | CPU占用百分比 |
| mem | float64 | 内存占用百分比 |
| command | string | 进程命令 |

---

### POST /dashboard/system/restart/:operation
**功能**: System restart (系统重启/关机)

**路径参数**:
| 参数 | 类型 | 必填 | 说明 | 取值示例 |
|------|------|------|------|----------|
| operation | string | 是 | 操作类型 | "reboot"(重启), "shutdown"(关机) |

**返回**: 操作成功返回 200

---

## 通用说明

### 认证方式
- 需要 `ApiKeyAuth` 和 `Timestamp` 认证头

### 响应格式
- 成功: `{"code": 200, "data": {...}}`
- 失败: `{"code": 500, "message": "error message"}`

### 压缩支持
- 部分接口(如 `/dashboard/app/launcher`)支持 Gzip 压缩返回


path: docs/SKILL-databases.md
content: # Database, Database Common, Database Mysql, Database PostgreSQL, Database Redis - 1Panel API

## 模块说明
Database, Database Common, Database Mysql, Database PostgreSQL, Database Redis 模块接口

## 接口列表 (42 个)

---

### GET /databases/db/:name
**功能**: Get databases - 获取数据库详情

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |

**返回**: `dto.DatabaseInfo` - 数据库详细信息

---

### GET /databases/db/item/:type
**功能**: List databases - 获取数据库列表项

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 是 | 数据库类型 (mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster) |

**返回**: `dto.DatabaseItem[]` - 数据库列表项数组

---

### GET /databases/db/list/:type
**功能**: List databases - 获取数据库选项列表

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 是 | 数据库类型 (mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster) |

**返回**: `dto.DatabaseOption[]` - 数据库选项数组

---

### POST /databases
**功能**: Create mysql database - 创建 MySQL 数据库

**请求体 (dto.MysqlDBCreate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 数据库名称 | 最大256字符 |
| from | string | 是 | 数据来源 | local, remote |
| database | string | 是 | 远程数据库标识 | |
| format | string | 是 | 字符集格式 | utf8mb4, utf8, latin1 等 |
| collation | string | 否 | 排序规则 | |
| username | string | 是 | 数据库用户名 | |
| password | string | 是 | 数据库密码 (Base64编码) | |
| permission | string | 是 | 权限 | ALL, SELECT, INSERT, UPDATE, DELETE 等 |
| description | string | 否 | 数据库描述 | 最大256字符 |

---

### POST /databases/bind
**功能**: Bind user of mysql database - 绑定 MySQL 数据库用户

**请求体 (dto.BindUser)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| database | string | 是 | 数据库名称 |
| db | string | 是 | 数据库标识 |
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 (Base64编码) |
| permission | string | 是 | 权限 |

---

### POST /databases/change/access
**功能**: Change mysql access - 修改 MySQL 数据库访问权限

**请求体 (dto.ChangeDBInfo)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| from | string | 是 | 数据来源 | local, remote |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| database | string | 是 | 数据库名称 |
| value | string | 是 | 权限设置 (如 %) | |

---

### POST /databases/change/password
**功能**: Change mysql password - 修改 MySQL 数据库密码

**请求体 (dto.ChangeDBInfo)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| from | string | 是 | 数据来源 | local, remote |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| database | string | 是 | 数据库名称 |
| value | string | 是 | 新密码 (Base64编码) | |

---

### POST /databases/common/info
**功能**: Load base info - 加载数据库基础信息

**请求体 (dto.OperationWithNameAndType)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 数据库名称 | |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |

**返回**: `dto.DBBaseInfo` - 数据库基础信息
| 字段 | 类型 | 说明 |
|------|------|------|
| Name | string | 数据库名称 |
| ContainerName | string | 容器名称 |
| Port | int64 | 端口号 |

---

### POST /databases/common/load/file
**功能**: Load Database conf - 加载数据库配置文件

**请求体 (dto.OperationWithNameAndType)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 数据库名称 | |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |

**返回**: `string` - 配置文件内容

---

### POST /databases/common/update/conf
**功能**: Update conf by upload file - 通过上传文件更新数据库配置

**请求体 (dto.DBConfUpdateByFile)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| database | string | 是 | 数据库名称 | |
| file | string | 否 | 配置文件内容 | |

---

### POST /databases/db
**功能**: Create database - 创建远程数据库

**请求体 (dto.DatabaseCreate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 数据库名称 | 最大256字符 |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| from | string | 是 | 数据来源 | local, remote |
| version | string | 是 | 数据库版本 | |
| address | string | 否 | 远程数据库地址 | |
| port | uint | 否 | 端口号 | |
| initialDB | string | 否 | 初始数据库 | |
| username | string | 是 | 数据库用户名 | |
| password | string | 否 | 数据库密码 | |
| ssl | bool | 否 | 是否使用SSL连接 | |
| rootCert | string | 否 | CA证书 (Base64编码) | |
| clientKey | string | 否 | 客户端私钥 (Base64编码) | |
| clientCert | string | 否 | 客户端证书 (Base64编码) | |
| skipVerify | bool | 否 | 是否跳过证书验证 | |
| timeout | uint | 否 | 连接超时时间(秒) | |
| description | string | 否 | 数据库描述 | |

---

### POST /databases/db/check
**功能**: Check database - 检查数据库连接性

**请求体 (dto.DatabaseCreate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 数据库名称 | 最大256字符 |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| from | string | 是 | 数据来源 | local, remote |
| version | string | 是 | 数据库版本 | |
| address | string | 否 | 远程数据库地址 | |
| port | uint | 否 | 端口号 | |
| initialDB | string | 否 | 初始数据库 | |
| username | string | 是 | 数据库用户名 | |
| password | string | 否 | 数据库密码 | |
| ssl | bool | 否 | 是否使用SSL连接 | |
| rootCert | string | 否 | CA证书 (Base64编码) | |
| clientKey | string | 否 | 客户端私钥 (Base64编码) | |
| clientCert | string | 否 | 客户端证书 (Base64编码) | |
| skipVerify | bool | 否 | 是否跳过证书验证 | |
| timeout | uint | 否 | 连接超时时间(秒) | |
| description | string | 否 | 数据库描述 | |

**返回**: `boolean` - 是否可连接

---

### POST /databases/db/del
**功能**: Delete database - 删除远程数据库

**请求体 (dto.DatabaseDelete)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 是 | 数据库记录ID |
| forceDelete | bool | 否 | 是否强制删除 |
| deleteBackup | bool | 否 | 是否删除备份 |

---

### POST /databases/db/del/check
**功能**: Check before delete remote database - 删除前检查远程数据库

**请求体 (dto.OperateByID)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 是 | 数据库记录ID |

**返回**: `string[]` - 关联的应用列表

---

### POST /databases/db/search
**功能**: Page databases - 分页查询数据库

**请求体 (dto.DatabaseSearch)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | |
| pageSize | int | 是 | 每页数量 | |
| info | string | 否 | 搜索关键词 | |
| type | string | 否 | 数据库类型 | |
| orderBy | string | 是 | 排序字段 | name, createdAt |
| order | string | 是 | 排序方式 | null, ascending, descending |

**返回**: `dto.PageResult` - 分页结果

---

### POST /databases/db/update
**功能**: Update database - 更新远程数据库

**请求体 (dto.DatabaseUpdate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| type | string | 是 | 数据库类型 | mysql, mariadb, postgresql, redis, mysql-cluster, postgresql-cluster, redis-cluster |
| version | string | 是 | 数据库版本 | |
| address | string | 否 | 远程数据库地址 | |
| port | uint | 否 | 端口号 | |
| initialDB | string | 否 | 初始数据库 | |
| username | string | 是 | 数据库用户名 | |
| password | string | 否 | 数据库密码 | |
| ssl | bool | 否 | 是否使用SSL连接 | |
| rootCert | string | 否 | CA证书 (Base64编码) | |
| clientKey | string | 否 | 客户端私钥 (Base64编码) | |
| clientCert | string | 否 | 客户端证书 (Base64编码) | |
| skipVerify | bool | 否 | 是否跳过证书验证 | |
| timeout | uint | 否 | 连接超时时间(秒) | |
| description | string | 否 | 数据库描述 | |

---

### POST /databases/del
**功能**: Delete mysql database - 删除 MySQL 数据库

**请求体 (dto.MysqlDBDelete)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |
| database | string | 是 | 数据库名称 | |
| forceDelete | bool | 否 | 是否强制删除 | |
| deleteBackup | bool | 否 | 是否删除备份 | |

---

### POST /databases/del/check
**功能**: Check before delete mysql database - 删除 MySQL 数据库前检查

**请求体 (dto.MysqlDBDeleteCheck)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |
| database | string | 是 | 数据库名称 | |

**返回**: `string[]` - 关联的应用列表

---

### POST /databases/description/update
**功能**: Update mysql database description - 更新 MySQL 数据库描述

**请求体 (dto.UpdateDescription)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 是 | 数据库记录ID |
| description | string | 是 | 数据库描述 (最大256字符) |

---

### POST /databases/format/options
**功能**: List mysql database format collation options - 获取 MySQL 数据库字符集和排序规则选项

**请求体 (dto.OperationWithName)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |

**返回**: `dto.MysqlFormatCollationOption[]` - 字符集选项列表
| 字段 | 类型 | 说明 |
|------|------|------|
| Format | string | 字符集格式 |
| Collations | string[] | 可用的排序规则列表 |

---

### POST /databases/load
**功能**: Load mysql database from remote - 从远程加载 MySQL 数据库

**请求体 (dto.MysqlLoadDB)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| from | string | 是 | 数据来源 | local, remote |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |
| database | string | 是 | 数据库名称 | |

---

### POST /databases/pg
**功能**: Create postgresql database - 创建 PostgreSQL 数据库

**请求体 (dto.PostgresqlDBCreate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 数据库名称 | |
| from | string | 是 | 数据来源 | local, remote |
| database | string | 是 | 远程数据库标识 | |
| format | string | 否 | 字符集格式 | |
| username | string | 是 | 数据库用户名 | |
| password | string | 是 | 数据库密码 (Base64编码) | |
| superUser | bool | 否 | 是否为超级用户 | |
| description | string | 否 | 数据库描述 | |

---

### POST /databases/pg/:database/load
**功能**: Load postgresql database from remote - 从远程加载 PostgreSQL 数据库

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| database | string | 是 | 数据库名称 |

---

### POST /databases/pg/bind
**功能**: Bind postgresql user - 绑定 PostgreSQL 用户

**请求体 (dto.PostgresqlBindUser)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |
| database | string | 是 | 数据库标识 |
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| superUser | bool | 否 | 是否为超级用户 |

---

### POST /databases/pg/del
**功能**: Delete postgresql database - 删除 PostgreSQL 数据库

**请求体 (dto.PostgresqlDBDelete)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| type | string | 是 | 数据库类型 | postgresql, postgresql-cluster |
| database | string | 是 | 数据库名称 | |
| forceDelete | bool | 否 | 是否强制删除 | |
| deleteBackup | bool | 否 | 是否删除备份 | |

---

### POST /databases/pg/del/check
**功能**: Check before delete postgresql database - 删除 PostgreSQL 数据库前检查

**请求体 (dto.PostgresqlDBDeleteCheck)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| type | string | 是 | 数据库类型 | postgresql, postgresql-cluster |
| database | string | 是 | 数据库名称 | |

**返回**: `string[]` - 关联的应用列表

---

### POST /databases/pg/description
**功能**: Update postgresql database description - 更新 PostgreSQL 数据库描述

**请求体 (dto.UpdateDescription)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 是 | 数据库记录ID |
| description | string | 是 | 数据库描述 (最大256字符) |

---

### POST /databases/pg/password
**功能**: Change postgresql password - 修改 PostgreSQL 密码

**请求体 (dto.ChangeDBInfo)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 数据库记录ID | |
| from | string | 是 | 数据来源 | local, remote |
| type | string | 是 | 数据库类型 | postgresql, postgresql-cluster |
| database | string | 是 | 数据库名称 |
| value | string | 是 | 新密码 (Base64编码) | |

---

### POST /databases/pg/privileges
**功能**: Change postgresql privileges - 修改 PostgreSQL 用户权限

**请求体 (dto.PostgresqlPrivileges)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |
| database | string | 是 | 数据库标识 |
| username | string | 是 | 用户名 |
| superUser | bool | 否 | 是否为超级用户 |

---

### POST /databases/pg/search
**功能**: Page postgresql databases - 分页查询 PostgreSQL 数据库

**请求体 (dto.PostgresqlDBSearch)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | |
| pageSize | int | 是 | 每页数量 | |
| info | string | 否 | 搜索关键词 | |
| database | string | 是 | 数据库标识 | |
| orderBy | string | 是 | 排序字段 | name, createdAt |
| order | string | 是 | 排序方式 | null, ascending, descending |

**返回**: `dto.PageResult` - 分页结果

---

### POST /databases/redis/conf
**功能**: Load redis conf - 加载 Redis 配置

**请求体 (dto.LoadRedisStatus)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |
| type | string | 是 | 数据库类型 |

**返回**: `dto.RedisConf` - Redis 配置信息
| 字段 | 类型 | 说明 |
|------|------|------|
| Database | string | 数据库标识 |
| Name | string | 数据库名称 |
| Port | int64 | 端口号 |
| ContainerName | string | 容器名称 |
| Timeout | string | 超时时间 |
| Maxclients | string | 最大客户端数 |
| Requirepass | string | 密码 |
| Maxmemory | string | 最大内存 |

---

### POST /databases/redis/conf/update
**功能**: Update redis conf - 更新 Redis 配置

**请求体 (dto.RedisConfUpdate)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| database | string | 是 | 数据库标识 |
| timeout | string | 否 | 超时时间 |
| maxclients | string | 否 | 最大客户端数 |
| maxmemory | string | 否 | 最大内存 |
| dbType | string | 是 | 数据库类型 (redis, redis-cluster) |

---

### POST /databases/redis/install/cli
**功能**: Install redis-cli - 安装 Redis CLI 工具

**无请求参数**

---

### POST /databases/redis/password
**功能**: Change redis password - 修改 Redis 密码

**请求体 (dto.ChangeRedisPass)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| database | string | 是 | 数据库标识 |
| value | string | 是 | 新密码 |

---

### POST /databases/redis/persistence/conf
**功能**: Load redis persistence conf - 加载 Redis 持久化配置

**请求体 (dto.LoadRedisStatus)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |
| type | string | 是 | 数据库类型 |

**返回**: `dto.RedisPersistence` - Redis 持久化配置
| 字段 | 类型 | 说明 |
|------|------|------|
| Database | string | 数据库标识 |
| Appendonly | string | AOF持久化开关 |
| Appendfsync | string | AOF同步策略 |
| Save | string | RDB保存策略 |

---

### POST /databases/redis/persistence/update
**功能**: Update redis persistence conf - 更新 Redis 持久化配置

**请求体 (dto.RedisConfPersistenceUpdate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| database | string | 是 | 数据库标识 | |
| type | string | 是 | 持久化类型 | aof, rbd |
| appendonly | string | 否 | AOF持久化开关 | |
| appendfsync | string | 否 | AOF同步策略 | |
| save | string | 否 | RDB保存策略 | |
| dbType | string | 是 | 数据库类型 | redis, redis-cluster |

---

### POST /databases/redis/status
**功能**: Load redis status info - 加载 Redis 状态信息

**请求体 (dto.LoadRedisStatus)**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 数据库名称 |
| type | string | 是 | 数据库类型 |

**返回**: `dto.RedisStatus` - Redis 状态信息

---

### POST /databases/remote
**功能**: Load mysql remote access - 加载 MySQL 远程访问设置

**请求体 (dto.OperationWithNameAndType)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 数据库名称 | |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |

**返回**: `boolean` - 是否开启远程访问

---

### POST /databases/search
**功能**: Page mysql databases - 分页查询 MySQL 数据库

**请求体 (dto.MysqlDBSearch)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | |
| pageSize | int | 是 | 每页数量 | |
| info | string | 否 | 搜索关键词 | |
| database | string | 是 | 数据库标识 | |
| orderBy | string | 是 | 排序字段 | name, createdAt |
| order | string | 是 | 排序方式 | null, ascending, descending |

**返回**: `dto.PageResult` - 分页结果

---

### POST /databases/status
**功能**: Load mysql status info - 加载 MySQL 状态信息

**请求体 (dto.OperationWithNameAndType)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 数据库名称 | |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |

**返回**: `dto.MysqlStatus` - MySQL 状态信息

---

### POST /databases/variables
**功能**: Load mysql variables info - 加载 MySQL 变量信息

**请求体 (dto.OperationWithNameAndType)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 数据库名称 | |
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |

**返回**: `dto.MysqlVariables` - MySQL 变量信息
| 字段 | 类型 | 说明 |
|------|------|------|
| BinlogCacheSize | string | Binlog缓存大小 |
| InnodbBufferPoolSize | string | InnoDB缓冲池大小 |
| InnodbLogBufferSize | string | InnoDB日志缓冲大小 |
| JoinBufferSize | string | Join缓冲大小 |
| KeyBufferSize | string | 键缓冲大小 |
| MaxConnections | string | 最大连接数 |
| MaxHeapTableSize | string | 最大内存表大小 |
| QueryCacheSize | string | 查询缓存大小 |
| QueryCacheType | string | 查询缓存类型 |
| ReadBufferSize | string | 读缓冲大小 |
| ReadRndBufferSize | string | 随机读缓冲大小 |
| SortBufferSize | string | 排序缓冲大小 |
| TableOpenCache | string | 表缓存大小 |
| ThreadCacheSize | string | 线程缓存大小 |
| ThreadStack | string | 线程栈大小 |
| TmpTableSize | string | 临时表大小 |
| SlowQueryLog | string | 慢查询日志 |
| LongQueryTime | string | 慢查询时间阈值 |

---

### POST /databases/variables/update
**功能**: Update mysql variables - 更新 MySQL 变量

**请求体 (dto.MysqlVariablesUpdate)**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 数据库类型 | mysql, mariadb, mysql-cluster |
| database | string | 是 | 数据库名称 | |
| variables | array | 是 | 变量数组 | |

**variables 数组项 (dto.MysqlVariablesUpdateHelper)**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| param | string | 变量名 |
| value | any | 变量值 |



path: docs/SKILL-files.md
content: # File - 1Panel API

## 模块说明
File 模块接口，提供文件管理功能，包括上传、下载、复制、移动、压缩等操作。

## 文件路径说明

### 1Panel 目录结构

| 路径类型 | 说明 | 默认位置 |
|----------|------|----------|
| **网站根目录** | 网站文件存放目录 | `/opt/1panel/www/sites/{网站名称}/index` |
| **应用目录** | 已安装应用的目录 | `/opt/1panel/apps/{应用Key}/{应用名称}` |
| **备份目录** | 备份文件存放目录 | `/opt/1panel/backup/{类型}` |
| **日志目录** | 系统和应用日志目录 | `/opt/1panel/logs/{类型}` |
| **数据库目录** | 数据库数据存放目录 | `/opt/1panel/mysql/{数据库名称}` |
| **Redis 目录** | Redis 数据存放目录 | `/opt/1panel/redis/{实例名称}` |

### 常用文件操作路径

| 操作类型 | API | 说明 |
|----------|-----|------|
| **下载文件** | `GET /files/download` | 通过 `path` 参数指定文件路径 |
| **上传文件** | `POST /files/upload` | 上传到指定目录 |
| **批量下载** | `POST /files/chunkdownload` | 支持大文件分块下载 |
| **批量上传** | `POST /files/chunkupload` | 支持大文件分块上传 |
| **读取文件** | `POST /files/content` | 获取文件内容 |
| **保存文件** | `POST /files/save` | 保存或创建文件 |

### 路径参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| path | 文件或目录的完整绝对路径 | `/opt/1panel/www/mywebsite/index.html` |
| name | 文件或目录名称 | `index.html` |
| dir | 目录路径 | `/opt/1panel/www/mywebsite` |

### 源码位置

- **路由**: `/agent/router/ro_file.go`
- **API Handler**: `/agent/app/api/v2/file.go`
- **DTO**: `/agent/app/dto/file.go`, `/agent/app/dto/request/file.go`

## 接口列表 (37 个)

---

### GET /files/download
**功能**: Download file

**Query 参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件路径 | 任意有效文件路径 |

---

### GET /files/recycle/status
**功能**: Get RecycleBin status

**参数**: 无

---

### POST /files
**功能**: Create file

**Body 参数** (FileCreate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件或目录的完整路径 | 任意有效路径 |
| content | string | 否 | 文件内容 | 任意文本内容 |
| isDir | bool | 否 | 是否创建目录 | true/false |
| mode | int64 | 否 | 权限模式 | 八进制权限值，如 0755 |
| isLink | bool | 否 | 是否为链接 | true/false |
| isSymlink | bool | 否 | 是否为符号链接 | true/false |
| linkPath | string | 否 | 符号链接目标路径 | 任意有效路径 |
| sub | bool | 否 | 是否包含子目录/文件 | true/false |

---

### POST /files/batch/check
**功能**: Batch check file exist

**Body 参数** (FilePathsCheck):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| paths | []string | 是 | 要检查的文件路径列表 | 任意有效路径数组 |

---

### POST /files/batch/del
**功能**: Batch delete file

**Body 参数** (FileBatchDelete):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| paths | []string | 是 | 要删除的文件路径列表 | 任意有效路径数组 |
| isDir | bool | 否 | 路径是否为目录 | true/false |

---

### POST /files/batch/role
**功能**: Batch change file mode and owner

**Body 参数** (FileRoleReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| paths | []string | 是 | 要修改的文件路径列表 | 任意有效路径数组 |
| mode | int64 | 是 | 权限模式 | 八进制权限值，如 0755 |
| user | string | 是 | 用户名 | 系统存在的用户 |
| group | string | 是 | 用户组名 | 系统存在的用户组 |
| sub | bool | 否 | 是否包含子目录/文件 | true/false |

---

### POST /files/check
**功能**: Check file exist

**Body 参数** (FilePathCheck):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 要检查的文件路径 | 任意有效路径 |
| withInit | bool | 否 | 路径不存在时是否自动创建 | true/false |

---

### POST /files/chunkdownload
**功能**: Chunk Download file

**Body 参数** (FileChunkDownload):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 要下载的文件路径 | 任意有效文件路径 |
| name | string | 是 | 下载时的文件名 | 任意文件名 |

---

### POST /files/chunkupload
**功能**: ChunkUpload file

**FormData 参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| chunk | file | 是 | 分片文件数据 | 文件二进制数据 |
| chunkIndex | int | 是 | 当前分片索引 | 从 0 开始的整数 |
| chunkCount | int | 是 | 总分片数量 | 大于 0 的整数 |
| filename | string | 是 | 原始文件名 | 任意文件名 |
| path | string | 是 | 上传目标目录 | 任意有效目录路径 |
| overwrite | bool | 否 | 是否覆盖已存在文件 | true/false (默认 true) |

---

### POST /files/compress
**功能**: Compress file

**Body 参数** (FileCompress):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| files | []string | 是 | 要压缩的文件/目录路径列表 | 任意有效路径数组 |
| dst | string | 是 | 压缩文件目标目录 | 任意有效目录路径 |
| type | string | 是 | 压缩类型 | zip/gz/bz2/tar/tar.gz/tgz/xz/tar.xz/7z |
| name | string | 是 | 压缩文件名(不含扩展名) | 任意文件名 |
| replace | bool | 否 | 是否覆盖已存在的压缩文件 | true/false |
| secret | string | 否 | 压缩密码(加密压缩时使用) | 任意密码字符串 |

---

### POST /files/content
**功能**: Load file content

**Body 参数** (FileContentReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件路径 | 任意有效文件路径 |
| isDetail | bool | 否 | 是否获取详细信息 | true/false |

---

### POST /files/convert
**功能**: Convert file

**Body 参数** (FileConvertRequest):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| files | []FileConvert | 是 | 要转换的文件列表 | 至少一个文件 |
| outputPath | string | 是 | 输出目录路径 | 任意有效目录路径 |
| deleteSource | bool | 否 | 转换后是否删除源文件 | true/false |
| taskID | string | 否 | 任务 ID | 任意字符串 |

**FileConvert 子参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件路径 | 任意有效文件路径 |
| type | string | 是 | 转换类型 | 转换类型标识 |
| inputFile | string | 是 | 输入文件名 | 任意文件名 |
| extension | string | 是 | 目标扩展名 | 目标文件扩展名 |
| outputFormat | string | 是 | 输出格式 | 输出格式标识 |
| status | string | 否 | 状态 | 状态标识 |

---

### POST /files/convert/log
**功能**: Convert file

**Body 参数** (PageInfo):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | 大于 0 的整数 |
| pageSize | int | 是 | 每页数量 | 1-100 |

---

### POST /files/decompress
**功能**: Decompress file

**Body 参数** (FileDeCompress):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| dst | string | 是 | 解压目标目录 | 任意有效目录路径 |
| type | string | 是 | 压缩文件类型 | zip/gz/bz2/tar/tar.gz/tgz/xz/tar.xz/7z |
| path | string | 是 | 压缩文件路径 | 任意有效的压缩文件路径 |
| secret | string | 否 | 解压密码 | 任意密码字符串 |

---

### POST /files/del
**功能**: Delete file

**Body 参数** (FileDelete):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 要删除的文件/目录路径 | 任意有效路径 |
| isDir | bool | 否 | 路径是否为目录 | true/false |
| forceDelete | bool | 否 | 是否强制删除(不经过回收站) | true/false |

---

### POST /files/depth/size
**功能**: Multi file size

**Body 参数** (DirSizeReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 目录路径 | 任意有效目录路径 |

---

### POST /files/favorite
**功能**: Create favorite

**Body 参数** (FavoriteCreate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 要收藏的文件/目录路径 | 任意有效路径 |

---

### POST /files/favorite/del
**功能**: Delete favorite

**Body 参数** (FavoriteDelete):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 收藏记录 ID | 收藏记录的主键 ID |

---

### POST /files/favorite/search
**功能**: List favorites

**Body 参数** (SearchUploadWithPage):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 搜索路径(收藏夹固定路径) | 收藏夹路径 |
| page | int | 是 | 页码 | 大于 0 的整数 |
| pageSize | int | 是 | 每页数量 | 1-100 |

---

### POST /files/mode
**功能**: Change file mode

**Body 参数** (FileCreate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件/目录路径 | 任意有效路径 |
| mode | int64 | 否 | 权限模式 | 八进制权限值，如 0755 |

---

### POST /files/mount
**功能**: system mount

**参数**: 无

---

### POST /files/move
**功能**: Move file

**Body 参数** (FileMove):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 移动类型 | move/copy |
| oldPaths | []string | 是 | 原路径列表 | 任意有效路径数组 |
| newPath | string | 是 | 目标目录路径 | 任意有效目录路径 |
| name | string | 否 | 重命名时的新名称 | 任意文件名 |
| cover | bool | 否 | 是否覆盖已存在的文件 | true/false |
| coverPaths | []string | 否 | 需要覆盖的路径列表 | 路径数组 |

---

### POST /files/owner
**功能**: Change file owner

**Body 参数** (FileRoleUpdate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件/目录路径 | 任意有效路径 |
| user | string | 是 | 用户名 | 系统存在的用户 |
| group | string | 是 | 用户组名 | 系统存在的用户组 |
| sub | bool | 否 | 是否包含子目录/文件 | true/false |

---

### POST /files/preview
**功能**: Preview file content

**Body 参数** (FileContentReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件路径 | 任意有效文件路径 |
| isDetail | bool | 否 | 是否获取详细信息 | true/false |

---

### POST /files/read
**功能**: Read file by Line

**Body 参数** (FileReadByLineReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | 大于 0 的整数 |
| pageSize | int | 是 | 每页行数 | 1-1000 |
| type | string | 是 | 文件类型 | 文件类型标识 |
| ID | uint | 否 | 资源 ID | 资源主键 ID |
| name | string | 否 | 文件名 | 任意文件名 |
| latest | bool | 否 | 是否只读取最新内容 | true/false |
| taskID | string | 否 | 任务 ID | 任意字符串 |
| taskType | string | 否 | 任务类型 | 任务类型标识 |
| taskOperate | string | 否 | 任务操作 | 操作标识 |
| resourceID | uint | 否 | 资源 ID | 资源主键 ID |

---

### POST /files/recycle/clear
**功能**: Clear RecycleBin files

**参数**: 无

---

### POST /files/recycle/reduce
**功能**: Reduce RecycleBin files

**Body 参数** (RecycleBinReduce):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| from | string | 是 | 回收站中的原始路径 | 回收站记录路径 |
| rName | string | 是 | 回收站中的文件名 | 回收站文件名 |
| name | string | 否 | 恢复后的文件名 | 任意文件名 |

---

### POST /files/recycle/search
**功能**: List RecycleBin files

**Body 参数** (SearchUploadWithPage):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 搜索路径(回收站固定路径) | 回收站路径 |
| page | int | 是 | 页码 | 大于 0 的整数 |
| pageSize | int | 是 | 每页数量 | 1-100 |

---

### POST /files/rename
**功能**: Change file name

**Body 参数** (FileRename):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| oldName | string | 是 | 原文件名(完整路径) | 任意有效文件路径 |
| newName | string | 是 | 新文件名(完整路径) | 任意有效文件路径 |

---

### POST /files/save
**功能**: Update file content

**Body 参数** (FileEdit):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 文件路径 | 任意有效文件路径 |
| content | string | 否 | 文件内容 | 任意文本内容 |

---

### POST /files/search
**功能**: List files

**Body 参数** (FileOption):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 否 | 目录路径 | 任意有效目录路径 |
| search | string | 否 | 搜索关键字 | 任意搜索字符串 |
| containSub | bool | 否 | 是否包含子目录搜索 | true/false |
| expand | bool | 否 | 是否展开子目录 | true/false |
| dir | bool | 否 | 是否只显示目录 | true/false |
| showHidden | bool | 否 | 是否显示隐藏文件 | true/false |
| page | int | 否 | 页码 | 大于 0 的整数 |
| pageSize | int | 否 | 每页数量 | 1-100 |
| sortBy | string | 否 | 排序字段 | name/size/modTime |
| sortOrder | string | 否 | 排序方式 | ascending/descending |
| isDetail | bool | 否 | 是否获取详细信息 | true/false |

---

### POST /files/size
**功能**: Load file size

**Body 参数** (DirSizeReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 目录路径 | 任意有效目录路径 |

---

### POST /files/tree
**功能**: Load files tree

**Body 参数** (FileOption):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 否 | 目录路径 | 任意有效目录路径 |
| search | string | 否 | 搜索关键字 | 任意搜索字符串 |
| containSub | bool | 否 | 是否包含子目录搜索 | true/false |
| expand | bool | 否 | 是否展开子目录 | true/false |
| dir | bool | 否 | 是否只显示目录 | true/false |
| showHidden | bool | 否 | 是否显示隐藏文件 | true/false |
| page | int | 否 | 页码 | 大于 0 的整数 |
| pageSize | int | 否 | 每页数量 | 1-100 |
| sortBy | string | 否 | 排序字段 | name/size/modTime |
| sortOrder | string | 否 | 排序方式 | ascending/descending |
| isDetail | bool | 否 | 是否获取详细信息 | true/false |

---

### POST /files/upload
**功能**: Upload file

**FormData 参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| file | file | 是 | 上传的文件 | 文件二进制数据 |
| path | string | 是 | 上传目标目录 | 任意有效目录路径 |
| overwrite | bool | 否 | 是否覆盖已存在文件 | true/false (默认 true) |

---

### POST /files/upload/search
**功能**: Page file

**Body 参数** (SearchUploadWithPage):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | 搜索目录路径 | 任意有效目录路径 |
| page | int | 是 | 页码 | 大于 0 的整数 |
| pageSize | int | 是 | 每页数量 | 1-100 |

---

### POST /files/user/group
**功能**: system user and group

**参数**: 无

---

### POST /files/wget
**功能**: Wget file

**Body 参数** (FileWget):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| url | string | 是 | 下载 URL | HTTP/HTTPS URL |
| path | string | 是 | 下载保存目录 | 任意有效目录路径 |
| name | string | 是 | 保存的文件名 | 任意文件名 |
| ignoreCertificate | bool | 否 | 是否忽略 SSL 证书错误 | true/false |

---

## 压缩类型参考

| 类型 | 说明 |
|------|------|
| zip | ZIP 压缩 |
| gz | Gzip 压缩 |
| bz2 | Bzip2 压缩 |
| tar | Tar 打包 |
| tar.gz / tgz | Tar + Gzip 压缩 |
| xz | XZ 压缩 |
| tar.xz | Tar + XZ 压缩 |
| 7z | 7-Zip 压缩 |

## 排序字段参考

| 字段 | 说明 |
|------|------|
| name | 按名称排序 |
| size | 按大小排序 |
| modTime | 按修改时间排序 |


path: docs/SKILL-groups.md
content: # System Group - 1Panel API

## 模块说明
System Group 模块接口，用于管理系统中的分组（如网站分组、主机分组、命令分组等）

## Group Type 取值范围
- `website` - 网站分组
- `host` - 主机分组
- `command` - 命令分组
- `script` - 脚本分组
- `cronjob` - 定时任务分组

## 接口列表 (8 个)

---

### POST /core/groups
**功能**: Create group (Core 创建分组)
**说明**: 创建一个新的分组

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 否 | 分组ID（创建时通常不传，由系统自动生成） | - |
| name | string | **是** | 分组名称 | 最大长度根据实际业务 |
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |

---

### POST /core/groups/del
**功能**: Delete group (Core 删除分组)
**说明**: 根据ID删除指定分组

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | **是** | 分组ID | 有效的分组记录ID |

---

### POST /core/groups/search
**功能**: List groups (Core 查询分组列表)
**说明**: 根据类型查询分组列表

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |

**返回**: `GroupInfo[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 分组ID |
| name | string | 分组名称 |
| type | string | 分组类型 |
| isDefault | bool | 是否为默认分组 |

---

### POST /core/groups/update
**功能**: Update group (Core 更新分组)
**说明**: 更新指定分组的信息

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | **是** | 分组ID | 有效的分组记录ID |
| name | string | 否 | 分组名称（更新时可选） | 最大长度根据实际业务 |
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |
| isDefault | bool | 否 | 是否设为默认分组 | `true`, `false` |

---

### POST /groups
**功能**: Create group (Agent 创建分组)
**说明**: 创建一个新的分组（Agent端接口）

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 否 | 分组ID（创建时通常不传，由系统自动生成） | - |
| name | string | **是** | 分组名称 | 最大长度根据实际业务 |
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |

---

### POST /groups/del
**功能**: Delete group (Agent 删除分组)
**说明**: 根据ID删除指定分组（Agent端接口）

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | **是** | 分组ID | 有效的分组记录ID |

---

### POST /groups/search
**功能**: List groups (Agent 查询分组列表)
**说明**: 根据类型查询分组列表（Agent端接口）

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |

**返回**: `GroupInfo[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 分组ID |
| name | string | 分组名称 |
| type | string | 分组类型 |
| isDefault | bool | 是否为默认分组 |

---

### POST /groups/update
**功能**: Update group (Agent 更新分组)
**说明**: 更新指定分组的信息（Agent端接口）

**参数 (Body)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | **是** | 分组ID | 有效的分组记录ID |
| name | string | 否 | 分组名称（更新时可选） | 最大长度根据实际业务 |
| type | string | **是** | 分组类型 | `website`, `host`, `command`, `script`, `cronjob` |
| isDefault | bool | 否 | 是否设为默认分组 | `true`, `false` |

---

## DTO 结构参考

### GroupCreate (创建分组)
```go
type GroupCreate struct {
    ID   uint   `json:"id"`
    Name string `json:"name" validate:"required"`
    Type string `json:"type" validate:"required"`
}
```

### OperateByID (删除分组)
```go
type OperateByID struct {
    ID uint `json:"id" validate:"required"`
}
```

### GroupSearch / OperateByType (查询分组)
```go
type GroupSearch struct {
    Type string `json:"type" validate:"required"`
}

type OperateByType struct {
    Type string `json:"type"`
}
```

### GroupUpdate (更新分组)
```go
type GroupUpdate struct {
    ID        uint   `json:"id"`
    Name      string `json:"name"`
    Type      string `json:"type" validate:"required"`
    IsDefault bool   `json:"isDefault"`
}
```

### GroupInfo (分组信息)
```go
type GroupInfo struct {
    ID        uint   `json:"id"`
    Name      string `json:"name"`
    Type      string `json:"type"`
    IsDefault bool   `json:"isDefault"`
}
```


path: docs/SKILL-hosts.md
content: # Disk Management, Firewall, Host, Host tool, Monitor, SSH - 1Panel API

## 模块说明
Disk Management, Firewall, Host, Host tool, Monitor, SSH 模块接口

## 接口列表 (53 个)

---

### GET /hosts/components/{name}
**功能**: Check if a system component exists

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | Component name to check | 例如: rsync, docker |

---

### GET /hosts/disks
**功能**: Get complete disk information

**响应参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| (全盘信息) | object | 包含所有磁盘的完整信息，包括已分区和未分区磁盘 |

---

### GET /hosts/monitor/setting
**功能**: Load monitor setting

**响应参数** (MonitorSetting):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| MonitorStatus | string | 监控状态 (enable/disable) |
| MonitorStoreDays | string | 数据保留天数 |
| MonitorInterval | string | 监控间隔 |
| DefaultNetwork | string | 默认网卡 |
| DefaultIO | string | 默认IO设备 |

---

### GET /hosts/tool/supervisor/process
**功能**: Get Supervisor process config

**响应参数** ([]SupervisorProcessConfig):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | 进程名称 |
| command | string | 启动命令 |
| user | string | 运行用户 |
| dir | string | 工作目录 |
| numprocs | string | 进程数量 |
| autoRestart | string | 自动重启 (true/false) |
| autoStart | string | 开机自启 (true/false) |
| environment | string | 环境变量 |
| status | array | 进程状态列表 |
| msg | string | 消息 |

---

### POST /hosts/disks/mount
**功能**: Mount disk

**请求参数** (DiskMountRequest):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| device | string | ✅ | 设备路径 | 例如: /dev/sdb1 |
| mountPoint | string | ✅ | 挂载点 | 例如: /mnt/data |
| filesystem | string | ✅ | 文件系统类型 | ext4, xfs |
| autoMount | bool | - | 是否开机自动挂载 | true/false |
| noFail | bool | - | 挂载失败时忽略 | true/false |

---

### POST /hosts/disks/partition
**功能**: Partition disk

**请求参数** (DiskPartitionRequest):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| device | string | ✅ | 设备路径 | 例如: /dev/sdb |
| filesystem | string | ✅ | 文件系统类型 | ext4, xfs |
| label | string | - | 卷标 | - |
| autoMount | bool | - | 是否开机自动挂载 | true/false |
| mountPoint | string | ✅ | 挂载点 | 例如: /mnt/data |

---

### POST /hosts/disks/unmount
**功能**: Unmount disk

**请求参数** (DiskUnmountRequest):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| mountPoint | string | ✅ | 挂载点 | 例如: /mnt/data |

---

### POST /hosts/firewall/base
**功能**: Load firewall base info

**请求参数** (OperationWithName):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | 防火墙类型 | firewalld, ufw, iptables |

**响应参数** (FirewallBaseInfo):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | 防火墙名称 |
| isExist | bool | 是否存在 |
| isActive | bool | 是否激活 |
| isInit | bool | 是否初始化 |
| isBind | bool | 是否绑定 |
| version | string | 版本号 |
| pingStatus | string | Ping 状态 |

---

### POST /hosts/firewall/batch
**功能**: Batch operate rule

**请求参数** (BatchRuleOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✅ | 规则类型 | port, addr, forward |
| rules | array | - | 规则列表 | PortRuleOperate 数组 |

**规则参数** (PortRuleOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | ✅ | 操作类型 | add, remove |
| port | string | ✅ | 端口号 | - |
| protocol | string | ✅ | 协议 | tcp, udp, tcp/udp |
| strategy | string | ✅ | 策略 | accept, drop |
| address | string | - | IP 地址 | - |
| chain | string | - | 链 | - |
| description | string | - | 描述 | - |

---

### POST /hosts/firewall/filter/chain/status
**功能**: load chain status with name

**请求参数** (OperationWithName):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | 链名称 | 1PANEL_INPUT, 1PANEL_OUTPUT, 1PANEL_BASIC |

**响应参数** (IptablesChainStatus):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| isBind | bool | 是否绑定 |
| defaultStrategy | string | 默认策略 |

---

### POST /hosts/firewall/filter/operate
**功能**: Apply/Unload/Init iptables filter

**请求参数** (IptablesOp):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | 链名称 | 1PANEL_INPUT, 1PANEL_OUTPUT, 1PANEL_BASIC |
| operate | string | ✅ | 操作类型 | init-base, init-forward, init-advance, bind-base, unbind-base, bind, unbind |

---

### POST /hosts/firewall/filter/rule/batch
**功能**: Batch operate iptables filter rules

**请求参数** (IptablesBatchOperate):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| rules | array | - | 规则列表 (IptablesRuleOp 数组) |

**规则参数** (IptablesRuleOp):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | ✅ | 操作类型 | add, remove |
| chain | string | ✅ | 链名称 | 1PANEL_BASIC, 1PANEL_BASIC_BEFORE, 1PANEL_INPUT, 1PANEL_OUTPUT |
| protocol | string | - | 协议 | tcp, udp 等 |
| srcIP | string | - | 源 IP | - |
| srcPort | uint | - | 源端口 | - |
| dstIP | string | - | 目标 IP | - |
| dstPort | uint | - | 目标端口 | - |
| strategy | string | ✅ | 策略 | accept, drop, reject |
| description | string | - | 描述 | - |

---

### POST /hosts/firewall/filter/rule/operate
**功能**: Operate iptables filter rule

**请求参数** (IptablesRuleOp):
同 batch 参数

---

### POST /hosts/firewall/filter/search
**功能**: search iptables filter rules

**请求参数** (SearchPageWithType):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | ✅ | 页码 | - |
| pageSize | int | ✅ | 每页数量 | - |
| info | string | - | 搜索关键词 | - |
| type | string | - | 规则类型 | - |

---

### POST /hosts/firewall/forward
**功能**: Operate forward rule

**请求参数** (ForwardRuleOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| forceDelete | bool | - | 强制删除 | true/false |
| rules | array | - | 规则列表 | - |

**规则参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | ✅ | 操作类型 | add, remove |
| num | string | - | 规则编号 | - |
| protocol | string | ✅ | 协议 | tcp, udp, tcp/udp |
| interface | string | - | 网络接口 | - |
| port | string | ✅ | 源端口 | - |
| targetIP | string | - | 目标 IP | - |
| targetPort | string | ✅ | 目标端口 | - |

---

### POST /hosts/firewall/ip
**功能**: Operate Ip rule

**请求参数** (AddrRuleOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | - | 规则 ID | - |
| operation | string | ✅ | 操作类型 | add, remove |
| address | string | ✅ | IP 地址 | - |
| strategy | string | ✅ | 策略 | accept, drop |
| description | string | - | 描述 | - |

---

### POST /hosts/firewall/operate
**功能**: Operate firewall

**请求参数** (FirewallOperation):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | ✅ | 操作类型 | start, stop, restart, disableBanPing, enableBanPing |
| withDockerRestart | bool | - | 是否同时重启 Docker | true/false |

---

### POST /hosts/firewall/port
**功能**: Create group (端口规则操作)

**请求参数** (PortRuleOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | - | 规则 ID | - |
| operation | string | ✅ | 操作类型 | add, remove |
| chain | string | - | 链 | - |
| address | string | - | IP 地址 | - |
| port | string | ✅ | 端口号 | - |
| protocol | string | ✅ | 协议 | tcp, udp, tcp/udp |
| strategy | string | ✅ | 策略 | accept, drop |
| description | string | - | 描述 | - |

---

### POST /hosts/firewall/search
**功能**: Page firewall rules

**请求参数** (RuleSearch):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | ✅ | 页码 | - |
| pageSize | int | ✅ | 每页数量 | - |
| info | string | - | 搜索关键词 | - |
| status | string | - | 状态 | - |
| strategy | string | - | 策略 | accept, drop |
| type | string | ✅ | 规则类型 | port, addr, forward |

---

### POST /hosts/firewall/update/addr
**功能**: Update Ip rule

**请求参数** (AddrRuleUpdate):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| oldRule | object | ✅ | 旧规则 (AddrRuleOperate) |
| newRule | object | ✅ | 新规则 (AddrRuleOperate) |

---

### POST /hosts/firewall/update/description
**功能**: Update rule description

**请求参数** (UpdateFirewallDescription):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | - | 规则类型 | - |
| chain | string | - | 链 | - |
| srcIP | string | - | 源 IP | - |
| dstIP | string | - | 目标 IP | - |
| srcPort | string | - | 源端口 | - |
| dstPort | string | - | 目标端口 | - |
| protocol | string | - | 协议 | - |
| strategy | string | ✅ | 策略 | accept, drop |
| description | string | - | 描述 | - |

---

### POST /hosts/firewall/update/port
**功能**: Update port rule

**请求参数** (PortRuleUpdate):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| oldRule | object | ✅ | 旧规则 (PortRuleOperate) |
| newRule | object | ✅ | 新规则 (PortRuleOperate) |

---

### POST /hosts/monitor/clean
**功能**: Clean monitor data

**说明**: 清空所有监控数据，无需请求参数

---

### POST /hosts/monitor/gpu/search
**功能**: Load GPU monitor data

**请求参数** (MonitorGPUSearch):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| productName | string | - | GPU 产品名称 |
| startTime | time | ✅ | 开始时间 |
| endTime | time | ✅ | 结束时间 |

**响应参数** (MonitorGPUData):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| date | array | 时间列表 |
| gpuValue | array | GPU 使用率 |
| temperatureValue | array | 温度 |
| powerTotal | array | 总功率 |
| powerUsed | array | 使用功率 |
| powerPercent | array | 功率百分比 |
| memoryTotal | array | 总显存 |
| memoryUsed | array | 已用显存 |
| memoryPercent | array | 显存百分比 |
| speedValue | array | 速度 |
| processCount | array | 进程数 |
| gpuProcesses | array | GPU 进程列表 |

---

### POST /hosts/monitor/search
**功能**: Load monitor data

**请求参数** (MonitorSearch):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| param | string | ✅ | 监控指标 | all, cpu, memory, load, io, network |
| io | string | - | IO 设备名 | - |
| network | string | - | 网卡名 | - |
| startTime | time | ✅ | 开始时间 | - |
| endTime | time | ✅ | 结束时间 | - |

**响应参数** ([]MonitorData):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| param | string | 监控指标 |
| date | array | 时间列表 |
| value | array | 监控值 |

---

### POST /hosts/monitor/setting/update
**功能**: Update monitor setting

**请求参数** (MonitorSettingUpdate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | ✅ | 设置项 | MonitorStatus, MonitorStoreDays, MonitorInterval, DefaultNetwork, DefaultIO |
| value | string | ✅ | 设置值 | - |

---

### GET /hosts/monitor/gpuoptions
**功能**: Get CPU/GPU options

**响应参数** (MonitorGPUOptions):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| gpuType | string | GPU 类型 |
| chartHide | array | 隐藏图表列表 |
| options | array | 可选 GPU 列表 |

---

### GET /hosts/monitor/netoptions
**功能**: Get network options

**响应参数** ([]string):
| 说明 |
|------|
| 网卡列表 (包含 "all" 选项) |

---

### GET /hosts/monitor/iooptions
**功能**: Get IO options

**响应参数** ([]string):
| 说明 |
|------|
| IO 设备列表 (包含 "all" 选项) |

---

### POST /hosts/ssh/cert
**功能**: Generate host SSH secret

**请求参数** (RootCertOperate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | - | 证书 ID | - |
| name | string | - | 证书名称 | - |
| mode | string | - | 模式 | - |
| encryptionMode | string | ✅ | 加密类型 | rsa, ed25519, ecdsa, dsa |
| passPhrase | string | - | 密码短语 (Base64 编码) | - |
| publicKey | string | - | 公钥 (Base64 编码) | - |
| privateKey | string | - | 私钥 (Base64 编码) | - |
| description | string | - | 描述 | - |

---

### POST /hosts/ssh/cert/delete
**功能**: Delete host SSH secret

**请求参数** (ForceDelete):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | array | ✅ | 证书 ID 列表 |
| forceDelete | bool | - | 强制删除 |

---

### POST /hosts/ssh/cert/search
**功能**: Load host SSH secret

**请求参数** (SearchWithPage):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | ✅ | 页码 |
| pageSize | int | ✅ | 每页数量 |
| info | string | - | 搜索关键词 |

**响应参数** (RootCert):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | uint | 证书 ID |
| createdAt | time | 创建时间 |
| name | string | 证书名称 |
| encryptionMode | string | 加密类型 |
| passPhrase | string | 密码短语 |
| publicKey | string | 公钥 |
| privateKey | string | 私钥 |
| description | string | 描述 |

---

### POST /hosts/ssh/cert/sync
**功能**: Sync host SSH secret

**说明**: 同步 SSH 密钥，无需请求参数

---

### POST /hosts/ssh/cert/update
**功能**: Update host SSH secret

**请求参数** (RootCertOperate):
同 cert 接口参数

---

### POST /hosts/ssh/file
**功能**: Load host SSH conf

**请求参数** (OperationWithName):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | 文件名 | sshd_config |

**响应参数**: SSH 配置文件内容 (string)

---

### POST /hosts/ssh/file/update
**功能**: Update host SSH setting by file

**请求参数** (SettingUpdate):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| key | string | ✅ | 配置项 |
| value | string | - | 配置值 |

---

### POST /hosts/ssh/log
**功能**: Load host SSH logs

**请求参数** (SearchSSHLog):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | ✅ | 页码 | - |
| pageSize | int | ✅ | 每页数量 | - |
| info | string | - | 搜索关键词 | - |
| status | string | ✅ | 登录状态 | Success, Failed, All |

**响应参数** (SSHHistory):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| date | time | 登录时间 |
| dateStr | string | 时间字符串 |
| area | string | 地区 |
| user | string | 用户名 |
| authMode | string | 认证方式 |
| address | string | IP 地址 |
| port | string | 端口 |
| status | string | 状态 |
| message | string | 消息 |

---

### POST /hosts/ssh/log/export
**功能**: Export host SSH logs

**请求参数** (SearchSSHLog):
同 log 接口参数

**响应参数**: 导出文件路径 (string)

---

### POST /hosts/ssh/operate
**功能**: Operate SSH

**请求参数** (Operate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | ✅ | 操作类型 | start, stop, restart |

---

### POST /hosts/ssh/search
**功能**: Load host SSH setting info

**响应参数** (SSHInfo):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| autoStart | bool | 开机自启 |
| isExist | bool | 是否存在 |
| isActive | bool | 是否激活 |
| message | string | 消息 |
| port | string | 端口 |
| listenAddress | string | 监听地址 |
| passwordAuthentication | string | 密码认证 |
| pubkeyAuthentication | string | 公钥认证 |
| permitRootLogin | string | Root 登录 |
| useDNS | string | 使用 DNS |
| currentUser | string | 当前用户 |

---

### POST /hosts/ssh/update
**功能**: Update host SSH setting

**请求参数** (SSHUpdate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | ✅ | 配置项 | Port, ListenAddress, PasswordAuthentication, PubkeyAuthentication, PermitRootLogin, UseDNS 等 |
| oldValue | string | - | 旧值 | - |
| newValue | string | - | 新值 | - |

---

### POST /hosts/tool
**功能**: Get tool status

**请求参数** (HostToolReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✅ | 工具类型 | supervisord |
| operate | string | - | 操作类型 | status, restart, start, stop |

**响应参数** (HostToolRes):
| 参数名 | 类型 | 说明 |
|--------|------|------|
| type | string | 工具类型 |
| config | object | 工具配置 (Supervisor) |

**Supervisor 配置**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| configPath | string | 配置路径 |
| includeDir | string | 包含目录 |
| logPath | string | 日志路径 |
| isExist | bool | 是否存在 |
| init | bool | 是否初始化 |
| msg | string | 消息 |
| version | string | 版本 |
| status | string | 状态 |
| ctlExist | bool | 控制命令是否存在 |
| serviceName | string | 服务名称 |

---

### POST /hosts/tool/config
**功能**: Get tool config

**请求参数** (HostToolConfig):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✅ | 工具类型 | supervisord |
| operate | string | - | 操作类型 | get, set |
| content | string | - | 配置内容 | - |

**响应参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| content | string | 配置文件内容 |

---

### POST /hosts/tool/init
**功能**: Create Host tool Config

**请求参数** (HostToolCreate):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✅ | 工具类型 | supervisord |
| configPath | string | - | Supervisor 配置文件路径 | - |
| serviceName | string | - | Supervisor 服务名称 | - |

---

### POST /hosts/tool/operate
**功能**: Operate tool

**请求参数** (HostToolReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | ✅ | 工具类型 | supervisord |
| operate | string | - | 操作类型 | status, restart, start, stop |

---

### POST /hosts/tool/supervisor/process
**功能**: Create Supervisor process

**请求参数** (SupervisorProcessConfig):
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | - | 进程名称 |
| operate | string | - | 操作类型 |
| command | string | - | 启动命令 |
| user | string | - | 运行用户 |
| dir | string | - | 工作目录 |
| numprocs | string | - | 进程数量 |
| autoRestart | string | - | 自动重启 (true/false) |
| autoStart | string | - | 开机自启 (true/false) |
| environment | string | - | 环境变量 |

---

### POST /hosts/tool/supervisor/process/file
**功能**: Get Supervisor process config file

**请求参数** (SupervisorProcessFileReq):
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | ✅ | 进程名称 | - |
| operate | string | ✅ | 操作类型 | get, clear, update |
| content | string | - | 文件内容 | - |
| file | string | ✅ | 文件类型 | out.log, err.log, config |

**响应参数**: 配置文件内容 (string)

---

### GET /hosts/terminal
**功能**: WebSocket SSH 终端

**说明**: 通过 WebSocket 协议建立 SSH 连接



path: docs/SKILL-logs.md
content: # Logs, TaskLog - 1Panel API

## 模块说明
Logs 模块提供系统日志文件查询和任务日志分页查询功能。

## 接口列表 (3 个)

---

### GET /logs/system/files
**功能**: 获取系统日志文件列表

**说明**: 返回服务器上所有可用的系统日志文件路径列表。

**请求参数**: 无

**返回示例**:
```json
[
  "/var/log/syslog",
  "/var/log/nginx/access.log",
  "/var/log/nginx/error.log"
]
```

---

### POST /logs/tasks/search
**功能**: 分页查询任务日志

**说明**: 分页获取任务执行记录，支持按状态和类型筛选。

**请求参数 (SearchTaskLogReq)**:

| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| status | string | 否 | 任务状态筛选 | `running`, `success`, `failed`, `waiting` |
| type | string | 否 | 任务类型筛选 | 任意任务类型字符串 |
| page | int | 是 | 页码 | >= 1 |
| pageSize | int | 是 | 每页大小 | 1-100 |

**请求体示例**:
```json
{
  "status": "success",
  "type": "backup",
  "page": 1,
  "pageSize": 10
}
```

**返回字段 (Task)**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 任务唯一标识 |
| name | string | 任务名称 |
| type | string | 任务类型 |
| operate | string | 操作类型 |
| logFile | string | 日志文件路径 |
| status | string | 任务状态 |
| errorMsg | string | 错误信息 |
| operationLogID | uint | 操作日志ID |
| resourceID | uint | 资源ID |
| currentStep | string | 当前步骤 |
| endAt | time | 结束时间 |
| createdAt | time | 创建时间 |

---

### GET /logs/tasks/executing/count
**功能**: 获取当前正在执行的任务数量

**说明**: 返回当前处于 running 状态的任务总数。

**请求参数**: 无

**返回示例**:
```json
3
```

---

## 补充说明

### 任务状态说明
- `waiting`: 等待执行
- `running`: 执行中
- `success`: 执行成功
- `failed`: 执行失败

### 通用分页参数
所有分页接口使用以下通用结构：
```json
{
  "page": 1,
  "pageSize": 10
}
```

### 返回格式 (PageResult)
```json
{
  "items": [],
  "total": 100
}
```


path: docs/SKILL-openresty.md
content: # OpenResty - 1Panel API

## 模块说明
OpenResty 模块接口

## 接口列表 (10 个)

---

### GET /openresty
**功能**: Load OpenResty conf
**说明**: 获取 OpenResty 完整配置文件

**参数**: 无

**返回**: NginxFile 对象

---

### GET /openresty/https
**功能**: Get default HTTPs status
**说明**: 获取默认 HTTPS 配置状态

**参数**: 无

**返回**: NginxConfigRes 对象

---

### GET /openresty/modules
**功能**: Get OpenResty modules
**说明**: 获取已安装的 OpenResty 模块列表

**参数**: 无

**返回**: NginxBuildConfig 对象

---

### GET /openresty/status
**功能**: Load OpenResty status info
**说明**: 获取 OpenResty 运行状态信息

**参数**: 无

**返回**: NginxStatus 对象

---

### POST /openresty/build
**功能**: Build OpenResty
**说明**: 编译构建 OpenResty

**参数 (NginxBuildReq)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| taskID | string | 是 | 任务ID，用于跟踪构建进度 | - |
| mirror | string | 是 | 镜像源地址 | - |

---

### POST /openresty/file
**功能**: Update OpenResty conf by upload file
**说明**: 通过上传文件方式更新 OpenResty 配置

**参数 (NginxConfigFileUpdate)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| content | string | 是 | 配置文件完整内容 | - |
| backup | bool | 否 | 是否在更新前备份原配置 | true/false |

---

### POST /openresty/https
**功能**: Operate default HTTPs
**说明**: 启用或禁用默认 HTTPS 配置

**参数 (NginxDefaultHTTPSUpdate)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| operate | string | 是 | 操作类型 | `enable`, `disable` |
| sslRejectHandshake | bool | 否 | 是否拒绝 SSL 握手 | true/false |

---

### POST /openresty/modules/update
**功能**: Update OpenResty module
**说明**: 创建、更新或删除 OpenResty 模块

**参数 (NginxModuleUpdate)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| operate | string | 是 | 操作类型 | `create`, `delete`, `update` |
| name | string | 是 | 模块名称 | - |
| script | string | 否 | 模块初始化脚本 | - |
| packages | string | 否 | 依赖包列表，多个包用空格分隔 | - |
| enable | bool | 否 | 是否启用该模块 | true/false |
| params | string | 否 | 模块额外参数 | - |

---

### POST /openresty/scope
**功能**: Load partial OpenResty conf
**说明**: 根据指定范围获取部分 OpenResty 配置

**参数 (NginxScopeReq)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| scope | NginxKey | 是 | 配置范围类型 | 见下方 NginxKey 取值 |
| websiteId | uint | 否 | 网站ID，范围为 website 时需要 | - |

**NginxKey 取值范围**:

| 值 | 说明 |
|----|------|
| `index` | 首页配置 |
| `limit-conn` | 连接限流配置 |
| `ssl` | SSL 证书配置 |
| `cache` | 缓存配置 |
| `http-per` | HTTP 性能配置 |
| `proxy-cache` | 代理缓存配置 |

---

### POST /openresty/update
**功能**: Update OpenResty conf
**说明**: 根据范围更新 OpenResty 配置

**参数 (NginxConfigUpdate)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| scope | NginxKey | 否 | 配置范围类型 | 同上 NginxKey 取值 |
| operate | string | 是 | 操作类型 | `add`, `update`, `delete` |
| websiteId | uint | 否 | 网站ID | - |
| params | interface{} | 否 | 具体参数值，类型根据 scope 而定 | - |

**scope 对应 params 结构**:

- `index`: 数组，如 `["index.php", "index.html"]`
- `limit-conn`: 对象，如 `{"limit_conn": 10, "limit_rate": 100}`
- `ssl`: 对象，如 `{"ssl_certificate": "/path/to/cert"}`
- `http-per`: 对象，如 `{"client_max_body_size": "100m", "keepalive_timeout": 60}`

---

## 枚举值参考

### NginxKey 范围键
```go
const (
    Index      NginxKey = "index"
    LimitConn  NginxKey = "limit-conn"
    SSL        NginxKey = "ssl"
    CACHE      NginxKey = "cache"
    HttpPer    NginxKey = "http-per"
    ProxyCache NginxKey = "proxy-cache"
)
```

### 操作类型 operate
- **模块操作**: `create`, `delete`, `update`
- **HTTPS操作**: `enable`, `disable`
- **配置操作**: `add`, `update`, `delete`

### 负载均衡算法
```go
var LBAlgorithms = map[string]struct{}{
    "ip_hash": {},    // IP 哈希
    "least_conn": {}, // 最少连接
}
```


path: docs/SKILL-process.md
content: # Process - 1Panel API

## 模块说明
Process 模块提供进程管理功能，包括实时进程监控、进程终止、端口监听查询等。

## 接口列表 (4 个)

---

### GET /process/ws
**功能**: WebSocket 实时进程监控
**描述**: 建立 WebSocket 连接，实时获取系统进程信息

**参数**: 无

**WebSocket 消息格式**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| type | string | 是 | 请求类型 | `ps`, `wget`, `ssh`, `net` |
| pid | int32 | 否 | 按 PID 过滤 | > 0 |
| name | string | 否 | 按进程名过滤（模糊匹配） | - |
| username | string | 否 | 按用户名过滤（模糊匹配） | - |

**type=ps 请求示例**:
```json
{"type":"ps","pid":0,"name":"","username":""}
```

**type=net 请求示例**:
```json
{"type":"net","port":0,"processName":"","processID":0}
```

**WebSocket 响应 (type=ps)**:
```json
[
  {
    "PID": 1234,
    "name": "nginx",
    "PPID": 1,
    "username": "root",
    "status": "R",
    "startTime": "2024-01-01 12:00:00",
    "numThreads": 10,
    "numConnections": 5,
    "cpuPercent": "2.50%",
    "cpuValue": 2.5,
    "diskRead": "1.5 MB",
    "diskWrite": "512 KB",
    "cmdLine": "/usr/sbin/nginx -g 'daemon off;'",
    "rss": "50 MB",
    "rssValue": 52428800,
    "vms": "200 MB",
    "hwm": "80 MB",
    "data": "30 MB",
    "stack": "1 MB",
    "locked": "0 B",
    "swap": "0 B",
    "dirty": "0 B",
    "pss": "45 MB",
    "uss": "35 MB",
    "shared": "10 MB",
    "text": "5 MB",
    "envs": ["PATH=/usr/local/bin", ...],
    "openFiles": [...],
    "connects": [...]
  }
]
```

---

### POST /process/stop
**功能**: 终止指定进程
**描述**: 根据 PID 终止进程

**参数 (Body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| PID | int32 | 是 | 进程 ID | > 0 |

**请求示例**:
```json
{"PID": 1234}
```

**响应**: 
```json
{"status":"success","message":""}
```

**错误响应**:
```json
{"status":"error","message":"process not found"}
```

---

### POST /process/listening
**功能**: 获取监听端口的进程列表
**描述**: 查询所有正在监听网络端口的进程，返回进程 ID、端口号、协议和进程名

**参数**: 无

**响应**:
```json
[
  {
    "PID": 1234,
    "Port": { "80": {}, "443": {} },
    "Protocol": 1,
    "Name": "nginx"
  }
]
```

**响应字段说明**:

| 字段 | 类型 | 说明 |
|------|------|------|
| PID | int32 | 进程 ID |
| Port | map[uint32]struct{} | 监听的端口号集合 |
| Protocol | uint32 | 协议类型 (1=SOCK_STREAM/TCP, 2=SOCK_DGRAM/UDP) |
| Name | string | 进程名称 |

---

### GET /process/{pid}
**功能**: 获取指定进程的详细信息
**描述**: 根据 PID 获取进程的详细属性信息

**参数 (Path)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| pid | int32 | 是 | 进程 ID | > 0 |

**响应**:
```json
{
  "PID": 1234,
  "name": "nginx",
  "PPID": 1,
  "username": "root",
  "status": "R",
  "startTime": "2024-01-01 12:00:00",
  "numThreads": 10,
  "numConnections": 5,
  "cpuPercent": "2.50%",
  "cpuValue": 2.5,
  "diskRead": "1.5 MB",
  "diskWrite": "512 KB",
  "cmdLine": "/usr/sbin/nginx -g 'daemon off;'",
  "rss": "50 MB",
  "rssValue": 52428800,
  "vms": "200 MB",
  "hwm": "80 MB",
  "data": "30 MB",
  "stack": "1 MB",
  "locked": "0 B",
  "swap": "0 B",
  "dirty": "0 B",
  "pss": "45 MB",
  "uss": "35 MB",
  "shared": "10 MB",
  "text": "5 MB",
  "envs": ["PATH=/usr/local/bin", ...],
  "openFiles": [...],
  "connects": [...]
}
```

**响应字段说明**:

| 字段 | 类型 | 说明 |
|------|------|------|
| PID | int32 | 进程 ID |
| name | string | 进程名称 |
| PPID | int32 | 父进程 ID |
| username | string | 进程所属用户 |
| status | string | 进程状态 (R=运行, S=睡眠, Z=僵尸等) |
| startTime | string | 进程启动时间 (格式: YYYY-MM-DD HH:mm:ss) |
| numThreads | int32 | 线程数 |
| numConnections | int | 网络连接数 |
| cpuPercent | string | CPU 占用百分比 (格式化字符串) |
| cpuValue | float64 | CPU 占用数值 |
| diskRead | string | 磁盘读取量 (格式化字符串) |
| diskWrite | string | 磁盘写入量 (格式化字符串) |
| cmdLine | string | 进程命令行完整参数 |
| rss | string | 实际物理内存占用 (Resident Set Size) |
| rssValue | uint64 | 实际物理内存字节数 |
| vms | string | 虚拟内存大小 (Virtual Memory Size) |
| hwm | string | 物理内存峰值 (High Water Mark) |
| data | string | 数据段大小 |
| stack | string | 栈大小 |
| locked | string | 锁定的内存大小 |
| swap | string | 交换空间使用量 |
| dirty | string | 脏页大小 |
| pss | string | Proportional Set Size (比例分配内存) |
| uss | string | Unique Set Size (独占内存) |
| shared | string | 共享内存大小 |
| text | string | 代码段大小 |
| envs | []string | 进程环境变量列表 |
| openFiles | []OpenFilesStat | 打开的文件列表 |
| connects | []ProcessConnect | 网络连接详情列表 |

**ProcessConnect 结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 连接类型 (tcp, tcp6, udp, udp6, unknown) |
| status | string | 连接状态 (LISTEN, ESTABLISHED, TIME_WAIT 等) |
| localaddr | net.Addr | 本地地址 (IP:Port) |
| remoteaddr | net.Addr | 远程地址 (IP:Port) |
| PID | int32 | 进程 ID |
| name | string | 进程名称 |

---

## 使用示例

### 1. WebSocket 实时监控进程列表
```javascript
const ws = new WebSocket('ws://your-1panel-host:65432/api/v1/process/ws');
ws.onopen = () => {
    ws.send(JSON.stringify({ type: 'ps', pid: 0, name: '', username: '' }));
};
ws.onmessage = (event) => {
    const processes = JSON.parse(event.data);
    console.log(processes);
};
```

### 2. 终止进程
```bash
curl -X POST http://your-1panel-host:65432/api/v1/process/stop \
  -H "Content-Type: application/json" \
  -d '{"PID": 1234}'
```

### 3. 查询监听端口的进程
```bash
curl -X POST http://your-1panel-host:65432/api/v1/process/listening
```

### 4. 查看指定进程详情
```bash
curl http://your-1panel-host:65432/api/v1/process/1234
```


path: docs/SKILL-runtimes.md
content: # PHP Extensions, Runtime - 1Panel API

## 模块说明
PHP Extensions, Runtime 模块接口，包含运行时创建、删除、配置、管理等完整功能。

## 接口列表 (31 个)

---

### GET /runtimes/:id
**功能**: Get runtime - 获取运行时详情
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | 运行时 ID |

**响应**: `RuntimeDTO`
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 运行时 ID |
| name | string | 运行时名称 |
| type | string | 运行时类型 (php/node/python/java/go) |
| resource | string | 资源类型 |
| image | string | 容器镜像 |
| version | string | 版本号 |
| status | string | 运行状态 |
| message | string | 状态消息 |
| port | string | 端口 |
| path | string | 路径 |
| codeDir | string | 代码目录 |
| container | string | 容器名称 |
| containerStatus | string | 容器状态 |
| remark | string | 备注 |
| params | map | 运行时参数 |
| exposedPorts | array | 暴露端口列表 |
| environments | array | 环境变量列表 |
| volumes | array | 挂载卷列表 |
| extraHosts | array | 额外 hosts 列表 |
| appParams | array | 应用参数列表 |

---

### GET /runtimes/installed/delete/check/:id
**功能**: Delete runtime check - 检查运行时删除条件
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | 运行时 ID |

---

### POST /runtimes/search
**功能**: List runtimes - 分页查询运行时列表
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeSearch)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| PageInfo | object | 是 | 分页信息 | 见 PageInfo |
| type | string | 否 | 运行时类型 | php/node/python/java/go |
| name | string | 否 | 运行时名称 | 模糊匹配 |
| status | string | 否 | 运行状态 | running/stopped/error |

**PageInfo 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 是 | 页码，从 1 开始 |
| pageSize | int | 是 | 每页数量 |

**响应**: `PageResult<RuntimeDTO>`

---

### POST /runtimes
**功能**: Create runtime - 创建运行时
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeCreate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| appDetailId | uint | 是 | 应用详情 ID | |
| name | string | 是 | 运行时名称 | 唯一标识 |
| type | string | 是 | 运行时类型 | php/node/python/java/go |
| version | string | 是 | 版本号 | 如 8.2, 18, 3.10 |
| resource | string | 否 | 资源类型 | local/remote |
| image | string | 否 | 容器镜像 | 自定义镜像地址 |
| source | string | 否 | 来源 | official/custom |
| codeDir | string | 否 | 代码目录 | 应用代码路径 |
| remark | string | 否 | 备注 | |
| params | map | 否 | 运行时参数 | 键值对配置 |
| install | bool | 否 | 是否安装 | 默认 true |
| clean | bool | 否 | 是否清理 | 默认 false |
| exposedPorts | array | 否 | 暴露端口列表 | |
| environments | array | 否 | 环境变量列表 | |
| volumes | array | 否 | 挂载卷列表 | |
| extraHosts | array | 否 | 额外 hosts 列表 | |

**Environment 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 环境变量名 |
| value | string | 是 | 环境变量值 |

**Volume 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| source | string | 是 | 宿主机路径 |
| target | string | 是 | 容器内路径 |

**ExposedPort 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| hostPort | int | 是 | 宿主机端口 |
| containerPort | int | 是 | 容器端口 |
| hostIP | string | 否 | 绑定 IP，默认 0.0.0.0 |

**ExtraHost 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| hostname | string | 是 | 主机名 |
| ip | string | 是 | IP 地址 |

---

### POST /runtimes/del
**功能**: Delete runtime - 删除运行时
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeDelete)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| forceDelete | bool | 否 | 是否强制删除，默认 false |

---

### POST /runtimes/update
**功能**: Update runtime - 更新运行时
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 运行时 ID | |
| name | string | 否 | 运行时名称 | |
| type | string | 否 | 运行时类型 | php/node/python/java/go |
| version | string | 否 | 版本号 | |
| image | string | 否 | 容器镜像 | |
| source | string | 否 | 来源 | official/custom |
| codeDir | string | 否 | 代码目录 | |
| rebuild | bool | 否 | 是否重建容器 | 默认 false |
| remark | string | 否 | 备注 | |
| params | map | 否 | 运行时参数 | |
| install | bool | 否 | 是否安装 | |
| clean | bool | 否 | 是否清理 | |
| exposedPorts | array | 否 | 暴露端口列表 | |
| environments | array | 否 | 环境变量列表 | |
| volumes | array | 否 | 挂载卷列表 | |
| extraHosts | array | 否 | 额外 hosts 列表 | |

---

### POST /runtimes/operate
**功能**: Operate runtime - 操作运行时（启动/停止/重启）
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeOperate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 运行时 ID | |
| operate | string | 是 | 操作类型 | start/stop/restart |

---

### POST /runtimes/sync
**功能**: Sync runtime status - 同步运行时状态
**参数**: 无

---

### POST /runtimes/node/package
**功能**: Get Node package scripts - 获取 Node.js 包运行脚本
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (NodePackageReq)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| codeDir | string | 是 | 代码目录路径 |

**响应**: `PackageScripts[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 脚本名称 |
| script | string | 脚本内容 |

---

### POST /runtimes/node/modules
**功能**: Get Node modules - 获取 Node.js 模块列表
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (NodeModuleReq)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |

**响应**: `NodeModule[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 模块名称 |
| version | string | 版本号 |
| license | string | 许可证 |
| description | string | 描述 |

---

### POST /runtimes/node/modules/operate
**功能**: Operate Node modules - 操作 Node.js 模块（安装/卸载/更新）
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (NodeModuleOperateReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | 运行时 ID | |
| operate | string | 是 | 操作类型 | install/uninstall/update |
| module | string | 是 | 模块名称 | |
| pkgManager | string | 否 | 包管理器 | npm/yarn，默认 npm |

---

### GET /runtimes/php/:id/extensions
**功能**: Get php runtime extension - 获取 PHP 扩展列表
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | PHP 运行时 ID |

**响应**: `PHPExtensionRes`
| 字段 | 类型 | 说明 |
|------|------|------|
| extensions | array | 已安装的扩展名列表 |
| supportExtensions | array | 支持的扩展列表 |

**SupportExtension 结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 扩展名称 |
| description | string | 扩展描述 |
| installed | bool | 是否已安装 |
| check | string | 检查命令 |
| versions | array | 可用版本列表 |
| file | string | 配置文件 |

---

### POST /runtimes/php/extensions/search
**功能**: Page Extensions - 分页查询 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionsSearch)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| PageInfo | object | 是 | 分页信息 |
| all | bool | 否 | 是否查询所有 |

---

### POST /runtimes/php/extensions
**功能**: Create Extensions - 创建 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionsCreate)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 扩展名称 |
| extensions | string | 是 | 扩展配置 |

---

### POST /runtimes/php/extensions/update
**功能**: Update Extensions - 更新 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionsUpdate)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 扩展 ID |
| extensions | string | 是 | 扩展配置 |

---

### POST /runtimes/php/extensions/del
**功能**: Delete Extensions - 删除 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionsDelete)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 扩展 ID |

---

### POST /runtimes/php/extensions/install
**功能**: Install php extension - 安装 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionInstallReq)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| name | string | 是 | 扩展名称 |
| taskID | string | 否 | 任务 ID |

---

### POST /runtimes/php/extensions/uninstall
**功能**: UnInstall php extension - 卸载 PHP 扩展
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPExtensionInstallReq)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| name | string | 是 | 扩展名称 |
| taskID | string | 否 | 任务 ID |

---

### GET /runtimes/php/config/:id
**功能**: Load php runtime conf - 获取 PHP 配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | PHP 运行时 ID |

**响应**: `PHPConfig`

---

### POST /runtimes/php/config
**功能**: Update runtime php conf - 更新 PHP 配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPConfigUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | PHP 运行时 ID | |
| scope | string | 是 | 配置范围 | php-fpm/php |
| params | map | 否 | 配置参数 | 键值对 |
| disableFunctions | array | 否 | 禁用函数列表 | |
| uploadMaxSize | string | 否 | 上传文件最大尺寸 | 如 50M |
| maxExecutionTime | string | 否 | 最大执行时间 | 如 60 |

---

### POST /runtimes/php/update
**功能**: Update php conf file - 更新 PHP 配置文件
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPFileUpdate)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | PHP 运行时 ID | |
| type | string | 是 | 文件类型 | php/php-fpm |
| content | string | 是 | 文件内容 | 配置内容 |

---

### POST /runtimes/php/file
**功能**: Get php conf file - 获取 PHP 配置文件
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPFileReq)**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | PHP 运行时 ID | |
| type | string | 是 | 文件类型 | php/php-fpm |

**响应**: `FileInfo`
| 字段 | 类型 | 说明 |
|------|------|------|
| content | string | 文件内容 |

---

### GET /runtimes/php/fpm/config/:id
**功能**: Get fpm config - 获取 PHP-FPM 配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | PHP 运行时 ID |

**响应**: `FPMConfig`

---

### POST /runtimes/php/fpm/config
**功能**: Update fpm config - 更新 PHP-FPM 配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (FPMConfig)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | PHP 运行时 ID |
| params | map | 是 | FPM 配置参数 |

---

### GET/php/fpm/status /runtimes/:id
**功能**: Get PHP runtime status - 获取 PHP-FPM 状态
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | PHP 运行时 ID |

**响应**: `FpmStatusItem[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| key | string | 状态项名称 |
| value | interface{} | 状态值 |

---

### POST /runtimes/php/container/update
**功能**: Update PHP container config - 更新 PHP 容器配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPContainerConfig)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | PHP 运行时 ID |
| containerName | string | 否 | 容器名称 |
| exposedPorts | array | 否 | 暴露端口列表 |
| environments | array | 否 | 环境变量列表 |
| volumes | array | 否 | 挂载卷列表 |
| extraHosts | array | 否 | 额外 hosts 列表 |

---

### GET /runtimes/php/container/:id
**功能**: Get PHP container config - 获取 PHP 容器配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | PHP 运行时 ID |

**响应**: `PHPContainerConfig`

---

### GET /runtimes/supervisor/process/:id
**功能**: Get supervisor process - 获取 Supervisor 进程配置
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| id | path | integer | 是 | 运行时 ID |

**响应**: `SupervisorProcessConfig[]`

---

### POST /runtimes/supervisor/process
**功能**: Operate supervisor process - 操作 Supervisor 进程
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPSupervisorProcessConfig)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| SupervisorProcessConfig | object | 是 | Supervisor 进程配置 |

**SupervisorProcessConfig 结构**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| command | string | 是 | 启动命令 |
| user | string | 否 | 运行用户 |
| directory | string | 否 | 工作目录 |
| autostart | bool | 否 | 自动启动 |
| autorestart | bool | 否 | 自动重启 |
| redirectStderr | bool | 否 | 重定向错误输出 |
| stdoutLogFile | string | 否 | 标准输出日志 |
| stderrLogFile | string | 否 | 错误输出日志 |

---

### POST /runtimes/supervisor/process/file
**功能**: Operate supervisor process file - 操作 Supervisor 进程配置文件
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (PHPSupervisorProcessFileReq)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| SupervisorProcessFileReq | object | 是 | 文件操作请求 |

**SupervisorProcessFileReq 结构**:
| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| operation | string | 是 | 操作类型 | get/update |
| name | string | 否 | 进程名称 | |

**响应**: 文件内容或操作结果

---

### POST /runtimes/remark
**功能**: Update runtime remark - 更新运行时备注
**参数**:
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|--------|------|------|------|------|
| request | body | object | 是 | 请求体 |

**request 请求体 (RuntimeRemark)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | uint | 是 | 运行时 ID |
| remark | string | 是 | 备注内容 |

---

## 通用结构说明

### PageInfo (分页信息)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 是 | 页码，从 1 开始 |
| pageSize | int | 是 | 每页数量，默认 20 |

### PageResult (分页结果)
| 字段 | 类型 | 说明 |
|------|------|------|
| total | int64 | 总数 |
| items | array | 数据列表 |

### ExposedPort (暴露端口)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| hostPort | int | 是 | 宿主机端口 |
| containerPort | int | 是 | 容器端口 |
| hostIP | string | 否 | 绑定 IP，默认 0.0.0.0 |

### Environment (环境变量)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 环境变量名 |
| value | string | 是 | 环境变量值 |

### Volume (挂载卷)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| source | string | 是 | 宿主机路径 |
| target | string | 是 | 容器内路径 |

### ExtraHost (额外 hosts)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| hostname | string | 是 | 主机名 |
| ip | string | 是 | IP 地址 |

## 运行时类型 (Type 取值)
- `php` - PHP 运行环境
- `node` - Node.js 运行环境
- `python` - Python 运行环境
- `java` - Java 运行环境
- `go` - Go 运行环境

## 运行状态 (Status 取值)
- `running` - 运行中
- `stopped` - 已停止
- `error` - 错误状态
- `installing` - 安装中
- `unknown` - 未知

## 操作类型 (Operate 取值)
- `start` - 启动
- `stop` - 停止
- `restart` - 重启

## Node 模块操作类型
- `install` - 安装
- `uninstall` - 卸载
- `update` - 更新


path: docs/SKILL-script.md
content: # ScriptLibrary, Command - 1Panel API

## 模块说明
ScriptLibrary, Command 模块接口

## 接口列表 (13 个)

---

### GET /core/commands/command
**功能**: List commands - 获取命令列表

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 命令类型 | `redis`, `command` |

**请求体示例**:
```json
{
  "type": "command"
}
```

**响应参数**: 返回 `CommandInfo[]` 数组

---

### GET /core/commands/tree
**功能**: Tree commands - 获取命令树形结构

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| type | string | 是 | 命令类型 | `redis`, `command` |

**请求体示例**:
```json
{
  "type": "command"
}
```

**响应参数**: 返回 `CommandTree[]` 数组，包含树形结构

---

### POST /core/commands
**功能**: Create command - 创建快捷命令

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 否 | 命令ID（更新时必填） | - |
| type | string | 否 | 命令类型 | `redis`, `command` |
| groupID | uint | 否 | 分组ID | - |
| groupBelong | string | 否 | 所属分组名称 | - |
| name | string | 是 | 命令名称 | - |
| command | string | 是 | 命令内容 | - |

**请求体示例**:
```json
{
  "name": "查看进程",
  "command": "ps aux"
}
```

---

### POST /core/commands/del
**功能**: Delete command - 删除快捷命令

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | []uint | 是 | 要删除的命令ID数组 |

**请求体示例**:
```json
{
  "ids": [1, 2, 3]
}
```

---

### POST /core/commands/export
**功能**: Export command - 导出快捷命令

**请求参数**: 无

**响应参数**: 返回导出文件路径

---

### POST /core/commands/import
**功能**: Import command - 导入快捷命令

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| items | []CommandOperate | 是 | 命令列表 |

**CommandOperate 结构**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 否 | 命令ID |
| type | string | 否 | 命令类型 |
| groupID | uint | 否 | 分组ID |
| groupBelong | string | 否 | 所属分组 |
| name | string | 是 | 命令名称 |
| command | string | 是 | 命令内容 |

**请求体示例**:
```json
{
  "items": [
    {
      "name": "查看内存",
      "command": "free -h"
    }
  ]
}
```

---

### POST /core/commands/search
**功能**: Page commands - 分页查询命令

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| orderBy | string | 是 | 排序字段 | `name`, `command`, `createdAt` |
| order | string | 是 | 排序方式 | `null`, `ascending`, `descending` |
| groupID | uint | 否 | 分组ID | - |
| type | string | 是 | 命令类型 | `redis`, `command` |
| info | string | 否 | 搜索关键词 | - |

**请求体示例**:
```json
{
  "page": 1,
  "pageSize": 10,
  "orderBy": "createdAt",
  "order": "descending",
  "type": "command"
}
```

**响应参数**: 返回分页结果 `PageResult` { total: int64, items: []CommandInfo }

---

### POST /core/commands/update
**功能**: Update command - 更新快捷命令

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 命令ID | - |
| type | string | 否 | 命令类型 | `redis`, `command` |
| groupID | uint | 否 | 分组ID | - |
| groupBelong | string | 否 | 所属分组名称 | - |
| name | string | 是 | 命令名称 | - |
| command | string | 是 | 命令内容 | - |

**请求体示例**:
```json
{
  "id": 1,
  "name": "更新后的命令名称",
  "command": "updated command"
}
```

---

### POST /core/script
**功能**: Add script - 添加脚本

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 否 | 脚本ID（更新时必填） |
| isInteractive | bool | 否 | 是否交互式脚本 |
| name | string | 是 | 脚本名称 |
| script | string | 是 | 脚本内容 |
| groups | string | 否 | 所属分组（多个用逗号分隔） |
| description | string | 否 | 脚本描述 |

**请求体示例**:
```json
{
  "name": "备份脚本",
  "script": "#!/bin/bash\necho 'backup'",
  "description": "用于备份的脚本"
}
```

---

### POST /core/script/del
**功能**: Delete script - 删除脚本

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | []uint | 是 | 要删除的脚本ID数组 |

**请求体示例**:
```json
{
  "ids": [1, 2, 3]
}
```

---

### POST /core/script/search
**功能**: Page script - 分页查询脚本

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 是 | 页码 |
| pageSize | int | 是 | 每页数量 |
| groupID | uint | 否 | 分组ID |
| info | string | 否 | 搜索关键词 |

**请求体示例**:
```json
{
  "page": 1,
  "pageSize": 10,
  "info": "备份"
}
```

**响应参数**: 返回分页结果 `PageResult` { total: int64, items: []ScriptInfo }

---

### POST /core/script/sync
**功能**: Sync script - 同步远程脚本

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskID | string | 是 | 任务ID |

**请求体示例**:
```json
{
  "taskID": "sync-123"
}
```

---

### POST /core/script/update
**功能**: Update script - 更新脚本

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | uint | 是 | 脚本ID |
| isInteractive | bool | 否 | 是否交互式脚本 |
| name | string | 是 | 脚本名称 |
| script | string | 是 | 脚本内容 |
| groups | string | 否 | 所属分组 |
| description | string | 否 | 脚本描述 |

**请求体示例**:
```json
{
  "id": 1,
  "name": "更新后的脚本名称",
  "script": "#!/bin/bash\necho 'updated'",
  "description": "更新后的描述"
}
```

---

## 公共类型定义

### PageInfo
分页信息
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 是 | 页码，从1开始 |
| pageSize | int | 是 | 每页记录数 |

### PageResult
分页结果
| 字段 | 类型 | 说明 |
|------|------|------|
| total | int64 | 总记录数 |
| items | interface{} | 数据列表 |

### CommandInfo
命令信息
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 命令ID |
| groupID | uint | 分组ID |
| name | string | 命令名称 |
| type | string | 命令类型 |
| command | string | 命令内容 |
| groupBelong | string | 所属分组 |

### CommandTree
命令树结构
| 字段 | 类型 | 说明 |
|------|------|------|
| label | string | 显示名称 |
| value | string | 值 |
| children | []CommandTree | 子节点 |

### ScriptInfo
脚本信息
| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 脚本ID |
| name | string | 脚本名称 |
| isInteractive | bool | 是否交互式 |
| lable | string | 标签 |
| script | string | 脚本内容 |
| groupList | []uint | 分组ID列表 |
| groupBelong | []string | 所属分组名称列表 |
| isSystem | bool | 是否系统脚本 |
| description | string | 脚本描述 |
| createdAt | time.Time | 创建时间 |


path: docs/SKILL-settings.md
content: # Menu Setting, System Setting - 1Panel API

## 模块说明
Menu Setting, System Setting 模块接口，包含系统设置、快照管理、SSH连接配置等功能。

## 接口列表 (26 个)

---

### POST /settings/search
**功能**: Load system setting info - 获取系统设置信息

**请求参数**: 无 (不需要请求体)

**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| dockerSockPath | string | Docker socket 路径 |
| systemVersion | string | 系统版本 |
| systemIP | string | 系统 IP 地址 |
| localTime | string | 本地时间 |
| timeZone | string | 时区 |
| ntpSite | NTP 服务器地址 |
| defaultNetwork | string | 默认网络类型 |
| defaultIO | string | 默认 IO 调度器 |
| lastCleanTime | string | 上次清理时间 |
| lastCleanSize | string | 上次清理大小 |
| lastCleanData | string | 上次清理数据类型 |
| monitorStatus | string | 监控状态 (enable/disable) |
| monitorInterval | string | 监控间隔 |
| monitorStoreDays | string | 监控数据保留天数 |
| appStoreVersion | string | 应用商店版本 |
| appStoreLastModified | string | 应用商店最后修改时间 |
| appStoreSyncStatus | string | 应用商店同步状态 |
| fileRecycleBin | string | 文件回收站状态 |

---

### GET /settings/search/available
**功能**: Load system available status - 获取系统可用状态

**请求参数**: 无

**返回参数**: 无 (返回 200 表示系统可用)

---

### POST /settings/update
**功能**: Update system setting - 更新系统设置

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| key | string | 是 | 设置项键名 | validate:"required" |
| value | string | 否 | 设置项值 | - |

**常见 key 值**:
- `DockerSockPath` - Docker socket 路径
- `SystemIP` - 系统 IP
- `TimeZone` - 时区
- `NtpSite` - NTP 服务器
- `MonitorStatus` - 监控状态 (enable/disable)
- `MonitorInterval` - 监控间隔
- `MonitorStoreDays` - 监控数据保留天数
- `AppStoreVersion` - 应用商店版本
- `FileRecycleBin` - 文件回收站

---

### GET /settings/get/{key}
**功能**: Load system setting by key - 根据键名获取系统设置

**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 设置项键名 |

**返回参数**: string (设置项的值)

---

### GET /settings/basedir
**功能**: Load local backup dir - 获取本地备份目录

**请求参数**: 无

**返回参数**: string (备份目录路径)

---

### POST /settings/description/save
**功能**: Save common description - 保存通用描述

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| id | string | 是 | 关联 ID | validate:"required" |
| type | string | 是 | 类型 | validate:"required" |
| detailType | string | 否 | 详细类型 | - |
| isPinned | boolean | 否 | 是否置顶 | - |
| description | string | 否 | 描述内容 | - |

---

### GET /settings/snapshot/load
**功能**: Load system snapshot data - 加载系统快照数据

**请求参数**: 无

**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| appData | array | 应用数据树 |
| backupData | array | 备份数据树 |
| panelData | array | 面板数据树 |
| withDockerConf | boolean | 是否包含 Docker 配置 |
| withMonitorData | boolean | 是否包含监控数据 |
| withLoginLog | boolean | 是否包含登录日志 |
| withOperationLog | boolean | 是否包含操作日志 |
| withSystemLog | boolean | 是否包含系统日志 |
| withTaskLog | boolean | 是否包含任务日志 |
| ignoreFiles | array | 忽略文件列表 |

**DataTree 子结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 节点 ID |
| label | string | 显示标签 |
| key | string | 键名 |
| name | string | 名称 |
| isLocal | boolean | 是否本地 |
| size | number | 大小 |
| isCheck | boolean | 是否选中 |
| isDisable | boolean | 是否禁用 |
| path | string | 路径 |
| relationItemID | string | 关联项 ID |
| children | array | 子节点 |

---

### POST /settings/snapshot
**功能**: Create system snapshot - 创建系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| id | number | 否 | 快照 ID | - |
| name | string | 否 | 快照名称 | - |
| taskID | string | 否 | 任务 ID | - |
| sourceAccountIDs | string | 是 | 源账户 ID 列表 | validate:"required" |
| downloadAccountID | number | 是 | 下载账户 ID | validate:"required" |
| description | string | 否 | 描述 | validate:"max=256" |
| secret | string | 否 | 密钥 | - |
| interruptStep | string | 否 | 中断步骤 | - |
| timeout | number | 否 | 超时时间(秒) | - |
| appData | array | 否 | 应用数据 | - |
| backupData | array | 否 | 备份数据 | - |
| panelData | array | 否 | 面板数据 | - |
| withDockerConf | boolean | 否 | 包含 Docker 配置 | - |
| withMonitorData | boolean | 否 | 包含监控数据 | - |
| withLoginLog | boolean | 否 | 包含登录日志 | - |
| withOperationLog | boolean | 否 | 包含操作日志 | - |
| withSystemLog | boolean | 否 | 包含系统日志 | - |
| withTaskLog | boolean | 否 | 包含任务日志 | - |
| ignoreFiles | array | 否 | 忽略文件列表 | - |

---

### POST /settings/snapshot/recreate
**功能**: Recreate system snapshot - 重新创建系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| id | number | 是 | 快照 ID | validate:"required" |

---

### POST /settings/snapshot/search
**功能**: Page system snapshot - 分页查询系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| page | number | 是 | 页码 | validate:"required,number" |
| pageSize | number | 是 | 每页数量 | validate:"required,number" |
| info | string | 否 | 搜索关键词 | - |
| orderBy | string | 是 | 排序字段 | validate:"required,oneof=name createdAt" |
| order | string | 是 | 排序方向 | validate:"required,oneof=null ascending descending" |

**返回参数** (PageResult):
| 字段 | 类型 | 说明 |
|------|------|------|
| total | number | 总数 |
| items | array | 快照列表 |

**SnapshotInfo 子结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 快照 ID |
| name | string | 快照名称 |
| description | string | 描述 |
| sourceAccounts | array | 源账户列表 |
| downloadAccount | string | 下载账户 |
| status | string | 状态 |
| message | string | 消息 |
| createdAt | time | 创建时间 |
| version | string | 版本 |
| size | number | 大小 |
| taskID | string | 任务 ID |
| taskRecoverID | string | 恢复任务 ID |
| taskRollbackID | string | 回滚任务 ID |
| interruptStep | string | 中断步骤 |
| recoverStatus | string | 恢复状态 |
| recoverMessage | string | 恢复消息 |
| lastRecoveredAt | string | 最后恢复时间 |
| rollbackStatus | string | 回滚状态 |
| rollbackMessage | string | 回滚消息 |
| lastRollbackedAt | string | 最后回滚时间 |

---

### POST /settings/snapshot/import
**功能**: Import system snapshot - 导入系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| backupAccountID | number | 否 | 备份账户 ID | - |
| names | array | 否 | 快照名称列表 | - |
| description | string | 否 | 描述 | validate:"max=256" |

---

### POST /settings/snapshot/del
**功能**: Delete system backup - 删除系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| deleteWithFile | boolean | 否 | 是否同时删除文件 | - |
| ids | array | 是 | 快照 ID 列表 | validate:"required" |

---

### POST /settings/snapshot/recover
**功能**: Recover system backup - 恢复系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| isNew | boolean | 否 | 是否新建恢复 | - |
| reDownload | boolean | 否 | 是否重新下载 | - |
| id | number | 是 | 快照 ID | validate:"required" |
| taskID | string | 否 | 任务 ID | - |
| secret | string | 否 | 密钥 | - |

---

### POST /settings/snapshot/rollback
**功能**: Rollback system backup - 回滚系统快照

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| isNew | boolean | 否 | 是否新建回滚 | - |
| reDownload | boolean | 否 | 是否重新下载 | - |
| id | number | 是 | 快照 ID | validate:"required" |
| taskID | string | 否 | 任务 ID | - |
| secret | string | 否 | 密钥 | - |

---

### POST /settings/snapshot/description/update
**功能**: Update snapshot description - 更新快照描述

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| id | number | 是 | 快照 ID | validate:"required" |
| description | string | 否 | 描述内容 | validate:"max=256" |

---

### GET /settings/ssh/conn
**功能**: Load local conn - 获取本地 SSH 连接信息

**请求参数**: 无

**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| addr | string | SSH 地址 |
| port | number | SSH 端口 |
| user | string | 用户名 |
| authMode | string | 认证模式 (password/key) |
| password | string | 密码 |
| privateKey | string | 私钥 |
| passPhrase | string | 私钥密码短语 |
| localSSHConnShow | string | 本地 SSH 连接显示配置 |

---

### POST /settings/ssh
**功能**: Save local conn info - 保存本地 SSH 连接信息

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| addr | string | 是 | SSH 地址 | validate:"required" |
| port | number | 是 | SSH 端口 (1-65535) | validate:"required,number,max=65535,min=1" |
| user | string | 是 | 用户名 | validate:"required" |
| authMode | string | 是 | 认证模式 | validate:"oneof=password key" |
| password | string | 否 | 密码 (authMode=password 时必填) | - |
| privateKey | string | 否 | 私钥 (authMode=key 时必填) | - |
| passPhrase | string | 否 | 私钥密码短语 | - |
| localSSHConnShow | string | 否 | 本地 SSH 连接显示配置 | - |

---

### POST /settings/ssh/check
**功能**: Check local conn - 检查本地 SSH 连接

**请求参数**: 无 (使用已保存的连接信息)

**返回参数**: boolean (连接是否成功)

---

### POST /settings/ssh/check/info
**功能**: Check local conn info - 通过连接信息检查 SSH 连接

**请求参数**:
| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|------|------|------|------|----------|
| addr | string | 是 | SSH 地址 | validate:"required" |
| port | number | 是 | SSH 端口 (1-65535) | validate:"required,number,max=65535,min=1" |
| user | string | 是 | 用户名 | validate:"required" |
| authMode | string | 是 | 认证模式 | validate:"oneof=password key" |
| password | string | 否 | 密码 | - |
| privateKey | string | 否 | 私钥 | - |
| passPhrase | string | 否 | 私钥密码短语 | - |

**返回参数**: boolean (连接是否成功)

---

### POST /settings/ssh/default
**功能**: Update local is conn - 设置默认 SSH 连接方式

**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| withReset | boolean | 否 | 是否重置 |
| defaultConn | string | 否 | 默认连接方式 |

---

## 废弃/未实现的 API (参考原 SKILL 文件，可能已移除或重构)

以下 API 在当前源码中未找到对应实现，可能已被废弃或重构：

- `GET /core/settings/interface` - Load system address
- `GET /core/settings/search/available` - Load system available status
- `GET /core/settings/ssl/info` - Load system cert info
- `GET /core/settings/upgrade` - Load upgrade info
- `GET /core/settings/upgrade/releases` - Load upgrade notes
- `POST /core/settings/api/config/generate/key` - generate api key
- `POST /core/settings/api/config/update` - Update api config
- `POST /core/settings/bind/update` - Update system bind info
- `POST /core/settings/by` - Load system setting by key
- `POST /core/settings/expired/handle` - Reset system password expired
- `POST /core/settings/menu/default` - Default menu
- `POST /core/settings/menu/update` - Update system setting
- `POST /core/settings/mfa` - Load mfa info
- `POST /core/settings/mfa/bind` - Bind mfa
- `POST /core/settings/password/update` - Update system password
- `POST /core/settings/port/update` - Update system port
- `POST /core/settings/proxy/update` - Update proxy setting
- `POST /core/settings/ssl/download` - Download system cert
- `POST /core/settings/ssl/update` - Update system ssl
- `POST /core/settings/terminal/search` - Load system terminal setting info
- `POST /core/settings/terminal/update` - Update system terminal setting
- `POST /core/settings/upgrade` - Upgrade
- `POST /core/settings/upgrade/notes` - Load release notes by version


path: docs/SKILL-toolbox.md
content: # Device, FTP, Fail2ban, Clam - 1Panel API

## 模块说明
Device, FTP, Fail2ban, Clam 模块接口，提供主机设备管理、FTP 用户管理、Fail2ban 防火墙和 Clam 杀毒软件的相关 API。

## 接口列表 (39 个)

---

### Device 设备管理

#### POST /toolbox/device/base
**功能**: 获取设备基础信息
**说明**: 返回主机的基础配置信息，包括 DNS、主机名、时区、用户、Swap 内存等
**参数**: 无

#### GET /toolbox/device/users
**功能**: 获取用户列表
**说明**: 返回系统所有用户列表
**参数**: 无

#### GET /toolbox/device/zone/options
**功能**: 获取时区选项列表
**说明**: 返回可用的时区列表
**参数**: 无

#### POST /toolbox/device/conf
**功能**: 加载设备配置文件
**说明**: 根据名称加载指定的配置文件内容
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 是 | 配置文件名称 | - |

#### POST /toolbox/device/update/conf
**功能**: 更新设备配置
**说明**: 更新主机的系统配置参数
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | 是 | 配置键名 | DNS/NtpSite/TimeZone 等 |
| value | string | 否 | 配置值 | - |

#### POST /toolbox/device/update/host
**功能**: 更新主机 Hosts
**说明**: 更新系统的 hosts 映射配置
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| ip | string | 是 | IP 地址 | - |
| host | string | 是 | 主机名 | - |

#### POST /toolbox/device/update/passwd
**功能**: 更新用户密码
**说明**: 修改指定用户的密码
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| user | string | 是 | 用户名 | - |
| passwd | string | 是 | 新密码（Base64 编码） | - |

#### POST /toolbox/device/update/swap
**功能**: 更新 Swap 配置
**说明**: 创建、删除或修改 Swap 文件
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| path | string | 是 | Swap 文件路径 | - |
| size | uint64 | 否 | Swap 大小（字节） | - |
| used | string | 否 | 使用状态 | - |
| isNew | bool | 否 | 是否新建 | - |
| taskID | string | 否 | 任务 ID | - |

#### POST /toolbox/device/update/byconf
**功能**: 通过配置文件更新设备
**说明**: 通过文件内容更新设备配置
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 配置名称 | - |
| file | string | 否 | 配置文件内容 | - |

#### POST /toolbox/device/check/dns
**功能**: 检查 DNS 配置
**说明**: 验证 DNS 配置是否有效
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | 是 | DNS 配置键 | - |
| value | string | 否 | DNS 服务器地址 | - |

#### POST /toolbox/scan
**功能**: 扫描系统垃圾文件
**说明**: 扫描可清理的系统垃圾文件，返回清理建议
**参数**: 无

#### POST /toolbox/clean
**功能**: 清理系统垃圾文件
**说明**: 根据扫描结果清理指定的垃圾文件
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| treeType | string | 是 | 清理类型 | - |
| name | string | 是 | 清理项名称 | - |
| size | uint64 | 是 | 清理大小（字节） | - |

---

### Fail2ban 防护

#### GET /toolbox/fail2ban/base
**功能**: 获取 Fail2ban 基础信息
**说明**: 返回 Fail2ban 服务状态和配置信息
**参数**: 无

#### GET /toolbox/fail2ban/load/conf
**功能**: 加载 Fail2ban 配置文件
**说明**: 返回 /etc/fail2ban/jail.local 配置文件内容
**参数**: 无

#### POST /toolbox/fail2ban/search
**功能**: 查询封禁 IP 列表
**说明**: 分页查询被封禁或忽略的 IP 地址
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| status | string | 是 | 查询状态 | banned / ignore |

#### POST /toolbox/fail2ban/operate
**功能**: 操作 Fail2ban 服务
**说明**: 启动、停止、重启 Fail2ban 服务
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | 是 | 操作类型 | start / stop / restart |

#### POST /toolbox/fail2ban/operate/sshd
**功能**: 操作 SSH 防护规则
**说明**: 手动封禁或解封 IP
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| ips | []string | 否 | IP 地址列表 | - |
| operate | string | 是 | 操作类型 | banned / ignore |

#### POST /toolbox/fail2ban/update
**功能**: 更新 Fail2ban 配置
**说明**: 修改 Fail2ban 的运行参数
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| key | string | 是 | 配置键 | port / bantime / findtime / maxretry / banaction / logpath |
| value | string | 否 | 配置值 | - |

#### POST /toolbox/fail2ban/update/byconf
**功能**: 通过配置文件更新 Fail2ban
**说明**: 通过文件内容更新 Fail2ban 配置
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| file | string | 否 | 配置文件内容 | - |

---

### FTP 管理

#### GET /toolbox/ftp/base
**功能**: 获取 FTP 基础信息
**说明**: 返回 FTP 服务状态和安装状态
**参数**: 无

#### POST /toolbox/ftp/log/search
**功能**: 查询 FTP 操作日志
**说明**: 分页查询 FTP 用户的操作日志
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| user | string | 否 | 用户名（筛选） | - |
| operation | string | 否 | 操作类型（筛选） | - |

#### POST /toolbox/ftp/operate
**功能**: 操作 FTP 服务
**说明**: 启动、停止、重启 FTP 服务
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | 是 | 操作类型 | start / stop / restart |

#### POST /toolbox/ftp/search
**功能**: 分页查询 FTP 用户
**说明**: 分页查询已创建的 FTP 账户
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |

#### POST /toolbox/ftp
**功能**: 创建 FTP 用户
**说明**: 创建新的 FTP 账户
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| user | string | 是 | 用户名 | - |
| password | string | 是 | 密码（Base64 编码） | - |
| path | string | 是 | 根目录路径 | - |
| description | string | 否 | 描述信息 | - |

#### POST /toolbox/ftp/update
**功能**: 更新 FTP 用户
**说明**: 修改 FTP 账户信息
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | FTP 账户 ID | - |
| password | string | 是 | 新密码（Base64 编码） | - |
| path | string | 是 | 根目录路径 | - |
| status | string | 否 | 状态 | enabled / disabled |
| description | string | 否 | 描述信息 | - |

#### POST /toolbox/ftp/del
**功能**: 删除 FTP 用户
**说明**: 删除指定的 FTP 账户
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| ids | []uint | 是 | FTP 账户 ID 列表 | - |

#### POST /toolbox/ftp/sync
**功能**: 同步 FTP 用户
**说明**: 同步系统用户与 FTP 账户
**参数**: 无

---

### Clam 杀毒

#### POST /toolbox/clam
**功能**: 创建扫描规则
**说明**: 创建新的 Clam 扫描规则
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 规则名称 | - |
| status | string | 否 | 状态 | enabled / disabled |
| path | string | 否 | 扫描路径 | - |
| infectedStrategy | string | 否 | 感染文件处理策略 | - |
| infectedDir | string | 否 | 感染文件隔离目录 | - |
| spec | string | 否 | 定时任务规格 | cron 表达式 |
| timeout | uint | 否 | 超时时间（秒） | - |
| description | string | 否 | 描述信息 | - |
| alertCount | uint | 否 | 告警数量阈值 | - |
| alertTitle | string | 否 | 告警标题 | - |
| alertMethod | string | 否 | 告警方式 | - |

#### POST /toolbox/clam/base
**功能**: 获取 Clam 基础信息
**说明**: 返回 ClamAV 杀毒软件的状态和版本信息
**参数**: 无

#### POST /toolbox/clam/update
**功能**: 更新扫描规则
**说明**: 修改已存在的 Clam 扫描规则
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 规则 ID | - |
| name | string | 否 | 规则名称 | - |
| path | string | 否 | 扫描路径 | - |
| infectedStrategy | string | 否 | 感染文件处理策略 | - |
| infectedDir | string | 否 | 感染文件隔离目录 | - |
| spec | string | 否 | 定时任务规格 | cron 表达式 |
| timeout | uint | 否 | 超时时间（秒） | - |
| description | string | 否 | 描述信息 | - |
| alertCount | uint | 否 | 告警数量阈值 | - |
| alertTitle | string | 否 | 告警标题 | - |
| alertMethod | string | 否 | 告警方式 | - |

#### POST /toolbox/clam/status/update
**功能**: 更新规则状态
**说明**: 启用或禁用指定的扫描规则
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 规则 ID | - |
| status | string | 否 | 状态 | enabled / disabled |

#### POST /toolbox/clam/search
**功能**: 分页查询扫描规则
**说明**: 分页查询已创建的 Clam 扫描规则
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| info | string | 否 | 搜索关键词 | - |
| orderBy | string | 是 | 排序字段 | name / status / createdAt |
| order | string | 是 | 排序方式 | null / ascending / descending |

#### POST /toolbox/clam/operate
**功能**: 操作 Clam 服务
**说明**: 启动、停止 ClamAV 服务
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| operation | string | 是 | 操作类型 | start / stop |

#### POST /toolbox/clam/record/clean
**功能**: 清空扫描记录
**说明**: 清空指定规则的扫描记录
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 规则 ID | - |

#### POST /toolbox/clam/record/search
**功能**: 分页查询扫描记录
**说明**: 分页查询扫描任务的执行记录
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | - |
| pageSize | int | 是 | 每页数量 | - |
| clamID | uint | 否 | 规则 ID | - |
| status | string | 否 | 扫描状态 | - |
| startTime | time | 否 | 开始时间 | - |
| endTime | time | 否 | 结束时间 | - |

#### POST /toolbox/clam/file/search
**功能**: 加载扫描日志文件
**说明**: 加载指定规则或记录的战斗日志
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| tail | string | 否 | 日志尾行数 | - |
| name | string | 是 | 规则名称 | - |

#### POST /toolbox/clam/file/update
**功能**: 更新扫描文件配置
**说明**: 更新规则的文件扫描配置
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| name | string | 否 | 配置名称 | - |
| file | string | 否 | 配置文件内容 | - |

#### POST /toolbox/clam/del
**功能**: 删除扫描规则
**说明**: 删除指定的扫描规则，可选择是否删除感染文件
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| removeInfected | bool | 否 | 是否删除感染文件 | - |
| ids | []uint | 是 | 规则 ID 列表 | - |

#### POST /toolbox/clam/handle
**功能**: 执行病毒扫描
**说明**: 手动触发一次扫描任务
**参数**:
| 字段名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | 规则 ID | - |


path: docs/SKILL-websites_acme.md
content: # Website Acme - 1Panel API

## 模块说明
Website Acme 模块接口，用于管理 ACME 证书账户（Let's Encrypt、ZeroSSL 等）

## 接口列表 (4 个)

---

### POST /websites/acme/search
**功能**: Page website acme accounts - 分页获取 ACME 账户列表
**认证**: ApiKeyAuth, Timestamp
**日志**: -

**请求参数 (PageInfo)**:

| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| page | int | 是 | 页码 | > 0 |
| pageSize | int | 是 | 每页数量 | > 0 |

**返回示例**:
```json
{
  "total": 1,
  "items": [
    {
      "ID": 1,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "email": "[REDACTED_SECRET]",
      "url": "https://.api.letsencryptacme-v02.org/directory",
      "type": "letsencrypt",
      "keyType": "2048",
      "useProxy": false,
      "caDirURL": "",
      "eabKid": "",
      "eabHmacKey": "",
      "useEAB": false
    }
  ]
}
```

---

### POST /websites/acme
**功能**: Create website acme account - 创建 ACME 账户
**认证**: ApiKeyAuth, Timestamp
**日志**: 创建网站 acme [email]

**请求参数 (WebsiteAcmeAccountCreate)**:

| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| email | string | 是 | ACME 账户邮箱地址 | 有效的邮箱格式 |
| type | string | 是 | ACME 服务提供商类型 | `letsencrypt`, `zerossl`, `buypass`, `google`, `custom` |
| keyType | string | 是 | 密钥类型 | `P256`, `P384`, `2048`, `3072`, `4096`, `8192` |
| eabKid | string | 否 | EAB Key ID（外部账户绑定） | - |
| eabHmacKey | string | 否 | EAB HMAC Key（外部账户绑定） | - |
| useProxy | bool | 否 | 是否使用代理 | `true`, `false` |
| caDirURL | string | 否 | CA Directory URL（自定义 ACME 服务时使用） | - |
| useEAB | bool | 否 | 是否使用 EAB（外部账户绑定） | `true`, `false` |

**返回示例**:
```json
{
  "ID": 1,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "email": "[REDACTED_SECRET]",
  "url": "https://acme-v02.api.letsencrypt.org/directory",
  "type": "letsencrypt",
  "keyType": "2048",
  "useProxy": false,
  "caDirURL": "",
  "eabKid": "",
  "eabHmacKey": "",
  "useEAB": false
}
```

---

### POST /websites/acme/del
**功能**: Delete website acme account - 删除 ACME 账户
**认证**: ApiKeyAuth, Timestamp
**日志**: 删除网站 acme [email]

**请求参数 (WebsiteResourceReq)**:

| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | ACME 账户 ID | > 0 |

**返回**: 成功时返回空对象

---

### POST /websites/acme/update
**功能**: Update website acme account - 更新 ACME 账户
**认证**: ApiKeyAuth, Timestamp
**日志**: 更新 acme [email]

**请求参数 (WebsiteAcmeAccountUpdate)**:

| 参数名 | 类型 | 必填 | 说明 | 取值范围 |
|--------|------|------|------|----------|
| id | uint | 是 | ACME 账户 ID | > 0 |
| useProxy | bool | 否 | 是否使用代理 | `true`, `false` |

**返回示例**:
```json
{
  "ID": 1,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "email": "[REDACTED_SECRET]",
  "url": "https://acme-v02.api.letsencrypt.org/directory",
  "type": "letsencrypt",
  "keyType": "2048",
  "useProxy": true,
  "caDirURL": "",
  "eabKid": "",
  "eabHmacKey": "",
  "useEAB": false
}
```

---

## 数据模型

### WebsiteAcmeAccount (数据库模型)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 ID |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
| email | string | ACME 账户邮箱 |
| url | string | ACME 服务目录 URL |
| type | string | ACME 提供商类型 |
| keyType | string | 密钥类型 |
| useProxy | bool | 是否使用代理 |
| caDirURL | string | 自定义 CA Directory URL |
| eabKid | string | EAB Key ID |
| eabHmacKey | string | EAB HMAC Key（敏感，不返回） |
| useEAB | bool | 是否使用 EAB |

---

## 使用说明

1. **创建 ACME 账户**: 使用 `POST /websites/acme` 创建账户，需要提供邮箱、类型和密钥类型
2. **查询账户列表**: 使用 `POST /websites/acme/search` 进行分页查询
3. **更新账户**: 使用 `POST /websites/acme/update` 更新账户配置（目前仅支持更新 useProxy）
4. **删除账户**: 使用 `POST /websites/acme/del` 删除账户

### 常用场景

- **Let's Encrypt**: `type=letsencrypt`, `keyType=2048`
- **ZeroSSL**: `type=zerossl`, `keyType=2048`
- **自定义 ACME**: `type=custom`, `caDirURL` 设置为自定义服务 URL
- **使用 EAB**: 设置 `useEAB=true`, 并配置 `eabKid` 和 `eabHmacKey`


path: docs/SKILL-websites_dns.md
content: # Website DNS - 1Panel API

## 模块说明
Website DNS 模块接口，用于管理 DNS 账户，支持通过 DNS API 自动验证域名所有权。

## 接口列表 (4 个)

---

### POST /websites/dns/search
**功能**: 分页查询 DNS 账户列表
**描述**: 获取所有 DNS 账户的分页列表

**参数 (Body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| page | int | 是 | 页码 | >= 1 |
| pageSize | int | 是 | 每页数量 | 1-100 |

**响应示例**:
```json
{
  "total": 10,
  "items": [
    {
      "id": 1,
      "name": "Cloudflare Account",
      "type": "cloudflare",
      "authorization": {...}
    }
  ]
}
```

---

### POST /websites/dns
**功能**: 创建 DNS 账户
**描述**: 添加新的 DNS 账户，用于自动 DNS 验证

**参数 (Body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| name | string | 是 | DNS 账户名称 | 最大 64 字符 |
| type | string | 是 | DNS 提供商类型 | 详见下方支持类型 |
| authorization | object | 是 | DNS API 授权信息 | 根据 type 不同而变化 |

**Authorization 参数 (根据 type 不同)**:

| type 类型 | authorization 字段 | 说明 |
|-----------|-------------------|------|
| cloudflare | api_key | Cloudflare API Key |
| aliyun | access_key_id, access_key_secret | 阿里云 AccessKey |
| tencent | secret_id, secret_key | 腾讯云 Secret |
| dnspod | id, token | DNSPod API Token |
| namesilo | key | Namesilo API Key |
| godaddy | key, secret | GoDaddy API Key/Secret |
| aws | access_key_id, secret_access_key | AWS Access Key |
| google | service_account_json | Google Cloud Service Account JSON |

**请求示例**:
```json
{
  "name": "My Cloudflare",
  "type": "cloudflare",
  "authorization": {
    "api_key": "your-cloudflare-api-key"
  }
}
```

---

### POST /websites/dns/update
**功能**: 更新 DNS 账户
**描述**: 修改已有的 DNS 账户信息

**参数 (Body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | DNS 账户 ID | > 0 |
| name | string | 是 | DNS 账户名称 | 最大 64 字符 |
| type | string | 是 | DNS 提供商类型 | 需与原类型一致 |
| authorization | object | 是 | DNS API 授权信息 | 根据 type 不同而变化 |

**请求示例**:
```json
{
  "id": 1,
  "name": "Updated Cloudflare",
  "type": "cloudflare",
  "authorization": {
    "api_key": "your-new-cloudflare-api-key"
  }
}
```

---

### POST /websites/dns/del
**功能**: 删除 DNS 账户
**描述**: 删除指定的 DNS 账户

**参数 (Body)**:

| 字段 | 类型 | 必填 | 说明 | 取值范围 |
|------|------|------|------|----------|
| id | uint | 是 | DNS 账户 ID | > 0 |

**请求示例**:
```json
{
  "id": 1
}
```

---

## 错误响应格式

所有接口的错误响应格式如下：

```json
{
  "code": 400,
  "message": "错误描述信息"
}
```

## 常用状态码

| code | 说明 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)