Automatyczny HTTPS w Caddy: jak działa auto TLS i jak naprawić błędy

Krótko: Caddy automatycznie włącza HTTPS dla każdego adresu strony, który jest publiczną nazwą domeny. Zamawia certyfikat przez ACME (domyślnie Let's Encrypt lub ZeroSSL), potwierdza kontrolę nad domeną wyzwaniem HTTP-01 lub TLS-ALPN-01 na portach 80 i 443, przekierowuje HTTP na HTTPS i odnawia certyfikat przed wygaśnięciem — bez dodatkowej konfiguracji.

Reverse proxy w Caddy to po prostu Caddy, który kończy to połączenie HTTPS i przekazuje żądanie do aplikacji na innym porcie, w kontenerze lub na innym hoście za pomocą dyrektywy `reverse_proxy`. To połączenie — TLS plus proxy w kilku linijkach — jest głównym powodem, dla którego ludzie go wybierają.

Reverse proxy z SSL w trzech linijkach

Gdy DNS wskazuje na serwer, a porty 80 i 443 są osiągalne, ten Caddyfile to kompletny reverse proxy HTTPS dla dwóch nazw hostów. Caddy przy starcie uzyskuje certyfikaty dla obu nazw, obsługuje HTTP/1.1, HTTP/2 i HTTP/3 oraz przekazuje do backendu `X-Forwarded-For`, `X-Forwarded-Proto` i `X-Forwarded-Host`. Opcja `email` jest opcjonalna, ale pozwala urzędowi certyfikacji kontaktować się z Tobą w sprawie wygasających lub unieważnionych certyfikatów.

Instalację z oficjalnego repozytorium apt i podstawy systemd opisuje poradnik o reverse proxy w Caddy; dla kontenerów zobacz Caddy jako reverse proxy dla Dockera. Zmiany zastosujesz poleceniem `sudo systemctl reload caddy`.

# /etc/caddy/Caddyfile
{
	email [email protected]
}

example.com, www.example.com {
	reverse_proxy 127.0.0.1:8080
}

Jak działa auto TLS w Caddy od środka

Gdy Caddy wczytuje konfigurację, zbiera wszystkie nazwy hostów z adresów stron i decyduje, kto ma wystawić każdy certyfikat. Domeny publiczne trafiają do publicznych wystawców ACME; `localhost`, adresy IP i nazwy wyłącznie wewnętrzne dostają certyfikaty z lokalnego CA Caddy (tak samo jak przy wpisaniu `tls internal`). Certyfikaty, klucze i konto ACME są przechowywane w katalogu danych Caddy: `/var/lib/caddy/.local/share/caddy` dla pakietu apt, `/data` w oficjalnym obrazie Dockera.

Odnawianie odbywa się w tle, długo przed wygaśnięciem, a Caddy dołącza (stapling) odpowiedzi OCSP tam, gdzie CA je obsługuje. Jeśli wystawienie się nie powiedzie, Caddy ponawia próby z wykładniczym opóźnieniem i używa przy ponowieniach środowiska staging CA, aby nie wyczerpać produkcyjnych limitów. Wiele instancji Caddy współdzielących ten sam magazyn koordynuje się tak, by tylko jedna zamawiała dany certyfikat.

Certyfikaty wildcard przez DNS-01

Certyfikaty wildcard, takie jak `*.example.com`, można uzyskać wyłącznie przez wyzwanie DNS-01. Standardowa binarka Caddy nie zawiera wtyczek dostawców DNS, więc budujesz ją przez xcaddy (lub wybierasz dostawcę na oficjalnej stronie pobierania) i dajesz Caddy token API ograniczony do edycji DNS tej strefy. DNS-01 działa także wtedy, gdy porty 80 i 443 nie są osiągalne z internetu, np. na serwerze wyłącznie wewnętrznym.

Nie trzymaj tokenu w Caddyfile: umieść go w pliku środowiskowym używanym przez jednostkę systemd (`sudo systemctl edit caddy`, potem `EnvironmentFile=/etc/caddy/caddy.env` w sekcji `[Service]`) i ogranicz uprawnienia pliku przez `chmod 600`.

# Build Caddy with a DNS provider module (example: Cloudflare)
xcaddy build --with github.com/caddy-dns/cloudflare

# Caddyfile: one wildcard certificate for all subdomains
*.example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}

	@app host app.example.com
	handle @app {
		reverse_proxy 127.0.0.1:3000
	}

	handle {
		respond "Unknown host" 404
	}
}

On-demand TLS i staging

