企业官网建设流程全解析

• 网络安全
• CLI
• 后端

Certbot 是 EFF 出品的 ACME 协议客户端，用于从 Let's Encrypt 等 CA 自动获取证书并（可选）在服务器上自动启用 HTTPS。本文基于 certbot/docs/install.rst 的官方安装文档，结合本仓库的 Snap 构建配置、Docker 镜像定义与插件源码，系统讲解 Certbot 在服务器上的系统要求、Snap 推荐安装、Docker 容器化部署、Pip 虚拟环境安装以及旧版certbot-auto的迁移清理，帮助你根据实际环境选择最合适的安装路径并正确管理证书文件。

系统要求（System Requirements）

在动手安装之前，请先确认目标服务器满足以下条件：

关于权限，官方文档明确指出：Certbot 以 root 权限运行时最有用，因为这样它才能自动为 Apache 和 nginx 配置 TLS/SSL。同时要理解 Certbot 的设计定位——它应当直接运行在 Web 服务器上，通常由系统管理员操作。在大多数情况下，把 Certbot 安装在个人电脑上并不是有用的选择，因为 ACME 域名验证需要从公网访问到你的服务器，且证书签发后需要安装到实际提供服务的机器上。以下所有安装与运行说明均以服务器环境为前提。

安装方式总览

官方建议优先前往 certbot.eff.org 的 Instructions 页面，按你的服务器软件与操作系统选择对应的安装指引，这是最稳妥、与官方测试同步的方案。除该系统化指引外，本仓库文档提供以下备选路径，按推荐程度排序：

1. Snap（官方推荐）——跨发行版统一、自动续期开箱即用；
2. Docker（备选方案 1）——快速获取证书，但无法自动安装证书或配置 Web 服务器；
3. Pip（备选方案 2）——仅最佳努力（best effort）支持，且必须配合虚拟环境；
4. 第三方发行版（备选方案 3）——满足特定需求，但维护方在项目之外，LTS 发行版上易过时；
5. certbot-auto（已弃用）——旧版脚本安装方式，需要主动清理。

Snap 安装（推荐）

Snap 是官方推荐的安装方式，其最大优势是：所有使用 Snap 的系统安装指令完全相同，不存在发行版之间的差异。你只需在 certbot.eff.org 的 Instructions 页面选择你的服务器软件，并在 "System" 下拉框中选择 "snapd" 即可。

适用条件与架构支持

• 绝大多数现代 Linux 发行版（基本覆盖所有使用 systemd 的系统）都可以通过 Snap 安装 Certbot；
• Snap 包提供x86_64、ARMv7 和 ARMv8三种架构；
• Snap 版本自带自动续期等特性，确保你始终运行最新版本且无需额外配置定时任务。

从仓库构建配置看 Snap 包的设计

本仓库的 snap/snapcraft.yaml 完整定义了 Certbot Snap 包的构建方式，从中可以验证文档中“自动化续期预配置”的说法：

name: certbot summary: Automatically configure HTTPS using Let's Encrypt confinement: classic base: core24 apps: certbot: command: bin/python3 -s $SNAP/bin/certbot renew: command: bin/python3 -s $SNAP/bin/certbot -q renew daemon: oneshot # Run approximately twice a day with randomization timer: 00:00~24:00/2

关键细节：

• 采用classic安全等级（confinement），意味着 Snap 内的 Certbot 可以像普通系统程序一样读写系统目录（如/etc/letsencrypt、Apache/nginx 配置）；
• 内置一个名为renew的 systemd 定时服务，使用timer: 00:00~24:00/2让certbot -q renew每天大约运行两次且带随机化，这正是文档所说“自动化证书续期预配置”的底层实现——你装完 Snap 后无需自己编写 cron 或 systemd timer；
• 构建时会打包acme、certbot、certbot-apache、certbot-nginx等核心组件（见parts.certbot.python-packages），因此 Snap 版天然包含 Apache/nginx 安装器插件。

如果你的系统无法使用 Snap，则需改用下面介绍的替代方案。

方案一：Docker 部署

Docker 是获取证书的“惊人简单且快速”的方式，但有一个关键限制需要明确：这种模式无法安装证书，也无法配置你的 Web 服务器，因为安装器插件无法从 Docker 容器内部访问你的 Web 服务器。官方建议大多数用户使用 certbot.eff.org 的 Instructions 指引，只有在明确了解其限制并有充分理由时才使用 Docker。

使用 Docker 前必须了解的两件事

1. 证书的存放位置：Docker 容器内的文件系统是临时的，必须通过卷挂载把证书目录持久化到宿主机。因此使用 Docker 前务必阅读 Where are my certificates? 一节，学会手动管理证书；
2. 推荐的密码套件：可参考 ciphersuites 页面 了解推荐的密码套件配置。如果这些概念让你感到困难，就应该改用官方推荐的系统安装方式，让安装器插件替你处理这两个难题。

基本用法与命令解析

在证书域名解析到的服务器上安装 Docker 后，执行以下命令：

sudo docker run -it --rm --name certbot \ -v "/etc/letsencrypt:/etc/letsencrypt" \ -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ certbot/certbot certonly

逐项解读：

执行certonly后，证书会被放置到宿主机（即挂载点）的/etc/letsencrypt/live目录下。由于 Docker 模式下无法在容器内安装证书，你必须按照 Web 服务器厂商推荐的手动流程完成证书安装。

本仓库的 tools/docker/Dockerfile 印证了上述用法设计：镜像基于python:3.14-alpine3.23，声明了ENTRYPOINT [ "certbot" ]（因此命令直接以certbot开头）、EXPOSE 80 443，并声明VOLUME /etc/letsencrypt /var/lib/letsencrypt，与文档中的卷挂载路径完全对应。

