caddy-reverse-proxy

Caddy 反向代理

Caddy 是一款支持自动 HTTPS 的 Web 服务器。它会自动获取和续期证书，将 HTTP 重定向到 HTTPS，并提供简洁的配置语法。

快速参考

任务	语法
基本代理	reverse_proxy backend:8080
多个上游	reverse_proxy node1:80 node2:80
路径路由	handle /api/* { reverse_proxy api:8080 }
剥离路径前缀	handle_path /api/* { reverse_proxy api:8080 }
设置请求标头	header_up Host localhost
移除响应标头	header_down -Server
通配符证书	tls { dns cloudflare {env.CF_API_TOKEN} }
重新加载配置	caddy reload --config /etc/caddy/Caddyfile

基本模式

简单反向代理

example.com {
    reverse_proxy backend:8080
}

多个站点

app.example.com {
    reverse_proxy app:3000
}

api.example.com {
    reverse_proxy api:8080
}

基于路径的路由

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

剥离路径前缀

example.com {
    handle_path /api/* {
        reverse_proxy api:8080  # /api/users → /users
    }
}

标头操作

example.com {
    reverse_proxy backend:8080 {
        # Set Host header (required by some backends)
        header_up Host localhost

        # Add client IP
        header_up X-Real-IP {remote_host}

        # Remove sensitive header
        header_up -Authorization

        # Remove server identity from response
        header_down -Server
    }
}

Docker 集成

代理到容器（同一网络）

# docker-compose.yml
services:
  caddy:
    image: caddy:2-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
    networks:
      - web

  app:
    image: myapp
    networks:
      - web
    expose:
      - "8080"

# Caddyfile - use container name as hostname
example.com {
    reverse_proxy app:8080
}

代理到主机服务

services:
  caddy:
    extra_hosts:
      - "host.docker.internal:host-gateway"

example.com {
    reverse_proxy host.docker.internal:8080
}

TLS 配置

自动配置（默认）

Caddy 会在满足以下条件时自动获取证书：

• 域名 DNS 指向服务器
• 80/443 端口可访问

通配符证书

需要 DNS 提供商插件：

*.example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }

    @app1 host app1.example.com
    handle @app1 {
        reverse_proxy app1:8080
    }

    @app2 host app2.example.com
    handle @app2 {
        reverse_proxy app2:8080
    }
}

内部/开发环境

localhost {
    tls internal
    reverse_proxy app:8080
}

请求匹配器

# Path matching
@api path /api/*

# Header matching
@websocket header Connection *Upgrade*

# Method matching
@post method POST

# Combined (AND logic)
@api_post {
    path /api/*
    method POST
}

# Use matcher
handle @api {
    reverse_proxy api:8080
}

负载均衡

example.com {
    reverse_proxy node1:80 node2:80 node3:80 {
        lb_policy round_robin
        health_uri /health
        health_interval 30s
    }
}

常见配置

安全标头

(security) {
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
    }
}

example.com {
    import security
    reverse_proxy backend:8080
}

www 重定向

www.example.com {
    redir https://example.com{uri} permanent
}

SPA（单页应用）

example.com {
    root * /srv
    try_files {path} /index.html
    file_server
}

gRPC / HTTP/2 明文传输

example.com {
    reverse_proxy h2c://grpc-server:9000
}

全局选项

{
    email [email protected]

    # Use staging for testing
    # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

example.com {
    # site config
}

参考文件

文件	阅读时机
reverse-proxy.md	负载均衡、运行状况检查、传输选项
caddyfile-syntax.md	匹配器、handle 块、指令
tls-certificates.md	DNS 挑战、通配符、mTLS
docker-patterns.md	Docker Compose、网络、主机访问
troubleshooting.md	常见错误和诊断

常见问题

问题	解决方案
"no upstreams available"	检查后端是否正在运行，以及是否处于同一 Docker 网络
"connection refused"	后端应绑定到 0.0.0.0，而不是 127.0.0.1
未获取到证书	检查 DNS 是否指向服务器，以及 80/443 端口是否开放
403 Forbidden	后端需要 header_up Host localhost
WebSocket 失败	通常可以正常工作；对于 SSE，请检查 flush_interval -1

验证命令

# Validate config
caddy validate --config /etc/caddy/Caddyfile

# Format config
caddy fmt --overwrite /etc/caddy/Caddyfile

# Reload (zero-downtime)
caddy reload --config /etc/caddy/Caddyfile

# Debug mode
# Add to global options: { debug }

# Check certificate
openssl s_client -connect example.com:443 -servername example.com

官方文档

主题	URL
Caddyfile	https://caddyserver.com/docs/caddyfile
reverse_proxy	https://caddyserver.com/docs/caddyfile/directives/reverse_proxy
自动 HTTPS	https://caddyserver.com/docs/automatic-https
常见模式	https://caddyserver.com/docs/caddyfile/patterns