NPV-AM

Caddyfile: шаблоны и паттерны

Caddyfile — декларативный язык конфигурации для Caddy. Он проще, чем nginx.conf, но при этом offers гибкие возможности. Рассмотрим основные паттерны использования.

Reverse proxy

Базовый обратный прокси — самая частая задача Caddy:

# Простой reverse proxy
example.com {
    reverse_proxy localhost:8080
}

# Балансировка между несколькими бэкендами
api.example.com {
    reverse_proxy localhost:8080 localhost:8081 localhost:8082 {
        lb_policy round_robin
        health_uri /health
        health_interval 10s
    }
}

# С заголовками
example.com {
    reverse_proxy localhost:8080 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

Rate limiting

Caddy поддерживает rate limiting через плагин или встроенную функциональность:

# Rate limiting через плагин
example.com {
    rate_limit {
        zone api_zone {
            key {remote_host}
            events 100
            window 1m
        }
    }

    reverse_proxy localhost:8080
}

# Более сложный пример
api.example.com {
    rate_limit {
        zone login_zone {
            key {remote_host}
            events 5
            window 1m
        }
        zone api_zone {
            key {remote_host}
            events 1000
            window 1h
        }
    }
}

Basic auth

# Простая аутентификация
admin.example.com {
    basicauth * {
        admin $2a$14$hashed_password_here
    }

    reverse_proxy localhost:8080
}

# Генерация хеша
# caddy hash-password --plaintext mypassword

Request matching

# По пути
example.com {
    /api/* {
        reverse_proxy localhost:8080
    }
    /static/* {
        root * /var/www/static
        file_server
    }
}

# По методу
example.com {
    @post {
        method POST PUT DELETE
    }
    @post {
        reverse_proxy localhost:8080
    }
}

# По заголовкам
example.com {
    @json {
        header Content-Type application/json
    }
    handle @json {
        reverse_proxy localhost:8080
    }
}

# По query параметрам
example.com {
    @debug {
        query debug=true
    }
    handle @debug {
        reverse_proxy localhost:8080
        log {
            output file /var/log/caddy/debug.log
        }
    }
}

Variables

Caddy поддерживает переменные через {} синтаксис:

# Доступные переменные
example.com {
    log {
        output stdout
        format json
        args {request>uri} {request>method} {remote_host}
    }

    reverse_proxy localhost:8080 {
        header_up X-Request-ID {uuid}
    }
}

# Кастомные переменные через vars
example.com {
    vars {
        my_api_key "secret-key"
    }

    reverse_proxy localhost:8080 {
        header_up Authorization "Bearer {vars.my_api_key}"
    }
}

Handle и reverse proxy

# Маршрутизация по домену
*.example.com {
    @service {host_regexp ^(.+)\.example\.com$}
    handle @service {
        reverse_proxy localhost:8080
    }
}

# Обработка ошибок
example.com {
    reverse_proxy localhost:8080 {
        fail_duration 30s
    }

    handle_errors {
        @404 {err.status_code} 404
        handle @404 {
            root * /var/www/errors
            rewrite /404.html
            file_server
        }
    }
}

HTTPS и TLS

# Автоматический TLS (по умолчанию)
example.com {
    reverse_proxy localhost:8080
}

# С кастомными сертификатами (если нужно)
example.com {
    tls /path/to/cert.pem /path/to/key.pem
    reverse_proxy localhost:8080
}

# Wildcard сертификат
*.example.com {
    reverse_proxy localhost:8080
}

Caddy автоматически получает и обновляет wildcard сертификаты через DNS-01 challenge. Убедитесь, что DNS API настроен правильно.

Env vars и динамическая конфигурация

# Использование env vars в Caddyfile
example.com {
    reverse_proxy {$BACKEND_URL:localhost:8080}

    log {
        output file {$LOG_PATH:/var/log/caddy/access.log}
    }
}

Практические паттерны

• Используйте handle и route для разделения логики
• Комбинируйте matchers для гибкой маршрутизации
• Используйте vars для вынесения общих значений
• Настройте log для каждого домена отдельно
• Используйте encode gzip для сжатия ответов

Заключение

Caddyfile offers простой и мощный способ конфигурации веб-сервера. Reverse proxy, rate limiting, auth и request matching покрывают большинство задач. Декларативный синтаксис делает конфигурацию читаемой и поддерживаемой.