acme.sh：纯 Shell 版免费 SSL 证书自动签发与续期部署使用指南

acme.sh 是一个用纯 Shell 语言编写的 ACME 协议客户端，用来自动申请、续期和安装免费的 SSL/TLS 证书（Let's Encrypt、ZeroSSL、SSL.com、Google Public CA 等）。它不依赖 Python、不要求 root 权限，一条脚本就能完成签发、续期、安装，是目前最流行的 Shell 版证书工具。

一、项目官方信息

项目	信息
GitHub 仓库	https://github.com/acmesh-official/acme.sh
官方网站	https://acme.sh
开源协议	GPL-3.0
主要语言	Shell（约 99.9%）
Star 数	约 48.0k
维护方	现由 ZeroSSL 官方维护，原作者 Neil Pang

acme.sh 完整实现了 ACME 协议，支持 ECDSA 证书、SAN 多域名证书和通配符证书，兼容 Bash、dash、sh，支持 IPv6、Docker，还能通过 cron 邮件通知续期结果或错误。默认 CA 是 ZeroSSL，同时内置支持 Let's Encrypt、SSL.com、Google Public CA、Actalis 以及任何符合 RFC 8555 的 CA。

二、官方图片

下图是 acme.sh 项目 README 顶部的官方横幅（由维护方 ZeroSSL 提供）：

三、环境要求

操作系统：Linux（Debian、Ubuntu、CentOS、Alpine、Arch、Fedora、openSUSE、OpenEuler 等）、macOS、FreeBSD、OpenBSD、NetBSD、Solaris、Windows（Cygwin）、OpenWRT、Proxmox、OPNsense 等，README 中已实测支持 30+ 平台。
基础命令：curl 或 wget（安装用）、cron（自动续期）、openssl 或 curl（ACME 通信与加密）。
端口要求：
Standalone 模式：需要能监听 TCP 80（或 --alpn 模式下的 TCP 443），通常需要 root/sudo。
Webroot 模式：对网站根目录有写权限即可，不需要额外端口。
DNS 模式：不需要开放 80/443，适合内网服务器或需要通配符证书的场景。
不需要 root 即可安装，但监听特权端口、写系统目录时建议用 root。

四、完整部署步骤

1. 在线安装（推荐）

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

或用 wget：

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

其中 my@example.com 换成你自己的邮箱，用于 CA 注册账户与到期提醒。

2. 从 Git 安装

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

安装脚本会自动完成三件事：

把 acme.sh 复制到用户主目录 ~/.acme.sh/，后续所有证书也存放在这个目录；
创建 alias：acme.sh=~/.acme.sh/acme.sh；
自动添加一条每日 cron 任务，用于检查并续期证书，示例：

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

安装完成后，必须关闭当前终端并重新打开，alias 才能生效。

3. 验证安装

acme.sh -h

能输出帮助信息即说明安装成功。

4. 用 Webroot 模式签发证书（最常用）

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

-d example.com：要签发证书的主域名；
-w /home/wwwroot/example.com：网站根目录，必须对它有写权限。

多域名签在同一张证书里：

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

所有域名必须解析到同一台服务器并指向同一 webroot 目录。证书会保存在 ~/.acme.sh/example.com/，默认每 30 天自动续期一次，默认签发 ECC（ECDSA P-256）证书。

5. 安装证书到 Nginx / Apache

重要：不要直接使用 ~/.acme.sh/ 里的证书文件，它们是内部文件，目录结构可能变动。必须用 --install-cert 命令把证书复制到 Web 服务器路径，并配置 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 示例：

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"

reloadcmd 非常关键：证书自动续期后会自动执行它来重载 Web 服务器，否则新证书不会被加载。

五、使用方法

Standalone 模式（无网站时）

需要能监听 TCP 80：

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

用 TLS-ALPN 监听 443 端口：

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

Nginx / Apache 模式

acme.sh 会临时改 Nginx/Apache 配置完成验证，验证完自动还原，不会改你的网站配置：

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

DNS 模式（签通配符证书首选）

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

dns_cf 是 Cloudflare 的 DNS API 插件。acme.sh 支持几乎所有主流 DNS 服务商的 API，配置好对应的 API Key 后即可全自动签发与续期，无需手动添加 TXT 记录。

手动 DNS 模式

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

按提示手动添加 _acme-challenge 的 TXT 记录后，再执行：

acme.sh --renew -d example.com

手动 DNS 模式无法自动续期，每次续期都要手动加 TXT 记录，生产环境请用 DNS API 模式。

指定密钥类型

默认 ECDSA P-256，可切换：

# ECDSA P-384
acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-384
# RSA 4096
acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength 4096

可选值：ec-256（默认）、ec-384、ec-521、2048、3072、4096。

续期、升级与停止续期

# 强制续期
acme.sh --renew -d example.com --force
# ECC 证书强制续期
acme.sh --renew -d example.com --force --ecc
# 升级到最新版
acme.sh --upgrade
# 开启自动升级
acme.sh --upgrade --auto-upgrade
# 从续期列表移除（不删本地文件）
acme.sh --remove -d example.com [--ecc]

acme.sh 已支持 RFC 9773 ARI：cron 运行时会自动询问 CA 建议的续期时间窗口，并在窗口内随机选点续期，无需任何额外参数。

六、常见问题 FAQ

1. 为什么续期后浏览器还是显示旧证书？ 因为 --install-cert 时没有配置正确的 --reloadcmd，证书续期后 Nginx/Apache 没有被重载。重新执行一次 --install-cert，把 --reloadcmd 设为 service nginx force-reload（或对应服务命令）即可。

2. Standalone 模式报 80 端口被占用？ Standalone 模式要求 TCP 80 空闲。先停掉正在运行的 Nginx/Apache，或改用 Webroot 模式；也可以用 --alpn 模式（需要 443 空闲）。

3. 通配符证书为什么签发失败？ 通配符证书（如 *.example.com）不支持 HTTP 验证，必须用 DNS 模式，即配置 DNS 服务商的 API（如 dns_cf）后执行 acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf。

4. 为什么不能直接用 ~/.acme.sh/ 里的证书文件？ 这是内部目录，目录结构和文件名未来可能调整。官方明确要求用 --install-cert 把证书复制到 Web 服务器路径，并通过 reloadcmd 自动重载。

5. 安装后 alias 不生效？ 安装脚本写入的是 ~/.bashrc（或对应 shell 配置），必须关闭当前终端重新打开，或执行 source ~/.bashrc 后再用 acme.sh 命令。

6. 怎么换成 Let's Encrypt（而不是默认 ZeroSSL）？

acme.sh --set-default-ca --server letsencrypt

之后签发的证书默认走 Let's Encrypt。

七、跳转链接

GitHub 仓库：https://github.com/acmesh-official/acme.sh
官方网站：https://acme.sh
Wiki（DNS API、Docker、通知等）：https://github.com/acmesh-official/acme.sh/wiki