经验 - Wizard Doc

最后修改人	孙荣利
最后修改时间	2026-10-03 15:55:20
创建人	孙荣利
创建时间	2026-10-03 15:27:39

该文档由孙荣利创建于 2026-10-03 15:27:39 ，孙荣利在 2026-10-03 15:55:20 修改了该文档。

[TOCM]

## 一、简介

```text
acme.sh 是一个纯 Shell 编写的 ACME 协议客户端，可自动申请、续期 Let's Encrypt 证书，续期后自动安装到 Nginx 并重载，实现 HTTPS 证书全自动管理。

验证方式：webroot 验证（在域名可访问的目录下放置验证文件，证明域名所有权）。
WAF 差异：无 WAF 产品时，安装命令可加 --reloadcmd "nginx -s reload" 自动重载；有 WAF 时需人工执行 nginx -s reload 重载（WAF 会拦截验证流量）。
```

## 二、安装与使用

#### 1. 安装 acme.sh

```shell
# 安装 acme.sh（注册邮箱 langbaby@163.com），并加载环境变量
curl https://get.acme.sh | sh -s email=langbaby@163.com; source ~/.bashrc

# 验证安装版本
acme.sh --version
```

#### 2. 通用流程说明

```text
每个域名证书的申请分三步（均为 webroot 验证方式）：
  1. 设置变量：DOMAIN（域名）、WEBROOT（验证目录，仅用于存放验证文件）
  2. 准备验证目录并授权（nginx 用户可读写）
  3. 首次申请（--issue）→ 安装部署（--install-cert）

注意：
  - --issue 只申请证书；--install-cert 负责安装证书到指定路径并写入定时任务（续期后自动重新安装）
  - --reloadcmd 决定续期后是否自动重载 nginx：无 WAF 可加，有 WAF 不加（人工重载）
  - 验证目录需在 Nginx 中配置 location 放行（见第 4 节）
```

#### 3. 证书申请示例（按域名）

**场景一：www.358369.xyz（无 WAF，自动重载）**

```shell
DOMAIN="www.358369.xyz"  # 申请证书的域名
# 新建任意随机目录（如 /opt/xxx）作为 WEBROOT，核心作用仅为验证域名所有权
WEBROOT="/opt/www"  # 验证目录
mkdir -p ${WEBROOT}/.well-known/acme-challenge  # 创建 ACME 验证目录
chmod -R 755 ${WEBROOT}/.well-known  # 授权 755
chown -R nginx:nginx ${WEBROOT}/.well-known  # 归属 nginx 用户

# 首次申请证书（执行一次即可，ECC 256 位密钥，Let's Encrypt）
/root/.acme.sh/acme.sh --issue -d ${DOMAIN} --webroot ${WEBROOT} --server letsencrypt --keylength ec-256

# 安装部署规则（执行一次，写入定时任务配置，永久生效）
mkdir -p /etc/nginx/conf.d/ssl/www  # 创建证书存放目录
/root/.acme.sh/acme.sh --install-cert -d ${DOMAIN} \
  --key-file /etc/nginx/conf.d/ssl/www.358369.xyz.key \  # 私钥输出路径
  --fullchain-file /etc/nginx/conf.d/ssl/www.358369.xyz_bundle.crt \  # 完整证书链输出路径
  --reloadcmd "nginx -s reload"  # 无 WAF：续期后自动重载 nginx
```

**场景二：xmkl.top（人工重载）**

```shell
DOMAIN="xmkl.top"
# 新建任意随机目录（如 /opt/xxx）作为 WEBROOT，核心作用仅为验证域名所有权
WEBROOT="/data/html/opt/dshf"
mkdir -p ${WEBROOT}/.well-known/acme-challenge
chmod -R 755 ${WEBROOT}/.well-known
chown -R nginx:nginx ${WEBROOT}/.well-known

# 首次申请证书（执行一次即可）
/root/.acme.sh/acme.sh --issue -d ${DOMAIN} --webroot ${WEBROOT} --server letsencrypt --keylength ec-256

# 安装部署规则（执行一次，写入定时任务配置，永久生效）
mkdir -p /etc/nginx/conf.d/ssl/dshf
/root/.acme.sh/acme.sh --install-cert -d ${DOMAIN} \
  --key-file /etc/nginx/conf.d/ssl/dshf/xmkl.top.key \
  --fullchain-file /etc/nginx/conf.d/ssl/dshf/xmkl.top_bundle.crt
# 没有 --reloadcmd：有 WAF 或人工管理场景，续期后需人工 nginx -s reload
```

**场景三：hp.dfgbjy.com（适用无 WAF 产品的场景）**

```shell
/root/.acme.sh/acme.sh --install-cert -d ${DOMAIN} \
  --key-file /etc/nginx/conf.d/ssl/dfgb/hp.dfgbjy.com.key \
  --fullchain-file /etc/nginx/conf.d/ssl/dfgb/hp.dfgbjy.com_bundle.crt \
  --reloadcmd "nginx -s reload"  # 无 WAF：续期后自动重载 nginx
```

**场景四：mz.scdongsheng.com（已有 SSL 证书，迁移到 acme.sh 自动续期）**

```shell
DOMAIN="mz.scdongsheng.com"
# 新建任意随机目录（如 /opt/xxx）作为 WEBROOT，核心作用仅为验证域名所有权
WEBROOT="/data/html/opt/dongsheng"
mkdir -p ${WEBROOT}/.well-known/acme-challenge
chmod -R 755 ${WEBROOT}/.well-known
chown -R nginx:nginx ${WEBROOT}/.well-known

# 首次申请证书（执行一次即可，替换原有证书）
/root/.acme.sh/acme.sh --issue -d ${DOMAIN} --webroot ${WEBROOT} --server letsencrypt --keylength ec-256

# 安装部署规则（执行一次，写入定时任务配置，永久生效）
# mkdir -p /etc/nginx/conf.d/ssl/dfgb;  # 原注释：如需建目录可参考（本场景证书目录已存在）
/root/.acme.sh/acme.sh --install-cert -d ${DOMAIN} \
  --key-file /etc/nginx/conf.d/ssl/dongsheng/mz.scdongsheng.com.key \
  --fullchain-file /etc/nginx/conf.d/ssl/dongsheng/mz.scdongsheng.com.crt
# 无 --reloadcmd：续期后需人工 nginx -s reload
```

#### 4. nginx 验证目录配置（放行 ACME 验证请求）

```nginx
# 在对应域名的 server 块中添加（root 路径需与上述 WEBROOT 保持一致）
location /.well-known/acme-challenge/ {
    root /opt/www;   # 示例：场景一（场景二为 /data/html/opt/dshf）
    allow all;       # 放行验证请求（仅 ACME 验证文件，无安全风险）
}
```

#### 5. 证书管理与验证

```shell
# 查看已申请的证书列表
acme.sh --list

# 手动触发续期测试（验证自动续期链路是否正常）
acme.sh --renew -d ${DOMAIN} --force

# 续期后确认 nginx 已加载新证书（无 reloadcmd 的场景需手动执行）
nginx -s reload
nginx -t   # 先校验配置语法
```