Path: 宝塔面板 API 参考 › ACME 证书

`POST /acme`

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

## Request body

_Required._

One of:

- `SetCertToSite (ACME)`
- `apply_cert_api`
- `apply_dns_auth`
- `download_cert`
- `get_order_find`
- `get_orders`
- `remove_order`
- `renew_cert`

## Example request

```text
{
  "request_time": "string",
  "request_token": "string",
  "action": "SetCertToSite",
  "index": "string",
  "siteName": "string"
}
```

## Code samples

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

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

## Responses

### default

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


## SetCertToSite (ACME)

将通过 ACME（Let's Encrypt 等）签发的 SSL 证书部署到指定网站，开启 HTTPS。

- **路由**：`POST /acme`
- **action**：`SetCertToSite`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `SetCertToSite` |
| index | 是 | String | 证书订单索引 ID |
| siteName | 是 | String | 目标网站域名 |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 部署成功 |
| msg | String | `SSL开启成功!` |
| csr | String | 部署的完整证书链（PEM 格式） |

## 示例

### 请求

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

action=SetCertToSite&index=851cc157ad22888459e59c3cfdc5ac95&siteName=testapi.bt.local
```

### 响应

```json
{
  "status": true,
  "msg": "SSL开启成功!",
  "csr": "-----BEGIN CERTIFICATE-----\nMIIE7T..."
}
```

## 相关接口

- [apply_cert_api](/api/acme/apply_cert_api) — 申请证书
- [apply_dns_auth](/api/acme/apply_dns_auth) — DNS 验证签发


## apply_cert_api

创建 Let's Encrypt（或其他 ACME CA）证书申请订单。支持三种验证方式。

- **路由**：`POST /acme`
- **action**：`apply_cert_api`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `apply_cert_api` |
| id | 是 | Integer | 关联网站 ID |
| domains | 是 | String | JSON 数组，要申请的域名列表 `["example.com","www.example.com"]` |
| auth_type | 是 | String | 验证方式：`http`(文件)、`tls`(TLS)、`dns`(DNS) |
| auth_to | 是 | String | 验证路径。HTTP/TLS 传网站目录；**DNS 验证传 `dns`** |
| auto_wildcard | 否 | String | `"1"` 自动申请泛域名 `*.example.com` |
| ca | 否 | String | CA 标识，默认 Let's Encrypt |

> **提示**：`auth_type=dns`, `auth_to=dns` 时仅创建订单。需再用 [apply_dns_auth](/api/acme/apply_dns_auth) 完成 DNS TXT 记录创建和验证。


## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | String | `pending` 订单待验证 |
| index | String | 订单索引 ID，后续操作需要 |
| domains | Array | 申请的域名列表 |
| authorizations | Array | Let's Encrypt 授权 URL 列表 |
| expires | Integer | 订单过期时间戳 |
| create_time | Integer | 创建时间戳 |

## 示例

### 请求（DNS 验证）

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

action=apply_cert_api&id=1&domains=["dnstest.cc"]&auth_type=dns&auth_to=dns
```

### 响应

```json
{
  "status": "pending",
  "index": "a7a0472c4a5061ec83450119b874a5d3",
  "domains": ["dnstest.cc"],
  "auth_type": "dns",
  "expires": 1780111135,
  "create_time": 1779506335,
  "authorizations": ["https://acme-v02.api.letsencrypt.org/acme/authz/..."]
}
```

## 相关接口

- [apply_dns_auth](/api/acme/apply_dns_auth) — 完成 DNS 验证并签发
- [SetCertToSite](/api/acme/setcerttosite) — 部署证书到网站


## apply_dns_auth

自动调用已配置的 DNS 提供商 API（如腾讯云 DNSPod）创建 ACME 所需的 `_acme-challenge` TXT 记录，完成域名验证，签发并下载证书。验证完成后自动删除临时 TXT 记录。

**前置条件**：已通过 `/ssl/dnsapi/add_dns_data` 配置 DNS API 密钥，并通过 `/ssl/data/add_domain` 添加域名。

