这次我们来看一个家庭实验室Homelab中 HTTPS 通配符证书的配置方案。对于自建了 NAS、Nextcloud、GitLab、Jellyfin 等服务的玩家来说为每个子域名手动申请和续期 SSL 证书是件麻烦事。通配符证书Wildcard Certificate可以一劳永逸地解决*.yourdomain.com下所有子域名的 HTTPS 加密需求而 Lets Encrypt 提供的免费证书服务配合 acme.sh 等自动化工具是实现这一目标最经济、高效的选择。本文的核心是提供一个“听劝改进”后的完美配置方案它直接回应了社区实践中常见的痛点如何稳定申请通配符证书、如何自动化续期、如何适配 Nginx/Apache 等不同 Web 服务器以及如何解决 DNS API 配置、证书验证失败等典型问题。方案基于 acme.sh 这一成熟的 ACME 客户端支持包括阿里云、Cloudflare 在内的数十家 DNS 服务商 API实现全自动的证书签发与部署。如果你正在为 Homelab 内一堆服务的 HTTPS 红色警告而烦恼或者对证书续期总是提心吊胆那么这套方案值得你花十分钟部署。它不依赖特定硬件在树莓派、旧笔记本或服务器上都能运行核心是脚本的自动化能力。接下来我们将从核心能力、环境准备、一步步的配置过程、功能验证到最后的排错与最佳实践完整走通整个流程。1. 核心能力速览在深入细节前先用一个表格快速了解本方案的核心特性和能力边界帮助你判断是否适合你的 Homelab 环境。能力项说明核心目标为 Homelab 内所有子域名自动申请、部署、续期免费的 HTTPS 通配符证书。核心工具acme.sh– 一个纯 Shell 编写的 ACME 协议客户端以轻量和自动化著称。证书颁发机构Let‘s Encrypt – 提供免费的 DV SSL/TLS 证书支持通配符。验证方式DNS API 验证推荐。无需开放 80/443 端口到公网通过 DNS 服务商的 API 自动添加 TXT 记录完成域名所有权验证。支持的 DNS 服务商阿里云、Cloudflare、腾讯云 DNSPod、华为云、GoDaddy 等数十家主流厂商。证书类型RSA 或 ECC 算法证书。ECC 证书更小、更安全但需确认后端服务兼容性。自动化程度全自动。证书申请、部署到 Web 服务器如 Nginx、以及每 60 天的自动续期均由acme.sh管理。系统依赖支持 Linux (包括树莓派)、macOS、Windows (通过 WSL 或 Git Bash)。需要curl、cron服务。Web 服务器支持Nginx、Apache、Caddy 等。支持自动配置ssl_certificate和ssl_certificate_key路径。适合场景个人或家庭实验室拥有自己的域名并希望通过自动化管理所有内部服务的 HTTPS。不适合场景需要 OV/EV 级别证书的商业生产环境没有公网域名或无法配置 DNS API 的环境。2. 适用场景与使用边界这个方案是为谁准备的简单说是给那些喜欢折腾 Homelab拥有一个或多个自定义域名并且希望内部服务访问时浏览器不报安全警告的技术爱好者。它能解决什么问题统一管理用一个通配符证书如*.home.lab覆盖nas.home.lab、nextcloud.home.lab、git.home.lab等所有子域名。自动化续期Let‘s Encrypt 证书只有 90 天有效期手动续期极易忘记。本方案通过cron定时任务自动续期完全无需人工干预。提升安全性与体验启用 HTTPS 可以加密局域网甚至公网访问流量防止中间人攻击。对于 Nextcloud、Bitwarden 等涉及敏感数据的服务HTTPS 是必须的。同时现代浏览器对 HTTP 站点的“不安全”标识非常显眼HTTPS 能提供更专业的访问体验。它的使用边界在哪里域名要求你必须拥有一个可以在公网解析的域名例如在阿里云、Cloudflare 注册的并且能够配置该域名的 DNS 解析记录。网络环境如果使用 DNS API 验证方式推荐则对 Homelab 的网络出口没有特殊要求。如果使用 HTTP-01 验证不推荐用于通配符则需要 Homelab 的 80 端口能被公网访问。证书类型Let‘s Encrypt 签发的是域名验证DV证书仅能证明你对域名的控制权不包含组织身份信息OV/EV。这对于个人和 Homelab 使用完全足够但不适用于需要展示企业身份的商业网站。合规与责任请确保你申请证书的域名用于合法合规的服务。自动化工具的使用应遵守 Let‘s Encrypt 的 速率限制政策 避免滥用。3. 环境准备与前置条件在开始安装和配置之前请确保你的 Homelab 服务器满足以下条件。绝大多数 Linux 发行版都能完美运行。操作系统一台运行 Linux 的服务器如 Ubuntu 22.04/20.04, Debian 11/12, CentOS 7/8 Stream。本文以 Ubuntu 22.04 为例其他系统命令略有差异。域名与 DNS拥有一个域名例如example.com。该域名的 DNS 解析管理在一个acme.sh支持的 DNS 服务商处如阿里云、Cloudflare。你需要在 DNS 服务商处获取 API 密钥或 Token。这是最关键的一步。服务器权限需要root或具有sudo权限的用户。基础工具确保curl和cron已安装。通常它们默认存在。# 检查并安装如果需要 sudo apt update sudo apt install curl cron -yWeb 服务器假设你已安装并配置了 Nginx 或 Apache并且知道其配置文件和站点目录的位置。网络连通性服务器需要能正常访问互联网以下载acme.sh和与 Let‘s Encrypt、DNS 服务商 API 通信。4. 安装部署与启动方式acme.sh的安装极其简单它会被安装到你的用户目录下并以该用户身份运行无需root权限除了一些需要写系统目录的部署操作。4.1 安装 acme.sh通过一条命令完成安装。它会从 GitHub 拉取脚本并安装到~/.acme.sh/目录。# 使用 curl 安装 curl https://get.acme.sh | sh -s emailmyexample.com重要说明将myexample.com替换为你自己的邮箱地址。这个邮箱用于接收证书到期提醒和 Let‘s Encrypt 的重要通知。安装脚本会自动为你创建cron定时任务用于每天检查证书是否需要续期。安装完成后需要重新加载 Shell 配置或新开一个终端以便acme.sh命令生效。source ~/.bashrc # 如果你用的是 bash # 或者 source ~/.zshrc # 如果你用的是 zsh验证安装是否成功acme.sh --version4.2 配置 DNS API 凭证以阿里云为例这是实现自动化的核心。我们需要将 DNS 服务商的 API 密钥告知acme.sh。这里以阿里云Alibaba Cloud为例其他服务商如 Cloudflare原理类似只是环境变量名不同。获取阿里云 API 密钥登录阿里云控制台进入 RAM 访问控制 。创建一个专用于证书管理的子用户例如acme-user并为其勾选“OpenAPI 调用访问”权限。为该用户添加AliyunDNSFullAccess策略使其拥有管理 DNS 的完整权限。创建 AccessKeyAccessKey ID 和 AccessKey Secret。请妥善保存 Secret它只显示一次。在服务器上设置环境变量acme.sh支持多种方式导入凭证最安全方便的是使用环境变量。在你的用户 Shell 配置文件中如~/.bashrc或~/.zshrc末尾添加# 阿里云 DNS API 配置 export Ali_Key你的AccessKey ID export Ali_Secret你的AccessKey Secret然后使配置生效source ~/.bashrc安全提示确保你的服务器环境安全避免 API 密钥泄露。也可以选择将密钥保存在acme.sh的配置目录中但环境变量方式在脚本运行时更通用。5. 功能测试与效果验证现在让我们进入最关键的环节申请第一张通配符证书并验证其是否生效。5.1 申请通配符证书假设你的域名是example.com你想为*.home.example.com申请证书。执行以下命令acme.sh --issue --dns dns_ali -d *.home.example.com -d home.example.com命令参数解析--issue签发证书。--dns dns_ali指定使用阿里云的 DNS API 进行验证。如果是 Cloudflare则用dns_cf。-d ‘*.home.example.com‘指定通配符域名。-d ‘home.example.com‘同时为主域名也申请证书可选但有时直接访问主域名也需要证书。执行过程脚本会使用你配置的Ali_Key和Ali_Secret调用阿里云 API在home.example.com的 DNS 记录中自动添加一条用于验证的_acme-challengeTXT 记录。等待 DNS 记录在全球生效通常几十秒到几分钟脚本会自动检测。验证通过后Let‘s Encrypt 会签发证书acme.sh将其保存到~/.acme.sh/*.home.example.com/目录下。脚本会自动清理刚才添加的临时 TXT 记录。如果一切顺利你会看到类似Cert success.的成功信息。证书文件fullchain.cer或.crt和私钥文件*.home.example.com.key已经生成。5.2 部署证书到 Web 服务器以 Nginx 为例证书申请成功只是第一步我们需要将其安装到 Web 服务器才能生效。acme.sh提供了--install-cert命令来简化这个过程。假设你的 Nginx 配置目录是/etc/nginx站点配置中 SSL 证书的路径通常为/etc/nginx/ssl/。我们先创建这个目录sudo mkdir -p /etc/nginx/ssl/然后使用acme.sh部署证书acme.sh --install-cert -d ‘*.home.example.com‘ \ --key-file /etc/nginx/ssl/home.example.com.key \ --fullchain-file /etc/nginx/ssl/home.example.com.crt \ --reloadcmd sudo systemctl reload nginx参数解析--install-cert执行证书安装。-d指定证书对应的域名。--key-file指定私钥文件的存放路径。--fullchain-file指定完整证书链文件的存放路径包含服务器证书和中间 CA 证书。--reloadcmd证书安装或未来续期后需要执行的命令。这里我们设置成重载 Nginx 配置使新证书立即生效。这是实现自动化续期的关键执行后证书和私钥会被复制到指定路径并且acme.sh会记住这个“部署配置”。未来证书自动续期后它会自动将新证书复制到相同位置并执行sudo systemctl reload nginx命令。5.3 配置 Nginx 使用证书现在你需要修改你的 Nginx 站点配置文件例如/etc/nginx/sites-available/your-site将其从监听 HTTP 80 端口改为监听 HTTPS 443 端口并指向我们刚才部署的证书。一个最基本的配置示例如下server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name nas.home.example.com; # 你的具体子域名 # 指定证书路径就是上面 --install-cert 设置的路径 ssl_certificate /etc/nginx/ssl/home.example.com.crt; ssl_certificate_key /etc/nginx/ssl/home.example.com.key; # 可选的 SSL 优化配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384; ssl_prefer_server_ciphers off; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 你的网站根目录和其他配置 root /var/www/nas; index index.html index.htm; location / { try_files $uri $uri/ 404; } } # 可选将 HTTP 80 端口重定向到 HTTPS 443 端口 server { listen 80; listen [::]:80; server_name nas.home.example.com; return 301 https://$server_name$request_uri; }修改配置后检查语法并重载 Nginxsudo nginx -t # 测试配置文件语法 sudo systemctl reload nginx # 重载配置5.4 验证 HTTPS 访问打开浏览器访问https://nas.home.example.com。你应该能看到绿色的安全锁标志点击锁标志可以查看证书详情确认颁发者为 “Let‘s Encrypt”且证书适用于*.home.example.com。你也可以使用curl命令快速测试curl -I https://nas.home.example.com如果返回HTTP/2 200或类似成功状态码并且没有 SSL 证书错误说明配置成功。至此你的第一个子域名已经成功配置了自动化的 HTTPS 通配符证书。对于nextcloud.home.example.com、git.home.example.com等其他服务你无需再次申请证书只需在它们的 Nginx 配置中ssl_certificate和ssl_certificate_key指向同一个证书文件即可。6. 接口 API 与批量任务acme.sh本身是一个命令行工具但它通过将配置和任务写入cron来实现“后台服务”和“批量任务”的效果。理解其自动化机制有助于你管理和排查问题。6.1 自动化续期机制安装时acme.sh会自动添加一个每日运行的cron任务。你可以通过以下命令查看crontab -l你应该会看到一行类似这样的记录0 0 * * * /home/your_username/.acme.sh/acme.sh --cron --home /home/your_username/.acme.sh /dev/null这个任务每天午夜检查所有由该acme.sh实例管理的证书。如果证书有效期不足30天它会自动触发续期流程重新验证 DNS - 申请新证书 - 执行--install-cert时设置的--reloadcmd。这就是“一键启动永久自动”的核心。你完全不用再操心证书过期问题。6.2 管理多个域名和证书如果你有多个主域名例如example.com和another.com需要为它们分别申请通配符证书。只需重复执行acme.sh --issue和acme.sh --install-cert命令指定不同的-d参数即可。acme.sh会独立管理每一套证书。所有证书的续期都会由同一个cron任务处理。6.3 证书列表与状态查询你可以随时查看当前由acme.sh管理的所有证书acme.sh --list这个命令会列出所有证书的域名、主目录、密钥类型、到期时间等信息非常便于管理。7. 资源占用与性能观察这个方案对系统资源的占用几乎可以忽略不计非常适合 Homelab 环境。CPU/内存占用acme.sh本身是 Shell 脚本运行时消耗极少的 CPU 和内存通常几 MB。证书续期操作每分钟最多发生一次受 Let‘s Encrypt 速率限制日常没有任何常驻进程。磁盘空间每张证书及相关文件约占 10-20 KB。管理几十个证书也只用不到 1 MB 空间。网络流量仅在申请和续期证书时与 Let‘s Encrypt 的服务器以及 DNS 服务商的 API 有少量 HTTPS 通信。性能影响SSL/TLS 握手会带来额外的计算开销但现代 CPU 处理 RSA 或 ECC 解密绰绰有余。对于家庭内部服务这点开销完全可以忽略。启用 HTTP/2 或 HTTP/3 反而可能因为多路复用而提升性能。观察方法你几乎不需要特意监控它。唯一需要关注的是cron的日志或acme.sh的邮件通知如果你在安装时提供了邮箱以确认续期是否成功。可以定期比如每月运行acme.sh --list检查证书到期时间。8. 常见问题与排查方法即使按照步骤操作也可能遇到一些问题。下表列出了常见问题及其解决方法。问题现象可能原因排查方式解决方案执行acme.sh --issue时报错Create new order error. Le_OrderFinalize not found或 DNS 验证超时1. DNS API 凭证环境变量未生效或错误。2. 域名不在当前 DNS 服务商处解析或 API 权限不足。3. 网络问题无法连接到 Let‘s Encrypt 或 DNS 服务商 API。1. 执行echo $Ali_Key和echo $Ali_Secret检查环境变量是否正确设置。2. 在 DNS 服务商控制台手动添加一条 TXT 记录测试确认域名管理权。3. 使用curl -v https://acme-v02.api.letsencrypt.org/测试网络连通性。1. 重新source ~/.bashrc或检查拼写错误。2. 检查 RAM 用户权限确保有 DNS 管理权限。确认域名已正确设置 NS 记录。3. 检查服务器防火墙/安全组确保允许对外 HTTPS 连接。证书申请成功但 Nginx 重启失败或浏览器提示证书无效1. Nginx 配置中证书或私钥路径错误。2. 证书文件权限问题Nginx 进程用户如www-data无法读取。3.--install-cert的--reloadcmd命令执行失败。1. 使用sudo nginx -t检查配置语法。2. 使用ls -l /etc/nginx/ssl/检查文件权限和所有者。3. 手动执行sudo systemctl reload nginx看是否有错误。1. 核对 Nginx 配置中的ssl_certificate和ssl_certificate_key路径。2. 使用sudo chmod 644 /etc/nginx/ssl/*.crt /etc/nginx/ssl/*.key和sudo chown root:root /etc/nginx/ssl/*修正权限。3. 检查--reloadcmd命令的语法和sudo权限。证书没有自动续期1.cron服务未运行。2.acme.sh的cron任务被移除或修改。3. 续期时 DNS API 验证再次失败。1. 运行systemctl status cron检查服务状态。2. 运行crontab -l查看任务是否存在。3. 查看acme.sh的日志~/.acme.sh/acme.sh.log。1. 启动cron服务sudo systemctl start cron sudo systemctl enable cron。2. 重新安装acme.sh或手动添加cron任务。3. 根据日志错误重新检查 DNS API 凭证和网络。浏览器访问显示 “不安全” 或 “NET::ERR_CERT_COMMON_NAME_INVALID”1. 访问的子域名与证书的通用名称CN不匹配。通配符证书只覆盖一级子域名。2. 证书链不完整。1. 点击浏览器锁图标查看证书详情确认证书是否包含你访问的域名。2. 使用在线 SSL 检查工具如 SSL Labs 诊断。1. 确保访问的域名是*.home.example.com的形式。a.b.home.example.com需要二级通配符证书Let‘s Encrypt 不支持。2. 确保 Nginx 配置中ssl_certificate指向的是--install-cert生成的.crt完整链文件而不是.cer文件。申请 ECC 证书后某些老旧客户端无法连接ECC 证书的兼容性不如 RSA 证书广泛。检查无法连接的客户端系统或浏览器版本是否过旧。如果遇到兼容性问题可以改用 RSA 证书重新申请acme.sh --issue ... --keylength 2048。9. 最佳实践与使用建议为了让你的 Homelab HTTPS 方案更稳健遵循以下建议先测试后上线首次配置时可以使用 Let‘s Encrypt 的测试环境Staging Environment来避免触发生产环境的速率限制。在--issue命令后加上--staging参数即可。测试通过后移除--staging参数申请正式证书。acme.sh --issue --dns dns_ali -d ‘*.home.example.com‘ --staging使用 ECC 证书在确认客户端兼容后优先使用更安全、性能更好的 ECC 证书。acme.sh默认使用 ECC 密钥。如果需要 RSA需指定--keylength 2048。集中管理证书路径建议将所有证书和私钥统一存放在一个目录下如/etc/nginx/ssl/并建立清晰的命名规范如域名.crt和域名.key。方便备份和配置管理。备份与监控定期备份/etc/nginx/ssl/目录和 Nginx 配置文件。可以设置一个简单的监控定期检查证书过期时间例如通过acme.sh --list输出到日志或用脚本解析并发送提醒。安全加固确保私钥文件.key权限为600或644且所有者是root。用于 DNS API 的 AccessKey 权限应遵循最小化原则仅授予 DNS 管理权限。考虑在防火墙规则中仅允许 Homelab 内部 IP 段访问管理端口。多服务器场景如果你的 Homelab 有多个服务器需要同样的证书可以在主服务器上运行acme.sh管理证书然后使用scp、rsync或配置管理工具如 Ansible将续期后的证书文件分发到其他服务器并触发相应的服务重载命令。10. 总结与下一步这套基于acme.sh和 Let‘s Encrypt 的 Homelab HTTPS 通配符证书方案核心优势在于“一次配置终身免管”的自动化能力。它完美解决了自建服务中证书管理的繁琐问题将企业级的安全实践以零成本的方式带入个人实验室。你最应该优先验证的就是 DNS API 的配置是否正确。这是整个流程能否自动化的闸口。一旦通过后续的申请、部署、续期都将畅通无阻。最容易踩的坑通常是文件路径、权限和 Nginx 配置语法务必在每一步之后使用nginx -t这样的命令进行验证。部署成功后你可以将更多内部服务迁移到 HTTPS甚至可以考虑为你的 Homelab 网关如 Traefik, Nginx Proxy Manager配置自动证书发现实现更高级的透明化 HTTPS 管理。整个 Homelab 的访问安全性和专业度将因此提升一个档次。建议收藏本文在配置时按步骤操作遇到问题对照排查即可轻松搭建属于你自己的安全访问环境。