1. 背景与核心概念在家庭实验室Homelab的搭建和维护过程中我们常常会部署各种自托管服务比如 Nextcloud、Jellyfin、Home Assistant、Portainer 等。为了让这些服务更安全、更专业启用 HTTPS 加密是必不可少的一步。然而为每个子域名如nas.home.lab、plex.home.lab单独申请和管理证书不仅繁琐而且容易出错。这正是通配符证书Wildcard Certificate大显身手的地方。一张*.home.lab的通配符证书可以保护所有同级的子域名极大地简化了证书管理。本文将围绕如何为 Homelab 环境配置一个近乎完美的 HTTPS 通配符证书方案展开这套方案尤其适合拥有公网 IP 或通过 Cloudflare 等平台进行 DNS 管理的用户。本文适合的读者拥有 Homelab 或对自建服务感兴趣的开发者、运维爱好者。希望将内网服务通过 HTTPS 安全暴露提升访问体验和安全性的用户。正在寻找比自签名证书更通用、比单域名证书更便捷的 HTTPS 解决方案的朋友。你将学到理解通配符证书的原理、优势与限制。掌握使用 Let‘s Encrypt 的 ACME 协议通过 DNS-01 挑战方式自动化签发通配符证书。学习如何将证书部署到 Nginx 等主流 Web 服务器。了解如何借助 Cloudflare API 实现证书的自动续期打造“一次配置永久有效”的自动化流程。获得一套可直接复用的配置脚本和最佳实践。2. 环境准备与版本说明在开始动手之前请确保你已准备好以下环境。版本信息仅供参考核心是理解流程你的实际环境可能略有不同。核心环境操作系统Ubuntu Server 22.04 LTS 或 Debian 11/12其他 Linux 发行版步骤类似。域名与 DNS一个你拥有的公网域名例如example.com。你需要能管理该域名的 DNS 记录。本文将使用 Cloudflare 作为 DNS 服务商进行演示因其 API 友好且免费。网络环境你的 Homelab 服务器需要能访问互联网用于 ACME 验证。如果你通过 Cloudflare 代理服务器甚至可以不暴露公网 IP。Web 服务器Nginx本文示例或 Apache。确保已安装并运行。关键软件与版本ACME 客户端certbot。这是 Let‘s Encrypt 官方推荐的客户端我们将使用其 DNS 插件。Certbot 版本 2.0Cloudflare API Token用于自动化 DNS 验证。示例域名与结构为清晰起见本文假设主域名home.lab请替换为你自己的域名计划使用的子域名nas.home.lab,media.home.lab,admin.home.lab等。目标为*.home.lab申请通配符证书。重要提示Let‘s Encrypt 的通配符证书只能通过 DNS-01 挑战方式签发这意味着你需要证明你拥有该域名的 DNS 解析控制权。HTTP-01 挑战方式无法用于通配符证书。3. 核心原理与方案选择3.1 为什么是 DNS-01 挑战ACME 协议自动化证书管理环境是 Let‘s Encrypt 用于验证域名所有权的标准。对于通配符证书唯一可行的验证方式是 DNS-01。工作流程简述挑战ACME 客户端如 Certbot向 Let‘s Encrypt 申请为*.home.lab签发证书。验证Let‘s Encrypt 会提供一个随机的、唯一的 TXT 记录值要求你在_acme-challenge.home.lab这个子域名下添加这条 TXT 记录。证明ACME 客户端通过调用 DNS 服务商如 Cloudflare的 API自动添加这条 TXT 记录。签发Let‘s Encrypt 查询该 TXT 记录确认值匹配后即认为你拥有home.lab及其所有子域名的控制权随后签发证书。清理ACME 客户端自动删除之前添加的 TXT 记录。这种方式安全且高效特别适合服务器没有开放 80/443 端口例如纯内网服务通过 Cloudflare Tunnel 暴露或需要为大量子域名管理证书的场景。3.2 方案对比自签名 vs 单域名 vs 通配符证书类型优点缺点适用场景自签名证书完全免费自己控制无需网络。浏览器会显示“不安全”警告需要手动在所有客户端导入根证书。封闭的内网测试环境或仅限自己设备访问的服务。单域名证书免费Let‘s Encrypt浏览器完全信任配置简单HTTP-01。每个子域名都需要单独申请和续期管理成本高。仅有少数固定子域名的生产环境。通配符证书一张证书保护所有同级子域名管理极其方便浏览器完全信任。申请稍复杂必须用 DNS-01对 DNS 服务商有要求需支持 API。Homelab 的理想选择子域名多且可能动态增加。显然对于追求便捷和安全的 Homelab 用户通配符证书是平衡性最佳的选择。4. 完整实战基于 Cloudflare API 自动化配置接下来我们一步步实现自动化签发和部署通配符证书。4.1 获取 Cloudflare API Token首先你需要一个 Cloudflare API Token 来让 Certbot 自动操作你的 DNS 记录。登录 Cloudflare 控制台进入你的域名管理页面。在左侧菜单栏找到“我的个人资料”-“API 令牌”。点击“创建令牌”。选择使用模板“编辑区域 DNS”。在“区域资源”部分选择需要授权的域名例如home.lab。点击“继续以显示摘要”然后点击“创建令牌”。重要复制生成的长串令牌密钥并立即妥善保存。它只会显示一次4.2 安装 Certbot 及 Cloudflare DNS 插件在 Homelab 服务器上执行以下命令# 更新系统包列表 sudo apt update # 安装 certbot 和 python3-certbot-dns-cloudflare 插件 sudo apt install certbot python3-certbot-dns-cloudflare -ypython3-certbot-dns-cloudflare这个插件包含了与 Cloudflare API 交互的必要库。4.3 配置 Cloudflare API 凭据为了让 Certbot 安全地使用你的 API Token需要创建一个配置文件。创建配置目录和文件sudo mkdir -p /etc/letsencrypt/ sudo nano /etc/letsencrypt/cloudflare.ini在文件中写入以下内容将your-cloudflare-api-token替换为你刚才保存的令牌# Cloudflare API token used by Certbot dns_cloudflare_api_token your-cloudflare-api-token保存并退出编辑器在 nano 中按CtrlX然后Y 回车。设置严格的文件权限防止其他用户读取你的 Tokensudo chmod 600 /etc/letsencrypt/cloudflare.ini4.4 申请通配符证书现在使用 Certbot 通过 DNS-01 挑战申请证书。我们将申请一张覆盖home.lab和*.home.lab的证书。执行以下命令记得替换域名sudo certbot certonly \ --dns-cloudflare \ --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \ --preferred-challenges dns-01 \ -d home.lab \ -d *.home.lab \ --agree-tos \ --email your-emailexample.com # 替换为你的邮箱用于接收续期通知命令参数解释certonly仅获取证书不尝试自动安装到 Web 服务器我们手动配置。--dns-cloudflare指定使用 Cloudflare DNS 插件。--dns-cloudflare-credentials指定包含 API Token 的凭据文件路径。--preferred-challenges dns-01明确指定使用 DNS-01 挑战方式。-d指定要包含在证书中的域名。第一个-d “home.lab”确保根域名也被覆盖虽然通配符*.home.lab不包含根域名。第二个-d “*.home.lab”就是通配符主体。--agree-tos同意 Let‘s Encrypt 的服务条款。--email注册和接收通知的邮箱。如果一切顺利你将看到类似下面的成功信息Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/home.lab/fullchain.pem /etc/letsencrypt/live/home.lab/privkey.pem Your certificate will expire on 2024-XX-XX.证书文件说明privkey.pem你的私钥文件必须严格保密。fullchain.pem完整的证书链文件包含你的证书和中间 CA 证书。Nginx 通常使用这个。cert.pem仅你的证书不包含链。chain.pem仅中间 CA 证书。4.5 配置 Nginx 使用新证书假设你有一个为nas.home.lab服务的 Nginx 站点配置。编辑你的 Nginx 站点配置文件例如/etc/nginx/sites-available/nassudo nano /etc/nginx/sites-available/nas修改或添加server块中的 SSL 相关配置server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name nas.home.lab; # 你的子域名 # 指向 Let‘s Encrypt 颁发的通配符证书 ssl_certificate /etc/letsencrypt/live/home.lab/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/home.lab/privkey.pem; # 强化的 SSL 配置推荐 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:...; ssl_prefer_server_ciphers off; ssl_session_cache shared:SSL:10m; ssl_session_timeout 1d; # 你的其他配置如根目录、代理等 root /var/www/nas; index index.html; ... } # 强制将 HTTP 重定向到 HTTPS server { listen 80; listen [::]:80; server_name nas.home.lab; return 301 https://$server_name$request_uri; }测试 Nginx 配置是否正确sudo nginx -t如果显示syntax is ok和test is successful则重载 Nginxsudo systemctl reload nginx现在你应该可以通过https://nas.home.lab安全地访问你的服务了浏览器会显示绿色的安全锁。为其他服务配置对于media.home.lab、admin.home.lab等只需在各自的 Nginx 配置中将server_name改为对应的子域名并指向同一套证书文件fullchain.pem和privkey.pem即可。这就是通配符证书的便利之处。5. 实现自动化续期Let‘s Encrypt 证书有效期只有 90 天手动续期是不可接受的。我们需要设置自动化。5.1 测试续期命令首先手动测试续期是否正常工作--dry-run参数模拟续期不会真的签发新证书sudo certbot renew --dry-run如果看到Congratulations, all renewals succeeded. The following certs have been renewed:之类的提示说明续期流程配置正确。5.2 配置系统定时任务CronCertbot 安装包通常会创建一个每日运行两次的定时任务。但为了确保万无一失我们可以手动检查或添加。编辑 root 用户的 crontabsudo crontab -e在文件末尾添加或确认存在类似以下的行如果已存在则无需重复添加# 每天凌晨2:30尝试续期所有证书并重启 Nginx 30 2 * * * /usr/bin/certbot renew --quiet --post-hook systemctl reload nginx--quiet静默模式只在出错时输出信息。--post-hook续期成功后执行的命令。这里我们重载 Nginx 以使新证书生效。根据你的服务可能还需要重启 Docker 容器或其他 Web 服务器。关键点--post-hook非常重要。因为续期后生成的是新证书文件但 Nginx 进程仍然在使用旧的文件句柄必须重载或重启才能加载新证书。5.3 验证自动化流程你可以通过调整系统时间仅限测试环境或等待证书快到期时观察日志来验证# 查看 Certbot 的续期日志 sudo tail -f /var/log/letsencrypt/letsencrypt.log6. 常见问题与排查思路在配置过程中你可能会遇到以下问题问题现象可能原因排查思路与解决方案申请证书时失败提示 DNS 问题1. API Token 权限不足或错误。2. DNS 记录传播延迟。3. 域名未正确指向 Cloudflare灰色云朵。1. 检查/etc/letsencrypt/cloudflare.ini文件内容和权限 (600)。2. 在 Cloudflare 控制台检查_acme-challenge.home.lab的 TXT 记录是否已添加且值正确。3. 确保域名的 DNS 记录在 Cloudflare 处是“已代理”橙色云朵或“仅 DNS”灰色云朵状态。Nginx 配置测试失败 (nginx -t)1. SSL 证书或密钥文件路径错误。2. 证书文件权限问题Nginx 用户通常是www-data无法读取。1. 仔细核对ssl_certificate和ssl_certificate_key的路径。2. 检查证书文件权限sudo ls -la /etc/letsencrypt/live/home.lab/。privkey.pem应仅对 root 可读。Let‘s Encrypt 的符号链接通常已设置正确权限。浏览器访问提示“证书无效”或“不安全”1. 证书域名与访问的域名不匹配。2. 系统时间不正确。3. 证书链不完整使用了cert.pem而非fullchain.pem。1. 点击浏览器锁图标查看证书详情确认颁发给Subject是否包含你访问的域名。2. 检查服务器和客户端的系统时间是否准确。3. 确保 Nginx 配置中ssl_certificate指向的是fullchain.pem。续期失败1. 服务器无法连接 Let‘s Encrypt 的 ACME 服务器。2. DNS 挑战再次失败。3. 证书存储目录磁盘空间不足。1. 检查网络连通性curl https://acme-v02.api.letsencrypt.org。2. 查看详细日志sudo certbot renew --force-renewal --dry-run -v。3. 清理旧证书sudo certbot delete --cert-name home.lab(危险先备份) 或增加磁盘空间。Docker 容器内服务如何使用此证书容器无法直接读取宿主机/etc/letsencrypt目录。推荐方案将/etc/letsencrypt目录作为只读卷-v挂载到容器内。例如在 Docker Compose 中volumes:- /etc/letsencrypt:/etc/letsencrypt:ro然后在容器内的应用配置中指向挂载的证书路径。7. 进阶优化与最佳实践7.1 使用 Docker 运行 Certbot可选如果你偏好容器化可以使用 Certbot 的官方 Docker 镜像避免在宿主机安装 Python 依赖。但需要处理好证书文件的持久化存储和 Nginx 重载的钩子。# 示例命令需根据实际情况调整卷挂载和钩子脚本 docker run -it --rm \ -v “/etc/letsencrypt:/etc/letsencrypt” \ -v “/var/lib/letsencrypt:/var/lib/letsencrypt” \ -v “/path/to/cloudflare.ini:/cloudflare.ini:ro” \ certbot/dns-cloudflare certonly \ --dns-cloudflare \ --dns-cloudflare-credentials /cloudflare.ini \ --email your-emailexample.com \ -d “home.lab” -d “*.home.lab” \ --agree-tos7.2 证书文件的安全与备份权限确保/etc/letsencrypt/archive/和/etc/letsencrypt/live/下的私钥文件 (privkey.pem) 权限为600(rw-------)所有者是 root。备份定期备份整个/etc/letsencrypt目录。如果服务器崩溃恢复证书和私钥至关重要。禁止存储切勿将私钥提交到 Git 仓库或任何版本控制系统。7.3 配置强化的 SSL/TLS 参数上述 Nginx 配置中已包含基础的 SSL 优化。你可以使用 Mozilla SSL Configuration Generator 生成更现代、更安全的配置。重点关注仅启用 TLS 1.2 和 1.3。使用前向保密的加密套件。启用 OCSP Stapling 以提高 TLS 握手性能。7.4 监控证书过期时间虽然自动化续期很可靠但添加监控仍是好习惯。你可以使用脚本定期检查并发送通知如通过 Telegram Bot、邮件。使用 Uptime Kuma、Healthchecks.io 等监控工具添加 HTTPS 证书过期检查。7.5 关于 Cloudflare 代理橙色云朵如果你的 DNS 记录在 Cloudflare 上开启了代理橙色云朵流量会先经过 Cloudflare 的 CDN。此时服务器源站可以使用自签名证书、HTTP、或本文申请的通配符证书。因为 Cloudflare 到源站的连接“边缘证书到源站”可以单独配置。用户到 Cloudflare由 Cloudflare 提供的“边缘证书”保护可以是 Cloudflare 的通用 SSL免费也可以上传自定义证书。本文方案的价值即使开启代理为源站配置有效的 HTTPS 证书如本文的通配符证书也是最佳实践可以确保“边缘到源站”的连接也是加密的并且避免浏览器可能出现的“混合内容”警告如果源站是 HTTP。在 Cloudflare SSL/TLS 设置中选择“完全”或“完全严格”模式即可。8. 总结通过本文的步骤你已经成功为你的 Homelab 搭建了一套基于 Let‘s Encrypt 通配符证书的自动化 HTTPS 解决方案。这套方案的核心优势在于一劳永逸一张证书保护所有现有和未来的子域名。完全免费利用 Let‘s Encrypt 和 Cloudflare 的免费服务。高度自动化通过 Cron 任务实现证书的自动续期和 Web 服务器重载。安全可信浏览器完全信任告别安全警告。整个过程的关键在于理解 DNS-01 挑战的原理并正确配置 Cloudflare API Token 的权限。一旦初始配置完成后续的维护成本几乎为零。你可以将这套方法扩展到更多域名或者尝试其他支持 ACME DNS-01 协议的 DNS 服务商如阿里云、腾讯云 DNSPodCertbot 也有相应插件。Homelab 的乐趣就在于不断优化让自建服务在功能和体验上向专业产品看齐。
