SSL证书管理 - OpsHub 文档

功能概览

图：SSL证书管理概览

ACME 自动申请

支持 Let's Encrypt、ZeroSSL、Google、BuyPass 等免费 CA

自动续期

定时检查证书有效期，到期前自动续期

自动部署

续期后自动部署到 Nginx（SSH）和 Kubernetes Secret

DNS 自动验证

通过阿里云 DNS API 自动完成域名所有权验证

手动导入

支持导入已有的 PEM 格式证书和私钥

任务记录

完整的证书签发、续期、部署任务记录

证书管理

图：证书列表

申请新证书（ACME）

通过 ACME 协议自动向 CA 申请免费 SSL 证书：

图：申请新证书

字段	说明
证书名称	便于识别的名称
主域名	主要域名，如 `example.com`
SAN 域名	附加域名，如 `www.example.com`、`api.example.com`
CA 提供商	Let's Encrypt / ZeroSSL / Google / BuyPass
密钥算法	RSA 2048/3072/4096 或 ECDSA P-256/P-384
DNS 服务商	选择已配置的 DNS 服务商用于域名验证
自动续期	是否在证书即将到期时自动续期
提前续期天数	证书到期前多少天开始续期（默认 30 天）

导入证书

手动导入已有的证书和私钥：

图：导入证书

字段	说明
证书名称	便于识别的名称
证书内容	PEM 格式的证书内容（`-----BEGIN CERTIFICATE-----`）
私钥内容	PEM 格式的私钥内容（`-----BEGIN PRIVATE KEY-----`）

证书详情

图：证书详情

证书状态

状态	说明
待申请 (pending)	证书已创建但尚未申请
正常 (active)	证书有效且未临近过期
即将过期 (expiring)	证书将在 30 天内过期
已过期 (expired)	证书已过期
错误 (error)	证书申请或续期出错

DNS 验证配置

ACME 证书申请需要通过 DNS-01 挑战验证域名所有权。目前支持阿里云 DNS。

图：DNS 验证配置列表

添加阿里云 DNS 配置

图：新增 DNS 配置

字段	说明
配置名称	便于识别的名称
DNS 服务商	阿里云
AccessKey ID	阿里云 AccessKey ID
AccessKey Secret	阿里云 AccessKey Secret
联系邮箱	联系人邮箱（可选）

建议为 DNS API 创建专用的 RAM 子账号，仅授予 alidns:AddDomainRecord、alidns:DeleteDomainRecord、alidns:DescribeDomainRecords 权限。

阿里云 RAM 权限策略

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "alidns:AddDomainRecord",
        "alidns:DeleteDomainRecord",
        "alidns:DescribeDomainRecords",
        "alidns:DescribeDomains"
      ],
      "Resource": "*"
    }
  ]
}

部署配置

配置证书续期后的自动部署目标，支持 Nginx SSH 部署和 Kubernetes Secret 部署。

图：部署配置列表

Nginx SSH 部署

通过 SSH 将证书文件上传到 Nginx 服务器并自动重载：

图：Nginx SSH 部署配置

字段	说明
配置名称	便于识别的名称
关联证书	选择要部署的证书
目标主机	选择资产管理中的主机
证书路径	如 `/etc/nginx/ssl/cert.pem`
私钥路径	如 `/etc/nginx/ssl/key.pem`
备份旧证书	部署前是否备份现有证书
自动部署	续期后是否自动部署

Kubernetes Secret 部署

将证书部署为 Kubernetes TLS Secret：

图：Kubernetes Secret 部署配置

字段	说明
配置名称	便于识别的名称
关联证书	选择要部署的证书
K8s 集群	选择目标集群
命名空间	Secret 所在命名空间
Secret 名称	TLS Secret 名称
触发滚动更新	是否触发关联 Deployment 重启
自动部署	续期后是否自动部署

任务记录

查看所有证书相关操作的执行记录。

图：任务记录列表

字段	说明
任务类型	issue（签发）/ renew（续期）/ deploy（部署）
关联证书	任务关联的证书名称和域名
状态	pending / running / success / failed
触发方式	auto（自动触发）/ manual（手动触发）
开始时间	任务开始执行时间
完成时间	任务完成时间
错误信息	失败时的错误详情

任务详情

图：任务详情

CA 提供商对比

CA 提供商	费用	有效期	特点
Let's Encrypt	免费	90 天	最常用的免费 CA，社区活跃
ZeroSSL	免费	90 天	提供 Web 管理界面
Google Trust Services	免费	90 天	Google 签发
BuyPass	免费	180 天	有效期较长

密钥算法选择

算法	密钥长度	推荐场景
RSA 2048	2048 位	兼容性最好，通用场景
RSA 4096	4096 位	高安全要求场景
ECDSA P-256	256 位	性能好，密钥短，推荐现代环境使用
ECDSA P-384	384 位	更高安全性

推荐使用 ECDSA P-256 算法，性能优于 RSA 且安全性不低于 RSA 2048。如需兼容旧设备，选择 RSA 2048。

环境变量配置

环境变量	说明	示例
`OPSHUB_ACME_EMAIL`	ACME 注册邮箱	admin@example.com
`ACME_EMAIL`	ACME 邮箱（备用）	admin@example.com
`OPSHUB_ACME_STAGING`	使用测试环境	true / false

开发测试时建议设置 OPSHUB_ACME_STAGING=true，使用 Let's Encrypt 测试环境，避免触发正式环境的频率限制。

最佳实践

开启自动续期

避免证书过期导致服务中断，建议所有 ACME 证书开启自动续期

提前 30 天续期

保持默认 30 天续期策略，留出充足的处理时间

使用 ECDSA 算法

ECDSA P-256 性能更好，密钥更短，安全性不低于 RSA 2048

最小权限原则

为 DNS API 创建专用子账号，仅授予必要的 DNS 权限

开启自动部署

配置续期后自动部署，确保新证书及时生效

定期检查任务记录

定期查看任务记录，确保续期和部署任务正常执行

常见问题

ACME 申请证书失败？

检查 DNS 配置

点击 DNS 配置的「测试」按钮，确认 API 密钥有效且权限正确

检查域名解析

确保域名已正确解析，且 DNS 服务商与配置一致

检查频率限制

Let's Encrypt 每周限制 50 个证书/域名，测试时请使用 Staging 环境

证书部署失败？

Nginx SSH 部署

检查主机凭据是否正确，目标路径是否有写入权限，Nginx 是否可正常重载

K8s Secret 部署

检查集群连接是否正常，是否有命名空间的 Secret 操作权限

自动续期没有生效？

确认开启自动续期

编辑证书，确认「自动续期」开关已开启

检查 DNS 配置关联

确认证书已关联正确的 DNS 服务商配置

查看任务记录

在任务记录中查看是否有失败的续期任务及其错误信息