反向代理之 Caddy

Caddy 是一个强大的、开源的、自动启用 HTTPS 的 Web 服务器，以其简单的配置和现代特性而闻名

一、核心特性

自动 HTTPS： Caddy 的杀手级功能。它会自动为你的域名申请并续签 TLS 证书（来自 Let's Encrypt），无需任何手动配置。

简洁的配置：使用 Caddyfile 格式，语法清晰易懂，远胜于 Nginx/Apache 的复杂性。

基于 Go 语言编写：单二进制文件，无需外部依赖，部署简单，性能优异。

强大的扩展性：通过插件系统可以扩展大量功能（如缓存、认证、日志格式等）。

支持现代协议：原生支持 HTTP/1.1, HTTP/2, 以及 HTTP/3 (QUIC)。

反向代理与负载均衡：轻松配置为后端服务的反向代理。

二、安装与运行

官方网站： https://caddyserver.com/


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
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# 安装后，Caddy 会作为 systemd 服务自动运行
sudo systemctl status caddy

基本命令：


caddy start      # 启动守护进程
caddy stop       # 停止守护进程
caddy reload     # 重新加载配置（不断开现有连接）
caddy run        # 在前台运行（推荐开发调试使用）
caddy version    # 查看版本
caddy adapt      # 验证 Caddyfile 语法是否正确

三、核心概念：Caddyfile

Caddyfile 是 Caddy 的主要配置文件，通常位于 /etc/caddy/Caddyfile（通过包管理器安装）或当前目录。

一个基本的 Caddyfile 结构如下：


<TEXT>
[地址] {
    [指令] [参数]
}

1. 静态文件服务器

这是最简单的用法，将域名指向一个本地文件夹。


<TEXT>
# 示例：托管位于 /var/www/html 的静态网站
mywebsite.com, www.mywebsite.com { # 定义站点地址，多个用逗号隔开
    root * /var/www/html           # * 是匹配所有路径，根目录设置为 /var/www/html
    file_server                    # 启用文件服务器功能
}

运行：


sudo caddy run

或


sudo systemctl reload caddy

访问


https://mywebsite.com

，HTTPS 已经自动配置好了！

2. 反向代理

将请求转发到后端应用服务器（如 Node.js, Python, Java 应用）。


<TEXT>
api.example.com {
    reverse_proxy /api/* http://localhost:3000 {
        # 可选：传输一些原始请求信息
        header_up Host {host}
        header_up X-Real-IP {remote_host}
    }
}
# 更简单的写法，匹配所有路径
backend.internal {
    reverse_proxy http://localhost:8080
}
# 代理到多个后端，实现负载均衡
reverse_proxy /node/* http://localhost:3000 http://localhost:3001 {
    lb_policy first
}

3. 路径路由（Path Routing）

根据不同路径前缀将请求分发到不同的后端或本地目录。


<TEXT>
example.com {
    # 根路径服务静态文件
    root * /var/www/static
    file_server
    # 以 /api 开头的请求代理到后端
    handle_path /api/* {
        reverse_proxy http://localhost:8000
    }
    # 以 /blog 开头的请求代理到另一个服务
    handle_path /blog/* {
        reverse_proxy http://localhost:2368
    }
}

4. 重写与重定向


<TEXT>
example.com {
    # 永久重定向（301）
    redir /old-url https://other-site.com/new-url permanent
    # 临时重定向（302）
    redir /temp-offer https://example.com/sale temporary
    # URL 重写（内部转发，浏览器地址不变）
    rewrite /pretty-url /actual-file.html
    # 强制 HTTPS（www 重定向也很常见，但 Caddy 通常自动处理）
    # https://example.com 和 http://example.com 都会自动服务 HTTPS
}

四、常见实用配置片段

1. 启用压缩


<TEXT>
encode gzip zstd

2. 自定义日志格式


<TEXT>
log {
    output file /var/log/caddy/access.log
    format json {
        time RFC3339
        id {request_id}
    }
}

3. 基本的访问限制


<TEXT>
# 基于 IP 的限制
@blocked_ips {
    not remote_ip 192.168.1.0/24
}
respond @blocked_ips "Access Denied" 403
# 密码认证（保护某个路径）
/browse/* {
    basicauth /browse/* {
        user1 JDJhJDEwJGE... # 密码使用 `caddy hash-password` 命令生成
    }
    file_server browse # 甚至允许目录浏览
}

4. 自定义错误页面


<TEXT>
handle_errors {
    @404 status 404
    handle @404 {
        rewrite * /404.html
        file_server
    }
}

5. 为 PHP 应用配置（通过 FastCGI）


<TEXT>
php.example.com {
    root * /var/www/php-app
    php_fastcgi unix//var/run/php/php8.2-fpm.sock # 连接到 PHP-FPM
    file_server
}

五、全局配置与进阶

你可以在 Caddyfile 顶部使用全局选项块 { ... } 来设置全局配置。


<TEXT>
{
    # 自定义 ACME CA（证书颁发机构），默认是 Let's Encrypt
    # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
    # 邮箱用于申请证书（可选，但推荐）
    email your-email@example.com
    # 日志级别
    log {
        level ERROR
    }
    # 自动 HTTPS 行为（内部接口不申请证书）
    auto_https disable_redirects
    on_demand_tls {
        ask http://localhost:9000/ask
    }
}
# 你的站点配置从这里开始
example.com {
    ...
}

六、API 配置（动态配置）

除了静态的 Caddyfile，Caddy 还提供了强大的 JSON API 用于动态加载和管理配置。这是更现代和灵活的方式，尤其适合集成到自动化工具中。

基本用法：

启动 Caddy：caddy run --config /path/to/config.json --adapter caddyfile

或通过 API 发送 POST 请求来加载配置。

总结：快速入门清单

安装：通过包管理器或下载二进制文件安装 Caddy。

创建 Caddyfile：在 /etc/caddy/Caddyfile 或当前目录创建配置文件。

编写配置：从最简单的静态文件服务或反向代理开始。

运行：使用 caddy run（前台）或 caddy start（后台）启动。

测试：用浏览器访问你的域名，观察神奇的自动 HTTPS。

重载：修改配置后，使用 caddy reload 应用更改。

Caddy 的哲学是“默认安全，简单易用”。对于大多数常见 Web 服务需求，一份简短清晰的 Caddyfile 就足够了，无需再为 SSL 证书和复杂的配置语法烦恼。

反向代理 之 Caddy