Acme.sh 使用
跳到导航
跳到搜索
关于
通过 acme.sh 脚本，可以申请、自动更新证书。 项目相关地址： 1、acme.sh 项目主页（中文说明） 2、acme.sh/wiki 3、acme.sh/wiki/Options-and-Params
支持的证书：
- ZeroSSL.com CA（default）
- Letsencrypt.org CA
- BuyPass.com CA
- SSL.com CA
- Pebble strict Mode
- Any other RFC8555-compliant CA
支持的模式：（使用场景）
- Webroot mode
- Standalone mode
- Standalone tls-alpn mode
- Apache mode
- Nginx mode
- DNS mode
- DNS alias mode
- Stateless mode
以下只关注其 DNS mode 模式的“Automatic DNS API integration”方式。 （目前 acme.sh 支持大多数 dns 提供商，包括 Cloudflare、GoDaddy、Aliyun 等） 官方连接：How to use DNS API
参考：
acme.sh
安装、更新、卸载
- 安装：
- 在线安装：
curl https://get.acme.sh | sh # 或者 wget -O - https://get.acme.sh | sh
- 通过 git 安装：
git clone https://github.com/acmesh-official/acme.sh.git cd ./acme.sh ./acme.sh --install
- 安装位置：“~/.acme.sh/”（若 root 用户安装，即：“/root/.acme.sh”）；
- 安装好后，会自动为你创建 cronjob（计划任务）, 每天 0:00 点自动检测所有的证书, 如果快过期了, 需要更新, 则会自动更新证书。
- 查看已创建的 cronjob：
[root@newjersey ~]# crontab -l 5 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null
- 在线安装：
- 更新：
# 升级 acme.sh 到最新版 : acme.sh --upgrade # 如果你不想手动升级, 可以开启自动升级: acme.sh --upgrade --auto-upgrade # 你也可以随时关闭自动更新: acme.sh --upgrade --auto-upgrade 0
- 卸载：
acme.sh --uninstall
- 并同时卸载 cron 作业；
其他命令
参考：
- GitHub 项目页面；
- acme.sh 命令行工具
证书管理
以下摘抄自项目说明。 参见： 1、acme.sh 项目 2、中文说明 3、More examples：How to issue a cert 4、How to use DNS API 5、DNS manual mode 6、DNS alias mode
证书颁发
以下： 1、除了“安装证书到 Apache/Nginx”、“Apache 模式”、“Nginx 模式”、“自动 DNS API”无需手动配置，其他的证书都生成在“~/.acme.sh/<example.com>/”目录下，需要手动拷贝到需要的位置； 2、除了“DNS 手动模式”，其他都可以自动续订；
acme.sh 有多种证书颁发用法：
- 颁发单个证书：
- 用于一个网站：
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
- 参数“/home/wwwroot/example.com”或“/home/username/public_html”或“/var/www/html”是承载网站文件的 web root 文件夹（您必须具有对此文件夹的写入权限）；
- 用于多个网站：
acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
- 必须将所有域名，指向并绑定到同一 webroot 目录（如上的“/home/wwwroot/example.com”）；
- 证书将放在：“~/.acme.sh/example.com/”；
- 证书将每60天自动更新一次；
- 用于一个网站：
- 安装证书到 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"
- 参数说明：
- “-d example.com”：指定域名；（此为必须参数，其他参数都是可选）
- “--cert-file”：颁发/续订后，将“证书文件”复制到的路径；
- “--key-file”：颁发/续订后，将“密钥文件”复制到的路径；
- “--fullchain-file”：颁发/续订后，将“fullchain证书文件”复制到的路径；
- “--reloadcmd”：发出/续订后，要“执行的命令”以重新加载服务器；
- 用于将“证书/密钥”，“安装/复制”到 Apache/Nginx 的生产路径；【无需任何证书相关的手动配置】
- 默认情况下，证书将每60天更新一次（可配置）。证书续订后，Apache/Nginx 服务将通过以下命令自动重新加载：“service apache2 force reload”或“service Nginx force reload”；
- 【如果没有正确的“reloadcmd”，证书可能不会刷新到您的服务器，那么您的网站将无法在 60 天内显示续订的证书】
- 使用独立服务器颁发证书：（如果你还没有运行任何 web 服务, 80 端口是空闲的）
acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
- 要求：root/sudoer，或具有侦听端口 80（TCP）的权限；
- 使用独立 ssl 服务器颁发证书：（如果你还没有运行任何 ssl 服务, 443 端口是空闲的）
acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com
- 要求：root/sudoer，或具有侦听端口 443（TCP）的权限；
- 使用 Apache 模式：（如果您正在运行 Web 服务器，且运行的是 Apache 服务器，则推荐使用此模式）
acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
- 要求：root/sudoer，因为它是与 Apache 服务器交互所必需的；
- 此模式不会将任何文件写入 web roo 文件夹（仅用于颁发证书，而不会更改您的 Apache 配置文件），所以，【需要自行配置网站配置文件以使用证书】；
- 使用 Nginx 模式：（如果您正在运行 Web 服务器，且运行的是 Nginx 服务器，则推荐使用此模式）
acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com
- 要求：root/sudoer，因为它是与 Nginx 服务器交互所必需的；
- 此模式不会将任何文件写入 web root 文件夹（仅用于颁发证书，而不会更改您的 Nginx 配置文件），所以，【需要自行配置网站配置文件以使用证书】；
- 自动 DNS API 集成：（如果您的 DNS 提供商支持 API 访问）
- 【无需任何证书相关的手动配置】
- 见：How to use DNS API；
- 使用 DNS 手动模式:（如果您的 DNS 提供商不支持任何 API 访问，可以手动添加 txt 记录）
- 生成解析记录：
acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
- 第一次申请在后面加上“--yes-I-know-dns-manual-mode-enough-go-ahead-please”；
acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please
- 然后，acme.sh 会生成相应的解析记录显示出来（如下），你需要在你的域名管理面板中添加这条 TXT 记录：
Add the following txt record: Domain:_acme-challenge.example.com Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c Add the following txt record: Domain:_acme-challenge.www.example.com Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Please add those txt records to the domains. Waiting for the dns to take effect.
- 等待解析完成之后，重新生成证书：（请先等待 1 分钟，等待 DNS 条目反映）
acme.sh --renew -d example.com -d www.example.com -d cp.example.com
- 第一次申请在后面加上“--yes-I-know-dns-manual-mode-enough-go-ahead-please”：
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please
- 如果您已使用 SHA CSR 颁发了 暂存/生产 证书，则使用“--force”开关覆盖旧 CER 的任何条目并颁发新 CER：
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please --force
- 如果您已使用 ECC CSR 颁发了 暂存/生产 证书，则使用“--ECC--force”开关覆盖旧 CER 的任何条目并颁发新 CER：
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please --ecc --force
- 这种方式的好处是，你不需要任何服务器，不需要任何公网 ip，只需要 dns 的解析记录即可完成验证；【一般用于测试，务必谨慎用于生产环境】
- 此模式不能自动续订。当您更新证书时，您必须手动将新的 txt 记录添加到您的域中；
- 见：DNS manual mode；
- 见：DNS alias mode；
- 生成解析记录：
- 颁发 ECC 证书：（Let's Encrypt 现在可以颁发 ECDSA 证书了）
- 单域 ECC 证书：
acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
- 多域 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", which is not supported by Let's Encrypt yet.）
- 单域 ECC 证书：
- 颁发通配符证书：
acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf
证书更新
您不需要手动续订证书。所有证书将每 60 天自动更新一次。
- 强制更新证书：
# 更新指定证书 acme.sh --renew -d example.com --force [--ecc] # 更新所有证书： acme.sh --renew-all
- --ecc：表示 ECC 证书
- 停止证书更新：
acme.sh --remove -d example.com [--ecc]
吊销证书
如果你的私钥文件泄露或者不再使用，可以选择吊销该证书。
如果要吊销一个证书，使用：
# 列出全部证书 acme.sh --list # 吊销证书： acme.sh --revoke -d example.com # 吊销证书，并指定理由： acme.sh --revoke -d example.com --revoke-reason 0
移除证书
用于从 acme.sh 已知的证书列表中删除证书。（但并不吊销该证书）
如果要删除一个证书，使用：
# 列出全部证书 acme.sh --list # acme.sh --remove -d example.com
- 执行证书移除命令后，acme.sh 仅不再参与该证书的工作，但证书文件仍然在“~/acme.sh”文件夹下，需要用户手动删除。
出错怎么办
如果出错, 请添加 debug log：
acme.sh --issue ..... --debug # 或者： acme.sh --issue ..... --debug 2
详解：DNS认证方式（推荐）
这种方式不需要服务器和公网 IP，只需要 DNS 的解析记录即可完成验证，一般主流域名服务商都提供 API 接口。 （目前 acme.sh 支持包括主流的 CloudFlare、DNSPod、Aliyun、Amazon Route53 在内的多达 131 个的域名 API，见：How to use DNS API）
- 给 GoDaddy 自动颁发证书：
#（替换 GD_Key 为自己的） export GD_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" #（替换 GD_Secret 为自己的） export GD_Secret="asdfsdafdsfdsfdsfdsfdsafd" #（<example.com> 为自己的域名） acme.sh --issue --dns dns_gd -d <example.com> [-d <example.com>]
- GoDaddy API Key 创建地址：https://developer.godaddy.com/keys/
- 给 CloudFlare 自动颁发证书：
#（替换 CF_Key 为自己的） export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" #（替换 CF_Email 为自己的 GoDaddy 登录邮箱） export CF_Email="xxxx@sss.com" #（<example.com> 为自己的域名） acme.sh --issue --dns dns_cf -d <example.com> [-d <example.com>]
- CloudFlare API Key 创建地址：https://dash.cloudflare.com/profile。
- 配置步骤，1、先配置 DNS 解析，2、生成 CloudFlare API Key：
- 在 CloudFlare 添加站点（根域名）；
- 在“DNS”项，添加记录（“类型”：A；“名称”：子域名的一级域名；“内容”：服务器IP）；
- 根据提示，修改域名供应商的 DNS 地址（在“DNS修改”将其 DNS 指定为 CloudFlare 的 DNS 地址）；
- 在 CloudFlare 将 SSL/TLS 更改为“完全”（Full）；
- 验证配置（ping 一下该域名，得到一个ip，查一查该ip是不是 CloudFlare 的地址）
CloudFlare 可用于“'''DNS 解析'''”和“'''CDN 加速'''”。 （此处只用其 DNS 解析的功能，因为国外的 CDN 反而可能导致降速） （如果 ip 被锁，倒是可以考虑使用其 CDN 功能拯救一下 ip）
FAQ
“-bash: acme.sh: command not found”
如果“acme.sh”命令提示：“-bash: acme.sh: command not found”，则先执行以下命令：
source ~/.bashrc
再继续执行其他命令。
关于使用的 CA 机构
执行时，提示：
[root@newjersey ~]# acme.sh --issue --dns dns_cf -d <example.com> [Tue Nov 30 23:12:51 UTC 2021] Using CA: https://acme.zerossl.com/v2/DV90 [Tue Nov 30 23:12:51 UTC 2021] Create account key ok. [Tue Nov 30 23:12:51 UTC 2021] No EAB credentials found for ZeroSSL, let's get one [Tue Nov 30 23:12:51 UTC 2021] acme.sh is using ZeroSSL as default CA now. [Tue Nov 30 23:12:51 UTC 2021] Please update your account with an email address first. [Tue Nov 30 23:12:51 UTC 2021] acme.sh --register-account -m my@example.com [Tue Nov 30 23:12:51 UTC 2021] See: https://github.com/acmesh-official/acme.sh/wiki/ZeroSSL.com-CA [Tue Nov 30 23:12:51 UTC 2021] Please add '--debug' or '--log' to check more details. [Tue Nov 30 23:12:51 UTC 2021] See: https://github.com/acmesh-official/acme.sh/wiki/How-to-debug-acme.sh
- 即，acme.sh（从2021年8月1日起）默认 CA 换成了 ZeroSSL（需要注册账号才能使用）。
所以如果需要使用其他 CA：（两种方式）
- 签发时指定：
# 本次使用 letsencrypt 机构的证书 acme.sh --issue --dns dns_cf -d <example.com> --server letsencrypt
- 更改默认：
# 指定默认的证书机构为 letsencrypt acme.sh --set-default-ca --server letsencrypt
- 以后就算版本升级也将一直默认使用指定的 CA。