ACME Shell脚本：acme.sh

Shellcheck PebbleStrict DockerHub

一个纯Shell（Unix shell）语言编写的ACME协议客户端。
完整实现ACME协议。
支持ECDSA证书
支持SAN和通配符证书
简单、强大且易于使用。您只需3分钟即可学会。
兼容Bash、dash和sh。
纯Shell编写，无Python依赖。
只需一个脚本即可自动签发、续期和安装证书。
无需root/sudoer权限。
支持Docker
支持IPv6
续期或错误等情况的Cron作业通知。

这可能是最简单、最智能的自动签发和续期免费证书的Shell脚本。

Wiki：https://github.com/acmesh-official/acme.sh/wiki

Docker爱好者：acme.sh :two_hearts: Docker

Twitter：@neilpangxa

中文说明

谁在使用：

已测试的操作系统

序号	状态	平台
1		Mac OSX
2		Windows（包含cygwin、curl、openssl和crontab）
3		FreeBSD
4		Solaris
5		Ubuntu
6	不适用	pfsense
7		OpenBSD
8		NetBSD
9		DragonFlyBSD
10		Omnios
11		Debian
12		CentOS
13		openSUSE
14		Alpine Linux（包含curl）
15		Archlinux
16		Fedora
17		Kali Linux
18		Oracle Linux
19		Mageia
20		Gentoo Linux
21		ClearLinux
22	-----	Cloud Linux https://github.com/acmesh-official/acme.sh/issues/111
23	-----	OpenWRT：已测试并可用。请参阅wiki页面
24		Proxmox：请参阅Proxmox VE维基。4.x、5.0、5.1版本，5.2及更高版本
查看我们的测试项目:

https://github.com/acmesh-official/acmetest

支持的证书颁发机构

ZeroSSL.com CA（默认）
Letsencrypt.org CA
BuyPass.com CA
SSL.com CA
Google.com 公共 CA
Pebble 严格模式
任何其他符合 RFC8555 的 CA

支持的模式

Webroot 模式
独立模式
独立 tls-alpn 模式
Apache 模式
Nginx 模式
DNS 模式
DNS 别名模式
无状态模式

1. 如何安装

1. 在线安装

查看此项目：https://github.com/acmesh-official/get.acme.sh

curl https://get.acme.sh | sh -s email=my@example.com

或：

wget -O -  https://get.acme.sh | sh -s email=my@example.com

2. 或者，从 git 安装

克隆此项目并启动安装：

git clone https://github.com/acmesh-official/acme.sh.git
cd ./acme.sh
./acme.sh --install -m my@example.com

你不必是 root 用户，尽管推荐使用 root。

高级安装：https://github.com/acmesh-official/acme.sh/wiki/How-to-install

安装程序将执行 3 个操作：

创建并复制 acme.sh 到你的主目录（$HOME）：~/.acme.sh/。所有证书也将放在这个文件夹中。
为以下命令创建别名：acme.sh=~/.acme.sh/acme.sh。
创建每日 cron 任务以检查并在需要时续期证书。

Cron 条目示例：

0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null

安装完成后，你必须关闭当前终端并重新打开，以使别名生效。

好了，现在你可以开始颁发证书了。

显示帮助信息：

root@v1:~# acme.sh -h

2. 仅颁发证书

示例 1： 单域名。

acme.sh --issue -d example.com -w /home/wwwroot/example.com

或：

acme.sh --issue -d example.com -w /home/username/public_html

或：

acme.sh --issue -d example.com -w /var/www/html

示例 2： 在同一证书中包含多个域名。

acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com

参数 /home/wwwroot/example.com 或 /home/username/public_html 或 /var/www/html 是你存放网站文件的网站根目录。你必须对这个文件夹有写入权限。

第二个参数 "example.com" 是你想要为其颁发证书的主域名。你必须至少有一个域名。

你必须将所有域名指向并绑定到同一个网站根目录：/home/wwwroot/example.com。

证书将被放置在 ~/.acme.sh/example.com/ 中。

证书将每 60 天自动续期一次。

3. 将证书安装到 Apache/Nginx 等

生成证书后，你可能想要将证书安装/复制到你的 Apache/Nginx 或其他服务器。你必须使用此命令将证书复制到目标文件，不要直接使用 ~/.acme.sh/ 文件夹中的证书文件，它们仅供内部使用，文件夹结构将来可能会改变。

Apache 示例：

acme.sh --install-cert -d example.com \
--cert-file      /path/to/certfile/in/apache/cert.pem  \
--key-file       /path/to/keyfile/in/apache/key.pem  \
--fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
--reloadcmd     "service apache2 force-reload"

Nginx 示例：

acme.sh --install-cert -d example.com \
--key-file       /path/to/keyfile/in/nginx/key.pem  \
--fullchain-file /path/to/fullchain/nginx/cert.pem \
--reloadcmd     "service nginx force-reload"

只有域名是必需的，所有其他参数都是可选的。

现有文件的所有权和权限信息将被保留。你可以预先创建文件以定义所有权和权限。

将证书/密钥安装/复制到生产环境的 Apache 或 Nginx 路径。

证书默认每 60 天续期一次（可配置）。一旦证书续期，Apache/Nginx 服务将通过命令自动重新加载：service apache2 force-reload 或 service nginx force-reload。