On-demand TLS sprawia, że Caddy uzyskuje certyfikat podczas pierwszego handshake TLS dla nazwy hosta, której wcześniej nie widział. Jest przeznaczony dla platform, na których klienci kierują własne domeny na Twój serwer. Zawsze konfiguruj endpoint `ask`: Caddy wywołuje go z `?domain=name` i kontynuuje tylko przy odpowiedzi 200. Bez niego każdy mógłby kierować losowe nazwy na Twój IP i doprowadzić do przekroczenia limitów.

Podczas eksperymentów przełącz się na staging CA Let's Encrypt globalną opcją `acme_ca`. Certyfikaty ze stagingu nie są zaufane przez przeglądarki, ale limity są znacznie wyższe, więc możesz swobodnie psuć i naprawiać. Po zakończeniu usuń tę opcję i opcjonalnie skasuj certyfikaty stagingowe z katalogu danych.

{
	on_demand_tls {
		ask http://127.0.0.1:5555/allowed
	}
}

https:// {
	tls {
		on_demand
	}
	reverse_proxy 127.0.0.1:8080
}

# Global options block for testing
{
	email [email protected]
	# Test against Let's Encrypt staging; remove when everything works
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

Typowe awarie TLS w Caddy i jak je naprawić

1. 01.DNS nie wskazuje na serwer: brakuje rekordu A lub AAAA, wciąż wskazuje on na stary serwer albo jest zbuforowany. Nieaktualny rekord AAAA to klasyczna pułapka, bo CA preferuje IPv6, jeśli istnieje. Sprawdź oba przez `dig`.
2. 02.Port 80 lub 443 zamknięty: firewall hosta, firewall w chmurze lub router blokuje ruch przychodzący, więc ani HTTP-01, ani TLS-ALPN-01 nie mogą się zakończyć. Otwórz 80/tcp i 443/tcp (oraz 443/udp dla HTTP/3).
3. 03.Port już zajęty: Apache, nginx lub inny kontener nasłuchuje na 80 lub 443, więc Caddy nie może się podpiąć. Zatrzymaj drugą usługę albo przenieś ją za Caddy.
4. 04.Proxy CDN przed serwerem: proxy w stylu „pomarańczowej chmurki” kończy TLS przed Caddy, co może zepsuć TLS-ALPN-01. Użyj DNS-01 albo przełącz rekord na tryb DNS-only na czas wystawiania.
5. 05.Limity: powtarzane nieudane próby lub czyszczenie katalogu danych prowadzą do przekroczenia limitów CA (Let's Encrypt ogranicza nieudane walidacje na nazwę hosta na godzinę i zduplikowane certyfikaty na tydzień). Usuń przyczynę, używaj stagingu i dbaj o trwałość katalogu danych.
6. 06.Rekord CAA: rekord CAA, który dopuszcza tylko inne CA, blokuje wystawienie. Dopuść `letsencrypt.org` i `sectigo.com` (używane przez ZeroSSL) albo usuń ograniczenie.

# Does the name resolve to this server (both IPv4 and IPv6)?
dig +short A example.com
dig +short AAAA example.com
curl -4 -s https://ifconfig.me ; echo

# Are ports 80 and 443 open in the host firewall?
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

# Is something else already bound to 80/443?
sudo ss -ltnp '( sport = :80 or sport = :443 )'

# What does Caddy say?
sudo journalctl -u caddy --no-pager -n 100

HTTPS także do backendu

Większość backendów na tym samym hoście mówi zwykłym HTTP na localhost i to jest w porządku. Gdy upstream jest na innej maszynie lub wymaga TLS, użyj upstreamu `https://` i wskaż Caddy, jaką nazwę ma weryfikować i któremu CA ufać. Unikaj `tls_insecure_skip_verify` poza szybkimi testami, bo usuwa ochronę przed przechwyceniem ruchu między proxy a backendem. Dla ruchu między serwerami prywatny tunel WireGuard jest często prostszy niż zarządzanie certyfikatami backendów.

Na VPS NoctisNode z pełnym rootem i dedykowanym adresem IPv4 typowa konfiguracja wygląda tak: skieruj rekord A (bez AAAA, chyba że serwer ma IPv6) na serwer, otwórz 80 i 443, a resztą zajmie się Caddy. Jeśli musisz przekazywać ruch inny niż HTTP, zobacz proxy TCP i SSH w Caddy.

example.com {
	reverse_proxy https://10.0.0.5:8443 {
		transport http {
			tls_server_name backend.internal
			tls_trust_pool file /etc/caddy/backend-ca.pem
		}
	}
}

FAQ