Certbot全平台部署指南：从环境配置到证书管理

环境准备

确认系统兼容性

Certbot作为ACME协议（自动化证书管理标准）客户端，支持Linux、Windows和macOS三大操作系统。在开始部署前，需验证目标环境是否满足以下基本要求：

• 权限要求：Linux/macOS需root权限，Windows需管理员权限
• 网络条件：可访问ACME服务器（默认Let's Encrypt）
• 端口占用：【端口要求：80/443】需确保验证端口未被占用

安装依赖组件

不同平台需预先安装基础依赖：

• Linux：glibc 2.17+、Python 3.7+
• Windows：.NET Framework 4.5+、PowerShell 5.1+
• macOS：Xcode Command Line Tools、Homebrew（推荐）

获取安装包

从项目仓库获取最新稳定版源码：

git clone https://gitcode.com/gh_mirrors/ce/certbot
cd certbot

环境变量配置

创建系统级环境变量以优化Certbot运行：

# Linux/macOS示例
export CERTBOT_HOME="/etc/certbot"
export PATH="$CERTBOT_HOME/bin:$PATH"

# Windows PowerShell示例
$env:CERTBOT_HOME = "C:\Certbot"
$env:PATH += ";$env:CERTBOT_HOME\bin"

核心功能解析

ACME协议工作流

Certbot通过以下四步完成证书生命周期管理：

1. 域名验证：通过HTTP-01或DNS-01挑战证明域名所有权
2. 证书签发：向ACME服务器提交CSR（证书签名请求）
3. 证书安装：将证书部署到Web服务器配置
4. 自动续期：在证书到期前30天自动执行更新流程

核心组件架构

• certbot-core：处理ACME协议交互的核心模块
• 插件系统：提供Web服务器集成（Apache/Nginx）和验证方式扩展
• 存储管理器：维护证书、私钥和配置文件的安全存储
• 续期调度器：通过系统任务（cron/Task Scheduler）实现自动化续期

安全机制解析

• 密钥管理：使用RSA 2048位或ECC P-256算法生成密钥对
• 权限控制：证书文件默认权限设置为600（仅root可读写）
• 审计日志：操作记录存储在/var/log/letsencrypt（Linux/macOS）或%LOCALAPPDATA%\Certbot\log（Windows）

平台适配

Linux部署策略

基础流程

1. 安装基础依赖：

# Debian/Ubuntu
sudo apt update && sudo apt install -y python3 python3-venv

# CentOS/RHEL
sudo yum install -y python3 python3-venv

2. 创建专用虚拟环境：

python3 -m venv /opt/certbot/venv
source /opt/certbot/venv/bin/activate

3. 安装Certbot核心组件：

pip install .

平台特性配置

• Systemd服务集成：

# /etc/systemd/system/certbot-renew.service
[Unit]
Description=Certbot auto-renewal service

[Service]
Type=oneshot
ExecStart=/opt/certbot/venv/bin/certbot renew

• ** SELinux策略调整**：

sudo semanage fcontext -a -t cert_t "/etc/letsencrypt(/.*)?"
sudo restorecon -Rv /etc/letsencrypt

Linux部署清单

✅ 已安装Python 3.7+环境
✅ 创建专用虚拟环境
✅ 配置自动续期服务
□ 完成SELinux/AppArmor策略配置
✅ 验证证书存储权限

Windows部署策略

基础流程

1. 安装Python环境： 从Python官网下载3.7+版本，勾选"Add Python to PATH"选项

2. 创建虚拟环境：

python -m venv C:\certbot\venv
C:\certbot\venv\Scripts\activate.bat

3. 安装Certbot：

pip install .

平台特性配置

• IIS集成配置：

<!-- C:\inetpub\wwwroot\.well-known\acme-challenge\web.config -->
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <staticContent>
            <mimeMap fileExtension="." mimeType="text/plain" />
        </staticContent>
    </system.webServer>
</configuration>

• 任务计划程序配置：

schtasks /create /tn "Certbot Renew" /tr "C:\certbot\venv\Scripts\certbot renew" /sc daily /st 03:00

Windows部署清单

✅ 已安装Python并配置PATH
✅ 创建专用虚拟环境
✅ 配置IIS挑战文件处理
□ 完成防火墙规则设置
✅ 创建自动续期任务

macOS部署策略

基础流程

1. 安装Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装依赖：

brew install python@3.9 openssl

3. 安装Certbot：

brew install certbot

平台特性配置

• Launchd服务配置：

<!-- ~/Library/LaunchAgents/org.certbot.renew.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.certbot.renew</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/certbot</string>
        <string>renew</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>3</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
</dict>
</plist>

• Apache集成：

sudo brew services restart httpd
sudo certbot --apache

macOS部署清单

✅ 已安装Homebrew包管理器
✅ 配置Apache/Nginx服务
✅ 创建Launchd自动续期任务
□ 配置防火墙例外规则
✅ 验证证书存储路径权限

问题诊断

证书获取失败

症状

执行certbot certonly后出现"Connection refused"错误

原因

• 80/443端口被占用
• 防火墙阻止了出站连接
• 域名解析指向错误服务器

解决方案

1. 检查端口占用情况：

# Linux/macOS
sudo lsof -i :80

# Windows
netstat -ano | findstr :80

2. 临时停止占用服务：

# Apache
sudo systemctl stop apache2

# Nginx
sudo systemctl stop nginx

3. 验证网络连通性：

curl -I http://acme-v02.api.letsencrypt.org/directory

自动续期失败

症状

certbot renew --dry-run提示"Authentication failed"

原因

• Web服务器配置已更改
• 挑战文件目录权限不足
• 续期任务未正确配置

解决方案

1. 检查续期日志：

# Linux/macOS
tail -f /var/log/letsencrypt/letsencrypt.log

# Windows
Get-Content "$env:LOCALAPPDATA\Certbot\log\letsencrypt.log" -Tail 100

2. 手动执行挑战验证：

certbot renew --debug-challenges

3. 重新配置续期任务：

# Linux - Systemd
sudo systemctl enable certbot-renew.timer

# Windows - 任务计划程序
schtasks /query /tn "Certbot Renew"

权限访问问题

症状

证书文件无法被Web服务器读取

原因

• 文件权限设置过于严格
• SELinux/AppArmor策略限制
• 证书存储路径变更

解决方案

1. 调整文件权限：

sudo chmod -R 0755 /etc/letsencrypt/live
sudo chgrp -R www-data /etc/letsencrypt/archive

2. 配置SELinux策略：

sudo setsebool -P httpd_read_user_content 1
sudo semanage fcontext -a -t httpd_config_t "/etc/letsencrypt(/.*)?"

3. 验证Web服务器配置：

# Apache
apachectl -t -D DUMP_VHOSTS

# Nginx
nginx -t

命令速查表

基础操作

功能	Linux/macOS	Windows
获取证书（Apache）	sudo certbot --apache -d example.com	certbot --apache -d example.com
获取证书（Nginx）	sudo certbot --nginx -d example.com	certbot --nginx -d example.com
仅获取证书	sudo certbot certonly --webroot -w /var/www/html -d example.com	certbot certonly --webroot -w C:\inetpub\wwwroot -d example.com
测试续期	sudo certbot renew --dry-run	certbot renew --dry-run
查看证书信息	sudo certbot certificates	certbot certificates

高级操作

功能	命令
强制续期	certbot renew --force-renewal
吊销证书	certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem
删除证书	certbot delete --cert-name example.com
配置钩子脚本	certbot renew --deploy-hook /path/to/deploy.sh
设置ECC证书	certbot certonly --elliptic-curve secp256r1 -d example.com