Caddy：默认自动 HTTPS 的可扩展 Web 服务器部署使用指南

Caddy 是一个可扩展的服务器平台，默认启用 TLS（HTTPS），口号是 "Every site on HTTPS"。它是历史上第一个默认自动使用 HTTPS 的 Web 服务器，由 Go 编写，无外部依赖（甚至不依赖 libc），支持 HTTP/1.1、HTTP/2 和 HTTP/3，生产环境已服务过数万亿次请求、管理数百万张 TLS 证书。

一、项目官方信息

Caddy 的核心特性：易用的 Caddyfile 配置、强大的原生 JSON 配置、可通过 JSON API 动态改配置、自动 HTTPS（公网域名用 ZeroSSL 和 Let's Encrypt，内网域名/IP 用自管理本地 CA）、多签发者故障转移、ECH 支持、模块化架构可高度扩展、单二进制随处运行。

二、官方图片

下图是 Caddy 项目 README 顶部的官方 Logo：

三、环境要求

• 操作系统：Linux（Debian/Ubuntu/CentOS 等）、macOS、Windows，单二进制无外部依赖。
• 预编译安装：无需任何运行时依赖，直接下载可执行文件。
• 从源码编译：需要 Go 1.26.0 或更新版本。
• 端口：80（HTTP）和 443（HTTPS）需要放行；Caddy 会自动申请并续期证书，因此域名必须已解析到本机。
• 绑定 80/443 低端口时，在 Linux 上可用 setcap 赋予二进制权限而不必用 root。

四、完整部署步骤

1. 下载官方预编译二进制（最简单）

从 GitHub Releases 页面下载对应平台的可执行文件，放到 PATH 目录即可：

# 查看最新版本
# https://github.com/caddyserver/caddy/releases
chmod +x caddy
sudo mv caddy /usr/local/bin/
caddy version

其他发行版安装方式（apt/dnf 等）见官方文档 https://caddyserver.com/docs/install 。以 Debian/Ubuntu 官方仓库为例：

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
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 apt update
sudo apt install caddy

安装后 Caddy 会作为 systemd 服务自动运行。

2. 从源码编译

需要 Go 1.26.0+：

git clone "https://github.com/caddyserver/caddy.git"
cd caddy/cmd/caddy/
go build

在 Linux 上允许新二进制绑定低端口（80/443）：

sudo setcap cap_net_bind_service=+ep ./caddy

如果用 go run（只产生临时二进制），可使用自带的脚本：

go run -exec ./setcap.sh main.go

运行测试：

go test ./...
go test ./modules/caddyhttp/tracing/

3. 带版本信息和/或插件编译（xcaddy）

官方推荐用 xcaddy 构建器：

xcaddy build

它会自动完成：新建 caddy 目录、放入 main.go、初始化 Go module、按需固定版本、引入插件、编译。手动等价步骤为：

mkdir caddy && cd caddy
# 把 cmd/caddy/main.go 拷进来，按需 import 插件
go mod init caddy
go get github.com/caddyserver/caddy/v2@<version>
# 如需插件，加 import：_ "import/path/here"
go build -tags=nobadger,nomysql,nopgx

4. 写第一个 Caddyfile

在工作目录新建 Caddyfile，最简静态站点示例：

example.com {
    root * /srv/www
    file_server
    encode zstd gzip
}

把 example.com 换成你已解析到本机的域名。Caddy 会自动向 Let's Encrypt/ZeroSSL 申请证书并开启 HTTPS，无需任何额外配置。

5. 启动与验证

# 前台启动
caddy run

# 或以服务方式（apt 安装后）
sudo systemctl status caddy
sudo systemctl reload caddy

打开浏览器访问 https://example.com，Caddy 已自动签发并部署了 HTTPS 证书。验证配置：

caddy validate --adapter caddyfile --config Caddyfile

五、使用方法

配置方式

• Caddyfile：人读友好的简洁配置（见上例）。
• 原生 JSON：Caddy 的原生配置语言，可精确控制内存中各类型的实际值。
• 配置适配器（config adapters）：把 Caddyfile、YAML、TOML、NGINX 配置等自动转成 JSON。
• JSON API：主要的动态配置方式，可在线热更新而不重启。

反向代理到后端服务

在 Caddyfile 中反代到本地应用：

api.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy 同样会自动为 api.example.com 申请 HTTPS 证书。

常用命令

caddy run                # 前台运行
caddy start              # 后台运行
caddy stop               # 停止后台实例
caddy reload --config Caddyfile   # 热重载
caddy validate --config Caddyfile # 校验配置
caddy list-modules       # 列出已编译模块

自动 HTTPS 行为

公网域名自动通过 ZeroSSL / Let's Encrypt 签发并续期；内网域名或 IP 则使用 Caddy 自管理的本地 CA；多实例集群间可协调；支持多签发者故障转移——这也是 Caddy"在其他服务器因 TLS/OCSP/证书问题宕机时仍能保持在线"的原因。

六、常见问题 FAQ

1. 为什么访问域名没有自动变成 HTTPS？ 自动 HTTPS 的前提是域名已正确解析到运行 Caddy 的服务器，且 80/443 端口对外可达。先确认 DNS 解析和防火墙放行，Caddy 会在首次请求时自动完成 ACME 验证。

2. 一定要用 root 启动吗？ 不必。Linux 上给二进制 setcap 即可绑定低端口：sudo setcap cap_net_bind_service=+ep /usr/local/bin/caddy。apt 安装的版本已配置好 systemd 服务，直接用服务管理。

3. 如何加第三方插件？ 官方预编译二进制不含插件，需要用 xcaddy build --with <插件包名> 自行编译。详见 https://github.com/caddyserver/xcaddy 。

4. Caddy 和 Nginx 配置能混用吗？ Caddy 提供配置适配器，可以把 NGINX 配置转换为 Caddy JSON，但不是所有指令都等价，复杂配置仍建议直接用 Caddyfile 重写。

5. 如何改配置不重启？ 两种方式：改完 Caddyfile 后执行 caddy reload --config Caddyfile（平滑重载），或直接调用 Caddy 的 JSON API 在线热更新，后者无需落盘。

6. 内网/IP 访问也能 HTTPS 吗？ 可以。Caddy 对非公网名称或 IP 会自动使用自管理本地 CA 签发证书，浏览器需信任该本地 CA；生产公网站点则走 Let's Encrypt / ZeroSSL。

七、跳转链接

• GitHub 仓库：https://github.com/caddyserver/caddy
• 官方网站与文档：https://caddyserver.com/docs/
• 下载 Releases：https://github.com/caddyserver/caddy/releases
• 社区论坛：https://caddy.community