Nginx & Caddy 완전 정복 6편 — Caddy 심화: 매처, 지시어 순서, 헬스 체크, Admin API, 플러그인

example.com {
	# 단일 조건은 한 줄로
	@static path *.css *.js *.png *.svg *.woff2
 
	# 여러 조건은 블록으로 (AND)
	@admin_internal {
		path /admin/*
		remote_ip 192.168.0.0/24 10.0.0.0/8
	}
 
	# 부정
	@admin_external {
		path /admin/*
		not remote_ip 192.168.0.0/24 10.0.0.0/8
	}
 
	# 메서드 + 헤더
	@api_write {
		path /api/*
		method POST PUT PATCH DELETE
		header Content-Type application/json*
	}
 
	# 정규식 (캡처 그룹은 {re.이름.1}로 사용)
	@legacy path_regexp legacy ^/old/(\d+)$
	redir @legacy /new/{re.legacy.1} permanent
 
	# CEL 표현식: 가장 강력한 매처
	@mobile expression {header.User-Agent}.contains("Mobile")
 
	header @static Cache-Control "public, max-age=31536000, immutable"
	respond @admin_external 403
	reverse_proxy @admin_internal localhost:9000
	reverse_proxy localhost:3000
}

tracing → map → vars → root → header → copy_response_headers
→ request_body → redir → method → rewrite → uri → try_files → basic_auth
→ forward_auth → request_header → encode → push → intercept → templates
→ handle → handle_path → route → abort → error → copy_response
→ respond → metrics → reverse_proxy → php_fastcgi → file_server → acme_server

example.com {
	file_server
	root * /var/www
	redir /old /new
}

example.com {
	handle /api/* {
		reverse_proxy localhost:8080
	}
	handle /docs/* {
		root * /var/www/docs
		file_server
	}
	handle {                 # 매처 없는 handle = fallback
		reverse_proxy localhost:3000
	}
}

handle_path /api/* {
	reverse_proxy localhost:8080    # /api/users → /users
}

route /special/* {
	header X-Step "1"
	rewrite * /rewritten{uri}
	reverse_proxy localhost:5000
}

{
	order rate_limit before basic_auth
}

(security_headers) {
	header {
		Strict-Transport-Security "max-age=63072000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "strict-origin-when-cross-origin"
		-Server
	}
}
 
(logging) {
	log {
		output file /var/log/caddy/{args[0]}.log {
			roll_size 50MiB
			roll_keep 5
		}
		format json
	}
}
 
app.example.com {
	import security_headers
	import logging app
	reverse_proxy localhost:3000
}
 
admin.example.com {
	import security_headers
	import logging admin
	reverse_proxy localhost:9000
}

api.example.com {
	reverse_proxy {
		to 10.0.0.11:8080 10.0.0.12:8080 10.0.0.13:8080
 
		# 로드 밸런싱
		lb_policy least_conn
		lb_retries 2
		lb_try_duration 5s
		lb_try_interval 250ms
 
		# 액티브 헬스 체크 (오픈소스에 내장!)
		health_uri      /health
		health_interval 10s
		health_timeout  2s
		health_status   2xx
		health_body     "ok"
 
		# 패시브 헬스 체크
		fail_duration     30s
		max_fails         3
		unhealthy_status  5xx
		unhealthy_latency 3s
 
		# 업스트림 연결 설정
		transport http {
			dial_timeout 3s
			response_header_timeout 30s
			keepalive 90s
			keepalive_idle_conns 64
		}
	}
}

reverse_proxy {
	dynamic a app.internal 8080 {
		refresh 10s
	}
	# 또는 SRV 레코드: dynamic srv _http._tcp.app.service.consul
	lb_policy least_conn
	health_uri /health
}

{
	servers {
		trusted_proxies static 173.245.48.0/20 103.21.244.0/22
		# 또는 사설 대역 전체: trusted_proxies static private_ranges
		client_ip_headers CF-Connecting-IP X-Forwarded-For
	}
}

xcaddy build --with github.com/caddy-dns/cloudflare

*.example.com, example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}
 
	@app host app.example.com
	handle @app {
		reverse_proxy localhost:3000
	}
 
	@grafana host grafana.example.com
	handle @grafana {
		reverse_proxy localhost:3001
	}
 
	handle {
		abort
	}
}

{
	on_demand_tls {
		ask http://localhost:5555/domain-check
	}
}
 
https:// {
	tls {
		on_demand
	}
	reverse_proxy localhost:3000
}

internal-api.example.com {
	tls {
		protocols tls1.3
		client_auth {
			mode require_and_verify
			trust_pool file /etc/caddy/ca/clients-ca.pem
		}
	}
	reverse_proxy localhost:8443
}

# CA 역할 서버
ca.internal {
	tls internal
	acme_server
}
 
# 다른 서버의 Caddyfile
app.internal {
	tls {
		ca https://ca.internal/acme/local/directory
		# CA 서버는 tls internal(자체 루트)로 서빙한다. CA 서버의 데이터 디렉터리에 있는
		# pki/authorities/local/root.crt를 복사해 두고 신뢰시켜야 발급이 된다
		ca_root /etc/caddy/ca-internal-root.crt
	}
	reverse_proxy localhost:8080
}

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
 
xcaddy build \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/mholt/caddy-ratelimit \
  --with github.com/mholt/caddy-l4
 
./caddy list-modules | grep -E "dns|rate|layer4"

FROM caddy:2-builder AS builder
RUN xcaddy build \
    --with github.com/caddy-dns/cloudflare \
    --with github.com/mholt/caddy-ratelimit
 
FROM caddy:2
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

{
	order rate_limit before basic_auth
}
 
api.example.com {
	rate_limit {
		zone per_ip {
			key    {client_ip}
			events 100
			window 1m
		}
	}
	reverse_proxy localhost:8080
}

caddy adapt --config Caddyfile --pretty

example.com {
	reverse_proxy localhost:3000
}

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [{ "host": ["example.com"] }],
              "handle": [
                {
                  "handler": "subroute",
                  "routes": [
                    {
                      "handle": [
                        {
                          "handler": "reverse_proxy",
                          "upstreams": [{ "dial": "localhost:3000" }]
                        }
                      ]
                    }
                  ]
                }
              ],
              "terminal": true
            }
          ]
        }
      }
    }
  }
}

# 현재 설정 조회
curl localhost:2019/config/ | jq
 
# 특정 경로만 조회
curl localhost:2019/config/apps/http/servers/srv0/routes
 
# 전체 설정 교체 (무중단)
curl localhost:2019/load \
  -H "Content-Type: application/json" \
  -d @caddy.json
 
# Caddyfile을 그대로 로드
curl localhost:2019/load \
  -H "Content-Type: text/caddyfile" \
  --data-binary @Caddyfile
 
# 업스트림 상태 확인
curl localhost:2019/reverse_proxy/upstreams | jq

{
	metrics {
		per_host
	}
}
 
:2020 {
	metrics /metrics
}

log {
	output file /var/log/caddy/access.log
	format filter {
		request>headers>Authorization delete
		request>headers>Cookie delete
		request>remote_ip ip_mask {
			ipv4 24
			ipv6 32
		}
	}
}

{
	servers {
		timeouts {
			read_body   30s
			read_header 10s
			write       60s
			idle        5m
		}
		max_header_size 16KB
		protocols h1 h2 h3
	}
}
 
example.com {
	request_body {
		max_size 10MB        # Nginx client_max_body_size
	}
	reverse_proxy localhost:3000 {
		flush_interval -1    # SSE/스트리밍: 즉시 플러시 (Nginx proxy_buffering off)
	}
}