Certbot 使用指南：用 Let‘s Encrypt 与 ACME 协议自动化获取和部署 HTTPS 证书

Certbot 使用指南用 Lets Encrypt 与 ACME 协议自动化获取和部署 HTTPS 证书【免费下载链接】certbotCertbot is EFFs tool to obtain certs from Lets Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.项目地址: https://gitcode.com/gh_mirrors/ce/certbot本篇指南以仓库内 certbot/README.rst 为骨架系统介绍 EFF 出品的 Certbot它如何作为 ACME 客户端从 Lets Encrypt或其他 ACME 兼容 CA获取 DV 证书、如何在 Apache/nginx/webroot/standalone 等多种场景下自动完成部署与续期。读完本文你将掌握 Certbot 的核心特性、主要子命令与关键参数、证书存储结构以及其本地生成私钥、配置可回滚、全自动续期的实现原理。背景为什么需要 CertbotWeb 上的安全通信依赖 HTTPS而 HTTPS 要求网站持有数字证书浏览器借此验证 Web 服务器的真实身份例如确认你访问的确实是 google.com 而不是仿冒站点。这类证书由受信任的第三方——证书颁发机构CA, Certificate Authority签发。手工申请、安装并持续维护证书历来是件麻烦事而 Certbot 正是为了解决这一痛点而生它是 EFF电子前沿基金会加密整个互联网encrypt the entire Internet倡议的一部分它作为易用的客户端从Lets Encrypt由 EFF、Mozilla 等发起的开放 CA获取证书并自动部署到 Web 服务器它把申请证书、部署证书、管理 HTTPS全部自动化成简单的命令行操作且完全免费。从源码看Certbot 的入口在 certbot/src/certbot/_internal/main.py 的main()函数它解析插件注册表、解析命令行参数然后根据子命令分发到对应的处理函数程序还通过misc.get_default_folder等机制确定配置文件、工作目录与日志目录默认目录布局在 certbot/src/certbot/_internal/constants.py 中统一定义。快速上手Getting Started使用 Certbot 最快捷的方式是访问官方交互式引导页面certbot.eff.org它可以根据你的服务器系统与 Web 软件组合生成专属的操作指令。大多数情况下运行 Certbot 需要 Web 服务器的root 或管理员权限因为 Certbot 需要修改 Web 服务器配置、写入验证文件或监听端口。需要特别强调两点使用前提Certbot 应直接运行在 Web 服务器上命令行环境而不是个人电脑上。它需要与服务器本地的配置、目录和端口直接交互如果你使用的是托管服务hosted service没有 Web 服务器的直接访问权可能无法使用 Certbot。此时应查阅托管服务商关于上传证书、使用 Lets Encrypt 证书的文档。主要子命令一览README 强调 Certbot 覆盖获取证书、部署证书、吊销证书、自动续期的完整生命周期。仓库中 certbot/src/certbot/_internal/cli/verb_help.py 的VERB_HELP表完整列出了所有支持的子命令子命令作用run默认获取/续期证书并安装到服务器certonly只获取或续期证书不安装到任何位置renew续期所有或--cert-name指定的临近过期的证书certificates列出 Certbot 管理的所有证书delete清理与某证书相关的所有文件revoke吊销证书--cert-path或--cert-name指定register在 Lets Encrypt / 其他 ACME 服务器注册账号update_account更新已有账号信息unregister永久停用账号install将任意证书安装到服务器rollback回滚安装证书时对服务器配置的修改plugins列出已安装并可用的插件enhance为已有配置添加安全增强如强制 HTTPSshow_account显示 ACME 服务器上的账号详情reconfigure更新--cert-name指定证书的续期配置典型的第一条命令安装并启用 HTTPS# 交互式按提示输入邮箱、同意服务条款、选择域名 sudo certbot --nginx -d example.com -d www.example.com # 只签发证书不安装适合自己手工配置服务器 sudo certbot certonly --webroot -w /var/www/example -d example.com # 仅测试签发流程是否可行不产生真实证书 sudo certbot certonly --dry-run -d example.com子命令与各插件--apache、--nginx、--standalone、--webroot及各--dns-*插件在 certbot/src/certbot/_internal/constants.py 的CLI_DEFAULTS中均有对应默认项例如apacheFalse、nginxFalse、standaloneFalse、webrootFalse使用对应 flag 即启用该插件。核心特性详解README 列出的Current Features是理解 Certbot 能力边界的最佳索引下面逐条结合仓库源码展开。1. 支持多种 Web 服务器与验证方式Certbot 通过插件plugin机制支持多种服务器与验证方式Apache 2.4自动修改 Apache 虚拟主机配置、安装证书并启用 HTTPS对应仓库 certbot-apache 包插件入口在 certbot-apache/src/certbot_apache/_internal/entrypoint.pynginx/0.8.48同样全自动完成 nginx 配置修改对应 certbot-nginx 包webroot在网站根目录写入验证文件以证明你对域名的控制权不需要服务器插件见下文standaloneCertbot 自己启动一个轻量 Web 服务器来完成域名控制验证其他服务器软件可通过第三方插件扩展例如仓库内 certbot-dns-cloudflare、certbot-dns-route53 等 DNS 插件即是以独立 Python 包形式注册到certbot.pluginsentry point 的见 certbot/src/certbot/_internal/constants.py 中的SETUPTOOLS_PLUGINS_ENTRY_POINT certbot.plugins。webroot 模式原理源码见 certbot/src/certbot/_internal/plugins/webroot.pyAuthenticator类会将必要的验证文件保存到 webroot 路径下的.well-known/acme-challenge/目录它只支持 HTTP 挑战即 http-01因此不支持通配符域名wildcards。它假设已有其他 HTTP 服务器在对外提供该 webroot 目录下的文件。关键参数sudo certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com \ -w /var/www/thing -d thing.net -d m.thing.net其中-w/--webroot-path可多次指定与后面的-d域名一一配对也支持用--webroot-map传入 JSON 字典如{example.com:/var/www}它优先于-w/-d组合。standalone 模式原理源码见 certbot/src/certbot/_internal/plugins/standalone.py由 Certbot 自带一个简单 Web 服务器监听 http-01 挑战端口默认即 HTTP 01 标准端口见CLI_DEFAULTS中的http01_port适合服务器上还没有运行 Web 服务、或暂时停用 Web 服务的场景sudo certbot certonly --standalone -d example.com2. 私钥在本地生成永不离开你的机器README 明确The private key is generated locally on your system.私钥在你的系统本地生成。这一点决定了信任模型Lets Encrypt 只负责验证你对域名的控制权并签发证书而私钥始终保存在服务器本地不会传输给 CA。3. 对接 Lets Encrypt 或其他 ACME 兼容服务Certbot 可以对接 Lets Encrypt CA也可以对接任何**符合 ACME 协议RFC 8555**的服务。默认服务器地址与备用地址在 certbot/src/certbot/_internal/constants.py 中生产环境https://acme-v02.api.letsencrypt.org/directory测试环境staginghttps://acme-staging-v02.api.letsencrypt.org/directory测试环境通过--staging或--test-cert启用用于验证签发流程而不会消耗生产环境速率限制也不会签发受浏览器信任的证书。若使用其他 ACME 服务可用--server directory-url指定其目录端点。4. 获取域名验证DV证书Certbot 签发的证书类型是**域名验证DV, Domain-Validated**证书——只要证明你对域名有控制权即可签发无需人工审核组织信息。证书签发流程在 certbot/src/certbot/_internal/main.py 的_get_and_save_cert()中实现调用hooks.pre_hook执行前置钩子、通过 ACME 客户端完成认证与签发、再写入本地存储。5. 吊销证书Certbot 可以吊销不再需要的证书吊销原因映射定义在 certbot/src/certbot/_internal/constants.py 的REVOCATION_REASONS中与 RFC 5280 §5.3.1 及 ACME 服务端实现对应原因数值unspecified0keycompromise1私钥泄露affiliationchanged3隶属关系变更superseded4已被替代cessationofoperation5停止运营# 按证书名吊销 sudo certbot revoke --cert-name example.com --reason keycompromise # 按证书文件路径吊销 sudo certbot revoke --cert-path /etc/letsencrypt/live/example.com/fullchain.pem6. 支持 ECDSA默认与 RSA 私钥README 指出 Certbot 默认生成ECDSA私钥同时支持RSA。对应默认值在 certbot/src/certbot/_internal/constants.py 的CLI_DEFAULTS中key_typeecdsa默认密钥类型为 ECDSAelliptic_curvesecp256r1默认椭圆曲线rsa_key_size2048使用 RSA 时的默认密钥长度。通过命令行可显式控制# 显式使用 RSA 2048 sudo certbot certonly --standalone -d example.com --key-type rsa --rsa-key-size 2048 # 显式使用 ECDSA 并指定曲线 sudo certbot certonly --standalone -d example.com --key-type ecdsa --elliptic-curve secp384r17. 可选安装 http → https 重定向Certbot 可以顺带把站点配置为仅 HTTPS即安装 http → https 重定向对应CLI_DEFAULTS中的redirect选项以及enhance子命令为已有配置添加安全增强。典型用法# 签发并安装证书同时开启重定向 sudo certbot --nginx -d example.com --redirect # 对已部署的证书补做安全增强如重定向、HSTS sudo certbot enhance --nginx -d example.com --redirect8. 全自动化自动续期Fully automated是 Certbot 的核心卖点renew子命令会检查所有已管理证书对临近过期的证书自动续期并复用当初签发时使用的插件和参数。按 certbot/src/certbot/_internal/cli/verb_help.py 中的描述renew会尝试续期所有此前获得、且接近过期的证书并打印结果摘要。默认情况下会复用各证书签发或最近一次续期时使用的插件与选项。可用--dry-run测试未来的续期是否成功。单个证书可用--cert-name指定续期。# 手动触发一次续期检查通常配合 crontab/systemd timer 定期执行 sudo certbot renew # 只测试续期流程不真正续期 sudo certbot renew --dry-runCLI_DEFAULTS中还有random_sleep_on_renewTrue续期时随机延迟避免所有客户端同时请求 CA、autorenewTrue等与自动化相关的默认项。9. 配置变更可记录、可回滚README 承诺Configuration changes are logged and can be reverted配置变更会被记录且可回滚。Certbot 在修改 Web 服务器配置前会先做检查点备份checkpoint对应的回滚操作就是rollback子命令# 回滚最近 3 次服务器配置变更 sudo certbot rollback --checkpoints 3其底层实现位于 certbot/src/certbot/reverter.py备份数据存放在工作目录下的backups/目录见 certbot/src/certbot/_internal/constants.py 的BACKUP_DIR常量。证书存储结构lineage证书谱系理解 Certbot 如何在磁盘上组织证书是排查问题的基础。当签发成功时certbot/src/certbot/_internal/storage.py 的RenewableCert.new_lineage()会创建一套证书谱系lineage其布局为/etc/letsencrypt/ ├── live/域名/ # 稳定符号链接服务器引用这里 │ ├── cert.pem # 服务器证书 │ ├── chain.pem # 中间链 │ ├── fullchain.pem # 证书 中间链服务器最常用 │ └── privkey.pem # 私钥 ├── archive/域名/ # 每次续期的历史版本 │ ├── cert1.pem / cert2.pem / ... │ ├── chain1.pem / ... │ ├── fullchain1.pem / ... │ └── privkey1.pem / ... └── renewal/域名.conf # 续期配置记录签发参数关键设计live/下的是指向archive/的符号链接续期时新版本写入 archivelive 链接原地切换因此 Web 服务器配置里引用的live/路径永远指向当前有效版本每次续期的私钥以BASE_PRIVKEY_MODE权限安全写入见 certbot/src/certbot/_internal/storage.py 的new_lineage实现。相关目录常量LIVE_DIR、ARCHIVE_DIR、RENEWAL_CONFIGS_DIR、KEY_DIR等均定义在 certbot/src/certbot/_internal/constants.py。查看已管理证书sudo certbot certificates参与贡献Contributing如果你希望参与 Certbot 的开发仓库根目录提供了完善的指引阅读 CONTRIBUTING.md 了解开发流程与规范查看 certbot/docs/ 下的开发者文档如 contributing.rst、using.rst阅读 CHANGELOG.md 了解各版本的功能演进本项目受 EFF 公共项目行为准则EFFs Public Projects Code of Conduct约束新增功能的变更记录遵循 towncrier 碎片机制见仓库 towncrier.toml 与 newsfragments 目录。仓库采用多包结构核心客户端位于 certbot/src/certbotACME 协议客户端库位于 acme/src/acme各服务器/DNS 插件为独立包如 certbot-apache、certbot-nginx、certbot-dns-cloudflare 等测试与 CI 配置见 tox.ini、pytest.ini。相关资源索引官方文档完整文档位于仓库 certbot/docs/包括install.rst、using.rst、intro.rst、cli-help.txt等变更日志certbot/CHANGELOG.md用户指南见 certbot/docs/using.rst其中详细介绍了续期、钩子renewal-hooks、第三方插件等主题ACME 规范RFC 8555Lets Encrypt 及所有兼容 CA 使用的协议标准社区支持Lets Encrypt 社区论坛community.letsencrypt.org。小结Certbot 把申请证书 → 部署证书 → 定期续期 → 吊销管理这条 HTTPS 运维链路完全自动化本地生成私钥保证安全、ACME 协议对接 Lets Encrypt 等任意兼容 CA、插件机制覆盖 Apache/nginx/webroot/standalone 及各类 DNS 服务商、ECDSA 默认密钥与 http→https 重定向等安全特性开箱即用、配置变更可记录可回滚。无论你是要在单台服务器上快速启用 HTTPS还是要为多域名、多服务器环境构建自动化证书管理体系Certbot 都能用简单的命令行完成这一切——而且完全免费。【免费下载链接】certbotCertbot is EFFs tool to obtain certs from Lets Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.项目地址: https://gitcode.com/gh_mirrors/ce/certbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考