Certbot 安装方案详解（apt/pip/snap 多方案）

目标：在 Ubuntu 22.04 上安装 Certbot 以申请 Let's Encrypt 免费 SSL 证书。本文对比 apt、pip、snap 三种安装方式，给出命令、装后位置、版本号与优劣势。所有命令均在 Ubuntu 22.04.5 (jammy) 服务器实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（jammy）
Nginx：1.18.0（Ubuntu）
Python：3.10
ACME 服务：acme-v02.api.letsencrypt.org（本机实测可解析）
证书目录：/etc/letsencrypt

二、三种安装方式对比

方式	路径	实测版本	是否支持 aliyun 插件	适用场景
apt	/usr/bin/certbot	1.21.0	需另 pip 插件，路径易冲突	快速装、只要基础功能
pip	/usr/local/bin/certbot	5.8.0	✅ 内置 dns-aliyun	需要阿里云 DNS 通配符（推荐）
snap	/snap/bin/certbot	5.8.0	无 dns-aliyun（自带 apache/nginx）	官方推荐，需 systemd（真机）

⚠️ 结论：若目标是「阿里云 DNS 通配符证书 + 自动续期」，用 pip 方案，能直接 certbot plugins 看到 dns-aliyun，路径统一、版本最新。

三、方式一：apt 安装（最简单）

apt-get update
apt-get install -y certbot python3-certbot-nginx

实测输出：

/usr/bin/certbot
certbot 1.21.0

💡 说明：apt 版是发行版打包（1.21.0），装到 /usr/bin/certbot，自带 --nginx 插件（HTTP-01 自动配置）。但它不带阿里云 DNS 插件，且版本偏旧。

四、方式二：pip 安装（推荐，内置 aliyun 插件）

# 1. 安装 Python 工具
apt-get install -y python3-pip python3-venv libaugeas0

# 2. 用 pip 安装 certbot 与阿里云 DNS 插件
pip3 install --upgrade certbot certbot-dns-aliyun

实测输出：

/usr/local/bin/certbot   # which certbot
certbot 5.8.0            # certbot --version

查看已识别插件：

certbot plugins | grep -i dns-aliyun

实测输出（确认 dns-aliyun 已被识别）：

