中文

应用程序

使用 Caddy 反向代理并自动启用 HTTPS

从官方软件源在 Debian 或 Ubuntu 上安装 Caddy,以自动 HTTPS 发布应用,保护管理界面,并完成更新与备份。

阅读约 8 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何在服务器上的应用前端部署 Caddy。Caddy 在 80 和 443 端口接收访客请求,自动获取并续期 TLS 证书,再将请求转发给应用,而应用本身只在本地可访问。

完成本指南后,您的应用将通过 https://app.您的域名.com 响应,HTTP 流量会被重定向到 HTTPS,您也将掌握如何保护管理界面、更新 Caddy 以及备份其数据。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

  • 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
  • 使用具有 sudo 权限的用户进行 SSH 访问
  • 一个由您管理 DNS 区域的域名
  • 一个在本地监听的应用,例如监听 127.0.0.1:3000
  • 没有其他软件占用 80 和 443 端口,例如 Nginx 或 Apache

使用的端口

端口 方向 作用 是否需要开放
80/tcp 入站 HTTP-01 验证以及重定向到 HTTPS 是
443/tcp 入站 HTTPS(HTTP/1.1 和 HTTP/2)以及 TLS-ALPN-01 验证 是
443/udp 入站 HTTP/3 建议开放
2019/tcp 本地 Caddy 管理 API,位于 localhost 否
3000/tcp 本地 示例应用 否

步骤 1:将域名指向服务器

为 app.您的域名.com 创建一条指向 您的服务器IP 的 A 记录。如果您的域名由 HostMyServers 管理,请参阅指南创建 A 记录。

然后在服务器上检查结果:

终端
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.您的域名.com
dig +short AAAA app.您的域名.com

第一条命令应返回您服务器的地址。如果第二条命令返回了 IPv6 地址,它也必须对应这台服务器:证书颁发机构可能会使用该地址来验证域名。否则,请删除该 AAAA 记录。

步骤 2:从官方软件源安装 Caddy

添加 Caddy 项目发布的稳定版软件源,然后安装软件包:

终端
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

该软件包会创建系统用户 caddy,并启动同名服务。请检查安装结果:

终端
caddy version
systemctl status caddy --no-pager

步骤 3:开放防火墙

如果您使用 UFW,请允许 Web 端口:

终端
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status

检查应用在本地是否正常响应:

终端
curl -I http://127.0.0.1:3000

如果应用运行在 Docker 中,请仅将其端口发布到本地回环地址,即 127.0.0.1:3000:3000。以 3000:3000 形式发布的端口仍可从互联网访问,因为 Docker 会插入自己的防火墙规则,而 UFW 不会对其进行过滤。

步骤 4:编写 Caddyfile

保留原有文件的备份,然后打开它:

终端
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.orig
sudo nano /etc/caddy/Caddyfile

将其内容替换为:

caddyfile
{
	email admin@您的域名.com
}

app.您的域名.com {
	encode zstd gzip
	reverse_proxy 127.0.0.1:3000
}
元素 作用
email 与 ACME 账户关联的邮箱,证书出现问题时会用到
app.您的域名.com 公开域名:写入它即会启用自动 HTTPS
encode zstd gzip 压缩响应
reverse_proxy 将请求转发给应用

Caddy 会自行处理从 HTTP 到 HTTPS 的重定向以及 WebSocket 的转发。它还会设置 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host 请求头,并将原始的 Host 传递给 HTTP 应用。

步骤 5:验证并应用配置

终端
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

重新加载不会中断正在进行的连接。如果新配置被拒绝,Caddy 会继续使用之前的配置。

验证结果

查看日志,然后测试两种协议:

终端
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.您的域名.com
curl -I https://app.您的域名.com

HTTP 请求应返回指向 HTTPS 的 308 重定向,HTTPS 请求应返回您应用的响应。日志中应包含 certificate obtained successfully。

接着检查证书的颁发者和有效期,以及正在监听的端口:

终端
echo | openssl s_client -connect app.您的域名.com:443 -servername app.您的域名.com 2>/dev/null | openssl x509 -noout -issuer -dates
sudo ss -tulpn | grep caddy

端口 2019 只应出现在 127.0.0.1 上。从您的电脑访问 http://您的服务器IP:3000 应当没有响应。

发布多个站点

若想每个站点使用一个文件,请创建一个专用文件夹:

终端
sudo mkdir -p /etc/caddy/sites
sudo nano /etc/caddy/sites/app.caddy

将站点配置块放入 /etc/caddy/sites/app.caddy:

caddyfile
app.您的域名.com {
	encode zstd gzip
	reverse_proxy 127.0.0.1:3000
}

文件 /etc/caddy/Caddyfile 现在只保留全局选项和导入语句:

caddyfile
{
	email admin@您的域名.com
}

