证书 certs
上传或自动签发的 HTTPS 证书。可绑定到站点;有站点在用时不能删除或停用。
点击任一接口,右侧显示对应的调用示例。
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
/api/v2/certs列出证书
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
tenant_ids | string | 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。 |
name | string | 名称包含。 |
domain | string | SAN 包含(域名或 IP 的一部分)。 |
scope | string | site = 站点证书;ip = 平台 IP 证书;panel = 面板证书(主控 HTTPS 监听用)。 |
enabled | boolean | 是否启用 |
expire_days | integer | 只列 N 天内到期(含已过期)的证书。 |
id | integer | 证书 id 精确匹配。 |
ids | string | 多个证书 id 逗号分隔(至多 200 个),命中其中任一个。 |
des | string | 备注包含。 |
type | string | 证书类型。 |
dns_api_id | integer | 用此 DNS API 凭据的证书。 |
dns_api_ids | string | 按 DNS API(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
q | string | 候选搜索:名称包含或域名(SAN)包含该词即命中(不分大小写,名称与域名是 OR),可与 name、domain 同用(都要满足)。 |
domains | string | 多个域名或 IP,逗号分隔,证书 SAN 里含其中任一个(精确匹配)。 |
issue_state | string | ACME 签发状态(上传的证书没有)。 |
kind | string | domain = SAN 含域名;ip = SAN 全是 IP。 |
/api/v2/certs创建证书
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
acme | CertAcmeSummary | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 |
cert | string | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 |
des | string | 备注说明 |
enabled | boolean | 是否启用 |
key | string | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
name必填 | string | 名称 |
scope | string | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 |
type | string | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |
/api/v2/certs/acme-states批量查 ACME 签发状态
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
ids必填 | string | 证书 id,逗号分隔,至多 200 个。 |
/api/v2/certs/batch批量申请 ACME 证书
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
acme_account_id | integer | 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。 |
auto_renew | boolean | 不给为 true。 |
des | string | 备注说明 |
dns_api_id | integer | DNS-01 验证用的 DNS API 凭据(ACME 证书用)。 |
items必填 | CertAcme[] | 签发状态。 |
type | string | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |
/api/v2/certs/batch-issue批量重签或续签 ACME 证书
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
ids必填 | integer[] | 证书 id。 |
/api/v2/certs/zerossl-ips列出可签 ZeroSSL 证书的 IP
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
/api/v2/certs/{id}获取证书
鉴权: 用户(部分参数仅管理员)
/api/v2/certs/{id}修改证书
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
acme | CertAcmeSummary | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 |
cert | string | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 |
des | string | 备注说明 |
enabled | boolean | 是否启用 |
key | string | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
name必填 | string | 名称 |
scope | string | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 |
type | string | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |
/api/v2/certs/{id}删除证书
鉴权: 用户(部分参数仅管理员)
/api/v2/certs/{id}/acme获取证书的 ACME 签发状态
鉴权: 用户(部分参数仅管理员)
/api/v2/certs/{id}/acme修改证书的自动续签开关
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
auto_renew必填 | boolean | 不给为 true。 |
/api/v2/certs/{id}/bind证书绑定到站点
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
site_ids必填 | integer[] | 在用此证书的站点。 |
/api/v2/certs/{id}/issue重新签发 ACME 证书
鉴权: 用户(部分参数仅管理员)
/api/v2/certs/{id}/private-key导出证书私钥
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
password | string | 当前登录口令。 |
totp_code | string | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |
证书对象
| 字段 | 类型 | 说明 |
|---|---|---|
acme | CertAcmeSummary | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 |
acme_account_id | integer | 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。 |
ari_end | string | CA 经 ARI 建议的续签窗口结束时间。 |
ari_start | string | CA 经 ARI 建议的续签窗口;null = CA 没给,按到期前 cert.acme.renew_before_days 天续签。 |
auto_renew | boolean | 不给为 true。 |
cert | string | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 |
cert_id | integer | 证书 id。 |
challenge | string | 验证方式:http-01、dns-01,或 http-file(zerossl_api 的 ZeroSSL 文件验证)。 |
created_at | string | 创建时间 |
des | string | 备注说明 |
dns_api_id | integer | DNS-01 验证用的 DNS API 凭据(ACME 证书用)。 |
enabled | boolean | 是否启用 |
err_times | integer | 这一轮已失败次数。 |
failed | integer | 失败的条数。 |
fingerprint | string | 叶证书 SHA-256 指纹(小写十六进制)。 |
id | integer | 记录 ID |
ids必填 | integer[] | 证书 id。 |
issued_at | string | 最近一次签发成功的时间。 |
issuer | string | 证书颁发者。 |
items | CertAcme[] | 签发状态。 |
key | string | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
last_error | string | 最近一次错误 |
name | string | 名称 |
names | string[] | SAN(域名、通配域名或 IP);无 SAN 时取 CN。 |
next_retry_at | string | 失败后等退避重试(state=pending 且 err_times>0)的下次重试时刻,取自延时任务队列;其余为 null。 |
next_try_at | string | 续签失败终态后,续签扫描最早再试的时刻。 |
not_after | string | 证书到期时间。 |
not_before | string | 证书生效时间。 |
ocsp | boolean | 叶证书带 OCSP 地址(节点可装订)。 |
ok | integer | 已排队签发的条数。 |
password | string | 当前登录口令。 |
renewing | boolean | 当前这轮是续签(失败时旧证书照用)。 |
scope | string | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 |
site_ids | integer[] | 在用此证书的站点。 |
state | string | pending 排队或等重试;running 签发中;issued 已签出;failed 重试用完(已发提醒)。 |
tenant_id | integer | 所属租户;null = 平台 IP 证书。 |
totp_code | string | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |
type | string | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |
updated_at | string | 更新时间 |
version | integer | 证书内容版本,换证 +1。 |
zerossl_order_id | string | zerossl_api 证书当前的 ZeroSSL 订单号;空 = 还没下单。 |
zerossl_order_state | string | ZeroSSL 订单状态(draft、pending_validation、issued、cancelled 等);空 = 还没下单。 |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}