caddy-reverse-proxy（球童反向 Agent）

Caddy Reverse Proxy

Caddy is a web server with automatic HTTPS. It obtains and renews certificates automatically, redirects HTTP to HTTPS, and provides a simple configuration syntax.

Quick Reference

Basic Patterns

Simple Reverse Proxy

example.com {
    reverse_proxy backend:8080
}

Multiple Sites

app.example.com {
    reverse_proxy app:3000
}

api.example.com {
    reverse_proxy api:8080
}

Path-Based Routing

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

Strip Path Prefix

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

Header Manipulation

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 Integration

Proxy to Container (Same Network)

# 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
}

Proxy to Host Service

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

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

TLS Configuration

Automatic (Default)

Caddy automatically obtains certificates when:

• Domain DNS points to server
• Ports 80/443 accessible

Wildcard Certificates

Requires DNS provider plugin:

*.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
    }
}

Internal/Development

localhost {
    tls internal
    reverse_proxy app:8080
}

Request Matchers

# 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
}

Load Balancing

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

Common Configurations

Security Headers

(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 Redirect

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

SPA (Single Page App)

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

gRPC / HTTP/2 Cleartext

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

Global Options

{
    email admin@example.com

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

example.com {
    # site config
}

Reference Files

Common Issues

Verification Commands

# 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

Official Documentation