使用 Caddy 反向代理并自动启用 HTTPS
从官方软件源在 Debian 或 Ubuntu 上安装 Caddy,以自动 HTTPS 发布应用,保护管理界面,并完成更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何在服务器上的应用前端部署 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将其内容替换为:
{
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.您的域名.comHTTP 请求应返回指向 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:
app.您的域名.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}文件 /etc/caddy/Caddyfile 现在只保留全局选项和导入语句:
{
email admin@您的域名.com
}
import sites/*.caddy请按照步骤 5 的方式再次验证并重新加载。
保护管理界面
管理界面不应对所有人开放。下面的示例叠加了两层保护:只接受您的 IP 地址,然后再要求输入密码。
首先生成密码的哈希值。该命令会要求您输入两次密码,然后显示结果:
caddy hash-password接着添加下面的站点,并将 BCRYPT_HASH 替换为得到的哈希值:
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 将该界面限定在私有网络中。
常用设置
在多个实例之间分配负载
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 的应用
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} 可保留公开域名。
将访问日志写入文件
app.您的域名.com {
log {
output file /var/log/caddy/app.log
}
reverse_proxy 127.0.0.1:3000
}软件包会为用户 caddy 创建 /var/log/caddy。请将日志保存在该文件夹中,以避免权限错误。
将 Caddy 置于另一个代理之后
如果在 Caddy 之前还有另一个代理接收访客请求,请在全局选项中声明该代理的地址。否则,Caddy 不会采信该代理传来的客户端地址。
{
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 的测试环境(其证书不被浏览器信任),之后再删除这一行:
{
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 caddyopen /var/log/...: permission denied
Caddy 以用户 caddy 运行,无法在任意位置写入。请将日志写入 /var/log/caddy/。