版本 2.1.1792967583 · 最新下载 OpenAPI Markdown 版

证书

上传或自动签发的 HTTPS 证书。可绑定到站点;有站点在用时不能删除或停用。

certs证书鉴权: 用户（部分参数仅管理员）14 个接口

列出证书

GET/api/v2/certs

鉴权: 用户（部分参数仅管理员）

查询参数

字段	类型	必填	说明
page	integer	—	页码,从 1 开始。默认 `1`
page_size	integer	—	每页条数。默认 `20`
sort	string	—	排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
tenant_id	integer	—	仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。
name	string	—	名称包含。
domain	string	—	SAN 包含(域名或 IP 的一部分)。
scope	string	—	site = 站点证书;ip = 平台 IP 证书;panel = 面板证书(主控 HTTPS 监听用)。可选值 `["site","ip","panel"]`
enabled	boolean	—	是否启用
expire_days	integer	—	只列 N 天内到期(含已过期)的证书。
id	integer	—	证书 id 精确匹配。
ids	string	—	多个证书 id 逗号分隔(至多 200 个),命中其中任一个。
des	string	—	备注包含。
type	string	—	证书类型。可选值 `["custom","lets","zerossl","zerossl_api"]`
dns_api_id	integer	—	用此 DNS API 凭据的证书。
domains	string	—	多个域名或 IP,逗号分隔,证书 SAN 里含其中任一个(精确匹配)。
issue_state	string	—	ACME 签发状态(上传的证书没有)。可选值 `["pending","running","issued","failed"]`
kind	string	—	domain = SAN 含域名;ip = SAN 全是 IP。可选值 `["domain","ip"]`

创建证书

POST/api/v2/certs

鉴权: 用户（部分参数仅管理员）

查询参数

字段	类型	必填	说明
tenant_id	integer	—	仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。

请求体 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 = 面板证书。可选值 `["site","ip","panel"]`
type	string	—	custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。

批量查 ACME 签发状态

GET/api/v2/certs/acme-states

鉴权: 用户（部分参数仅管理员）

查询参数

字段	类型	必填	说明
ids	string	必填	证书 id,逗号分隔,至多 200 个。

批量申请 ACME 证书

POST/api/v2/certs/batch

鉴权: 用户（部分参数仅管理员）

查询参数

字段	类型	必填	说明
tenant_id	integer	—	仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。

请求体 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 签发。

批量重签或续签 ACME 证书

POST/api/v2/certs/batch-issue

鉴权: 用户（部分参数仅管理员）

请求体 application/json

字段	类型	必填	说明
ids	integer[]	必填	证书 id。

列出可签 ZeroSSL 证书的 IP

GET/api/v2/certs/zerossl-ips

鉴权: 用户（部分参数仅管理员）

查询参数

字段	类型	必填	说明
tenant_id	integer	—	仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。

获取证书

GET/api/v2/certs/{id}

鉴权: 用户（部分参数仅管理员）

修改证书

PUT/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 = 面板证书。可选值 `["site","ip","panel"]`
type	string	—	custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。

删除证书

DELETE/api/v2/certs/{id}

鉴权: 用户（部分参数仅管理员）

获取证书的 ACME 签发状态

GET/api/v2/certs/{id}/acme

鉴权: 用户（部分参数仅管理员）

修改证书的自动续签开关

PUT/api/v2/certs/{id}/acme

鉴权: 用户（部分参数仅管理员）

请求体 application/json

字段	类型	必填	说明
auto_renew	boolean	必填	不给为 true。

证书绑定到站点

POST/api/v2/certs/{id}/bind

鉴权: 用户（部分参数仅管理员）

请求体 application/json

字段	类型	必填	说明
site_ids	integer[]	必填	在用此证书的站点。

重新签发 ACME 证书

POST/api/v2/certs/{id}/issue

鉴权: 用户（部分参数仅管理员）

导出证书私钥

POST/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 文件验证)。可选值 `["http-01","dns-01","http-file"]`
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_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","ip","panel"]`
site_ids	integer[]	—	在用此证书的站点。只读
state	string	—	pending 排队或等重试;running 签发中;issued 已签出;failed 重试用完(已发提醒)。可选值 `["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 等);空 = 还没下单。

curl

# 列出证书
curl "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 创建证书
curl -X POST "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 批量查 ACME 签发状态
curl "https://panel.example.com/api/v2/certs/acme-states" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 批量申请 ACME 证书
curl -X POST "https://panel.example.com/api/v2/certs/batch" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"domains":["a.example.com"]},{"domains":["b.example.com","www.b.example.com"]}],"type":"lets"}'

# 批量重签或续签 ACME 证书
curl -X POST "https://panel.example.com/api/v2/certs/batch-issue" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[1]}'

# 列出可签 ZeroSSL 证书的 IP
curl "https://panel.example.com/api/v2/certs/zerossl-ips" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取证书
curl "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 修改证书
curl -X PUT "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 删除证书
curl -X DELETE "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取证书的 ACME 签发状态
curl "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 修改证书的自动续签开关
curl -X PUT "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew":false}'

# 证书绑定到站点
curl -X POST "https://panel.example.com/api/v2/certs/{id}/bind" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_ids":[1]}'

# 重新签发 ACME 证书
curl -X POST "https://panel.example.com/api/v2/certs/{id}/issue" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 导出证书私钥
curl -X POST "https://panel.example.com/api/v2/certs/{id}/private-key" \
  -H "X-API-Key: $GOCDN_API_KEY"