请注意：reloadcmd 非常重要。证书可以自动续期，但如果没有正确的 'reloadcmd'，证书可能不会刷新到你的服务器（如 nginx 或 apache），那么你的网站在 60 天后将无法显示续期的证书。

4. 使用独立服务器颁发证书

（需要你是 root/sudoer 用户或有权限监听 80 端口（TCP））

端口 80（TCP）必须空闲以供监听，否则你将被提示释放它并重试。

acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com

5. 使用独立 SSL 服务器颁发证书

（需要你是 root/sudoer 用户或有权限监听 443 端口（TCP））

端口 443（TCP）必须空闲以供监听，否则你将被提示释放它并重试。

acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com

6. 使用 Apache 模式

(需要您是 root/sudoer 用户,因为需要与 Apache 服务器交互)

如果您正在运行 Web 服务器,建议使用 Webroot 模式。

特别是,如果您正在运行 Apache 服务器,可以使用 Apache 模式。这种模式不会向您的 Web 根目录写入任何文件。

只需将字符串 "apache" 作为第二个参数,它将自动强制使用 apache 插件。

acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com

这种 apache 模式仅用于颁发证书,不会更改您的 apache 配置文件。您需要自行配置网站配置文件以使用证书。我们不想干扰您的 apache 服务器,请放心。

7. 使用 Nginx 模式

(需要您是 root/sudoer 用户,因为需要与 Nginx 服务器交互)

如果您正在运行 Web 服务器,建议使用 Webroot 模式。

特别是,如果您正在运行 nginx 服务器,可以使用 nginx 模式。这种模式不会向您的 Web 根目录写入任何文件。

只需将字符串 "nginx" 作为第二个参数。

它将自动配置 nginx 服务器以验证域名,然后将 nginx 配置恢复到原始版本。

因此,配置不会改变。

acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com

这种 nginx 模式仅用于颁发证书,不会更改您的 nginx 配置文件。您需要自行配置网站配置文件以使用证书。我们不想干扰您的 nginx 服务器,请放心。

8. 自动 DNS API 集成

如果您的 DNS 提供商支持 API 访问,我们可以使用该 API 自动颁发证书。

您无需手动操作!

目前 acme.sh 支持大多数 DNS 提供商:

https://github.com/acmesh-official/acme.sh/wiki/dnsapi

9. 使用 DNS 手动模式:

首先参见: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode。

如果您的 DNS 提供商不支持任何 API 访问,您可以手动添加 txt 记录。

acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com

您应该会得到类似以下的输出:

添加以下 txt 记录:
域名:_acme-challenge.example.com
Txt 值:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c

添加以下 txt 记录:
域名:_acme-challenge.www.example.com
Txt 值:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

请将这些 txt 记录添加到域名中。等待 DNS 生效。

然后只需使用 renew 参数重新运行:

acme.sh --renew -d example.com

好了,完成了。

注意,这是 DNS 手动模式,无法自动续期。当您续期证书时,需要手动为域名添加新的 txt 记录。

请改用 DNS API 模式。

10. 颁发 ECC 证书

只需在 keylength 参数前加上 ec- 前缀。

例如:

单域名 ECC 证书

acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256

SAN 多域名 ECC 证书

acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256

请注意上面的 keylength 参数。

有效值为:

ec-256 (prime256v1, "ECDSA P-256", 这是默认密钥类型)
ec-384 (secp384r1, "ECDSA P-384")
ec-521 (secp521r1, "ECDSA P-521", Let's Encrypt 尚不支持)
2048 (RSA2048)
3072 (RSA3072)
4096 (RSA4096)

11. 颁发通配符证书

很简单,只需将通配符域名作为 -d 参数即可。

acme.sh  --issue -d example.com  -d '*.example.com'  --dns dns_cf

12. 如何续期证书

不,您不需要手动续期证书。所有证书将每 60 天自动续期一次。

但是,您也可以强制续期证书:

acme.sh --renew -d example.com --force

或者,对于 ECC 证书:

acme.sh --renew -d example.com --force --ecc

13. 如何停止证书续期

要停止续期证书,您可以执行以下操作将证书从续期列表中删除:

acme.sh --remove -d example.com [--ecc]

证书/密钥文件不会从磁盘中删除。

您可以自行删除相应的目录(例如 ~/.acme.sh/example.com)。

14. 如何升级 `acme.sh`

acme.sh 正在不断开发中,因此强烈建议使用最新代码。

您可以将 acme.sh 更新到最新代码:

acme.sh --upgrade

您还可以启用自动升级:

acme.sh --upgrade --auto-upgrade

然后 acme.sh 将自动保持最新状态。

禁用自动升级:

acme.sh --upgrade --auto-upgrade 0

15. 从现有 CSR 颁发证书

https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR

16. 在 cronjob 中发送通知

https://github.com/acmesh-official/acme.sh/wiki/notify

17. 底层原理

使用 shell 直接与 "Let's Encrypt" 通信 ACME 语言。

待完成:

18. 致谢

Acme-tiny: https://github.com/diafygi/acme-tiny
ACME 协议: https://github.com/ietf-wg-acme/acme

贡献者

代码贡献者

这个项目的存在要感谢所有做出贡献的人。 <a href="https://github.com/acmesh-official/acme.sh/graphs/contributors"><img src="https://yellow-cdn.veclightyear.com/835a84d5/7a15e140-da6e-4b08-95cb-d4a136c06ce3.svg?width=890&button=false" /></a>