Caddy操作指南

• Caddy (opens new window) 是一款现代化、自动化、简洁的Web服务器。
• 支持自动TLS证书管理、反向代理、静态文件服务等。

基础命令

检查配置文件

caddy validate --config /path/to/Caddyfile

提示

如果不带--config参数，默认加载当前目录下Caddyfile,否则加载系统默认路径。

操作系统	默认（相对安装路径）
Linux	caddy/Caddyfile
Windows	Caddy/Caddyfile
macOS	caddy/Caddyfile

前台启动

caddy run

作为服务启动

caddy start

重新加载配置

caddy reload --config /path/to/Caddyfile

docker-compose 安装

version: '3.8'
services:
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config
    networks:
      - prod # 指定网络


networks:
  prod:
    external: true # 使用现有网络

Caddyfile

最简单示例

:80 {
    #代理到8080
    reverse_proxy localhost:8080
}

反代多个站点（基于子域）

a.example.com {
    reverse_proxy localhost:5244
}

b.example.com {
    reverse_proxy localhost:8080
}

c.example.com {
    reverse_proxy localhost:9000
}

自动HTTPS（使用域名）

首先需要一个正常解析到IP的域名吗，这是必要条件

example.com {
    tls you@example.com #通知邮箱
    #代理到8080
    reverse_proxy localhost:8080
}

上面示例：HTTP会强制调整HTTPS （使用默认 80 → 443）

自签证书（无域名）

生成自签名证书

openssl req -x509 -newkey rsa:2048 -nodes -keyout /etc/caddy/ssl/key.pem  -out /etc/caddy/ssl/cert.pem -days 365 -subj "/CN=your.ip.address"

:8443 {
    tls /etc/caddy/ssl/cert.pem /etc/caddy/ssl/key.pem
    reverse_proxy localhost:8080
}

HTTP → HTTPS 手动跳转（特殊端口）

example.com:8080 {
    redir https://example.com:8443{uri}
}

example.com:8443 {
    tls you@example.com
    reverse_proxy localhost:5244
}

启用静态文件服务

example.com {
    # * 匹配所以请求
    # 静态资源存放目录
    root * /path/to/your/files
    file_server
}

路由控制

example.com {
    redir /old-url /new-url 301

    handle_path /blog/* {
        reverse_proxy localhost:8080
    }

    handle_path /api/* {
        reverse_proxy localhost:5000
    }

    handle * {
        root * /var/www/html
        file_server
    }
}

启用压缩和跨域

example.com {
    encode gzip
    header {
        Access-Control-Allow-Origin "*"
        X-Content-Type-Options "nosniff"
    }
    reverse_proxy localhost:5244
}

基础认证（HTTP Basic Auth）

example.com {
    route {
        basicauth / admin JDJhJDEyJHZiRzZwbjdVZUl4U0ZBQnM3L3lZZVJ4RnVaZlFlZ29IZUtIM0hoR0FZME1XNGRtd01yCnY2Vjhi
        reverse_proxy localhost:5244
    }
}

可用caddy hash-password 生成hash密码

限制正文大小

配置全局

{
    # 全局配置（可选）
    # 限制所有请求的最大请求体大小
    # 例如，限制请求体至10MB
    request_body {
        max_size 10MB
    }
}

配置站点

example.com {
    request_body {
        max_size 5MB
    }
    # 其他配置，比如反向代理或文件服务
    reverse_proxy localhost:8080
}

超出限制处理

example.com {
    # 范围：限制请求体最大为10MB
    @limit {
        request_body {
            max_size 10MB
        }
    }
    handle @limit {
        # 拒绝超出限制的请求
        respond "Payload Too Large" 413
    }
    reverse_proxy localhost:8080
}

基于匹配条件的限制

example.com {
    @large_body {
        header Content-Length * # 只限制具有Content-Length的请求
    }
    handle @large_body {
        request_body {
            max_size 20MB
        }
        # 后续中间件或响应
        reverse_proxy localhost:8080
    }

    # 对非匹配的请求继续处理
    handle {
        reverse_proxy localhost:8080
    }
}

tls属性示例

tls <email> {
    ca <acme-server-url>
    dns <provider>
    on_demand
    resolvers <ip>...
    ask <url>
    alpn <proto>...
    protocols <version>...
    client_auth {
        mode <request|require|verify_if_given|require_and_verify>
        trusted_ca_cert_file <path>
        trusted_ca_cert_files <paths...>
    }
    cert_file <path/to/cert.pem>
    key_file <path/to/key.pem>
}

字段说明

配置项	描述
tls you@example.com	指定邮箱（用于 Let's Encrypt 注册）
ca	自定义 ACME CA（比如 Let's Encrypt 以外的）
dns	启用 DNS 认证（需要 Caddy 插件）
on_demand	启用按需证书（首次访问时申请）
resolvers	自定义 DNS 解析器（默认用系统）
ask	访问特定 URL 判断是否允许发证书
alpn	限制允许的 ALPN 协议（HTTP/2, h3 等）
protocols	限制支持的 TLS 版本（如 tls1.2 tls1.3）
client_auth	启用客户端证书认证（双向 TLS）
cert_file / key_file	手动指定证书和私钥（跳过 ACME）