HOW_TO_VERIFY (Caddy AutoGen)

Denna fil beskriver hur du verifierar appen i en riktig ZimaOS-miljö och vilken data som behövs vid felsökning.

1) Förutsättningar

ZimaOS med appen caddy-autogen installerad.
En fungerande domän i Cloudflare (publik zon).
AdGuard Home (eller annan lokal DNS) i LAN.
Cloudflare API-token med minst:
- Zone.Zone:Read
- Zone.DNS:Edit
Minst en målcontainer med web UI-port.

2) Grundkonfiguration

Sätt appvariabler i caddy-autogen:

BASE_DOMAIN=home.example.com
WILDCARD_DOMAIN=home.example.com
CLOUDFLARE_API_TOKEN=<token>
REQUIRE_CLOUDFLARE=true
ALLOW_INTERNAL_TLS_FALLBACK=false

Konfigurera lokal DNS (AdGuard Home):

A/rewrite för *.home.example.com -> ZimaOS LAN-IP
A/rewrite för home.example.com -> ZimaOS LAN-IP

3) Positivt test: endpoint skapas korrekt

Exempel med Frigate (web UI på 5000):

Sätt env-vars på Frigate-containern:

LABEL_CADDY_ENABLE=true
LABEL_CADDY_TARGET_PORT=5000
LABEL_CADDY_HOST=frigate
LABEL_CADDY_SCHEME=http
LABEL_CADDY_PATH=/

Verifiera:

Vänta 15-30 sekunder (default polling).
Öppna https://frigate.home.example.com.
Kontrollera att sidan svarar med giltigt certifikat.
Kontrollera att media-portar (8554/8555) inte blivit egna hostnamn/endpoints.

Förväntat resultat:

Endpoint finns för web UI.
Certifikat utfärdas via Let's Encrypt DNS-01.
Endast explicit målport routas.

4) Negativt test: fail-closed

Scenario A, ingen opt-in:

Ta bort LABEL_CADDY_ENABLE=true från målcontainern.
Vänta en polling-cykel.
Kontrollera att endpointen försvinner/slutar routas.

Scenario B, saknad Cloudflare-token:

Sätt REQUIRE_CLOUDFLARE=true.
Ta bort eller ogiltiggör CLOUDFLARE_API_TOKEN.
Verifiera att ingen ny extern route publiceras.

Förväntat resultat:

Appen exponerar inte tjänster oavsiktligt.
Loggar visar tydligt fel kring token/Cloudflare.

5) Kommandon för snabb verifiering

Byt <domain> och <host> enligt din miljö.

nslookup frigate.home.example.com
curl -vk https://frigate.home.example.com/
openssl s_client -connect frigate.home.example.com:443 -servername frigate.home.example.com </dev/null

Containerloggar:

docker logs --tail 200 caddy-autogen-discovery
docker logs --tail 200 caddy-autogen
docker logs --tail 200 caddy-autogen-socket-proxy

6) Data att samla innan du ber en Codex-agent om hjälp

Samla detta först. Det kortar felsökningstiden avsevärt.

Miljöinfo:

ZimaOS-version.
Appens branch/commit eller zip-artefakt (filnamn + SHA256).
Vilken DNS-server som används lokalt.

Appkonfiguration:

Alla app-env-vars för caddy-autogen (maska secrets).
Målcontainerns LABEL_CADDY_*-env-vars.
Målcontainerns publicerade portar.

Nät/TLS-bevis:

nslookup-svar från en LAN-klient.
curl -vk output mot endpoint.
openssl s_client sammanfattning av cert/issuer.

Loggar:

Senaste 200 rader från caddy-autogen-discovery.
Senaste 200 rader från caddy-autogen.
Senaste 200 rader från caddy-autogen-socket-proxy.

Problemdefinition:

Exakt hostname som inte fungerar.
Förväntat beteende och faktiskt beteende.
Tidpunkt när felet observerades.

3.2 KiB Raw Permalink Blame History