Deployment-Fehlerbehebung

Vier Fehler fressen das erste Deploy. Führen Sie den Preflight aus, bevor Sie sonst etwas tun — er nennt die Fehlkonfiguration, statt Sie raten zu lassen:

pnpm import:self-host-check

docker run --rm --env-file .env ghcr.io/capitality-io/mildport-aio \
  bun dist/cli/self-host-check.js

Auf Kubernetes ist helm test mildport dieselbe Prüfung im Cluster.

Images pullen nicht (ImagePullBackOff)

Images liegen unter ghcr.io/capitality-io/* und sind privat. Ein Pod in ImagePullBackOff / ErrImagePull ist fast immer eines von:

1. Zugang noch nicht gewährt. Beantragen Sie ihn unter Self-Hosting in Ihrem Konto für den GitHub-User, der pullt. Ausstehende Grants sehen aus wie ein falsches Passwort.

2. Der Node ist nicht angemeldet. Ein docker login auf dem Laptop hilft dem Cluster nicht.

   echo $GITHUB_TOKEN | docker login ghcr.io -u <your-github-username> --password-stdin

   Auf Kubernetes gehören die Credentials in ein imagePullSecret:

   kubectl create secret docker-registry ghcr-pull \
     --docker-server=ghcr.io \
     --docker-username=<your-github-username> \
     --docker-password=$GITHUB_TOKEN \
     -n mildport

   imagePullSecrets:
     - name: ghcr-pull

3. Falsche Registry. Wir publizieren nach GHCR, nicht Docker Hub. Steht in den Values noch capitality/mildport, wird der Pull nie klappen. Siehe Image-Zugang.

Jeder Import liefert 401

401 heißt, der Lizenzschlüssel hat nicht verifiziert. Der Body sieht aus wie { "status": "error", "code": "UNAUTHORIZED", "reason": "…" }. reason ist die Lösung:

reason	Bedeutung	Tun
missing	Kein Authorization: Bearer …-Header	Lizenzschlüssel von Lizenzen übergeben
not_configured	Engine hat kein IMPORT_LICENSE_PUBLIC_KEY	Öffentlichen Schlüssel von Self-Hosting einfügen; neu starten
expired	exp des Schlüssels liegt in der Vergangenheit	Auf Lizenzen regenerieren; der alte gilt bis zum Ablauf
revoked	Die Lizenz-ID steht auf IMPORT_LICENSE_REVOKED_IDS	Runternehmen, oder neuen Schlüssel verwenden
malformed / bad_signature / bad_attestation	Abgeschnittener Schlüssel, extra Whitespace, oder ein Schlüssel eines anderen Issuers	Schlüssel erneut kopieren; stellen Sie keinen selbst aus

Ein fehlender öffentlicher Schlüssel ist auch ein Readiness-Fehler (checks.license: missing) — die Engine antwortet auf /health und 401t trotzdem jeden Import.

Kein 401:

• 403 ORIGIN_NOT_ALLOWED — der Schlüssel ist gültig, wurde aber mit einer Origin-Liste ausgestellt, die diese Seite nicht enthält. Schlüssel mit den richtigen Origins (oder leerer Liste) regenerieren. Das ist nicht CORS.
• CORS im Browser — die Anfrage bekommt nie einen JSON-Body. Nächster Abschnitt.

Einen Schlüssel gegen eine laufende Engine prüfen: GET /api/import/v1/license/verify. Mehr zu Schlüsseln: Lizenzierung.

Das Widget tut nichts (CORS)

Das Produktions-Image (NODE_ENV=production) lehnt jede Cross-Origin-Browser-Anfrage ab, wenn ALLOWED_ORIGINS leer ist — einschließlich http://localhost:5173. Dev-Mode localhost ist nur außerhalb von Production erlaubt.

Setzen Sie den exakten Origin der Seite, die das Widget einbettet, Schema und Port inklusive:

ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173

Bei Helm ist das app.allowedOrigins. Server-zu-Server-Aufrufer (kein Origin-Header) sind unberührt; die Variable nur weglassen, wenn nichts im Browser mit der Engine spricht.

Die Origin-Liste am Lizenzschlüssel (403 ORIGIN_NOT_ALLOWED) ist ein zweites, getrenntes Schloss. CORS entscheidet, ob der Browser sprechen darf; der Schlüssel entscheidet, ob dieser Origin diesen Schlüssel verwenden darf.

Der Pod wird nie Ready

GET /health ist Liveness. Es liefert {"status":"ok","service":"mildport",…}, sobald der Prozess antworten kann, bevor Mongo oder Lizenzierung arbeiten. Die Readiness-Probe des Charts ist GET /health/ready. Ein Pod der lebt aber nie Ready wird, scheitert an dieser Probe.

curl -i localhost:8090/health/ready

503 mit Body:

{
  "status": "not_ready",
  "service": "mildport",
  "checks": { "mongo": "down", "license": "missing" }
}

Check	down / missing heißt	Beheben
mongo	Die Engine kann Mongo nicht pingen (falsche URI, NetworkPolicy, Mongo nicht oben)	MONGO_CONNECTION_STRING; auf Mongo warten; helm test
license	Kein öffentlicher Schlüssel und Development-Modus aus	IMPORT_LICENSE_PUBLIC_KEY von der Seite Self-Hosting

license: dev-mode ist ready — synthetische Schlüssel funktionieren, und das sollten Sie nicht ausliefern.

Downed Sidecars lassen Readiness nicht fehlschlagen. Ungesetzte Decode-URLs heißen nur, dass diese Dateifamilien abgelehnt werden. Ein PDF das 503t während /health/ready 200 ist, ist eine Sidecar-URL, kein steckengebliebener Pod.

Weiter: Ihr erster Import · Konfiguration · Image-Zugang