接手过不少自托管项目之后我越来越确定一件事只要服务器上跑的服务数量超过两个“一个域名一个入口”的方案就该退休了。以前用 Nginx 的时候每加一个服务就要新写一段 server 配置证书、跳转、location 全都要自己管遇到泛域名还得手动拼正则。换到 Caddy 之后这套复杂度被压成了一行通配符加几个 handle 块。最近我在给一台旧服务器重新整理服务入口正好把所有泛域名配置重新捋了一遍这篇文章就把 Caddy 里用*.example.com匹配所有子域名、再用 handle 把不同子域名分流到不同后端的完整思路写清楚。说人话泛域名就是“一批子域名用同一套规则接入”handle 就是“接入之后按规则把请求分给不同程序”。这两件事是 Caddy 做多服务入口的地基。这篇东西适合谁刚准备把博客、API、管理面板、静态资源全部塞进同一条服务器链路的人以及已经被 Nginx 的 server 块逼疯、想换 Caddy 的人。下面我会从匹配原理讲到真实部署再到我踩过的坑尽量把能直接复用的经验都放进来。1. 为什么我会把“泛域名 handle”当成多服务入口的标准答案1.1 一台服务器上塞了三个服务配置入口成了最大的麻烦我有一台常年开机的服务器上面跑着一个静态博客、一个 Go 写的 API、一个 Node 写的小工具偶尔还要临时开个数据库管理面板。以前用 Nginx 的时候每接一个新服务就要新增一段 server 配置证书申请、跳转规则、location 匹配全要自己维护。服务多起来之后配置文件越改越长改完还要小心翼翼nginx -t再 reload。后来换成 Caddy最直观的感受是域名入口这件事被简化成了两行配置。一个*.example.com的站点块加上几个handle块所有子域名的接入和路由都变得肉眼可见。我不需要为每个子域名单独开一个 server 块也不需要操心证书续期Caddy 默认全包了。这种体验上的差距只有真的迁移过一次才能体会。1.2 泛域名负责接入handle 负责分拣我把这套思路总结成两句话泛域名负责“接入”handle 负责“分拣”。泛域名*.example.com把一批子域名收敛到同一个配置块里解决的是“入口”问题。无论你后来新增foo.example.com还是bar.example.com只要 DNS 解析指向这台服务器它们都会自动落入这个泛域名块。handle 块则在配置块内部按条件把请求分给不同后端解决的是“路由”问题。打个比方泛域名是公司前台handle 是分机表。前台把所有来电都接进来分机表决定电话转给哪个同事。每次新接入一个服务都只是新增一行handle的事。这种拆分思维一旦建立后面所有配置都是在往里填细节。2. *.example.com 是怎么匹配的Caddyfile 的匹配优先级与通配符语义2.1 泛域名匹配规则它只匹配子域名不匹配根域*.example.com不是正则表达式它有一个精确语义匹配“一层”子域名比如api.example.com、blog.example.com、app.example.com。它不匹配根域名example.com本身也不匹配更深的a.b.example.com。这个细节是新手上路时最容易踩的坑。如果你希望根域名也一起接管需要单独再加一个example.com的站点块。我在实际配置里就遇到过泛域名块配好了api.example.com访问正常打开example.com却显示连接被拒绝就是因为根域名没有对应块。Caddy 在站点块匹配时遵循“最具体优先”的原则。比如同时存在*.example.com和api.example.com两个块请求api.example.com会命中更具体的那个块而不是泛域名块其他子域名则全部落入泛域名块。这个规则的好处是你可以对个别子域名单独开小灶比如给api.example.com单独配一套更严格的 TLS 策略而其他子域名继续走泛域名逻辑。2.2 通配符证书与 DNS-01 challenge泛域名绕不过去的一关配置泛域名后Caddy 默认会尝试为*.example.com申请一张通配符证书。这里有一个很多人不知道的底层机制通配符证书不能用普通的 HTTP-01 验证方式因为 ACME 协议要求通配符域名通过 DNS-01 challenge 来验证证明你对该域名 DNS 记录有控制权。所以 Caddyfile 的全局段里通常要配置 DNS provider让 Caddy 能调用 DNS 服务商 API 自动添加和删除 TXT 记录。比如域名在 Cloudflare 解析可以配cloudflare这个 provider在 DNSPod 解析就配dnspod。不同 provider 的凭据获取方式不一样但核心思路一致Caddy 在申请证书时动态创建一条 TXT 记录ACME 服务商验证通过后自动删除。如果你只是在开发环境测试没有域名权限最简单的办法是给站点块加上tls internal这样 Caddy 会用内置 CA 生成自签证书。虽然浏览器会提示不可信但路由逻辑能正常验证开发阶段完全够用。2.3 本地测试最容易忽略的 internal CA 与 hosts 改写本地调试泛域名时我有一套固定三件套修改/etc/hosts把api.example.com、app.example.com全部指向127.0.0.1Caddyfile 里给站点块加tls internal前台执行caddy run看实时日志。如果嫌浏览器证书警告烦可以把 Caddy 内部 CA 的根证书导入系统信任区。之后访问这些子域名浏览器不再报错开发体验接近生产环境。不想处理证书时也可以临时把站点地址写成http://*.example.com直接关闭 TLS等调试完再改回默认写法。这里要提醒一句tls internal会生成内网自签证书生产环境千万别用否则用户访问时会看到大红色警告页观感极其灾难。3. handle 块把请求拆给不同后端的核心路由机制3.1 handle 按顺序执行第一个匹配生效handle是 Caddy 路由体系里的核心指令但它的执行模型和很多人习惯的逻辑不一样。请求进入站点块后Caddy 从上到下逐条执行 handle匹配到第一个符合条件的 handle 就执行它处理完直接 Caddy泛域名+handle：一行配置搞定多服务入口路由
接手过不少自托管项目之后我越来越确定一件事只要服务器上跑的服务数量超过两个“一个域名一个入口”的方案就该退休了。以前用 Nginx 的时候每加一个服务就要新写一段 server 配置证书、跳转、location 全都要自己管遇到泛域名还得手动拼正则。换到 Caddy 之后这套复杂度被压成了一行通配符加几个 handle 块。最近我在给一台旧服务器重新整理服务入口正好把所有泛域名配置重新捋了一遍这篇文章就把 Caddy 里用*.example.com匹配所有子域名、再用 handle 把不同子域名分流到不同后端的完整思路写清楚。说人话泛域名就是“一批子域名用同一套规则接入”handle 就是“接入之后按规则把请求分给不同程序”。这两件事是 Caddy 做多服务入口的地基。这篇东西适合谁刚准备把博客、API、管理面板、静态资源全部塞进同一条服务器链路的人以及已经被 Nginx 的 server 块逼疯、想换 Caddy 的人。下面我会从匹配原理讲到真实部署再到我踩过的坑尽量把能直接复用的经验都放进来。1. 为什么我会把“泛域名 handle”当成多服务入口的标准答案1.1 一台服务器上塞了三个服务配置入口成了最大的麻烦我有一台常年开机的服务器上面跑着一个静态博客、一个 Go 写的 API、一个 Node 写的小工具偶尔还要临时开个数据库管理面板。以前用 Nginx 的时候每接一个新服务就要新增一段 server 配置证书申请、跳转规则、location 匹配全要自己维护。服务多起来之后配置文件越改越长改完还要小心翼翼nginx -t再 reload。后来换成 Caddy最直观的感受是域名入口这件事被简化成了两行配置。一个*.example.com的站点块加上几个handle块所有子域名的接入和路由都变得肉眼可见。我不需要为每个子域名单独开一个 server 块也不需要操心证书续期Caddy 默认全包了。这种体验上的差距只有真的迁移过一次才能体会。1.2 泛域名负责接入handle 负责分拣我把这套思路总结成两句话泛域名负责“接入”handle 负责“分拣”。泛域名*.example.com把一批子域名收敛到同一个配置块里解决的是“入口”问题。无论你后来新增foo.example.com还是bar.example.com只要 DNS 解析指向这台服务器它们都会自动落入这个泛域名块。handle 块则在配置块内部按条件把请求分给不同后端解决的是“路由”问题。打个比方泛域名是公司前台handle 是分机表。前台把所有来电都接进来分机表决定电话转给哪个同事。每次新接入一个服务都只是新增一行handle的事。这种拆分思维一旦建立后面所有配置都是在往里填细节。2. *.example.com 是怎么匹配的Caddyfile 的匹配优先级与通配符语义2.1 泛域名匹配规则它只匹配子域名不匹配根域*.example.com不是正则表达式它有一个精确语义匹配“一层”子域名比如api.example.com、blog.example.com、app.example.com。它不匹配根域名example.com本身也不匹配更深的a.b.example.com。这个细节是新手上路时最容易踩的坑。如果你希望根域名也一起接管需要单独再加一个example.com的站点块。我在实际配置里就遇到过泛域名块配好了api.example.com访问正常打开example.com却显示连接被拒绝就是因为根域名没有对应块。Caddy 在站点块匹配时遵循“最具体优先”的原则。比如同时存在*.example.com和api.example.com两个块请求api.example.com会命中更具体的那个块而不是泛域名块其他子域名则全部落入泛域名块。这个规则的好处是你可以对个别子域名单独开小灶比如给api.example.com单独配一套更严格的 TLS 策略而其他子域名继续走泛域名逻辑。2.2 通配符证书与 DNS-01 challenge泛域名绕不过去的一关配置泛域名后Caddy 默认会尝试为*.example.com申请一张通配符证书。这里有一个很多人不知道的底层机制通配符证书不能用普通的 HTTP-01 验证方式因为 ACME 协议要求通配符域名通过 DNS-01 challenge 来验证证明你对该域名 DNS 记录有控制权。所以 Caddyfile 的全局段里通常要配置 DNS provider让 Caddy 能调用 DNS 服务商 API 自动添加和删除 TXT 记录。比如域名在 Cloudflare 解析可以配cloudflare这个 provider在 DNSPod 解析就配dnspod。不同 provider 的凭据获取方式不一样但核心思路一致Caddy 在申请证书时动态创建一条 TXT 记录ACME 服务商验证通过后自动删除。如果你只是在开发环境测试没有域名权限最简单的办法是给站点块加上tls internal这样 Caddy 会用内置 CA 生成自签证书。虽然浏览器会提示不可信但路由逻辑能正常验证开发阶段完全够用。2.3 本地测试最容易忽略的 internal CA 与 hosts 改写本地调试泛域名时我有一套固定三件套修改/etc/hosts把api.example.com、app.example.com全部指向127.0.0.1Caddyfile 里给站点块加tls internal前台执行caddy run看实时日志。如果嫌浏览器证书警告烦可以把 Caddy 内部 CA 的根证书导入系统信任区。之后访问这些子域名浏览器不再报错开发体验接近生产环境。不想处理证书时也可以临时把站点地址写成http://*.example.com直接关闭 TLS等调试完再改回默认写法。这里要提醒一句tls internal会生成内网自签证书生产环境千万别用否则用户访问时会看到大红色警告页观感极其灾难。3. handle 块把请求拆给不同后端的核心路由机制3.1 handle 按顺序执行第一个匹配生效handle是 Caddy 路由体系里的核心指令但它的执行模型和很多人习惯的逻辑不一样。请求进入站点块后Caddy 从上到下逐条执行 handle匹配到第一个符合条件的 handle 就执行它处理完直接