import sites/*.caddy

请按照步骤 5 的方式再次验证并重新加载。

保护管理界面

管理界面不应对所有人开放。下面的示例叠加了两层保护:只接受您的 IP 地址,然后再要求输入密码。

首先生成密码的哈希值。该命令会要求您输入两次密码,然后显示结果:

终端
caddy hash-password

接着添加下面的站点,并将 BCRYPT_HASH 替换为得到的哈希值:

caddyfile
admin.您的域名.com {
	@allowed client_ip 您的IP

	handle @allowed {
		basic_auth {
			admin BCRYPT_HASH
		}
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

来自其他地址的连接会被直接断开,不返回任何响应。如果您的 IP 地址经常变化,建议改为通过 WireGuard 或 Tailscale 将该界面限定在私有网络中。

常用设置

在多个实例之间分配负载

caddyfile
app.您的域名.com {
	reverse_proxy 127.0.0.1:3001 127.0.0.1:3002 {
		lb_policy round_robin
		health_uri /health
		health_interval 10s
	}
}

您的应用中必须存在 URL /health,并以 2xx 状态码响应。未通过该检查的实例会被剔除,直到恢复正常。

连接使用 HTTPS 的应用

caddyfile
app.您的域名.com {
	reverse_proxy https://127.0.0.1:8443 {
		header_up Host {host}
		transport http {
			tls_server_name backend.您的域名.com
		}
	}
}

Caddy 会验证应用的证书。tls_server_name 必须与该证书中的某个名称一致。自 Caddy 2.11 起,发送给 HTTPS 目标的 Host 默认是目标自身的主机名:对于需要公开域名的应用,header_up Host {host} 可保留公开域名。

将访问日志写入文件

caddyfile
app.您的域名.com {
	log {
		output file /var/log/caddy/app.log
	}
	reverse_proxy 127.0.0.1:3000
}

软件包会为用户 caddy 创建 /var/log/caddy。请将日志保存在该文件夹中,以避免权限错误。

将 Caddy 置于另一个代理之后

如果在 Caddy 之前还有另一个代理接收访客请求,请在全局选项中声明该代理的地址。否则,Caddy 不会采信该代理传来的客户端地址。

caddyfile
{
	email admin@您的域名.com
	servers {
		trusted_proxies static 203.0.113.10/32
	}
}

更新 Caddy

由于 Caddy 是通过软件包安装的,请使用 APT 进行更新:

终端
sudo apt update
sudo apt install --only-upgrade caddy
caddy version
systemctl status caddy --no-pager

请勿在此安装方式下使用 caddy upgrade:这个实验性命令会直接替换由软件包管理的二进制文件。

备份与恢复

需要保留两个位置:

路径 内容
/etc/caddy/ Caddyfile 及导入的文件
/var/lib/caddy/.local/share/caddy/ 证书、私钥和 ACME 账户
终端
sudo tar -czf /root/caddy-$(date +%F).tar.gz /etc/caddy /var/lib/caddy/.local/share/caddy
sudo chmod 600 /root/caddy-$(date +%F).tar.gz

该归档包含私钥:请将其复制到服务器之外的加密位置。数据文件夹不是缓存。保留它可以避免重新申请所有证书,从而不会触及证书颁发机构的限制。

要在已安装 Caddy 的服务器上恢复归档,请将 YYYY-MM-DD 替换为归档的日期:

终端
sudo systemctl stop caddy
sudo tar -xzf /root/caddy-YYYY-MM-DD.tar.gz -C /
sudo chown -R caddy:caddy /var/lib/caddy
sudo systemctl start caddy

故障排除

listen tcp :80: bind: address already in use

另一个服务占用了 80 或 443 端口:

终端
sudo ss -ltnp | grep -E ':(80|443) '

如果不再需要该服务,请将其停止并禁用,例如使用 sudo systemctl disable --now nginx。

urn:ietf:params:acme:error:dns 或 NXDOMAIN

该域名在 DNS 中尚不存在,或传播尚未完成。请使用 dig +short A app.您的域名.com 检查。Caddy 会自行重试:无需反复重启它。

urn:ietf:params:acme:error:unauthorized 或 urn:ietf:params:acme:error:connection

证书颁发机构无法连接到该服务器。请检查 A 和 AAAA 记录,然后检查 80 和 443 端口的防火墙规则。如果服务器上一切正常,但从外部仍无法访问该端口,请通过客户中心联系支持团队。

urn:ietf:params:acme:error:caa

域名的某条 CAA 记录禁止了所使用的证书颁发机构。请将相应的颁发机构加入其中(Let’s Encrypt 对应 letsencrypt.org),或取消该限制。

urn:ietf:params:acme:error:rateLimited

针对该域名发送的请求过多。请等待消息中指明的时间段结束。测试时,请使用 Let’s Encrypt 的测试环境(其证书不被浏览器信任),之后再删除这一行:

caddyfile
{
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

浏览器或 curl 中出现 tlsv1 alert internal error

Caddy 还没有该名称的证书。请在日志中查找原因:

终端
sudo journalctl -u caddy --no-pager -n 100 | grep -iE 'error|acme|challenge'

502 错误与 connect: connection refused

Caddy 无法连接到应用。请检查应用是否在运行,以及是否监听在 reverse_proxy 中指定的地址:

终端
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000

重定向循环

应用在不识别 X-Forwarded-Proto 请求头的情况下强制使用 HTTPS。请在应用中启用“trust proxy”选项或其等效选项。如果域名同时经过 Cloudflare 代理,请将 SSL/TLS 模式设为 Full (strict):Flexible 模式会导致此类循环。

localhost:2019 与重新加载时出现 connection refused

服务已停止,或管理 API 已被禁用。请查看其状态,修复所提示的错误,然后启动它:

终端
systemctl status caddy --no-pager
sudo systemctl start caddy

open /var/log/...: permission denied

Caddy 以用户 caddy 运行,无法在任意位置写入。请将日志写入 /var/log/caddy/。

参考资料