Entwicklung

Die Produktionsquellen liegen an drei Orten: dem privaten Agent/Worker-Repository, dem privaten Frontend-Repository und dem entschärften öffentlichen Repository. Das öffentliche Repository wird per Einweg-Sanitizer-Skript erzeugt; bearbeiten Sie dort keine Produktionslogik.

Worker und Frontend

node --test tests/*.test.mjs
node --check app.js
node --check js/admin.js

Vollständige Prüfung vor der Veröffentlichung:

bash test.sh
pnpm run build
pnpm test
pnpm run test:update
pnpm exec wrangler deploy --dry-run --outdir .wrangler-dry-run

pnpm run build bereitet die Worker Static Assets vor; kopieren Sie niemals alte Frontend-Kopien in das Build-Verzeichnis. Vor dem Deployment bestätigen, dass der Dry-Run die erwarteten D1-, R2-, Durable-Object-, Assets- und Cron-Bindings auflistet.

Rust Agent

Eine stabile Rust-Toolchain ist erforderlich; Cross-Architektur-Linux-Releases benötigen zusätzlich das Zig/Target-Setup des Projekts. Mindestprüfungen:

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

Lokal laufen lassen reicht nicht zum Veröffentlichen. Agent-Releases müssen statische Linux-ELF-Binaries für jede unterstützte Architektur erzeugen, VERSION und SHA256SUMS aktualisieren und die schrittweise Hash-Kette des Installers verifizieren.

Konfiguration und Secrets

Öffentliche Konfiguration und Secrets werden getrennt behandelt:

• ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_PATH sind für das erste Deployment erforderlich.
• Nach dem Login nutzt der Admin die kurzlebige x-admin-session; Clients dürfen das Passwort nicht speichern oder wiedergeben.
• Agents und Latenzknoten verwenden pro Knoten gescopte Tokens, die nie in der öffentlichen API erscheinen.
• DEVELOPER_API_ORIGINS steuert nur Browser-Lesezugriffe auf /api/v1.
• NQ-Image-Host-URL und -Token sind ausschließlich Worker Secrets; sie gelangen nie in D1-Einstellungen, normale Backups oder das Frontend.
• Benutzerdefinierte URLs müssen HTTPS ohne Zugangsdaten sein und die serverseitigen Privat-/Redirect-Prüfungen bestehen.

Nutzen Sie getrennte Cloudflare-Ressourcen und Test-Zugangsdaten für die Entwicklung. Richten Sie lokale Previews nicht auf die Produktions-Admin-API und akzeptieren Sie nie eine beliebige API-Basis über einen URL-Parameter ?api=.

Die öffentliche API ändern

/api/v1 ist die stabile Kompatibilitätslinie:

1. Optionale Felder und neue Endpoint-Fähigkeiten dürfen hinzukommen.
2. Innerhalb von v1 dürfen vorhandene Felder nicht stillschweigend gelöscht, umbenannt oder umgedeutet werden.
3. Neue Query-Parameter brauchen Defaults, Bereichsgrenzen und normalisierte Cache-Keys.
4. Historie-Endpoints müssen Limits haben; 0 oder negative Werte bedeuten nie „unbegrenzt".
5. Öffentliche Ausgabe muss von IPs, Ports, URL-Zugangsdaten und internen Fehlern bereinigt sein.
6. Browser-CORS spiegelt nur exakte Origins der Allowlist.
7. Manifest, Endpoint-Doku, Vertragstests und Beispiele für alternative Frontends aktualisieren.

Clients sollten das /api/v1-Manifest zur Fähigkeitserkennung lesen, statt aus worker_version zu raten.

Frontend-Regeln

• Öffentlicher Zustand und Agent-Online-Zustand sind verschiedene Quellen; nicht in einen Boolean zusammenfassen.
• lite=1 bedient den ersten Paint; Charts laden beim Öffnen der Details.
• Fehler, leere Daten und warnings[] müssen getrennt gerendert werden.
• API-Text mit textContent oder einem einheitlichen Escape-Helper rendern.
• Breiten 320, 375, 390, 768, 1280 und 1440 px ohne horizontales Seiten-Overflow prüfen.
• Modals brauchen Fokus-Fallen, Escape zum Schließen, Hintergrund-Scroll-Sperre und Fokus-Wiederherstellung des Öffners.
• Content-Cache-Key bei geänderten Static Assets erhöhen und den aktuellen Key in Tests festschreiben.

Agent-Regeln

• Root-Disk-Kapazität ist das System-Volume, keine Summe der Mounts; Linux-IO verwendet eine konsistente Buchführungsebene, um Doppelzählungen über Partitionen, LVM und physische Geräte zu vermeiden.
• Offline-Queue schreibt mit restriktiven Rechten, atomarem Ersetzen und fsync; bei Fehlern bleibt sie dirty.
• Vor Upload-ACK, Exit und Update-Neustarts flushen.
• Eingabemetriken brauchen Typ-, Bereichs- und Zeitfenster-Validierung.
• Install, Update und Rollback bewahren Binary-Eigentum, Ausführungsrechte und die SHA-256-Kette.
• Feste NQ/IP-Aktionen akzeptieren nur kompilierte Aktions-Enums; erweitern Sie sie nie zu beliebigen Befehlen, URLs, Argumenten oder Plänen.

Versionierung und Release

Anwendung, Worker, Dokumentation und Agent teilen eine Nummer. Stabile Versionen steigen dezimal: Patch 1.1.93, nächste Minor 1.2.0; niemals Überlauf auf 1.0.99.

App/Worker/Docs: 1.1.93
Agent: v1.1.93
App-Quell-Tag: app-v1.1.93
Agent-Tag/Release: v1.1.93

Veröffentlichte Binaries derselben Version niemals überschreiben und öffentliche Tags nicht verschieben. Vor release-relevanten Änderungen die Version erhöhen, dann testen, bauen, Prüfsummen erzeugen und Release-Assets lokal erstellen. Reine Dokumentationskorrekturen dürfen die Produktversion behalten, sollten aber angeben, dass der Runtime unverändert ist.

Das öffentliche Repository ist der einzige Quell-Snapshot, das Update-Manifest und der Release-Verteilungseinstieg für Self-Hoster; die privaten Agent/Worker- und Frontend-Repositories sind die Produktionsquellen, per Einweg-Sanitizer exportiert. Öffentliche Ein-Klick-Builds laden die durch update-manifest.json gepinnte Release; Produktions-Agents installieren und aktualisieren vom /bin der bereitgestellten Site und fragen nie die GitHub-API.

Release- und Deployment-Ablauf

1. Lokales Gate: bash test.sh führt die gesamte Worker-, Frontend- und Installer-Manifest-Suite aus; agent/build-release.sh baut die Binärdateien für sieben Architekturen und schreibt bin/VERSION und bin/SHA256SUMS.
2. Hash-Kette: neue Digests zuerst in setup.sh/update.sh (SHA256SUMS_SHA256), dann in install.sh/quick-install.sh (DEFAULT_SETUP_SHA256), zuletzt in die Manifest-Tests und die Installationsbefehl-Vorlage des Panels.
3. Release: privates Agent-Repo committen und pushen mit Tag vX.Y.Z und GitHub Release (sieben Assets) → Frontend-Repo committen und taggen → öffentlichen Snapshot einseitig exportieren und die Tags vX.Y.Z/app-vX.Y.Z samt Release-Assets in das öffentliche Repository spiegeln (Ein-Klick-Deployment und Online-Update hängen davon ab) → Deployment mit worker/deploy.sh → Verifikation mit scripts/smoke-prod.mjs.
4. Self-Hosted-Updates: Der Workflow NIE-SLA Online Update prüft alle 6 Stunden die stabile Version; für ein sofortiges Update Run workflow im Actions-Tab des Deployment-Repositories starten. Bleibt ein Deployment zurück, siehe FAQ „Das Panel zeigt eine neue Version, aber es wird nie aktualisiert“; ohne Actions das Repository synchronisieren und npm run deploy ausführen.

Pre-Commit-Checkliste

• Arbeitsbaum enthält nur Dateien im Umfang.
• Tests, Formatierung, Lint, Dependency-Audit und Produktions-Build bestehen.
• Worker-Änderungen bestehen einen Wrangler-Dry-Run.
• Frontend besteht Desktop-/Mobile-Seitenprüfungen.
• Öffentlicher Export besteht den Secret-Scan und wird per Einweg aus privaten Quellen erzeugt.
• Version, Manifest, Tag-Plan, Agent-VERSION und Dokumentation stimmen überein.
• Keine Dev-Logs, Caches, Build-Temp-Verzeichnisse oder Secrets werden committet.

Für reine alternative Frontends ist kein vollständiger Worker-Fork nötig; siehe API-Integration. Für rein visuelle Änderungen nutzen Sie Themes.