该模块的功能 #

TLS 证书就是把 http:// 变成 https:// 的东西：它加密访客与服务器之间的连接，并让浏览器显示挂锁图标，而不是「不安全」的警告。

tls 模块使用 certbot 处理该证书的整个生命周期：它向 Let's Encrypt（一个免费且广受认可的证书颁发机构）申请证书，通过 ACME 挑战证明该域名是你的，把证书安装到你的 Web 服务器期望的位置，并在证书到期前自动续期——无需你去惦记。

开始之前

你的域名（例如 app.ejemplo.com）必须通过 DNS 指向这台服务器的 IP，并且 80 端口对 HTTP-01 挑战可达。否则，签发会在验证步骤失败。

快速指南逐步任务

常见任务 #

选择你想做的事。每份配方都附有写好的命令——只需换上你自己的域名和邮箱，然后点击复制。

签发我的第一张证书查看有哪些证书以及何时到期强制续期一次吊销一张证书删除一张证书

1

签发我的第一张证书

一分钟内为你的域名拿到 HTTPS 挂锁。

用 ubuntu 用户通过 SSH 连接到你的服务器。

运行命令，换上你自己的域名和邮箱（邮箱仅用于在某项即将到期时提醒你）：

终端

$ sudo imaxe tls issue app.ejemplo.com --email [email protected]

等待几秒钟。你会看到挑战的进度，最后是到期日期。

现在你的站点已通过 https:// 带挂锁加载。自动续期已启用——你不需要再做任何事。

2

查看有哪些证书以及何时到期

一眼查看你证书的状态。

一份关于总体状态和续期定时器的快速摘要：

终端

$ sudo imaxe tls status

想逐个域名查看详情，包括剩余天数和 fullchain 路径？使用 list：

终端

$ sudo imaxe tls list

如果你看到某个域名剩余天数不多，就跳到强制续期一次配方。

3

强制续期一次

通常是自动的，但你可以在需要时提前触发。

续期所有临近到期的证书（这正是定时器所做的事）：

终端

$ sudo imaxe tls renew

想先在不触碰磁盘的情况下演练一遍，或者即使还有剩余天数也强制续期？加上 --dry-run 或 --force：

终端

$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force

Web 服务器会带着新证书自行重载。你的访客不会察觉到任何中断。

4

吊销一张证书

在证书颁发机构处使一张证书失效（例如私钥泄露时）。

在 Let's Encrypt 处吊销某个域名的证书，如果你知道原因就一并给出：

终端

$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromise

该证书立即不再有效。如果该域名仍在使用，请用 issue 签发一张新的。

5

从磁盘删除一张证书

停止管理一个你不再使用的域名。

从磁盘移除该证书及其密钥。注意：这不会在证书颁发机构处吊销它——若要吊销，请先使用 revoke。

终端

$ sudo imaxe tls delete tienda.ejemplo.com

该域名会从 imaxe tls list 中消失，其自动续期也随之停止。

有什么没成功？

最常见的问题是 DNS 尚未传播，或者 80 端口被关闭。等几分钟再重试。如果问题依旧，先用 --staging 试用测试模式（参见参考），以免耗尽你的尝试配额。

CLI 参考命令、标志与文件

用法概要 #

用法

imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]

涉及证书的子命令需要 root 权限（使用 sudo），因为它们会写入 /etc/imaxe/ 并重载系统服务。为 list 或 status 添加 --json 可获得适用于脚本的机器可读输出。

子命令 #

子命令	功能	相关标志
issue	为一个或多个域名签发证书，并解决 ACME 挑战。	--email, --webroot, --standalone, --staging
renew	续期临近到期的证书并重载 Web 服务器。适合用于定时器。	--dry-run, --force
list	列出受管理的证书，附带到期剩余天数和 fullchain 路径。	--json
status	摘要：证书数量、临近到期的证书，以及续期定时器状态。	--json
revoke	按域名在证书颁发机构处（ACME）吊销一张证书。	--reason
delete	从磁盘删除证书及其密钥。不在 ACME 处吊销。	—

参数与标志 #

标志	类型	默认值	说明
<dominio> 必填	string…	—	证书的一个或多个域名。在 `issue` 中，第一个是主域名（CN），其余为 SAN。在 `revoke`/`delete` 中，为要操作的域名。
--email	string	tls.yml	ACME 账户的联系邮箱。首次 `issue` 时必填；之后会复用 `tls.yml` 中的那个。
--webroot	path	/var/www/html	HTTP-01 挑战的根目录。默认方法。
--standalone	bool	false	使用 certbot 内置的服务器，而非 webroot。要求 80 端口空闲。
--staging	bool	false	使用 Let's Encrypt 的测试环境（不计入速率限制）。该证书不会被信任。
--dry-run	bool	false	在 `renew` 中，模拟续期而不触碰磁盘。
--force	bool	false	在 `renew` 中，即使尚未临近到期也进行续期。
--reason	enum	unspecified	在 `revoke` 中：`unspecified`、`keycompromise`、`superseded`、`cessationofoperation`。
--json	bool	false	在 `list`/`status` 中，将结果以 JSON 输出到 `stdout`。

文件与路径 #

路径	内容
/etc/imaxe/tls.yml	模块配置：默认邮箱、方法（`webroot`/`standalone`）、webroot、staging、自动续期以及重载钩子。
/etc/letsencrypt/live/<dominio>/	由 certbot 管理的证书（`fullchain.pem`）与私钥（`privkey.pem`）。
/var/log/imaxe/tls.log	每次签发、续期和吊销的结构化日志。
imaxe-tls.timer	周期性触发 `renew` 的 systemd 定时器。

tls.yml 示例：

/etc/imaxe/tls.yml

email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginx

退出码与日志 #

每次执行都会返回一个退出码，你可以用 echo $? 查看——便于在脚本中串联：

0OK操作完成，无待处理的变更。

1ERR未分类的通用错误。请查看日志。

2USAGE参数无效或缺失。

3CHALLENGEACME 验证失败（DNS/HTTP）。

4RATELIMIT已达到 Let's Encrypt 的限制。

5RELOAD签发成功，但 Web 服务器重载失败。

调试时实时跟踪日志：

终端

$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.log

高级示例 #

在单张证书中包含多个域名

第一个域名是主域名；后续的域名会作为 SAN 添加，全部包含在单张证书中：

终端

$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
    --email [email protected]

上生产前的一次安全测试

对照测试环境验证整条链路，以免耗尽你真实的配额。用 --standalone 时你不需要配置好的 Web 服务器：

终端

$ sudo imaxe tls issue app.ejemplo.com \
    --email [email protected] --standalone --staging \
  || echo "falló con código $?"

故障排查 #

现象	可能原因	解决方法
返回 CHALLENGE（退出码 3）	该域名未解析到这台主机，或者 80 端口被关闭。	核实 A/AAAA 记录，并在安全组中开放 80 端口；然后重试。
返回 RATELIMIT（退出码 4）	一周内对同一域名签发次数过多。	用 `--staging` 进行测试；等待时间窗释放。
HTTPS 能加载但带有警告	使用 `--staging` 签发：该证书不被信任。	不带 `--staging` 重新签发以获得有效证书。
返回 RELOAD（退出码 5）	`reload_hook` 指向了一个不存在的服务。	调整 `tls.yml` 中的 `reload_hook`，然后再次运行 `renew`。

TLS 模块遇到问题了？

把「imaxe <module> status --json」的输出发给我们，我们会尽快回复你。

联系支持

HTTPS 证书，轻松无痛