轻量级 Web 服务器 Caddy 使用指南

Caddy 是一个用 Go 语言编写的开源 Web 服务器，以"配置极简、自动 HTTPS"闻名。如果你厌倦了 Nginx 繁琐的配置和手动续签证书，Caddy 值得一试。

为什么选择 Caddy？

一句话总结：Caddy 是最省心的 Web 服务器，没有之一。

一、安装 Caddy

方式 1：直接下载二进制（推荐）

# 下载最新版本
curl -fsSL https://github.com/caddyserver/caddy/releases/latest/download/caddy_linux_amd64 -o caddy

# 赋予执行权限
chmod +x caddy

# 移动到系统路径
sudo mv caddy /usr/local/bin/

# 验证安装
caddy version

方式 2：包管理器安装

# Ubuntu / Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
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

方式 3：Docker 运行

docker run -d \
  --name caddy \
  -p 80:80 \
  -p 443:443 \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  -v $PWD/site:/srv \
  caddy

二、第一个 Caddyfile

Caddy 的配置文件叫 Caddyfile，语法非常直观。在项目根目录创建一个 Caddyfile：

localhost {
    respond "Hello, Caddy!"
}

启动：

caddy run

浏览器打开 http://localhost，就能看到 Hello, Caddy!。

就这么两行配置，一个 Web 服务器就跑起来了。

三、静态文件托管

最常见的场景——托管一个静态网站（比如博客、文档站）：

localhost:8080 {
    root * /srv/mysite
    file_server
}

• root * /srv/mysite：指定网站根目录
• file_server：启用静态文件服务

把你的 HTML 文件放到 /srv/mysite 目录下，访问 http://localhost:8080 即可。

启用目录浏览

localhost:8080 {
    root * /srv/mysite
    file_server browse
}

加上 browse 参数，访问目录时会显示文件列表，适合做文件下载站。

四、反向代理

Caddy 做反向代理同样简单。假设后端服务跑在 127.0.0.1:3000：

localhost {
    reverse_proxy 127.0.0.1:3000
}

多后端负载均衡

localhost {
    reverse_proxy 127.0.0.1:3000 127.0.0.1:3001 127.0.0.1:3002
}

Caddy 会自动在三个后端之间做轮询负载均衡。

按路径分流

example.com {
    # /api/* 转发到后端 API 服务
    handle /api/* {
        reverse_proxy 127.0.0.1:8080
    }

    # 其他请求托管静态文件
    handle {
        root * /srv/frontend
        file_server
    }
}

五、自动 HTTPS（Caddy 的杀手锏）

只要你的域名真实解析到了服务器，把 localhost 换成域名即可：

mywebsite.com {
    root * /srv/mysite
    file_server
}

启动后 Caddy 会自动：

1. 向 Let’s Encrypt / ZeroSSL 申请证书
2. 配置 HTTPS（监听 443 端口）
3. 自动把 HTTP 请求重定向到 HTTPS
4. 证书过期前自动续签

你不需要做任何额外配置，证书的事 Caddy 全包了。

⚠️ 注意：自动 HTTPS 需要服务器的 80 和 443 端口对外开放，且域名 A 记录已正确指向服务器 IP。

六、常用功能速查

1. 自定义错误页面

example.com {
    root * /srv/mysite
    file_server
    handle_errors {
        respond "出错了，请稍后再试" 500
    }
}

2. 开启 gzip 压缩

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

3. 设置响应头

example.com {
    header {
        Cache-Control "max-age=86400"
        X-Frame-Options "DENY"
    }
    root * /srv/mysite
    file_server
}

4. URL 重写

example.com {
    rewrite /old-path /new-path
    root * /srv/mysite
    file_server
}

5. 访问日志

example.com {
    log {
        output file /var/log/caddy/access.log
        format json
    }
    root * /srv/mysite
    file_server
}

6. 基础认证（Basic Auth）

example.com {
    basicauth {
        admin $2a$14$Zkx...  # 用 caddy hash-password 生成
    }
    root * /srv/mysite
    file_server
}

生成密码哈希：

caddy hash-password --plaintext "your-password"

七、作为系统服务运行

systemd 方式

创建 /etc/systemd/system/caddy.service：

[Unit]
Description=Caddy Web Server
After=network.target

[Service]
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

管理命令：

sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

Caddy 自带 API 管理

Caddy 运行后会在 localhost:2019 暴露管理 API：

# 查看当前配置
curl localhost:2019/config/

# 动态加载新配置（无需重启）
curl localhost:2019/load \
  -X POST \
  -H "Content-Type: application/json" \
  -d @caddy.json

八、完整实战示例

一个贴近真实场景的配置——前端静态站 + 后端 API + 日志 + 压缩 + 安全头：

example.com {
    # 日志
    log {
        output file /var/log/caddy/access.log
        format json
    }

    # 压缩
    encode gzip zstd

    # 安全响应头
    header {
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        Strict-Transport-Security "max-age=31536000"
    }

    # API 请求转发到后端
    handle /api/* {
        reverse_proxy 127.0.0.1:8080 {
            header_up X-Real-IP {remote_host}
        }
    }

    # 其他请求托管前端
    handle {
        root * /srv/frontend/dist
        try_files {path} /index.html
        file_server
    }
}

try_files {path} /index.html 这行是 SPA（单页应用）的标配——所有找不到的路径都回退到 index.html，交给前端路由处理。

小结

Caddy 的设计哲学是 “合理的默认值 + 极简的配置”。大部分场景下，几行 Caddyfile 就能搞定 Nginx 需要一大段配置才能完成的工作。如果你在做一个个人项目、小型网站或者需要快速搭建原型，Caddy 是非常理想的选择。

本文写于 2026 年 11 月，Caddy v2 版本。