使用 Standalone 插件时务必映射端口

如果使用Standalone认证插件，Certbot 会在容器内自己启动一个临时 HTTP 服务器来响应 ACME 验证请求，因此你必须把该插件使用的端口暴露到容器外部，在certbot/certbot之前加上类似-p 80:80或-p 443:443的端口映射。

从源码看，Standalone 插件的实现位于 certbot/src/certbot/_internal/plugins/standalone.py：

该认证器在所需端口上创建自己的临时 TCP 监听器，以响应来自 CA 的 http-01 挑战，因此不依赖任何现有服务器程序。它会在/.well-known/acme-challenge/请求路径下提供必要的验证文件，仅支持 HTTP 挑战（不支持通配符）。

这意味着使用 Standalone 时，宿主机 80 端口上不能有别的程序占用，否则绑定会失败。

使用 DNS 插件镜像完成域名验证

官方在 Docker Hub 上还为每个 DNS 插件提供了独立镜像，用于通过 DNS 方式自动化域名验证（适合申请通配符证书或在非目标 Web 服务器上运行 Certbot）。用法很简单：把命令中的certbot/certbot替换为对应插件镜像名即可。例如使用 Amazon Route 53 插件：

sudo docker run -it --rm --name certbot \ -v "/etc/letsencrypt:/etc/letsencrypt" \ -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ certbot/dns-route53 certonly

使用 DNS 插件时，你可能还需要额外挂载目录或添加参数，以提供 DNS API 凭证，具体见 DNS 插件文档。本仓库中每个 DNS 插件都有独立子项目（如 certbot-dns-route53、certbot-dns-cloudflare、certbot-dns-digitalocean 等），镜像命名与子项目一一对应。

方案二：Pip 安装

通过 Pip 安装 Certbot 有以下两点重要前提：

• 仅提供最佳努力（best effort）支持——不保证在所有环境都能顺利工作；
• 必须使用虚拟环境（virtual environment）——不要把 Certbot 直接装进系统级 Python 环境。

具体的 Pip 安装步骤，同样在 certbot.eff.org 的 Instructions 页面选择你的服务器软件，并在 "System" 下拉框中选择 "pip" 获取。

从 certbot/pyproject.toml 可以确认源码级约束：Certbot 要求Python >= 3.10（requires-python = ">=3.10"），并声明支持 Python 3.10 至 3.14。安装包会注册certbot = "certbot.main:main"控制台入口点，同时通过[project.entry-points."certbot.plugins"]声明内置插件（manual、null、standalone、webroot），因此源码安装后可直接使用这些插件。建议在虚拟环境中安装本仓库的acme与certbot两个包（二者位于 acme 与 certbot 目录），并遵循 tools/requirements.txt 中固定的依赖版本约束，以获得可复现的环境。

方案三：第三方发行版

除了官方途径，还存在面向特定需求的第三方发行版。需要注意：这些发行版通常由第三方在 Certbot 项目之外维护，且在 LTS 风格的发行版上很容易快速过时。如果你的系统要求必须使用这类渠道，建议保持谨慎并关注其更新频率。

certbot-auto：已弃用的旧安装方式

项目曾经提供一个名为certbot-auto的 shell 脚本，用于在 UNIX 操作系统上安装 Certbot，但该脚本已不再受支持。官方文档明确要求用户移除它，迁移需要完成以下三件事：

1. 删除自动续期任务：如果你按照旧指引添加了 cron 任务或 systemd timer 来自动运行 certbot-auto 续期证书，请将其删除。若是按官方指引配置的，可执行以下命令清除/etc/crontab中的相关条目：

   sudo sed -i '/certbot-auto/d' /etc/crontab

2. 删除 certbot-auto 脚本本身：如果按旧指引放在了/usr/local/bin，执行：

   sudo rm /usr/local/bin/certbot-auto

3. 删除 certbot-auto 创建的安装目录：

   sudo rm -rf /opt/eff.org

完成这三步后，建议改用本文介绍的 Snap 或官方推荐方式重新安装，以获得受支持的自动续期能力。

补充：证书在哪里（安装后必读）

无论通过哪种方式安装，了解证书的存放位置都是必需的，尤其是 Docker 用户需要手动管理证书。证书文件统一存放在：

/etc/letsencrypt/live/$domain/

其中$domain为证书名称，命名遵循以下约定：

• 优先使用--cert-name指定的名称；
• 未指定时，使用--domains的第一个域名；
• 若第一个域名是通配符域名（如*.example.com），证书名取example.com；
• 若与已有证书（如example.com）重名冲突，则使用数字序列构造新名称（如example.com-001）。

目录内包含的关键文件及用途：

配置服务器时应直接引用这些文件或创建符号链接，而不要复制——续期时/etc/letsencrypt/live会自动更新为最新文件。另外注意：出于历史原因，这些目录以0700权限创建，仅 root 可访问；如果你的服务器会以非 root 用户读取私钥，需要配合chgrp、chmod 0640调整privkey.pem的属组与权限。

小结

• 首选Snap：跨发行版统一安装、自带每日两次随机化自动续期（见 snap/snapcraft.yaml）；
• Docker适合快速取证，但需自行管理证书与 Web 服务器配置，务必按 Where are my certificates? 理解证书布局；
• Pip仅最佳努力支持且必须使用虚拟环境，注意 Python >= 3.10 的版本门槛；
• certbot-auto 已弃用，请按三步清理并迁移到受支持的方式。

• 网络安全
• CLI
• 后端