Caddy + Docker Compose 实现单机HTTPS自动证书部署实战

单机服务器上做HTTPS自动证书部署我折腾了一圈之后最后一直留用的方案是Caddy Docker Compose。这套组合的好处不是某个单一特性而是“自动证书”这件事被Caddy内建成了默认行为Compose又把服务的启动、升级、迁移变得可以用一份文件说清楚。如果你手头有一台云服务器只想快速把站点或者内部服务用HTTPS包起来又不想天天惦记证书什么时候到期那这篇文章应该能帮你少走很多弯路。我会从设计思路、部署前准备、配置文件、实操过程、问题排查一直讲到长期维护习惯尽量把我在单机环境下反复测试过的东西都写出来。1. 为什么我在单机服务器上选 Caddy Docker Compose1.1 Caddy在自动证书这件事上的独特做法很多Web服务要上HTTPS通常需要额外接一套证书申请与续签流程。Caddy比较不一样它从设计上就把“自动HTTPS”当作默认能力只要配置里有域名它就会主动去对接公共CA机构通过ACME协议完成证书申请、写入、续签、重载。对你来说配置文件里只需要填一个接收通知的邮箱地址剩下的交给进程自己处理。这个“默认自动”带来的实际体验差别很大。传统方案里你往往要手动生成密钥、处理Challenge、写入证书路径、设置定时续签任务再让Web服务重新加载。一旦中间某一步出错证书就可能一直停留在过期状态。Caddy把这一整套封装成内部逻辑单机部署时几乎不需要关心证书是如何落地的。我第一次用的时候看到日志里出现“successfully obtained certificate”之后才发现原来自动证书部署可以这么干净。另外Caddy在证书管理上不是简单申请完就结束。它会保存证书状态、跟踪续签时间进程每次重启后会先读取本地证书数据再根据实际情况决定是否需要重新申请。你不需要在Compose编排里额外加一个“cron”容器也不需要在宿主机上写定时任务这一点对单机服务器来说非常省心。1.2 单机场景下Docker Compose的优势和边界Docker Compose常被用在多服务编排里但单机环境下它同样值得用。你完全可以手写几个systemd service然后把Caddy直接装到宿主机上但那样操作流程会分散配置文件放一处、日志服务放一处、开机自启放一处、升级路径又是一套。用Compose把Caddy塞进一个独立容器之后整个服务就是一份“docker-compose.yml”它定义镜像、端口、目录挂载、重启策略、网络名称换一台服务器也能快速复原。Compose在单机场景的边界也不能忽视。它解决的是“单台主机上的容器编排”不是跨服务器集群。如果你以后服务规模涨到多台那就需要考虑Swarm或者Kubernetes那套体系。但在“单机服务器上使用Caddy Docker Compose实现HTTPS自动证书部署”这个目标里Compose的能力是完全够用的甚至可以说是最匹配的容器管理方式。我比较看重的另一点是可回滚。Compose文件写在项目目录里相当于把部署状态固化成了文本。Caddy版本要升级先改image字段再docker compose pull和docker compose up -d不满意可以切回旧版本重新拉取。这种操作在裸机安装方式里没有这么直观。1.3 如果只是单机用Caddy会不会显得重有朋友问过我单机服务器本来就跑几个小服务引入Caddy和Compose是不是增加了额外负担。我的判断是关键不是看“用了多少组件”而是看“省掉了多少手工维护”。Caddy镜像本身非常轻量日常内存占用不算高和传统Web服务器差不了太多。Compose只是一个客户端工具核心只有YAML文件没有额外常驻进程。真正需要权衡的是你如果已经有成熟的手工证书方案并且服务器上就一个静态站点那维持现状也合理。但如果你有多个子域名、多个服务容器还希望以后加站点时少折腾那Caddy Compose这套组合就很有吸引力。它能让你把“证书申请”这件事从每加一个域名的步骤里拿掉变成“填一个域名自动搞定”。2. 部署前的准备工作目录、端口、域名和网络2.1 服务器基础检查开始之前先确认服务器上已经安装好Docker和Docker Compose插件。以常见Linux发行版为例装好Docker后在终端里执行docker compose version能正常输出版本号就说明Compose插件可用。很多服务器可能只装了旧版docker-compose命令是带横线的配置思路一样但实际命令写法略有差异后面演示统一用docker compose。接着检查系统时间。证书申请过程依赖时间校验如果服务器时间偏差太大ACME请求可能直接失败。可以用date命令看一眼当前时间如果相差较多先开启系统时间自动同步。这个问题看起来基础但我在实际部署中遇到过好几次最常见的表现就是证书申请一直报“timeout”或者“certificate not yet valid”排查到最后才发现是服务器时钟问题。还要确认服务器可以访问外网。听起来像废话但很多机房环境会限制出站连接ACME协议需要服务器主动访问CA的接口目录。如果你在服务器上执行curl一个常见HTTPS站点都失败那Caddy申请证书大概率也会卡住。单机部署时先把网络连通性验证好能省掉很多后来才发现的诡异问题。2.2 端口与安全组规划HTTP-01方式的证书验证需要Caddy在80端口响应验证请求。HTTPS访问需要443端口。所以无论你用哪种Challenge方式80和443都建议保持开放。只开443不开80虽然部分场景可以通过TLS-ALPN完成验证但兼容性和可排查性都不如HTTP-01好特别是你以后可能要挂多个站点、多个容器时80端口随时会被用到。在云服务器上除了操作系统防火墙还要检查安全组配置。很多云厂商默认只开了少数端口你在系统里执行ufw allow 80,443/tcp只是放行了服务器自身的防火墙如果安全组不放行外部流量依然进不来。一个比较快的检查办法是在另一台机器上执行curl -I http://你的域名如果返回响应说明80端口已经通了如果卡住或超时优先查安全组和系统防火墙。端口规划上Caddy容器映射80和443到宿主机。业务容器不需要再把端口映射到宿主机Caddy通过容器网络访问它们即可。这样对外只暴露Caddy一个入口业务服务不直接暴露攻击面会小不少。默认容器网络里Caddy和业务容器用服务名互相通信比硬记IP地址要优雅得多。2.3 理解Caddy怎么存证书data卷和config卷Caddy官方镜像规定了两块关键目录一块是数据目录通常挂在/data另一块是配置目录通常挂在/config。证书、私钥、ACME账号信息都在数据目录里重启容器后还需要继续使用所以必须用named volume或者宿主机目录持久化。如果只挂代码不挂数据每次容器重建都会重新申请证书不仅慢还可能撞上CA的申请限额。我在第一次上手时只挂了Caddyfile没有挂数据卷结果每次docker compose down docker compose up -d之后Caddy都像新服务一样重新申请证书。日志里能看到证书申请成功但总觉得哪里不对劲后来才发现证书没有保留。后续我把caddy_data:/data和caddy_config:/config加上从此容器怎么重建证书都还在。理解这块之后你对“备份”也会更有概念。证书数据本质上是一组文件备份时把caddy_data卷的内容复制出来就行。以后换机器把Compose文件、Caddyfile、数据卷内容一起搬过去就能快速恢复HTTPS服务。3. 最容易上手的docker-compose.yml和Caddyfile3.1 docker-compose.yml模板先给出一份适合单机场景的编排文件。这份模板里我同时定义了一个业务容器和一个Caddy容器业务容器不需要直接暴露端口Caddy通过Compose内置网络访问它。version: 3.8 services: caddy: image: caddy:2 container_name: caddy restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config networks: - web app: image: your-app-image:latest container_name: app restart: unless-stopped networks: - web environment: - TZAsia/Shanghai networks: web: name: shared-web volumes: caddy_data: caddy_config:这份文件有几个细节。./Caddyfile:/etc/caddy/Caddyfile:ro表示宿主机当前目录下的Caddyfile被挂载进容器只读方式避免容器内误修改。caddy_data和caddy_config是named volume即使Compose项目重建数据也会被保留。container_name固定之后日志查找和进入容器执行命令都更方便。3.2 Caddyfile基础配置Caddyfile是Caddy的核心配置。最简单的HTTPS自动证书部署只需要一个站点块加一个反向代理指令{ email yourexample.com } your-domain.com { encode zstd gzip reverse_proxy app:8080 }其中your-domain.com必须是你自己的域名而且域名要解析到当前服务器。encode zstd gzip用来开启压缩reverse_proxy app:8080把请求转发给Compose网络里的app容器的8080端口。如果你的站点只是放一些静态文件那Caddyfile可以改成这样your-domain.com { root * /srv/www file_server }只要把/srv/www目录挂载进Caddy容器就能直接用Caddy托管静态页面同时自动完成证书申请。多个域名就写多个站点块Caddy会自动为每个域名分别申请证书互不干扰。比如一个域名反代到A容器另一个域名反代到B容器站点块之间完全独立。3.3 为什么挂载方式值得注意Caddyfile挂载成只读能防止容器内意外改动也提醒你所有配置修改都应该在宿主机完成。用caddy_data:/data而不是./data:/data主要考虑是权限。直接挂宿主机目录时容器内的用户可能没有权限写证书文件会导致申请失败。named volume由Docker管理首次创建时能自动处理权限问题比手动chown省心得多。不要直接把Caddy的/data挂到宿主机当前目录下的data文件夹除非你清楚容器内运行用户的UID/GID并且愿意承担权限配置成本。我见过不少案例证书申请一直报写文件失败最后发现问题都出在宿主机目录权限上。使用named volume可以有效绕开这一类坑数据备份依然可以通过docker volume相关命令来完成。4. 完整实操从空目录到HTTPS站点上线4.1 手工创建两个配置文件找一个干净的目录比如/opt/caddy-stack然后在里面创建两个文件docker-compose.yml和Caddyfile。你可以直接用文本编辑器写也可以用cat加heredoc方式快速创建。内容就参考上一章给出的模板但把域名替换成你自己的。创建完文件后第一步先做语法检查。docker compose config命令会解析YAML如果有语法错误会直接报出来。这个检查成本极低建议每次修改Compose文件后都跑一遍。Caddyfile也有对应的校验命令等容器启动后还可以执行docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile提前发现配置错误。这一步看起来简单却能避免很多“启动失败后再慢慢排查”的时间。如果你在配置里写错了缩进docker compose up -d虽然不一定会拒绝启动但容器可能反复重启日志又看不清楚。先用docker compose config文本层面验证是单机部署里最容易养成的习惯。4.2 第一次启动等待证书签发在项目目录里执行docker compose up -d启动后重点观察Caddy日志docker compose logs -f caddy正常情况下日志里会出现类似“certificate obtained successfully”的记录。我建议耐心多等十几秒钟因为ACME申请涉及网络请求第一次可能要几秒到几十秒。如果日志一直没有提到证书反而反复出现错误那就进入排查阶段。启动完成后在浏览器访问https://your-domain.com看到小锁图标说明证书已经生效。这时候再回看日志你会发现Caddy同时完成了“反向代理正常”“证书可用”“自动跳转HTTPS”三件事。后来想把HTTP请求统一跳到HTTPS也只需要在Caddyfile里配置redir不需要额外安装其他组件。4.3 验证证书和自动续签机制证书不是申请一次就永久有效。公共CA签发的证书有效期通常在三个月左右所以“自动续签”才是长期省心的关键。Caddy会自动跟踪证书剩余时间在合适的节点发起续签请求整个过程同样通过ACME协议完成不需要你干预。你可以主动验证续签机制是否正常。在项目目录执行docker compose exec caddy caddy renew --force这个命令会强制Caddy重新申请当前配置里的证书。如果成功日志会显示新证书已经生效。不建议频繁执行因为CA有申请频率限制但偶尔做一次“演练”能让你对自动续签机制有信心。日常使用中你只需要观察日志里有没有“renew”相关记录即可。Caddy管续签Docker管重启。Compose配置里设置了restart: unless-stopped意味着服务器重启后Caddy和业务容器都会自动拉起。即使容器重建caddy_data卷里保存的证书也会被继续使用不会因为一次重启就让HTTPS失效。4.4 把现有业务容器接入Caddy很多场景不是从零部署业务而是服务器上已经有一个跑在某个端口上的服务。为了让Caddy接管它最简单的做法是把这个服务也纳入同一个Compose项目网络然后Caddy用服务名访问。如果业务服务已经通过其他方式运行不在当前Compose项目里可以让Caddy容器加入同一个外部网络或者直接使用reverse_proxy localhost:端口这样的宿主机地址。在Caddyfile里可以这样写your-domain.com { reverse_proxy 127.0.0.1:8080 }前提是Caddy容器能够访问宿主机的8080端口。对于单机场景这种方案虽然是“绕过Compose网络”的例外但现实中经常用到因为很多旧服务都是直接挂在宿主机上的。缺点是对外仍然只暴露80和443业务端口不对公网开放安全性依然可控。如果你希望多个服务通过路径区分也可以在一个域名下分路径转发。Caddy会用路径前缀判断目标your-domain.com { handle /api/* { reverse_proxy app:8080 } handle { root * /srv/web file_server } }这样/api下的请求进入业务容器其他请求走静态文件。Caddy会自动为your-domain.com申请同一张证书所有路径共用不会因为多几个handle就多申请一次。5. 证书签发失败的常见原因与排查清单5.1 80端口被占、安全组未放行的经典问题证书签发出错时最常见的一类原因就是80端口没通。HTTP-01验证需要CA通过公网访问你的/.well-known/acme-challenge/路径。只要80端口不通验证请求就过不来。你可能看到日志报“timeout”“connection refused”或者“no response from server”。先排查端口占用。如果服务器上本来就有传统的Web服务占用了80端口Caddy容器就会绑定失败容器日志会直接报address already in use。解决办法是把旧服务停掉或改端口。如果旧服务本身也是你的业务入口那就需要让Caddy接管入口而不是继续由旧服务占用80。再看安全组。云服务器通常有两层防火墙系统防火墙和安全组。登录服务器后执行ufw status能看到系统防火墙规则安全组需要登录云控制台查看。测试连通性时可以从外部机器执行curl -I http://your-domain.com如果命令卡住或者超时问题基本就在网络层。别急着怀疑Caddy配置先把端口通不通确认清楚。我在排查证书问题时几乎总是先测端口再动配置文件可以避免浪费时间。5.2 域名解析没生效的排查路径域名解析也是一个高频问题。ACME验证时CA拿到你的域名会去查询DNS解析结果然后访问解析出来的IP。如果域名解析到的是旧服务器、CDN地址或者根本没有解析证书申请就不可能成功。Caddy能做的只是发起请求它无法帮你解决DNS问题。排查方式很直接dig short your-domain.com如果返回的IP不是你当前服务器的公网IP解析配置就是错的。你需要在DNS管理后台修改A记录让域名指向这台服务器。如果服务器有IPv6地址且配置了AAAA记录也要确保IPv6网络可达否则部分网络环境下访问会受影响。还有一个容易忽略的点解析生效需要时间修改DNS后不是立刻全局生效。你可以多等几分钟也可以用公共DNS查询工具确认。域名解析刚刚修改完就马上启动Caddy大概率会碰到“certificate obtained”失败这不是Caddy的问题是DNS还没有完全同步。5.3 卷权限、挂载目录大小写这类细节Caddy在容器内需要写数据目录。如果caddy_data挂载不当或者你改用了宿主机目录而权限不对日志里会出现“permission denied”或“write error”。用named volume时这类问题很少所以我的建议是不要折腾直接用named volume保存证书数据。如果你必须用宿主机目录可以这样做先创建一个data目录然后授权给Caddy容器内使用的用户。实际操作中最简单的办法是让目录对所有用户可写但生产环境不建议这样。更稳妥的方式是查看Caddy镜像默认运行用户的UID然后用chown -R 对应UID:对应GID修改目录归属。挂载静态站点目录时也要关心可读性。Caddy容器内的用户要能读取站点文件否则请求会返回403或者404。这时候不一定是配置写错而是文件权限不够。SELinux环境还会更复杂有时需要给挂载目录加上合适的上下文标签。单机部署时遇到403先检查文件权限总没错。5.4 用CA测试接口避免频繁触发限额CA对每个域名、每个IP都有限额限制。如果你在短时间内反复申请同一张测试证书可能会触发“too many certificates already issued”之类的错误然后申请被暂时封禁。这是ACME协议里的正常保护机制不是Caddy的问题。为了避免在调试阶段消耗真实配额可以先把Caddy的ACME目录切到测试环境。Caddy支持在全局配置里设置acme_ca指向CA的测试端点。具体URL以你所用CA的文档为准。测试环境下的证书不被浏览器信任但可以用来验证整条链路DNS解析、端口连通、容器网络、Caddy配置是否都正确。调试通过后再把测试端点注释掉重新加载Caddy让它申请正式的受信任证书。这个习惯能让你放心大胆地反复尝试不用担心把域名申请到限额。6. 单机长期运行的几个维护习惯6.1 证书数据卷的备份和多机器迁移证书数据与普通业务数据一样需要备份。因为caddy_data是一个named volume备份时可以利用临时容器打包内容。具体命令我不展开写但思路很简单把volume挂载到一个临时容器再打包导出。备份频率不用太高证书本身会自动续签只要CA账号信息和证书私钥还在恢复过程就能顺滑完成。多机器迁移时你需要迁移三样东西Compose文件、Caddyfile、数据卷内容。新服务器上先装好Docker和Compose插件把两个配置文件放到项目目录里再把数据卷内容还原到caddy_data卷。启动Caddy后它会发现本地已有证书并且仍然有效就不会重复申请。如果时间耽搁较长导致证书过期也不用慌Caddy会自动发起续签。这里有个心得不要在容器内部手工触发生成命令也不要随便删除caddy_data卷。一旦卷里的ACME账号信息丢失Caddy会重新注册账号旧的证书私钥也不再匹配。虽然Caddy能重新申请但过程中可能出现短暂的服务中断。6.2 升级Caddy与Compose的顺序升级Caddy是个很常见的操作。Caddy版本更新频繁会修复漏洞、改进自动证书逻辑。升级时不要直接docker compose up -d因为本地如果已经有旧镜像这个命令不会主动拉取新版本。推荐顺序是先执行docker compose pull caddy拉取新镜像然后再执行docker compose up -dCompose会发现Caddy镜像有更新用新版本重建容器。数据卷保持不变证书不会因此丢失。如果新版本有问题可以在Compose文件里把镜像版本改回旧版本号再up -d一次完成回滚。Compose插件本身的升级也要留意。新版Compose对网络名、卷名规则可能有过调整如果你从老版本迁移到新版本最好先查看Compose文件里的网络和卷定义避免因为默认名称变化导致容器找不到网络。6.3 合理利用日志提前发现问题Caddy日志能告诉你很多信息证书是否成功申请、续签是否发生、某个域名请求量如何、有没有代理后端报错。默认情况下日志会输出到容器的stdout你可以通过docker compose logs查看。我建议养成定期看日志的习惯尤其在新上线一个站点之后观察前几分钟的日志确认没有异常。如果希望日志更结构化可以在Caddyfile里开启访问日志把它输出到标准输出。这样Docker日志采集器也能统一收集。单机场景下不需要一开始就上复杂的日志系统但至少要让日志能在docker compose logs里完整看到。证书续签成功后日志会有记录你只要知道“自动续签确实发生过”就不需要每天担心证书过期。最后一个维护习惯是“改配置前先全局看一遍影响范围”。Caddy只有一个实例但它可能代理多个服务。你修改Caddyfile时要意识到改动会影响所有域名。先在非生产环境或低峰时段操作再用caddy validate校验配置最后才执行重载。我个人的做法是每次改完都先跑配置校验确认没问题再docker compose exec caddy caddy reload。单机服务器上的Caddy Docker Compose方案本质上是用一份声明式配置把“自动证书”这个复杂问题简化成了日常操作。我踩过不少坑之后才体会到稳定运行的秘诀不在于某个高深技巧而在于把端口、DNS、权限、数据卷这些基础环节提前检查清楚。按照这套流程走下去HTTPS自动证书部署对一台云服务器来说完全可以在一个下午内全部搞定。