Menüleiste am Handy, Updater in zwei Schritten, Absturzerkennung ohne Merkdateien (0.62.0)
Some checks failed
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 11m34s
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 12m8s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 15m14s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 15m47s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 13m48s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 14m15s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 16m38s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 17m2s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 1m16s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m53s

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Friederich Loheide 2026-10-07 17:03:05 +00:00
parent 623d423ad8
commit c275db4dce
147 changed files with 760 additions and 498 deletions

View file

@ -3,14 +3,20 @@
namespace App\Http\Middleware;
use App\Support\Update\MaintenanceFlag;
use App\Support\Update\Updater;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\Response;
use Throwable;
/**
* Während eines Updates: 503 mit Wartungsseite. Ausgenommen sind die
* Update-Endpunkte, die Seite „Aktualisierung“, die Anmeldung und der
* Health-Check – sonst könnte niemand verfolgen, wie weit das Update ist.
*
* Wartet ein Update auf seinen zweiten Schritt (Datenbank mit dem neuen Code),
* erledigt ihn die erste Anfrage, die nach dem Dateiaustausch begonnen hat.
*/
class EnsureNotInMaintenance
{
@ -20,6 +26,14 @@ class EnsureNotInMaintenance
public function handle(Request $request, Closure $next): Response
{
if (is_file(Updater::pendingPath())) {
try {
app(Updater::class)->finishPending();
} catch (Throwable $e) {
Log::error('Zweiter Update-Schritt fehlgeschlagen: '.$e->getMessage());
}
}
if (! $this->maintenance->isActive() || $request->is(...self::EXCEPT)) {
return $next($request);
}

View file

@ -19,15 +19,17 @@ use Throwable;
* plugins-core/<slug>/ mitgeliefert (Teil jedes Updates)
* plugins/<slug>/ vom Kunden installiert (geschützt, Updates lassen sie in Ruhe)
*
* Wiederherstellungsmodus: Vor dem Laden eines Plugins wird eine Markierung
* geschrieben und danach entfernt. Bleibt sie liegen, ist der Prozess beim
* Laden abgestürzt (Fatal Error) – das Plugin wird beim nächsten Aufruf
* deaktiviert, das Portal bleibt erreichbar. Ausnahmen führen sofort dazu.
* Wiederherstellungsmodus: Ausnahmen beim Laden schalten ein Plugin sofort ab.
* Schwere Fehler (Fatal Error), die PHP beendet, fängt eine Shutdown-Funktion ab:
* Sie weiß, welches Plugin gerade geladen wurde, und vermerkt den Absturz in
* plugins.json. Zweimal binnen einer Stunde → abgeschaltet, das Portal bleibt
* erreichbar. Ohne Merkdateien: Ein von außen beendeter Prozess (Speicher,
* Hoster) hinterlässt nichts und kann kein gesundes Plugin mehr abschalten.
*/
class PluginManager
{
/** Ab diesem Alter gilt eine liegengebliebene Lade-Markierung als Absturz. */
private const CRASH_AFTER_SECONDS = 30;
/** Fehlerarten, bei denen PHP abbricht und kein catch mehr greift */
private const FATAL_ERRORS = [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR];
/** Zwei Abbrüche innerhalb dieser Zeit schalten ein Plugin ab */
private const STRIKE_WINDOW_SECONDS = 3600;
@ -46,6 +48,11 @@ class PluginManager
/** @var array<string, bool> */
private array $autoloaded = [];
/** Plugin, das gerade geladen wird – für die Shutdown-Funktion */
private ?string $booting = null;
private bool $shutdownHandlerRegistered = false;
public function __construct(
private readonly Application $app,
private readonly PluginState $state,
@ -180,7 +187,7 @@ class PluginManager
*/
public function registerAll(): void
{
$this->recoverFromCrash();
$this->removeLegacyMarkers();
$this->reenableAfterIncompleteUpload();
$this->reenableAfterUpdate();
@ -393,12 +400,20 @@ class PluginManager
// Während eines Updates tauscht das Portal gerade Dateien aus: Fehler beim Laden sind dann
// meist nur ein Zwischenstand – das Plugin fehlt in dieser Anfrage, wird aber nicht abgeschaltet.
$updating = $this->updateWindow()->isUpdating();
$marker = $this->markerPath($manifest->slug);
if (! $updating) {
@file_put_contents($marker, (string) time());
if (! $this->shutdownHandlerRegistered) {
$this->shutdownHandlerRegistered = true;
register_shutdown_function(function () {
$error = error_get_last();
if ($this->booting !== null && is_array($error)) {
$this->handleFatalError($error);
}
});
}
$this->booting = $manifest->slug;
try {
$callback();
} catch (PluginClassMissing $e) {
@ -425,49 +440,49 @@ class PluginManager
$this->state->setEnabled($manifest->slug, false, 'Fehler beim Laden: '.$e->getMessage());
}
} finally {
@unlink($marker);
$this->booting = null;
}
}
private function recoverFromCrash(): void
/**
* Aus der Shutdown-Funktion: PHP ist mit einem schweren Fehler abgebrochen, während
* ein Plugin geladen wurde. Erster Abbruch: nur vermerken (kann z. B. eine überschrittene
* Laufzeit auf einem überlasteten Server sein). Ein wirklich defektes Plugin bricht bei
* jeder Anfrage ab und fällt binnen Sekunden ein zweites Mal auf – dann wird es abgeschaltet.
*
* @param array{type: int, message: string, file?: string, line?: int} $error
*/
public function handleFatalError(array $error): void
{
foreach (glob($this->markerPath('*')) ?: [] as $marker) {
// Zeitpunkt aus dem Inhalt, nicht aus filemtime(): Liegt storage auf einem Netzlaufwerk,
// stammt die Dateizeit von dessen Uhr – geht sie nach, sähe eine eben geschriebene Marke
// wie ein alter Absturz aus und ein gesundes Plugin würde abgeschaltet.
$startedAt = $this->markerTime($marker);
$slug = $this->booting;
if ($startedAt === null || time() - $startedAt < self::CRASH_AFTER_SECONDS) {
continue; // Lädt vermutlich gerade in einer parallelen Anfrage.
if ($slug === null || ! in_array($error['type'], self::FATAL_ERRORS, true)) {
return;
}
$this->booting = null;
$message = mb_substr(trim(strtok($error['message'], "\n") ?: ''), 0, 300);
try {
if ($this->updateWindow()->isUpdating()) {
Log::warning("Plugin {$slug} ist während eines Updates beim Laden abgebrochen – es bleibt aktiv: {$message}");
return;
}
$slug = substr(basename($marker), strlen('booting-'));
$previous = $this->state->crashedAt($slug);
// Abgestürzt, während ein Update Dateien austauschte: kein Fehler des Plugins
if ($this->updateWindow()->covers($startedAt)) {
Log::warning("Plugin {$slug} ist während eines Updates beim Laden abgebrochen – es bleibt aktiv.");
@unlink($marker);
if ($previous === null || time() - $previous > self::STRIKE_WINDOW_SECONDS) {
$this->state->recordCrash($slug);
Log::warning("Plugin {$slug} ist beim Laden abgebrochen ({$message}) – es bleibt vorerst aktiv. Bricht es binnen einer Stunde erneut ab, wird es deaktiviert.");
continue;
return;
}
// Erster Abbruch: nur merken. Ein einzelner Abbruch kann auch von außen kommen (z. B. ein
// vom Hoster beendeter PHP-Prozess). Ein wirklich defektes Plugin bricht bei jeder Anfrage ab
// und fällt so binnen Sekunden ein zweites Mal auf.
$strike = $this->markerPath($slug, 'strike');
if (time() - (int) $this->markerTime($strike) > self::STRIKE_WINDOW_SECONDS) {
@file_put_contents($strike, (string) time());
@unlink($marker);
Log::warning("Plugin {$slug} ist beim Laden abgebrochen – es bleibt vorerst aktiv. Bricht es binnen einer Stunde erneut ab, wird es deaktiviert.");
continue;
}
Log::critical("Plugin {$slug} hat beim Laden einen schweren Fehler verursacht und wurde deaktiviert.");
$this->state->setEnabled($slug, false, 'Schwerer Fehler beim Laden (das Portal wurde dadurch unterbrochen).');
@unlink($marker);
@unlink($strike);
Log::critical("Plugin {$slug} hat beim Laden einen schweren Fehler verursacht und wurde deaktiviert: {$message}");
$this->state->setEnabled($slug, false, 'Schwerer Fehler beim Laden: '.$message);
} catch (Throwable) {
// Im Shutdown darf nichts mehr werfen.
}
}
@ -518,22 +533,22 @@ class PluginManager
return $this->updateWindow ??= $this->app->make(MaintenanceFlag::class);
}
/** Zeitpunkt, den die Marke enthält; null, solange sie noch geschrieben wird. */
private function markerTime(string $file): ?int
{
$content = trim((string) @file_get_contents($file));
return ctype_digit($content) ? (int) $content : null;
}
private function markerPath(string $slug, string $kind = 'booting'): string
/**
* Merkdateien früherer Versionen (storage/framework/plugins) aufräumen – sie würden
* sonst nie mehr gelesen. Danach kostet die Prüfung nur noch ein is_dir().
*/
private function removeLegacyMarkers(): void
{
$dir = storage_path('framework/plugins');
if (! is_dir($dir)) {
@mkdir($dir, 0775, true);
return;
}
return $dir.'/'.$kind.'-'.$slug;
foreach (array_merge(glob($dir.'/booting-*') ?: [], glob($dir.'/strike-*') ?: []) as $file) {
@unlink($file);
}
@rmdir($dir);
}
}

View file

@ -27,12 +27,29 @@ class PluginState
{
$entry = $this->all()[$manifest->slug] ?? null;
return is_array($entry) ? (bool) ($entry['enabled'] ?? false) : $manifest->core && ($manifest->enabledByDefault || self::$enableOptionalCorePlugins);
// Ein Eintrag kann auch nur einen vermerkten Absturz enthalten – dann gilt die Voreinstellung
return is_array($entry) && array_key_exists('enabled', $entry)
? (bool) $entry['enabled']
: $manifest->core && ($manifest->enabledByDefault || self::$enableOptionalCorePlugins);
}
public function setEnabled(string $slug, bool $enabled, ?string $reason = null): void
{
$this->update($slug, ['enabled' => $enabled, 'disabled_reason' => $enabled ? null : $reason, 'disabled_at' => $enabled ? null : time()]);
$this->update($slug, ['enabled' => $enabled, 'disabled_reason' => $enabled ? null : $reason, 'disabled_at' => $enabled ? null : time(), 'crashed_at' => null]);
}
/** Letzter Absturz beim Laden, der das Plugin noch nicht abgeschaltet hat (Unix-Zeit) */
public function crashedAt(string $slug): ?int
{
$this->data = null; // frisch lesen – eine parallele Anfrage kann ihn eben vermerkt haben
$at = $this->all()[$slug]['crashed_at'] ?? null;
return is_int($at) ? $at : null;
}
public function recordCrash(string $slug): void
{
$this->update($slug, ['crashed_at' => time()]);
}
/** Zeitpunkt der Deaktivierung (Unix-Zeit), falls bekannt */

View file

@ -14,6 +14,13 @@ use Throwable;
* Self-Updater: holt den Stand des aktiven Kanals als ZIP, legt ihn über die
* Produktion (mit geschützten Pfaden), migriert, leert Caches und merkt sich
* den neuen Commit-SHA. Ablauf und Prozentwerte nach docs/specs/self-updater.md.
*
* In zwei Schritten: installUpdate() tauscht die Dateien aus und endet. Migrationen
* laufen erst in der nächsten Anfrage (finishPending()) – mit dem neuen Code. In der
* Anfrage, die die Dateien austauscht, sind noch die alten Klassen geladen; neue
* Migrationen, die neue Klassen oder geänderte Modelle brauchen, liefen sonst mit
* dem alten Stand. Den zweiten Schritt löst die nächste Anfrage aus, die nach dem
* Austausch begonnen hat (EnsureNotInMaintenance) – meist die Fortschrittsabfrage.
*/
class Updater
{
@ -28,7 +35,10 @@ class Updater
) {}
/**
* @return array{sha: string, migrations: int, files: int}
* Schritt 1: herunterladen, prüfen, Dateien austauschen. Der Wartungsmodus bleibt
* an, bis finishPending() die Datenbank aktualisiert hat.
*
* @return array{sha: string, files: int, pending: bool}
*/
public function installUpdate(?int $userId = null, ?string $channel = null): array
{
@ -36,7 +46,6 @@ class Updater
$zipFile = storage_path('app/update-'.bin2hex(random_bytes(4)).'.zip');
$staging = storage_path('.update-staging');
$targetSha = null;
$migrationCount = 0;
try {
$this->progress->set(0, 'maintenance', 'Wartungsmodus wird aktiviert …');
@ -60,25 +69,21 @@ class Updater
$this->progress->set(65, 'apply', 'Dateien werden übernommen …');
$result = (new StagingApplier(ProtectedPaths::fromConfig()))->apply($staging, $this->basePath ?? base_path());
$this->progress->set(80, 'migrate', 'Datenbank wird aktualisiert …');
$migrationCount = $this->migrations->run();
$this->progress->set(90, 'cache', 'Zwischenspeicher werden geleert …');
// Bytecode-Cache verwerfen, bevor Schritt 2 freigegeben wird – sonst liefe er mit altem Code
$this->progress->set(70, 'cache', 'Zwischenspeicher werden geleert …');
$this->clearCaches();
$this->version->save($targetSha);
@file_put_contents(storage_path('.migrations-fingerprint'), $this->migrations->fingerprint());
Audit::log('update.installed', [
AtomicFile::write(self::pendingPath(), json_encode([
'channel' => $channel,
'sha' => $targetSha,
'migrations' => $migrationCount,
'files' => $result['copied'],
], $userId);
'user_id' => $userId,
'ready_at' => microtime(true),
]));
$this->progress->set(75, 'finalize', 'Dateien übernommen – die Datenbank wird mit der neuen Version aktualisiert …');
$this->progress->set(100, 'done', 'Aktualisierung abgeschlossen.');
return ['sha' => $targetSha, 'migrations' => $migrationCount, 'files' => $result['copied']];
return ['sha' => $targetSha, 'files' => $result['copied'], 'pending' => true];
} catch (Throwable $e) {
$message = $e instanceof ServerError ? ServerMessages::for($e) : $e->getMessage();
@ -87,19 +92,96 @@ class Updater
Audit::log('update.failed', [
'channel' => $channel,
'sha' => $targetSha,
'migrations' => $migrationCount,
'migrations' => 0,
'error' => $message,
'code' => $e instanceof ServerError ? $e->errorCode : null,
], $userId);
// Sind die Dateien schon getauscht, holt RunPendingMigrations die Datenbank nach
$this->maintenance->deactivate();
throw $e;
} finally {
$this->maintenance->deactivate();
@unlink($zipFile);
Filesystem::deleteDirectory($staging);
}
}
public static function pendingPath(): string
{
return storage_path('.update-pending');
}
/**
* Schritt 2: Migrationen und Caches mit dem neuen Code, danach Wartungsmodus aus.
* Nur in einer Anfrage, die nach dem Dateiaustausch begonnen hat – eine ältere hat
* womöglich schon alte Klassen geladen. Gibt null zurück, wenn nichts zu tun ist.
*
* @return array{sha: string, migrations: int, files: int}|null
*/
public function finishPending(?float $requestStartedAt = null): ?array
{
$pending = json_decode((string) @file_get_contents(self::pendingPath()), true);
if (! is_array($pending) || ! isset($pending['ready_at'])) {
return null;
}
$requestStartedAt ??= (float) ($_SERVER['REQUEST_TIME_FLOAT'] ?? microtime(true));
if ($requestStartedAt <= (float) $pending['ready_at']) {
return null;
}
$lock = @fopen(storage_path('.update-finish.lock'), 'c');
if ($lock === false || ! flock($lock, LOCK_EX | LOCK_NB)) {
return null; // Läuft gerade in einer anderen Anfrage.
}
$userId = isset($pending['user_id']) ? (int) $pending['user_id'] : null;
try {
if (! is_file(self::pendingPath())) {
return null; // Eine andere Anfrage war schneller.
}
@set_time_limit(0);
@ignore_user_abort(true);
$this->progress->set(80, 'migrate', 'Datenbank wird aktualisiert …');
$migrationCount = $this->migrations->run();
$this->progress->set(90, 'cache', 'Zwischenspeicher werden geleert …');
$this->clearCaches();
@file_put_contents(storage_path('.migrations-fingerprint'), $this->migrations->fingerprint());
Audit::log('update.installed', [
'channel' => $pending['channel'] ?? null,
'sha' => $pending['sha'] ?? null,
'migrations' => $migrationCount,
'files' => (int) ($pending['files'] ?? 0),
], $userId);
$this->progress->set(100, 'done', 'Aktualisierung abgeschlossen.');
return ['sha' => (string) ($pending['sha'] ?? ''), 'migrations' => $migrationCount, 'files' => (int) ($pending['files'] ?? 0)];
} catch (Throwable $e) {
$message = 'Die neue Version ist installiert, aber die Datenbank konnte nicht aktualisiert werden: '.$e->getMessage();
$this->progress->fail($message);
Log::error('Update: Migrationen fehlgeschlagen: '.$e->getMessage(), ['exception' => $e]);
Audit::log('update.failed', ['channel' => $pending['channel'] ?? null, 'sha' => $pending['sha'] ?? null, 'migrations' => 0, 'error' => $message, 'code' => null], $userId);
throw $e;
} finally {
// Nicht endlos wiederholen – ausstehende Migrationen holt RunPendingMigrations nach
@unlink(self::pendingPath());
$this->maintenance->deactivate();
flock($lock, LOCK_UN);
fclose($lock);
}
}
/**
* @param array{sha: string|null, sha256: string|null} $headers
*/

View file

@ -9,5 +9,5 @@ namespace App;
*/
final class Version
{
public const VERSION = '0.61.0';
public const VERSION = '0.62.0';
}