Caddy 安装与配置指南

Caddy 是一个强大的、用 Go 语言编写的现代 Web 服务器。它最大的特点是 默认启用自动 HTTPS（通过 Let's Encrypt 自动申请和续期证书），并且配置文件（Caddyfile）极其简洁易读。

HTTPS

Caddy 安装

Linux (Debian / Ubuntu / Raspberry Pi)

安装必要的依赖并添加官方密钥：

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

检查状态：

systemctl status caddy

Linux (CentOS / RHEL / Fedora)

sudo yum install yum-plugin-copr
sudo yum copr enable @caddy/caddy
sudo yum install caddy

Windows

1. 前往 Caddy 官方下载页 下载 Windows 版可执行文件（.exe）。
2. 将下载的文件重命名为 caddy.exe 并放置在合适的目录（如 C:\caddy）。
3. 在该目录下打开 PowerShell 或 CMD 运行。

Caddy 常用命令

命令	说明
caddy run	在前台运行 Caddy
caddy start	在后台启动 Caddy
caddy stop	停止运行中的 Caddy
caddy reload	重载配置文件（需在配置文件所在目录运行）
caddy fmt --overwrite	格式化 Caddyfile 并覆盖保存

Caddyfile 配置示例

Caddy 的默认配置文件通常位于 /etc/caddy/Caddyfile。

1. 极简静态网站

如果只在本地测试，一行配置即可：

:8080

file_server

这将在 8080 端口启动一个静态文件服务器，根目录为当前运行目录。

2. 生产环境静态站 (自动 HTTPS)

example.com {
    root * /var/www/html
    file_server
}

• 注意：替换 example.com 为你真实的域名，并确保域名解析到了服务器 IP。Caddy 会自动申请 SSL 证书并开启 HTTPS。

3. 反向代理

将流量转发给后端服务（如 3000 端口）：

api.example.com {
    reverse_proxy localhost:3000
}

就是这么简单！Caddy 会自动处理 HTTPS、Header 转发等。

4. 常见指令组合

example.com {
    # 开启 gzip 压缩
    encode gzip

    # 静态文件服务
    root * /var/www/my-site
    file_server

    # 将 /api/* 转发给后端
    handle /api/* {
        reverse_proxy localhost:8000
    }

    # 自定义日志
    log {
        output file /var/log/caddy/access.log
    }
}

进阶配置

1. 负载均衡 (Load Balancing)

Caddy 原生支持多种负载均衡策略。

backend.example.com {
    reverse_proxy {
        # 定义上游服务器列表
        to 10.0.0.1:80 10.0.0.2:80 10.0.0.3:80

        # 策略：least_conn (最少连接), round_robin (轮询,默认), ip_hash (IP哈希)
        lb_policy least_conn

        # 健康检查
        health_uri /healthz
        health_interval 5s
    }
}

2. 路径处理 (Path Handling)

在反向代理时，处理 URL 前缀常常让人头疼。Caddy 提供了优雅的解决方案。

场景：访问 example.com/api/v1/users，后端期望收到 /v1/users（保留 /api）。

example.com {
    handle /api/* {
        reverse_proxy localhost:8080
    }
}

场景：访问 example.com/api/v1/users，后端期望收到 /users（去除 /api/v1）。 使用 handle_path 指令会自动剥离匹配的前缀：

example.com {
    handle_path /api/v1/* {
        reverse_proxy localhost:8080
    }
}

3. 简单的访问鉴权 (Basic Auth)

保护敏感页面，快速添加账号密码认证。

首先生成哈希密码：

caddy hash-password --plaintext "mypassword"
# 输出类似: $2a$14$P...

在配置中使用：

admin.example.com {
    basicauth /* {
        # 用户名 哈希密码
        admin $2a$14$P...
    }
    
    file_server
}

4. 运行 PHP 应用 (如 WordPress)

Caddy 内置了针对 PHP 的优化指令 php_fastcgi。

example.com {
    root * /var/www/wordpress
    encode gzip
    
    # 转发给 php-fpm 服务
    php_fastcgi unix//run/php/php8.1-fpm.sock
    
    file_server
}

5. Docker 部署 (推荐)

使用 Docker 部署 Caddy 非常方便，支持配置持久化。

# docker-compose.yml
version: "3"
services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

• 注意：必须持久化 /data 目录，否则容器重启后 Caddy 会重新申请证书，可能触发 Let's Encrypt 的速率限制。