* dns-aliyun
Description: Obtain certificates using a DNS TXT record (if you are using Aliyun
Entry point: EntryPoint(name='dns-aliyun',
value='certbot_dns_aliyun.dns_aliyun:Authenticator', group='certbot.plugins')

插件版本：pip3 show certbot-dns-aliyun → Reference Version: 2.0.0。

⚠️ 说明：

pip 装完后 which certbot 指到 /usr/local/bin/certbot，若你之前装过 apt 版，需确保用新路径，避免调用到旧版；

较新系统因 PEP 668 保护会拒绝写入系统 Python，出现 externally-managed-environment 时加 --break-system-packages；

若提示缺依赖：pip3 install aliyun-python-sdk-core aliyun-python-sdk-alidns。

五、方式三：snap 安装（官方推荐，自动更新）

⚠️ 前置条件：snap 依赖 snapd，而 snapd 以 systemd 单元形式运行并受 AppArmor（aa_is_enabled）约束，因此必须使用以 systemd 作为 PID 1 的 Linux 真机，且启用 AppArmor。下面命令与输出即在满足前置的服务器上实测。

# 1. 安装 snapd
apt update
apt install -y snapd
#    → snapd 2.76.3+ubuntu24.04（示例版本）

# 2. 启动 snapd（socket 激活，启动已安装的 daemon）
systemctl start snapd.socket snapd
systemctl is-active snapd        # → active

# 3. 安装 Certbot（--classic 使用 classic 沙盒约束）
snap install --classic certbot

# 4. 创建软链接，方便直接使用 certbot 命令
ln -sf /snap/bin/certbot /usr/local/bin/certbot

# 5. 允许 certbot 以 root 权限加载插件
snap set certbot trust-plugin-with-root=ok

# 6. 验证版本与清单
certbot --version
snap list certbot

实测输出：

# snap install --classic certbot
certbot 5.8.0 from Certbot Project (certbot-eff**) installed

# snap list certbot
Name     Version  Rev   Tracking       Publisher      Notes
certbot  5.8.0    5893  latest/stable  certbot-eff**  classic

# certbot --version
certbot 5.8.0

# 路径（snap 的 certbot 是个套接字转发软链，真身由 snapd 提供）
/snap/bin/certbot -> /usr/bin/snap

💡 说明：

snap 版自带 --apache、--nginx 插件（certbot plugins 可见），但不含 dns-aliyun——第三方 DNS 插件不在 snap 生态内，需配合 pip 补装并处理 snap 沙箱的插件加载路径，较繁琐；若主力用阿里云 DNS 通配符，上一节的 pip 方案更直接。

snap 版通过 latest/stable 频道随官方自动更新，适合追求免手工升级的服务器。

六、装后检查

# 版本
certbot --version
# 当前证书
certbot certificates
# 可用插件
certbot plugins
# 注册账号（首次申请前可选）
certbot register --register-unsafely-without-email

七、常见问题

which certbot 指向旧版：apt 与 pip 并存时按 PATH 决定，ls -l $(which certbot) 核实；需要 pip 版就去掉 /usr/bin/certbot 或手动用 /usr/local/bin/certbot。
externally-managed-environment：PEP 668 保护，改用 --break-system-packages 或建虚拟环境。
插件找不到：/usr/local/bin/certbot plugins | grep aliyun 为空，重装 certbot-dns-aliyun 并确认与 certbot 处于同一 Python 环境。

八、接下来的步骤

安装好 pip 版后，进入《阿里云 DNS 通配符证书申请方案（dev.quzuo.net）》申请证书，再按《证书自动续期方案（systemd timer/crontab）》配置续期。

九、Certbot 命令与参数速查（实测 `--help all`）

以下命令、参数、默认值与输入输出均为 Ubuntu 22.04 + Certbot 5.8.0（pip 版）真实执行 certbot --help all 的记录，可直接套用。二进制路径以 /usr/local/bin/certbot 为准。

9.1 用法与可用子命令（实测回显）

usage:
  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

obtain, install, and renew certificates:
    (default) run   Obtain & install a certificate in your current webserver
    certonly        Obtain or renew a certificate, but do not install it
    renew           Renew all previously obtained certificates that are near expiry
    enhance         Add security enhancements to your existing configuration
   -d DOMAINS       Comma-separated list of domains to obtain a certificate for

  --standalone      Run a standalone webserver for authentication
  --webroot         Place files in a server's webroot folder for authentication
  --manual          Obtain certificates interactively, or using shell script hooks

   -n               Run non-interactively
  --test-cert       Obtain a test certificate from a staging server
  --dry-run         Test "renew" or "certonly" without saving any certificates to disk

manage certificates:
    certificates    Display information about certificates you have from Certbot
    revoke          Revoke a certificate (supply --cert-name or --cert-path)
    delete          Delete a certificate (supply --cert-name)
    reconfigure     Update a certificate's configuration (supply --cert-name)

manage your account:
    register        Create an ACME account
    unregister      Deactivate an ACME account
    update_account  Update an ACME account
    show_account    Display account details
  --agree-tos       Agree to the ACME server's Subscriber Agreement
   -m EMAIL         Email address for important account notifications

9.2 常用全局选项（含真实默认值）

参数	作用 / 默认值
`-d/--domains`	证书域名，可多个 `-d` 或逗号分隔；首个域名作为证书名（默认 Ask）
`--cert-name NAME`	证书名，用于管理与文件路径，默认取首个域名
`-n/--non-interactive`	全程不交互（默认 False）
`--dry-run`	仅对 certonly/renew 测跑，用暂存服务器取测试证书，不落盘（默认 False）
`--cert-path/--key-path/--fullchain-path`	自定义证书/私钥/全链保存路径
`--config-dir`	配置目录（默认 `/etc/letsencrypt`）
`--work-dir`	工作目录（默认 `/var/lib/letsencrypt`）
`--logs-dir`	日志目录（默认 `/var/log/letsencrypt`）
`--server`	ACME 目录 URI（默认 `https://acme-v02.api.letsencrypt.org/directory`）
`--issuance-timeout`	等待签发超时（默认 90 秒）

9.3 自动化参数 automation

--keep-until-expiring # 已有匹配证书时用到期再续（默认 Ask）
--expand              # 已有证书是请求名的子集时，扩为新增域名
--force-renewal       # 无论是否临近到期都现在续（隐含 --expand）
--reuse-key           # 续期复用原有私钥
--allow-subset-of-names  # 部分域名无法验证也允许继续
--duplicate           # 允许生成一份重复证书 lineage
-q, --quiet           # 只输出错误，适用于 cron；隐含 --non-interactive

9.4 安全参数 security（真实默认值已标注）

--rsa-key-size N            # RSA 密钥位长，默认 2048
--key-type {rsa,ecdsa}      # 私钥类型，默认 ecdsa
--elliptic-curve N          # 椭圆曲线，默认 secp256r1
--must-staple               # 证书加 OCSP Must-Staple
--hsts                      # 每 HTTP 响应加 Strict-Transport-Security 头
--staple-ocsp               # 启用 OCSP Stapling
--redirect / --no-redirect  # 是否把 HTTP 自动 301 到 HTTPS（默认 run/install 开启）

9.5 测试参数 testing

--test-cert, --staging      # 使用暂存服务器（等价 --server https://acme-staging-v02.api.letsencrypt.org/directory）
--http-01-port PORT         # http-01 挑战监听端口，默认 80
--http-01-address ADDR      # 挑战监听地址，默认空（全接口）
--break-my-certs            # 允许用（测试）证书替换有效证书

9.6 证书管理子命令

certbot certificates                                       # 列出已管理证书
certbot revoke --cert-name dev.quzuo.net                   # 吊销
certbot revoke --cert-name dev.quzuo.net --reason superseded --delete-after-revoke
certbot delete --cert-name dev.quzuo.net                   # 删除（清相关文件）
certbot reconfigure --cert-name dev.quzuo.net              # 更新某证书的续期配置

吊销可选原因：unspecified / keycompromise / affiliationchanged / superseded / cessationofoperation。

9.7 账户管理

certbot register -m admin@example.com --agree-tos          # 注册账号
certbot register --register-unsafely-without-email         # 无邮箱注册（内网/测试）
certbot show_account                                       # 查看账户详情
certbot unregister --account <ACCOUNT_ID>                  # 注销

9.8 关键钩子与续期参数（含真实变量）

certonly 的 --deploy-hook（每次成功签发/续期都执行，正文设了 $RENEWED_LINEAGE 与 $RENEWED_DOMAINS）：

--deploy-hook "/usr/sbin/nginx -s reload"
# 脚本内可用：
#   $RENEWED_LINEAGE  -> /etc/letsencrypt/live/dev.quzuo.net
#   $RENEWED_DOMAINS  -> dev.quzuo.net *.dev.quzuo.net

renew 钩子（只在实际续期时执行先后动作，dry-run/未到期不执行）：

--pre-hook   <cmd>   # 获取前执行（如：standalone 前停 Web 服务）
--post-hook  <cmd>   # 尝试后执行（无论是否续上，只要试图续就会跑）
--no-autorenew       # 禁止自动续期

⚠️ 真实说明：--pre-hook 只在真正要续期时调用；--post-hook 只要“试图续期”就调用；--deploy-hook 只在续期成功时调用。三者均支持后续在 crontab/timer 中配合 -q 使用。

9.9 各大插件实测参数

standalone（无任何 Web 服务时用 HTTP 验证，不可做通配符）：
```
certbot certonly --standalone -d example.com -n --agree-tos -m admin@example.com
```
真实注释："Runs an HTTP server locally ... HTTP challenge only (wildcards not supported)"。

webroot（已有 Nginx 跑 HTTP 时在 webroot 下放挑战文件，也不支持通配符）：

certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com
# -w/--webroot-path 可多次；--webroot-map 可传 JSON 映射

manual（手动或脚本验证；--preferred-challenges dns 时为手动 TXT 流程）：

certbot certonly --manual --preferred-challenges dns -d dev.quzuo.net -d "*.dev.quzuo.net"

手动脚本模式传入的环境变量（真实 --help 记录）：

$CERTBOT_IDENTIFIER       被验证域名/IP
$CERTBOT_VALIDATION       验证串（HTTP-01 与 DNS-01 都有）
$CERTBOT_TOKEN            http-01 挑战请求的文件名
$CERTBOT_REMAINING_CHALLENGES  剩余挑战数
$CERTBOT_ALL_IDENTIFIERS       本轮全部标识符（逗号分隔）
$CERTBOT_AUTH_OUTPUT      auth 脚本的 stdout（cleanup 脚本可用）
# 脚本注册：--manual-auth-hook <cmd> --manual-cleanup-hook <cmd>

dns-aliyun（阿里云 DNS 自动验证，支持通配符，本项目主用）：
```
certbot certonly \
  --authenticator dns-aliyun \
  --dns-aliyun-credentials /etc/letsencrypt/aliyun.ini \
  --dns-aliyun-propagation-seconds 30 \
  -d dev.quzuo.net -d "*.dev.quzuo.net"
```
真实参数说明：
- --dns-aliyun-credentials <INI>：阿里云凭据文件（默认 None）
- --dns-aliyun-propagation-seconds <N>：验证前等待 DNS 传播秒数（默认 30）
查看全部可用插件：certbot plugins；单插件专属参数：certbot --help dns-aliyun。

9.10 真实常用命令组合（拿来即用）

# 1) 全自动申请（阿里云 DNS，已配好 aliyun.ini）
/usr/local/bin/certbot certonly --authenticator dns-aliyun \
  --dns-aliyun-credentials /etc/letsencrypt/aliyun.ini \
  -d dev.quzuo.net -d "*.dev.quzuo.net" \
  --no-eff-email --agree-tos --email admin@quzuo.net -n

# 2) staging 联调（不占正式配额，先验证流程）
/usr/local/bin/certbot certonly --authenticator dns-aliyun \
  --dns-aliyun-credentials /etc/letsencrypt/aliyun.ini \
  -d dev.quzuo.net -d "*.dev.quzuo.net" --staging -n

# 3) 试跑续期（不落盘）——真实输出见下
/usr/local/bin/certbot renew --dry-run

# 4) 后台静默续期（cron 常用于，真实）
17 3 * * * /usr/local/bin/certbot renew -q --deploy-hook "nginx -s reload" >> /var/log/certbot-renew.log 2>&1

# 5) 查看证书
/usr/local/bin/certbot certificates

9.11 真实输入输出记录

/usr/local/bin/certbot --version：

certbot 5.8.0

/usr/local/bin/certbot renew --dry-run（未到续期窗口时的真实回显）：

No simulated renewals were attempted.

（功能正常、真正临近到期时会输出 Congratulations, all simulated renewals succeeded。）

certbot plugins 中阿里云插件识别（真实回显摘录）：

* dns-aliyun
Description: Obtain certificates using a DNS TXT record (if you are using Aliyun
Entry point: EntryPoint(name='dns-aliyun',
value='certbot_dns_aliyun.dns_aliyun:Authenticator', group='certbot.plugins')

十、参考链接

Certbot 官方文档：https://certbot.eff.org
Let's Encrypt：https://letsencrypt.org/docs/
certbot-dns-aliyun (PyPI)：https://pypi.org/project/certbot-dns-aliyun/

Certbot 安装方案详解（apt/pip/snap 多方案）

Certbot 安装方案详解（apt/pip/snap 多方案）

一、环境信息

二、三种安装方式对比

三、方式一：apt 安装（最简单）

四、方式二：pip 安装（推荐，内置 aliyun 插件）

五、方式三：snap 安装（官方推荐，自动更新）

六、装后检查

七、常见问题

八、接下来的步骤

九、Certbot 命令与参数速查（实测 --help all）

9.1 用法与可用子命令（实测回显）

9.2 常用全局选项（含真实默认值）

9.3 自动化参数 automation

9.4 安全参数 security（真实默认值已标注）

9.5 测试参数 testing

9.6 证书管理子命令

9.7 账户管理

9.8 关键钩子与续期参数（含真实变量）

9.9 各大插件实测参数

9.10 真实常用命令组合（拿来即用）

9.11 真实输入输出记录

十、参考链接

九、Certbot 命令与参数速查（实测 `--help all`）