Tag 14: Fehlersuche und Upgrades
Ziel: Du findest typische Backstage-Fehler systematisch über Log, API und DevTools, reparierst sie und hebst das Portal kontrolliert auf eine neue Version. · Dauer: ca. 120 min · Voraussetzung: Tag 13
Briefing
- Fehler zeigen sich selten dort, wo sie entstehen: Ein abgelaufenes Token wird zur roten Karte an einer Location, ein CORS-Fehler zur falschen Meldung beim Login.
- Vorgehen: Symptom einer Ebene zuordnen, dann das passende Werkzeug nehmen.
- Viele Werkzeuge kennst du schon (Tag 2, 3, 5, 10). Heute kommen
Log-Level,
backstage-cli config:*, DevTools und Unprocessed Entities dazu. - Ausgangslage: Ende von Tag 13. Du arbeitest wieder im
Entwicklungsmodus mit
portal.sh(Ports 3000/7007, PostgreSQL inbs-postgres, vorherdocker start bs-postgres) und meldest dich wie gewohnt an.
Symptom Ebene Werkzeug
Seite leer, Login scheitert ───► Frontend↔Backend Browser-Konsole, curl -H Origin
Portal startet nicht ──────────► Konfiguration config:check, portal.sh logs
Entity alt, rote Karte ────────► Katalog status.items, Inspect, Log
Entity fehlt ganz ─────────────► Katalog Unprocessed, Log
401/403/„not allowed" ─────────► Integration Dry-Run, Token gegen Forgejo
Task rot ──────────────────────► Scaffolder Task-Log, tasks/<id>/events
Drill 1: Lagebild in einer Minute
Bevor du einen Fehler jagst, prüfst du, ob die Grundlage stimmt: läuft alles, und welche Warnungen sind normales Grundrauschen?
source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
curl -s $BACKSTAGE/.backstage/health/v1/readiness | jq -c .
curl -s $BACKSTAGE/.backstage/health/v1/liveness | jq -c .
~/backstage-lab/setup/portal.sh logs 2000 | sed 's/\x1b\[[0-9;]*m//g' \
| awk '$3=="warn" || $3=="error" {print $2, $3}' | sort | uniq -c | sort -rnErwartet (gekürzt, die Zahlen weichen ab):
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{"status":"ok"}
{"status":"ok"}
7 catalog warn
2 search warn
1 signals warn
Spalte 2 der Log-Zeile ist das Plugin, Spalte 3 der Level. Was steckt dahinter?
~/backstage-lab/setup/portal.sh logs 2000 | sed 's/\x1b\[[0-9;]*m//g' \
| grep -E ' (warn|error) ' | cut -c26-110 | sort -uErwartet (gekürzt):
catalog warn Event subscribe request failed with status 404, events backend not f…
catalog warn Repo http://127.0.0.1:3300/kranich/katalog does not contain a catalo…
catalog warn Repo http://127.0.0.1:3300/kranich/org does not contain a catalog-in…
catalog warn Repo http://127.0.0.1:3300/kranich/templates does not contain a cata…
search warn Index for techdocs was not created: indexer received 0 documents docu…
signals warn Event subscribe request failed with status 404, events backend not f…
Das ist das Grundrauschen deines Labs: kein Events-Backend, drei
Repos ohne catalog-info.yaml (gewollt, Tag 3 bis 5) und ein
noch leerer TechDocs-Index. Merke dir diese Liste – alles, was neu
dazukommt, ist verdächtig. Für Fehlerberichte liefert die CLI die
Versionen:
cd ~/backstage-lab/portal
yarn backstage-cli info | head -6Erwartet:
OS: Darwin 24.6.0 - darwin/arm64
node: v24.21.0
yarn: 4.13.0
cli: 0.36.6 (installed)
info module: 0.1.4
backstage: 1.55.0
Den Rest des Werkzeugkastens kennst du schon:
| Symptom | Werkzeug | eingeführt |
|---|---|---|
| Entity zeigt alten Stand, rote Karte | status.items, Fehlerkarte |
Tag 2, Tag 3 |
| Woher kommt diese Entity? | Inspect entity → Ancestry | Tag 3 |
Entity abgelehnt (allowed kind) |
Backend-Log | Tag 3, Tag 4 |
| Verwaist oder doppelt | Orphan-Filter, conflicting entityRef |
Tag 3 |
| Task schlägt fehl | Task-Seite mit Log | Tag 5 |
| Plugin-Tab meldet 403/404 | Backend-Konfiguration, RBAC | Tag 10 |
Fortschritt speichern? Kostenlos registrieren
Drill 2: Log-Level gezielt erhöhen
Der Root-Logger aus @backstage/backend-defaults liest
LOG_LEVEL aus der Umgebung (error,
warn, info, debug). Für einen
Lauf:
LOG_LEVEL=debug ~/backstage-lab/setup/portal.sh restart
sleep 45
~/backstage-lab/setup/portal.sh logs 5000 | sed 's/\x1b\[[0-9;]*m//g' \
| awk '$3=="debug" {print $2}' | sort | uniq -c | sort -rn | head -4Erwartet (Zahlen weichen ab):
86 catalog
6 backstage
5 search
4 scaffolder
Schon nach 45 Sekunden kommen fast hundert Zeilen zusammen, die
meisten vom Katalog. Gezielter geht es mit
backend.logger.overrides: Ein Override gilt nur für
Log-Einträge, deren Felder zu matchers passen (Wert oder
Regex in /…/). Zuerst ohne Debug neu starten, dann den
Override setzen:
~/backstage-lab/setup/portal.sh restart
cd ~/backstage-lab/portal
yq -i '.backend.logger.overrides =
[{"matchers": {"plugin": "catalog"}, "level": "debug"}]' app-config.local.yaml
sleep 30
~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
| grep ' debug ' | tail -3 | cut -c26-100Erwartet:
catalog debug Processing location:default/kranich-extern
catalog debug Processing user:default/chris.dietz
catalog debug Processing user:default/thomas.zachmann
Warum ohne Neustart? Der Logger abonniert Konfigurationsänderungen
und übernimmt Overrides im laufenden Betrieb – auch in Produktion ein
Weg, Debug für ein Plugin kurz einzuschalten. yq ändert die
Datei gezielt, ohne einen zweiten backend:-Block zu
erzeugen. Wieder ausschalten:
yq -i 'del(.backend.logger)' app-config.local.yamlSicherheit: Der Logger ersetzt alle Werte aus der Konfiguration, die als Secret markiert sind (Tokens, Passwörter), durch
***. Werte, die nicht aus der Konfiguration stammen, schützt das nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Konfiguration prüfen, bevor du neu startest
backstage-cli lädt dieselben Dateien wie das Backend und
prüft sie gegen die Schemas aller installierten Pakete:
cd ~/backstage-lab/portal
yarn backstage-cli config:check && echo "✔ config ok"
yarn backstage-cli config:print 2>/dev/null | yq '.integrations.gitea'Erwartet:
Loaded config from app-config.yaml, app-config.local.yaml
✔ config ok
- host: 127.0.0.1:3300
baseUrl: http://127.0.0.1:3300
username: <secret>
password: <secret>
config:print maskiert alles, was ein Schema mit
visibility: secret markiert. Mit
--with-secrets siehst du Klartext – nie in ein Ticket
kopieren. Woher weiß die CLI, was geheim ist? Aus dem zusammengeführten
Schema:
mkdir -p ~/backstage-lab/tag14
S=~/backstage-lab/tag14/schema.json
yarn backstage-cli config:schema --merge --format json > $S
jq '.properties.integrations.properties.gitea.items.properties.password' $SErwartet (gekürzt):
{
"type": "string",
"description": "Gitea password used to authenticate requests. This can be ...",
"visibility": "secret"
}Tipp: Leite
config:schemaimmer in eine Datei um. Direkt in eine Pipe geschrieben, bricht die Ausgabe nach 64 KiB ab, undjqmeldetUnfinished JSON.
Eine fehlende Umgebungsvariable ist der stillste Fehler von allen:
env -u FORGEJO_TOKEN yarn backstage-cli config:print 2>/dev/null \
| yq '.integrations.gitea'
env -u FORGEJO_TOKEN yarn backstage-cli config:check && echo "✔ trotzdem ok"Erwartet:
- host: 127.0.0.1:3300
baseUrl: http://127.0.0.1:3300
username: <secret>
✔ trotzdem ok
Ist ${FORGEJO_TOKEN} leer oder falsch geschrieben, fällt
password einfach weg. Backstage liest öffentliche Repos
dann anonym weiter, private nicht mehr. Jetzt ein YAML-Fehler, wie ihn
eine verrutschte Einrückung erzeugt:
sed -i '' 's/^ database:/ database:/' app-config.local.yaml
yarn backstage-cli config:check; echo "exit=$?"Erwartet (die Zeilennummer weicht ab):
YAMLParseError: All mapping items must start at the same column at line 18, column 1:
subject: lab-cli
database:
^
exit=1
Hättest du stattdessen portal.sh restart aufgerufen,
stünde derselbe Fehler im Log: yarn start beendet sich,
portal.sh bemerkt das nach wenigen Sekunden und meldet
✘ Start fehlgeschlagen – siehe: tail -50 …/portal.log. Dann
portal.sh logs 30. Reparieren:
sed -i '' 's/^ database:/ database:/' app-config.local.yaml
yarn backstage-cli config:check && echo "✔ config ok"Erwartet:
Loaded config from app-config.yaml, app-config.local.yaml
✔ config ok
Warum? Merke dir die Reihenfolge ändern →
config:check → portal.sh restart.
Tippfehler in Schlüsselnamen findet config:check nur mit
--strict (Challenge).
Fortschritt speichern? Kostenlos registrieren
Drill 4: Integrationen – 401 und fehlender Host
Das Bot-Token läuft ab oder wird in Forgejo widerrufen. Du simulierst das mit einem falschen Wert:
sed -i '' 's/password: ${FORGEJO_TOKEN}/password: abgelaufen-0000/' \
app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
sleep 40
bs 'catalog/entities?fields=kind,metadata.name,status' \
| jq -r '.[] | .status.items[]?.message' | grep -o '[0-9]\{3\} [A-Z][a-z]*' \
| sort | uniq -c
~/backstage-lab/setup/portal.sh logs 600 | sed 's/\x1b\[[0-9;]*m//g' \
| grep 'gitea-provider.*failed' | cut -c26-124Erwartet:
12 401 Unauthorized
catalog error gitea-provider:kranich refresh failed, Error: Failed to list Gitea p…
Die Components zeigen weiter ihren letzten guten Stand. Die Fehler
hängen an den Locations, die die Dateien lesen. Im
Browser
http://localhost:3000/catalog/default/location/kranich-extern
öffnen.
Erwartet: zwei rote Karten mit 401 Unauthorized wie in
der Abbildung.
Ist es das Token oder Forgejo? Frag Forgejo direkt mit beiden Werten:
for t in abgelaufen-0000 "$FORGEJO_TOKEN"; do
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: token $t" \
$FORGEJO/api/v1/user
doneErwartet:
401
200
Fix: Token zurück, neu starten, warten, bis keine Entity mehr Fehler trägt.
sed -i '' 's/password: abgelaufen-0000/password: ${FORGEJO_TOKEN}/' \
app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
until [ "$(bs 'catalog/entities?fields=status' \
| jq '[.[] | select(.status.items)] | length')" = 0 ]; do sleep 5; done
echo "✔ keine Fehler mehr"Erwartet:
✔ keine Fehler mehr
Zweites Fehlerbild: jemand registriert eine URL mit
localhost statt 127.0.0.1. Für Backstage ist
das ein anderer Host – ohne Integration. Der Dry-Run zeigt es (direkt
mit curl, weil bs Fehlertexte
verschluckt):
for h in localhost:3300 127.0.0.1:3300; do
curl -s -X POST "$BACKSTAGE/api/catalog/locations?dryRun=true" \
-H "Authorization: Bearer $BACKSTAGE_TOKEN" \
-H 'Content-Type: application/json' -d "{\"type\": \"url\",
\"target\": \"http://$h/kranich/zustell-app/src/branch/main/catalog-info.yaml\"}" \
| jq -r '.error.message // "✔ \(.entities | length) Entities"' | cut -c1-120
doneErwartet:
Error: Unable to read url, Reading from 'http://localhost:3300/kranich/zustell-app/s…
✔ 2 Entities
Die vollständige Meldung endet mit „You may need to configure an
integration for the target host, or add it to the configured list of
allowed hosts at ‘backend.reading.allow’“. Der Host in
integrations.gitea[].host muss exakt zur URL passen,
inklusive Port.
Fortschritt speichern? Kostenlos registrieren
Drill 5: DevTools und unverarbeitete Entities
Eine Entity, die nie erfolgreich verarbeitet wurde, hat keinen
„letzten guten Stand” – sie fehlt einfach, status.items
gibt es nicht. Solche Fälle zeigt das Modul
catalog-backend-module-unprocessed, die Oberfläche dazu
liefern DevTools:
~/backstage-lab/setup/portal.sh stop
cd ~/backstage-lab/portal
yarn --cwd packages/backend add @backstage/plugin-devtools-backend \
@backstage/plugin-catalog-backend-module-unprocessed
yarn --cwd packages/app add @backstage/plugin-devtools \
@backstage/plugin-catalog-unprocessed-entities
sed -i '' "/plugin-catalog-backend-module-gitea/a\\
backend.add(import('@backstage/plugin-catalog-backend-module-unprocessed'));\\
backend.add(import('@backstage/plugin-devtools-backend'));
" packages/backend/src/index.ts
yq -i '.devTools.scheduledTasks.plugins = ["catalog", "search"]' \
app-config.local.yaml
grep -hE 'devtools|unprocessed' packages/*/package.jsonErwartet (gekürzt):
➤ YN0000: · Done with warnings in 12s 39ms
➤ YN0000: · Done with warnings in 5s 357ms
"@backstage/plugin-catalog-unprocessed-entities": "^0.2.35",
"@backstage/plugin-devtools": "^0.1.43",
"@backstage/plugin-catalog-backend-module-unprocessed": "^0.6.16",
"@backstage/plugin-devtools-backend": "^0.5.21",
Die Frontend-Pakete brauchen keinen Code:
app.packages: all findet sie, und
plugin-catalog-unprocessed-entities hängt sich als Reiter
in page:devtools. Der Schlüssel
devTools.scheduledTasks.plugins stammt aus dem
config.schema.json von
@backstage/plugin-devtools.
Achtung: DevTools prüft Permissions (
devtools.info,devtools.config,devtools.scheduler.read,catalog.entities.unprocessed.read…). Lehnt deine Policy aus Tag 12 unbekannte Permissions ab, gib sie fürplattformfrei.
Jetzt ein Repo, dessen catalog-info.yaml keinen Owner
hat:
~/backstage-lab/setup/portal.sh start
cat ~/backstage-lab/code/tag14/lieferschein/catalog-info.yaml | tail -4
~/backstage-lab/setup/mkrepo.sh kranich/lieferschein \
~/backstage-lab/code/tag14/lieferschein
sleep 75
bs catalog/entities/by-name/component/default/lieferschein-service \
|| echo "nicht im Katalog"
bs catalog/entities/unprocessed/pending | jq -r '.entities[]
| "\(.unprocessed_entity.metadata.name) \(.errors[0].cause.message)"'Erwartet:
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
spec:
type: service
lifecycle: experimental
system: sendungsverfolgung
✔ kranich/lieferschein angelegt (http://127.0.0.1:3300/kranich/lieferschein)
nicht im Katalog
lieferschein-service /spec must have required property 'owner' - missingProperty: …
Der Gitea-Provider hat das Repo gefunden, die Location ist da, die Component scheitert an der Validierung. Im Browser:
- In der Sidebar auf DevTools klicken.
- Reiter Unprocessed Entities, dann Pending.
Erwartet: eine Zeile mit Kind Component, Owner
unknown und leerer ENTITYREF.
- In der Spalte RAW auf das Dokument-Symbol klicken.
Erwartet: Rohdaten und Fehlerliste wie in der Abbildung.
Warum Pending und nicht Failed? Pending heißt „noch nie im Katalog angekommen”, Failed heißt „war schon da, letzter Lauf ohne Ergebnis”. Schau in beide Reiter. Reparieren:
mkdir -p ~/backstage-lab/tag14 && cd ~/backstage-lab/tag14
git clone -q http://lab-admin:[email protected]:3300/kranich/lieferschein.git
cd lieferschein
yq -i '.spec.owner = "team-sendung"' catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
commit -qam "Owner ergänzt" && git push -q
s=$SECONDS; until bs catalog/entities/by-name/component/default/lieferschein-service \
>/dev/null; do sleep 5; done; echo "nach $((SECONDS - s)) s im Katalog"
bs catalog/entities/unprocessed/pending | jq '.entities | length'Erwartet:
nach 26 s im Katalog
0
Die übrigen Reiter: Info zeigt Node- und
Backstage-Version plus alle @backstage/*-Pakete,
Config die Konfiguration mit
<secret> statt Werten
(bs devtools/config | jq .config.integrations liefert
dasselbe). Scheduled Tasks listet die Hintergrundjobs
der Plugins aus devTools.scheduledTasks.plugins.
Erwartet: die Tasks des Katalogs mit Trigger- und Cancel-Symbol.
Mit dem Pfeil-Symbol stößt du den Gitea-Provider sofort an, statt eine Minute zu warten. Vorsicht: Auch im 401-Fall aus Drill 4 stand er hier auf Idle – der Provider fängt seine Fehler selbst ab. Der Status ersetzt also nicht den Blick ins Log.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Frontend, Backend und belegte Ports
Das Frontend auf :3000 ruft das Backend auf
:7007 auf – eine andere Origin. Das Backend erlaubt das nur
für backend.cors.origin. Ein Tippfehler dort:
cd ~/backstage-lab/portal
yq -i '.backend.cors.origin = "http://localhost:3001"' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -D - -o /dev/null -H "Origin: $APP" "$BACKSTAGE/api/catalog/entities" \
| grep -i '^access-control-allow-origin' || echo "kein Access-Control-Allow-Origin"Erwartet:
kein Access-Control-Allow-Origin
Im Browser http://localhost:3000 öffnen und
anmelden.
Erwartet: Mit dem Gast-Login erscheint eine irreführende Meldung wie in der Abbildung. Bei OIDC-Login (Tag 12) scheitert der Login ebenfalls, nur mit anderem Text.
Die Wahrheit steht in der Browser-Konsole (F12 → Console):
Access to fetch at 'http://localhost:7007/api/auth/guest/refresh' from origin
'http://localhost:3000' has been blocked by CORS policy: Response to preflight
request doesn't pass access control check: No 'Access-Control-Allow-Origin' header
is present on the requested resource.
Fix: den Override löschen, dann gilt wieder
http://localhost:3000 aus app-config.yaml.
yq -i 'del(.backend.cors)' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -D - -o /dev/null -H "Origin: $APP" "$BACKSTAGE/api/catalog/entities" \
| grep -i '^access-control-allow-origin'Erwartet:
Access-Control-Allow-Origin: http://localhost:3000
Tipp:
app.baseUrl,backend.baseUrlundbackend.cors.origingehören zusammen. Wer das Portal hinter einem anderen Hostnamen betreibt, ändert alle drei.
Zweites Startproblem: Port 7007 ist schon belegt, etwa von einem
vergessenen yarn start in einem anderen Terminal. Du
simulierst das:
~/backstage-lab/setup/portal.sh stop
node -e "require('http').createServer((q, s) => s.end('belegt')).listen(7007)" &
~/backstage-lab/setup/portal.sh start
curl -s $BACKSTAGE/.backstage/health/v1/readiness; echo
~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
| grep EADDRINUSE | cut -c26-110
lsof -nP -iTCP:7007 -sTCP:LISTENErwartet (gekürzt, PID und User weichen ab):
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
belegt
backstage error Unhandled rejection listen EADDRINUSE: address already in use :::…
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 22395 du 12u IPv6 0xd12e… 0t0 TCP *:7007 (LISTEN)
portal.sh meldet ✔, weil der fremde Prozess auf die
Readiness-URL antwortet – mit belegt statt JSON. Das
Backend selbst ist nie gestartet. lsof nennt den
Schuldigen:
kill %1
~/backstage-lab/setup/portal.sh restart
curl -s $BACKSTAGE/.backstage/health/v1/readiness | jq -c .Erwartet:
{"status":"ok"}
Fortschritt speichern? Kostenlos registrieren
Drill 7: Template-Fehler im Task-Log
Der RepoUrlPicker lässt im Wizard nur
127.0.0.1:3300 zu (allowedHosts, Tag 5). Über
die API prüft das niemand:
id=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' -d '{
"templateRef": "template:default/node-service",
"values": {"name": "retouren-api", "description": "Retouren erfassen",
"owner": "group:default/team-sendung",
"repoUrl": "localhost:3300?owner=kranich&repo=retouren-api"}}' | jq -r .id)
sleep 8
bs scaffolder/v2/tasks/$id | jq -r .status
bs scaffolder/v2/tasks/$id/events | jq -r '.[] | select(.type=="log")
| .body.message' | grep -E '^(Beginning|Finished|Skipping|InputError)' \
| cut -c1-100Erwartet:
failed
Beginning step Skeleton füllen
Finished step Skeleton füllen
Beginning step Repo in Forgejo anlegen
InputError: No matching integration configuration for host localhost:3300, please c…
Skipping step register because a previous step failed
Im Browser http://localhost:3000/create/tasks öffnen und
den obersten Task wählen.
Erwartet: der erste Schritt grün, der zweite rot, der dritte übersprungen; oben die Fehlermeldung, darunter das Log.
Lies das Task-Log von oben: Der erste Fehler zählt,
alles danach sind Folgen. Die Meldung ist dieselbe Ursache wie in Drill
4, diesmal in der Action publish:gitea. Fehlt dagegen das
Passwort der Integration (leeres ${FORGEJO_TOKEN}, Drill
3), meldet die Action laut Quellcode wörtlich
Credentials for the gitea ${host} required. – mit dem
Platzhalter im Text.
Tipp: Template-Fehler findest du am schnellsten vor dem Lauf: Dry-Run im Template Editor oder per API (Tag 6). Fehlende Actions meldet
bs scaffolder/v2/actions | jq -r '.[].id'.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Upgrade auf den nächsten Patch
Backstage erscheint monatlich als Release (z. B. 1.55.0) mit Patches
dazwischen. Welches Release du nutzt, steht in
backstage.json. Zuerst einen sauberen Stand sichern:
cd ~/backstage-lab/portal
git add -A && git commit -qm "Stand vor Upgrade"; git status --short | wc -l
cat backstage.json
curl -s https://versions.backstage.io/v1/tags/main/manifest.json | jq -r .releaseVersionErwartet (das neueste Release weicht je nach Datum ab):
0
{
"version": "1.55.0"
}
1.55.3
versions:bump setzt alle
@backstage/*-Abhängigkeiten auf die Versionen des
Release-Manifests. --skip-install lässt
yarn install weg – so siehst du zuerst nur die
Änderungen:
yarn backstage-cli versions:bump --release 1.55.3 --skip-install 2>&1 \
| sed 's/\x1b\[[0-9;]*m//g' | grep -vE '^(Checking|bumping)'
git diff --statErwartet (gekürzt):
Using default pattern glob @backstage/*
Some packages are outdated, updating
Upgraded from release 1.55.0 to 1.55.3, please review these template changes:
https://backstage.github.io/upgrade-helper/?from=1.55.0&to=1.55.3
Skipping yarn install
...
Version bump complete!
backstage.json | 2 +-
packages/app/package.json | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
Zwei Quellen sagen dir, was sich geändert hat:
- Upgrade Helper (Link aus der Ausgabe): Diff der
create-app-Vorlage zwischen zwei Versionen – Änderungen anindex.ts,App.tsxoderapp-config.yaml, die du von Hand nachziehst. - Changesets/CHANGELOG jedes Pakets, ein Eintrag pro Änderung:
git diff packages/app/package.json | grep '^[-+] '
sed -n '/^## 1.18.2/,/^## 1.18.1/p' \
node_modules/@backstage/plugin-techdocs/CHANGELOG.md | head -5Erwartet:
- "@backstage/plugin-techdocs": "^1.18.1",
+ "@backstage/plugin-techdocs": "^1.18.2",
## 1.18.2
### Patch Changes
- f712f71: Fixed TechDocs addons silently not rendering in apps using the new …
Bei Minor-Releases (1.55 → 1.56) lies zusätzlich die Release Notes
unter https://backstage.io/docs/releases/v1.56.0/ – dort
stehen Breaking Changes und Migrationen. Der vollständige Ablauf eines
echten Upgrades:
yarn install # lädt die neuen Pakete
yarn tsc # Typen über alle Pakete prüfen
yarn --cwd packages/app lint
CI=true yarn test
yarn backstage-cli config:check
~/backstage-lab/setup/portal.sh restart
bash ~/backstage-lab/code/tag14/kontrolle.sh # Kontrollpunkt untenErwartet (gekürzt; beim Patch-Sprung hatte yarn.lock die
neuen Versionen dank ^-Ranges schon, deshalb ist nichts zu
laden):
➤ YN0000: · Done with warnings in 2s 281ms
Tests: 1 passed, 1 total
Loaded config from app-config.yaml, app-config.local.yaml
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
✔ DevTools meldet dieselbe Version wie backstage.json
yarn tsc und Lint geben ohne Fehler nichts aus. Das Lab
bleibt auf 1.55.0, damit alle Ausgaben im Buch passen – Änderungen
zurücknehmen:
git checkout -- . && yarn install >/dev/null && cat backstage.json
~/backstage-lab/setup/portal.sh restartErwartet:
{
"version": "1.55.0"
}
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
Warum diese Reihenfolge? tsc findet geänderte APIs,
bevor das Portal startet; config:check findet umbenannte
Konfigurationsschlüssel; erst dann kostet ein Neustart Zeit. Ein Commit
pro Upgrade macht den Rückweg zu einem git revert.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Die Datei liegt unter
~/backstage-lab/code/tag14/kontrolle.sh.
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 14 (✔/✘). Exit-Code = Anzahl Fehler.
source "${LAB:-$HOME/backstage-lab}/setup/env.sh"
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
else echo "✘ $1"; fail=$((fail+1)); fi; }
t "config:check ohne Fehler" "cd '$PORTAL' && yarn backstage-cli config:check"
t "Backend bereit (readiness)" \
"curl -sf $BACKSTAGE/.backstage/health/v1/readiness | jq -e '.status==\"ok\"'"
t "keine Entity mit Processing-Fehler" \
"bs 'catalog/entities?fields=kind,metadata.name,status' \
| jq -e '[.[] | select(.status.items)] | length == 0'"
t "keine unverarbeiteten Entities (pending/failed)" \
"[ \$(bs catalog/entities/unprocessed/pending | jq '.entities|length') = 0 ] &&
[ \$(bs catalog/entities/unprocessed/failed | jq '.entities|length') = 0 ]"
t "lieferschein-service im Katalog" \
"bs catalog/entities/by-name/component/default/lieferschein-service"
t "DevTools meldet dieselbe Version wie backstage.json" \
"[ \"\$(bs devtools/info | jq -r .backstageVersion)\" = \
\"\$(jq -r .version '$PORTAL/backstage.json')\" ]"
t "Gitea-Provider läuft ohne 401" \
"! '$LAB/setup/portal.sh' logs 400 | grep -q 'gitea-provider.*401'"
exit "$fail"bash ~/backstage-lab/code/tag14/kontrolle.shErwartet:
✔ config:check ohne Fehler
✔ Backend bereit (readiness)
✔ keine Entity mit Processing-Fehler
✔ keine unverarbeiteten Entities (pending/failed)
✔ lieferschein-service im Katalog
✔ DevTools meldet dieselbe Version wie backstage.json
✔ Gitea-Provider läuft ohne 401
Challenge
Ein Kollege schickt dir seine app-config.kaputt.yaml.
Finde alle vier Fehler, ohne das Portal zu starten.
Hinweis: Drei Fehler findet
backstage-cli (config:check,
--strict, config:print), den vierten ein
Vergleich der Hosts in integrations und
catalog.locations.
Lösung
Mit --config lädt die CLI genau die genannten Dateien,
app-config.local.yaml bleibt außen vor:
cd ~/backstage-lab/portal
K=~/backstage-lab/code/tag14/challenge/app-config.kaputt.yaml
yarn backstage-cli config:check --config app-config.yaml --config $KErwartet:
YAMLParseError: Nested mappings are not allowed in compact mappings at line 33, colum…
target: http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml
^
Fehler 1: rules: darunter ist eine Stelle zu weit
eingerückt (die Meldung zeigt auf die Zeile davor). Korrigieren und
strikt prüfen:
KK=~/backstage-lab/tag14/k.yaml
cp $K $KK && sed -i '' 's/^ rules:/ rules:/' $KK
yarn backstage-cli config:check --strict --config app-config.yaml \
--config $KK 2>&1 | grep additionalProperty
yarn backstage-cli config:print --config app-config.yaml --config $KK \
2>/dev/null | yq -o json '{"keys": (.integrations.gitea[0] | keys),
"hosts": [.integrations.gitea[].host], "targets": [.catalog.locations[].target]}'Erwartet:
Config must NOT have additional properties { additionalProperty=second } at /cata…
{
"keys": [
"host",
"baseUrl",
"username"
],
"hosts": [
"localhost:3300"
],
"targets": [
"http://127.0.0.1:3300/kranich/katalog/src/branch/main/locations.yaml",
"http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml"
]
}
Fehler 2: processingInterval: { second: 20 } statt
seconds – ohne --strict ignoriert. Fehler 3:
password fehlt, weil ${FORGEJO_TOKN} falsch
geschrieben ist. Fehler 4: Integration für localhost:3300,
Locations auf 127.0.0.1:3300 – jede Location scheiterte mit
„Reading from … is not allowed” (Drill 4). Die reparierte Fassung liegt
daneben:
diff $K ~/backstage-lab/code/tag14/challenge/app-config.repariert.yaml \
| grep '^[<>] [^#]'
yarn backstage-cli config:check --strict --config app-config.yaml \
--config ~/backstage-lab/code/tag14/challenge/app-config.repariert.yaml \
&& echo "✔ strikt ok"Erwartet:
< - host: localhost:3300
< baseUrl: http://localhost:3300
> - host: 127.0.0.1:3300
> baseUrl: http://127.0.0.1:3300
< password: ${FORGEJO_TOKN}
> password: ${FORGEJO_TOKEN}
< rules:
> rules:
< processingInterval: { second: 20 }
> processingInterval: { seconds: 20 }
Loaded config from app-config.yaml, app-config.repariert.yaml
✔ strikt ok
Achtung:
config:check --strictgegen deine echteapp-config.local.yamlmeldetadditionalProperty=providersan/catalog: Der Gitea-Provider bringt kein Schema fürcatalog.providers.giteamit. Das ist ein Fehlalarm – lies--strictdeshalb immer Zeile für Zeile.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Logs zentral sammeln: Mit
NODE_ENV=productionschreibt das Backend JSON-Zeilen (Tag 13); Alarme auflevel=errorund aufcatalog warnauscatalog-backend-module-logs, nicht auf das Grundrauschen. config:check --strict(mit bekannten Ausnahmen) undyarn tscals CI-Gate für jede Änderung anapp-config*.yamlund jedes Upgrade.- DevTools und Unprocessed Entities nur für das Plattform-Team
freigeben: Config zeigt die gesamte Struktur,
Unprocessed erlaubt Löschen
(
catalog.entities.unprocessed.delete). - Upgrades monatlich im Takt der Releases, je ein Branch mit
versions:bump, Upgrade Helper und CHANGELOG-Review; große Sprünge über mehrere Minor-Versionen vermeiden. - Tokens der Integrationen mit Ablaufdatum überwachen und rotieren, bevor sie ablaufen – sonst sieht man es erst an den roten Location-Karten.