使用文档

1 快速开始

三步完成第一张证书的签发。HTTP-01 适合单域名且服务器 80 端口可达；DNS-01 适合泛域名或无法开放 80 端口的场景。

2 域名与验证

证书签发前必须证明你对该域名拥有控制权。平台支持两种 ACME 标准验证方式，可按场景选择。

两种验证方式对比

配置 DNS 厂商凭证（DNS-01 自动模式）

若希望平台自动添加与清理 TXT 记录（无需手工操作），需在「用户中心 → DNS 凭证」中录入云厂商密钥，平台将加密存储。

手动 DNS 两步签发

3 申请证书

在「证书管理」中发起签发，选择域名、密钥算法与证书类型。

证书类型

• 单域名：仅保护一个域名，如 www.example.com。
• 泛域名：保护主域名及所有一级子域名，如 *.example.com，必须使用 DNS-01。
• 多域名 SAN：一张证书保护多个不同域名，减少部署与续期成本。

密钥算法选择

4 自动续期

证书有效期通常为 90 天，自动续期是避免服务中断的关键。

续期阈值设置

在「用户中心 → 自动续期」中，可为每张证书单独设置触发时机：

调度机制

平台通过定时任务扫描到期证书并触发续期，无需常驻进程。请在服务器添加如下 Crontab：

# 每分钟执行一次续期与提醒调度
* * * * * php /www/wwwroot/ssl.hshen.eu.cc/sslapp/cron/cert_cron.php >> /www/wwwroot/ssl.hshen.eu.cc/sslapp/runtime/cron.log 2>&1

5 到期提醒

在证书到期前按阈值分级预警，支持邮件与 Webhook 两大类渠道。

配置邮件通知（SMTP）

在「用户中心 → 通知渠道」新增邮件渠道，填入 SMTP 服务器信息：

Webhook 通知

支持钉钉、企业微信、飞书群机器人及自定义 Webhook。以钉钉机器人为例：

# 发送一条测试通知
curl -X POST "http://ssl.hshen.eu.cc/?r=api/notify_test" \
  -H "X-API-Key: sk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": 1, "subject": "测试通知", "body": "这是一条测试消息"}'

6 自动部署

续期成功后自动把新证书推送至目标，并按需执行重载命令，实现零人工干预。

支持的部署目标

Nginx 部署示例

选择「本机目录」并填写如下配置，平台会在续期成功后写入文件并执行重载：

{
  "cert_path":      "/www/server/panel/vhost/cert/example.com/fullchain.pem",
  "key_path":       "/www/server/panel/vhost/cert/example.com/privkey.pem",
  "fullchain_path": "/www/server/panel/vhost/cert/example.com/fullchain.pem",
  "reload_cmd":     "nginx -s reload"
}

7 证书下载

在「证书管理」列表点击下载，支持多种格式以适配不同服务端。

手动验证证书链

# 查看服务器实际下发的证书信息
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

# 校验证书与私钥是否匹配（比对两个 MD5）
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa  -noout -modulus -in key.pem  | openssl md5

8 API 接入

通过 API Key 以编程方式管理证书，适合集成到 CI/CD 或自建运维平台。

创建 API Key

在「用户中心 → API 密钥」中创建。密钥明文仅显示一次，请立即保存；可通过作用域（scopes）限制权限范围。

鉴权方式

在请求头中携带 X-API-Key：

curl -H "X-API-Key: sk_xxxxxxxxxxxxxxxx" \
  "http://ssl.hshen.eu.cc/?r=api/certs"

接口一览

返回示例

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "domains": ["example.com"],
      "issuer": "Let's Encrypt",
      "status": "active",
      "not_after": "2026-12-11 08:00:00",
      "days_left": 90
    }
  ]
}

9 常见问题

签发失败怎么办？

常见原因与排查方向：

• HTTP-01 校验失败：确认域名解析到本机、80 端口可从公网访问，且 /.well-known/acme-challenge/ 路径可读取。
• DNS-01 校验失败：确认 TXT 记录已生效（dig TXT _acme-challenge.example.com），TTL 较长时需等待。
• 触发频率限制：测试环境有更严格的限额，建议先 staging 调试；正式环境同一域名每周签发次数有限。

支持泛域名吗？

支持。*.example.com 必须使用 DNS-01 验证。若使用手动模式，需按平台提示分两步完成 TXT 记录添加与校验。

续期需要人工介入吗？

正常情况下不需要。配置好续期阈值与部署目标后，定时任务会自动完成续期与推送；仅在验证方式变更或 DNS 凭证失效时才需要人工处理。

私钥存储在哪里？安全吗？

私钥以 AES-256 加密后存入数据库，解密密钥保存在服务器配置文件中，不随代码分发；下载时仅临时解密并直接输出，不落明文文件。

可以自定义证书颁发机构吗？

平台内置 Let's Encrypt（含 staging / production）。如需接入其他 ACME 兼容 CA，可在后台配置 ACME 目录地址。