- **路由**：`POST /acme`
- **action**：`apply_dns_auth`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `apply_dns_auth` |
| index | 是 | String | 订单索引 ID（由 `apply_cert_api` 返回） |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 申请成功 |
| msg | String | `申请成功!` |
| cert | String | 完整证书链（PEM 格式） |
| private_key | String | 私钥（PEM 格式） |
| domains | Array | 证书覆盖的域名列表 |
| cert_timeout | Integer | 证书到期时间戳 |

## 示例

### 请求

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

action=apply_dns_auth&index=a7a0472c4a5061ec83450119b874a5d3
```

### 响应

```json
{
  "status": true,
  "msg": "申请成功!",
  "cert": "-----BEGIN CERTIFICATE-----\nMIIE7TCCA9W...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "domains": ["dnstest.cc"],
  "cert_timeout": 1780111135
}
```

## 相关接口

- [apply_cert_api](/api/acme/apply_cert_api) — 创建证书订单
- [SetCertToSite](/api/acme/setcerttosite) — 部署证书到网站


## download_cert

下载指定订单的证书文件到本地保存路径。

- **路由**：`POST /acme`
- **action**：`download_cert`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `download_cert` |
| index | 是 | String | 订单索引 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| cert | String | 证书内容（PEM 格式） |
| private_key | String | 私钥内容 |
| fullchain | String | 完整证书链 |
| cert_timeout | Integer | 证书到期时间戳 |
| domains | Array | 证书覆盖的域名 |

## 示例

### 请求

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

action=download_cert&index=851cc157ad22888459e59c3cfdc5ac95
```

### 响应

```json
{
  "cert": "-----BEGIN CERTIFICATE-----\n...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "domains": ["dnstest.cc"]
}
```


## get_order_find

获取指定订单的详细信息，包括证书内容。

- **路由**：`POST /acme`
- **action**：`get_order_find`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `get_order_find` |
| index | 是 | String | 订单索引 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| index | String | 订单索引 |
| domains | Array | 域名列表 |
| status | String | `valid` 有效 / `pending` 待验证 / `expired` 已过期 |
| cert_timeout | Integer | 证书到期时间戳 |
| cert | Object | 证书详情，含 `private_key`、`fullchain` |

## 示例

### 请求

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

action=get_order_find&index=851cc157ad22888459e59c3cfdc5ac95
```

### 响应

```json
{
  "index": "851cc157ad22888459e59c3cfdc5ac95",
  "domains": ["dnstest.cc"],
  "status": "valid",
  "cert_timeout": 1780111135,
  "cert": {
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "fullchain": "-----BEGIN CERTIFICATE-----\n..."
  }
}
```


## get_orders

列出所有 ACME 证书申请订单，包括进行中、已完成和已过期的订单。

- **路由**：`POST /acme`
- **action**：`get_orders`

## 输入参数

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

无其他参数。

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| - | Array&lt;Object&gt; | 订单列表，每项含 `index`(ID)、`domains`(域名)、`status`(状态)、`cert_timeout`(到期时间) |

## 示例

### 请求

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

action=get_orders
```

### 响应

```json
[{
  "index": "851cc157ad22888459e59c3cfdc5ac95",
  "domains": ["dnstest.cc"],
  "status": "valid",
  "cert_timeout": 1780111135,
  "auth_type": "dns",
  "create_time": 1779506335
}]
```


## remove_order

删除指定索引的 ACME 证书订单记录。

- **路由**：`POST /acme`
- **action**：`remove_order`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `remove_order` |
| index | 是 | String | 要删除的订单索引 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 删除成功 |
| msg | String | `订单删除成功!` |

## 示例

### 请求

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

action=remove_order&index=851cc157ad22888459e59c3cfdc5ac95
```

### 响应

```json
{"status": true, "msg": "订单删除成功!"}
```


## renew_cert

续签已有的 ACME 证书，使用原订单的验证方式和 DNS 配置。

- **路由**：`POST /acme`
- **action**：`renew_cert`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `renew_cert` |
| index | 是 | String | 要续签的订单索引 ID |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| status | Boolean | `true` 续签成功 |
| msg | String | `申请成功!` |
| cert | String | 新的证书链（PEM 格式） |
| cert_timeout | Integer | 新的到期时间戳 |

## 示例

### 请求

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

action=renew_cert&index=851cc157ad22888459e59c3cfdc5ac95
```

### 响应

```json
{"status": true, "msg": "续签成功!"}
```