Quickstart · 约 10 分钟

快速开始

从零到一张会自动续期的泛域名证书：添加域名、发布一条 CNAME、在服务器上创建受限的 SFTP 用户、绑定部署节点。之后的签发、分发、续期都由平台完成。

开始之前

一个可以修改 DNS 解析的域名，例如 example.com
一台可以 SSH 登录的 Linux 服务器（需要 root 或 sudo 权限）
服务器上已经跑着 Nginx / Apache / OpenResty 之类的 Web 服务
不需要开放 80 端口，也不需要把 DNS 服务商的 API 密钥交给平台

免费额度：1 个域名、10 个部署节点、续期不限次数，不需要信用卡。实际额度以控制台「个人额度」卡片显示为准。

接入流程

四个阶段，任何一步失败都会在域名列表里以红色状态标出，不需要靠猜。

注册并添加域名

注册后在控制台进入「域名列表」→ 新增，填写主域名 example.com。

不要填 *.example.com。填写主域名后，平台签发的是泛域名证书，同时覆盖 example.com 和 *.example.com（以及它们的下一级子域名）。只有当你确实只想给单个主机签证书时，才单独添加 api.example.com 这样的完整主机名。

保存后，系统会为该域名生成一条专属的 CNAME 记录值，形如 a1b2c3d4.sethttps.com。
发布一条 DNS 记录

到你的 DNS 服务商处添加下面这条记录（记录类型必须是 CNAME）：

记录类型主机记录记录值 TTL

CNAME _acme-challenge 域名详情页显示的 CNAME 记录值 300 或默认

这条记录的作用是把 Let's Encrypt 的 DNS-01 校验请求转发到平台，由平台统一应答。因为校验走 DNS，所以不需要开放 80 端口，也不需要安装任何插件。

回到列表点「验证」。DNS 生效通常需要 1–5 分钟，个别服务商需要更久；验证失败时等几分钟再点一次即可。各服务商的具体步骤见 DNS 与 CNAME。
在服务器上创建受限的部署用户

平台不直接使用 root 登录你的服务器。你需要在目标服务器上执行一次初始化脚本，它会创建一个专用的 SFTP 用户：
- 该用户的 shell 是 nologin，不能登录终端
- 目录被 chroot 限制在证书目录，只能看到这一个目录
- 只保留 SFTP 文件传输，关闭端口转发与 X11 转发
- 可选：为该用户配置一条免密 sudo 命令，用于后续重载 Web 服务
脚本内容可以在控制台的「部署节点」页面预览，确认后再以 root 身份执行。整个脚本不到 120 行，只做上面这几件事。

源码完全公开，建议先读再跑： github.com/jenawant-rgb/sethttps-agent —— 支持 --dry-run（只打印要做的每一步）和 --uninstall（撤销全部改动）。

记录类型	主机记录	记录值	TTL
CNAME	`_acme-challenge`	域名详情页显示的 CNAME 记录值	300 或默认

添加部署节点

「部署节点」→ 新增，填写这张表：

字段	填什么	示例
节点名称	方便识别的名字	`edge-sg-01`
主机	服务器 IP 或域名	`203.0.113.10`
端口	SSH 端口	`22`
SSH 用户	上一步脚本创建的专用用户	`sethttps_deploy`
密码	该用户的密码	—
证书路径	证书希望落地的目录	`/etc/nginx/ssl/example.com`
重启命令	重载 Web 服务的命令（可选）	`nginx -s reload`

密码使用服务端密钥加密后落库，接口不会回传明文。一个节点对应一个目录，多个域名共用一个目录时，证书文件会按域名前缀区分，不会互相覆盖。

申请证书并部署

回到域名列表点「申请」。DNS-01 校验通过后，Let's Encrypt 会在几十秒内签发证书，列表的「签发状态」变为已签发。

如果该域名已经绑定了部署节点，签发成功后会自动触发一次部署：证书通过 SFTP 上传到你填写的目录，文件名固定为三个：

文件	内容	用在哪
`example.com_cert.pem`	站点证书	一般不用，调试时看
`example.com_full_chain.pem`	站点证书 + 中间证书	`ssl_certificate`
`example.com_key.pem`	私钥	`ssl_certificate_key`

一定要用 full_chain。只配站点证书会让部分安卓设备和命令行客户端报「证书链不完整」，浏览器里看起来却是正常的，很容易漏掉。

在 Nginx 里引用证书

server {
    listen 443 ssl;
    http2 on;                      # nginx < 1.25.1 写成 listen 443 ssl http2;
    server_name example.com *.example.com;

    ssl_certificate     /etc/nginx/ssl/example.com/example.com_full_chain.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com/example.com_key.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
    add_header Strict-Transport-Security "max-age=31536000" always;
}

检查并重载：

nginx -t && nginx -s reload

验证线上实际生效的证书：

echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

重载由节点自己完成

如果部署节点填了重启命令，上面的初始化脚本会在服务器上装两样东西：

/usr/local/bin/sethttps-reload：root 所有、755，内容是你要执行的命令
sethttps-reload.path：一个 systemd path 单元，监听证书目录里的 reload.request

平台上传完证书后，只做一件事：写入这个 reload.request。systemd 随后以 root 执行包装脚本，Nginx 完成重载。

平台不能执行任何别的命令。账号被 chroot、没有 shell，命令内容写在 root 所有的文件里，平台只负责"按下按钮"。这是「自动重载」和「把服务器交出去」之间的分界线。

没填重启命令的节点不会有这个触发器，需要你自己处理，三种做法：

做法	适合	命令
手动	证书很少变、你能接受偶尔手动	`nginx -s reload`
监听目录	无人值守，推荐	`inotifywait` + reload
定时重载	最省事，代价是每天多一次 reload	systemd timer / cron

具体脚本在 Nginx 部署里可以直接复制。

之后会发生什么

平台每天 03:00 扫描全部证书，距到期 10 天以内自动续签
续签成功后自动重新上传到该域名绑定的节点，覆盖同名文件，并触发一次重载
每次签发、部署都会写任务日志，失败原因可以直接看到
续期不消耗额度，也不需要你做任何操作

判断是否真的生效：重载后重新跑一次上面的 openssl 命令，看 notAfter 是否变成了新的日期。只看到文件更新而证书没变，通常就是没有重载。

常见问题

验证一直失败

九成是 CNAME 还没生效，或者记录值填错（多一个点、少了前缀）。用 dig _acme-challenge.example.com CNAME +short 看返回值是否与平台显示的一致。如果域名在 Cloudflare 上，记录的云朵图标必须是灰色（DNS only）。

能不能只给一个子域名签证书

可以。直接添加 api.example.com 这样的完整主机名即可，不必先添加主域名。

部署失败，日志显示认证失败

检查节点的用户名、密码、端口是否正确，以及脚本是否以 root 执行完成（Match User 配置需要重启 sshd 才生效）。

支持多台服务器吗

支持。同一个域名可以绑定多个节点，证书会逐个上传。免费额度内提供 10 个节点。

平台能拿到我的私钥吗

私钥在平台侧生成并存储，用于上传到你的服务器，因此平台在技术上能接触到私钥——这一点任何自动化签发平台都一样。我们做的限制是：私钥不通过 API 回传、只走 SFTP 上传、不在服务器上执行任意命令。介意的话可以只把证书用于测试环境。