Codex mit einem NFS-Home-Verzeichnis ausführen

Konfigurieren Sie ein gemeinsames Codex-Home-Verzeichnis für interaktives Arbeiten auf mehreren Linux-Hosts.

Wenn Linux-Hosts ein Codex-Home-Verzeichnis (standardmäßig ~/.codex) über Network File System (NFS) gemeinsam nutzen, können sie eine SQLite-Datenbank beschädigen, wenn sie diese gleichzeitig im Write-Ahead-Log-Modus (WAL) öffnen. Für interaktives Arbeiten in der CLI oder der Codex-App über SSH migrieren Sie das gemeinsame Home-Verzeichnis. Für unabhängige Batchjobs speichern Sie das Codex-Home-Verzeichnis oder SQLite-Verzeichnis jedes Hosts auf einem lokalen Datenträger.

Warum NFS SQLite beschädigen kann

Die Codex-App und die Terminaloberfläche verwenden einen SQLite-Index, um Gespräche aufzulisten. Die Datenbanken speichern außerdem Ziele und den Verarbeitungszustand des Gedächtnisses. Auf lokalen Datenträgern verwendet Codex normalerweise den WAL-Modus. Prozesse auf verschiedenen Hosts können den von WAL benötigten Speicher nicht gemeinsam nutzen.

Wenn Codex Linux-NFS erkennt, erstellt es Datenbanken im Rollback-Journal-Modus (DELETE), der stattdessen Dateisperren verwendet. Migrieren Sie vorhandene WAL-Datenbanken, bevor Sie sie von einem anderen Host aus öffnen.

Codex speichert Gesprächsereignisse außerdem in rollout-*.jsonl-Dateien. Diese können bereits auf NFS liegen, da jeder Rollout jeweils von einem einzigen Prozess geschrieben wird. Bei der Migration von SQLite bleiben diese Dateien an ihrem Speicherort.

Ein vorhandenes NFS-Home-Verzeichnis migrieren

1. Das gemeinsame Home-Verzeichnis prüfen

Führen Sie codex --version auf jedem Host aus, einschließlich aller SSH-Backends. Verwenden Sie einen Build, der codex migrate-nfs-db enthält, beispielsweise Codex CLI 0.166.0. Stellen Sie sicher, dass alle Hosts, die dieses gemeinsame Home-Verzeichnis verwenden, dasselbe SQLite-Verzeichnis nutzen. Bitten Sie Ihren Speicheradministrator zu prüfen, ob eine auf einem Host gehaltene Dateisperre eine konkurrierende Sperre auf dem anderen Host blockiert. Speichern Sie SQLite lokal, wenn die Einbindung dies nicht unterstützt.

2. Codex auf allen Hosts beenden

Im Daemon-Modus verbindet sich die CLI mit einem Hintergrundserver, der zwischen Sitzungen weiterläuft. Sein Unix-Socket funktioniert nur auf dem Host, der ihn gestartet hat. Wir empfehlen, die CLI ohne Daemon auszuführen, wenn Hosts ein Codex-Home-Verzeichnis über NFS gemeinsam nutzen. Stoppen Sie den Daemon auf jedem Host, auf dem er läuft, mit codex app-server daemon stop.

Damit die CLI ihn nicht erneut startet, setzen Sie daemon_auto_start unter [features] in Ihrer gemeinsamen config.toml auf false.

[features]
daemon_auto_start = false

Übergeben Sie für eine einzelne CLI-Sitzung --no-daemon. Dieses Flag umgeht auch einen bereits laufenden Daemon.

3. Die Migration ausführen

Führen Sie die Migration für jedes gemeinsame Codex-Home-Verzeichnis auf genau einem Linux-Host aus. Verwenden Sie das Konto des Eigentümers des Home-Verzeichnisses und die übliche Konfiguration. Lassen Sie Codex auf den anderen Hosts beendet, bis die Migration abgeschlossen ist.

codex migrate-nfs-db

4. Ein Gespräch fortsetzen

Wenn der Befehl Skipped logs database meldet, prüfen Sie den Speicherort. Bei einer Protokolldatenbank auf einem lokalen Datenträger sind keine weiteren Maßnahmen erforderlich. Liegt sie auf NFS, stellen Sie sicher, dass sie den Journal-Modus DELETE verwendet, oder verschieben Sie sie auf einen lokalen Datenträger, bevor Sie Codex auf einem anderen Host erneut öffnen.

Öffnen Sie nach erfolgreicher Migration dasselbe Projekt auf einem anderen Host als derselbe Benutzer. Setzen Sie in der App ein bekanntes Gespräch fort oder führen Sie codex --no-daemon resume aus. Prüfen Sie, ob Ihr letzter Dialogschritt vorhanden ist und Sie das Gespräch fortsetzen können.

Diagnoseprotokolle auf einen lokalen Datenträger verschieben

Optional, nach der Migration empfohlen. Diagnoseprotokolle helfen Ihnen, Fehler und langsame Starts zu untersuchen. Wenn sie lokal geschrieben werden, verringert sich der Datenverkehr auf NFS.

Erstellen Sie auf jedem Host ein privates, beschreibbares Protokollverzeichnis. Setzen Sie log_dir in der config.toml des Benutzers auf den absoluten Pfad für diesen Benutzer. Alice könnte beispielsweise diese Einstellung verwenden.

log_dir = "/var/local/codex/alice/logs"

Neue Protokolle werden in diesem Verzeichnis gespeichert. Ältere Protokolle bleiben an ihrem bisherigen Speicherort.

Den Journal-Modus in einer gesamten Host-Flotte erzwingen

Beenden Sie zunächst alle Clients auf jedem Host, der ein betroffenes Home-Verzeichnis verwendet. Die Einstellung heißt unsafe, weil die Konvertierung einer Datenbank diese beschädigen kann, wenn ein anderer Host gleichzeitig darauf schreibt.

Fügen Sie bei beendeten Clients diese Einstellung der verwalteten Konfiguration der Hosts in /etc/codex/requirements.toml hinzu.

unsafe_enforce_sqlite_journal_mode = true

Die Einstellung gilt für jeden Benutzer auf den konfigurierten Hosts. Wenn ein Benutzer Codex das nächste Mal öffnet, migriert es vorhandene WAL-Datenbanken automatisch, sobald es sie auf NFS zum Schreiben öffnet. Lassen Sie die Migration für jedes gemeinsame Home-Verzeichnis auf einem Host abschließen, bevor Sie andere Hosts erneut verbinden. Wenn die Migration fehlschlägt, lassen Sie die anderen Clients beendet und befolgen Sie die Wiederherstellungsschritte.

Unabhängige Batchjobs ausführen

Wenn ein unbeaufsichtigter Job Ihren interaktiven Sitzungsverlauf nicht benötigt, führen Sie codex exec mit einem Codex-Home-Verzeichnis auf dem lokalen Datenträger des Workers aus. Wenn Sitzungsdateien auf NFS bleiben müssen, setzen Sie CODEX_SQLITE_HOME für jeden Job auf ein privates lokales Verzeichnis, damit Worker nicht um dieselbe Datenbank konkurrieren.

  • Ein Gesprächsprotokoll behalten. Geben Sie jedem Job ein privates, dauerhaftes CODEX_HOME für seinen Rollout und ein privates, hostlokales CODEX_SQLITE_HOME für seine Datenbank. Der Index des Workers ist von Ihrem interaktiven Index getrennt. Speichern Sie den Rollout unter $CODEX_HOME/sessions/, wenn Sie den Job nach dem Beenden des Workers prüfen müssen.
  • Nur das Ergebnis behalten. Legen Sie das Home-Verzeichnis des Jobs auf einem lokalen Datenträger ab und führen Sie codex exec --ephemeral aus. Dabei wird keine fortsetzbare Sitzung gespeichert. Verwenden Sie -o, um die abschließende Antwort in eine dauerhafte Datei zu schreiben, oder --json, um Ereignisse an Ihren Job-Runner zu streamen.

Lassen Sie für einen Job, der einen Rollout benötigt, den Scheduler beide Verzeichnisse erstellen und Authentifizierung und Konfiguration für das Home-Verzeichnis des Jobs bereitstellen. Ersetzen Sie die Beispielpfade durch das dauerhafte Codex-Home-Verzeichnis dieses Jobs und das workerlokale SQLite-Verzeichnis. Eine verwaltete oder konfigurierte Einstellung für sqlite_home hat Vorrang vor CODEX_SQLITE_HOME.

CODEX_HOME="/mnt/nfs/codex/jobs/job-1234" \
CODEX_SQLITE_HOME="/var/local/codex/jobs/job-1234" \
  codex exec "Summarize this repository's build steps."

Häufig gestellte Fragen

Wie erkenne ich, ob ein Fehler mit NFS zusammenhängt?

Ein Migrationsfehler wie cannot open source database exclusively bedeutet, dass Codex die Datenbank nicht sperren konnte. Ein anderer Client kann dies auch auf einem lokalen Datenträger verursachen. Führen Sie unter Linux findmnt -T "$DB_PATH" mit dem Pfad zur betroffenen Datenbank aus. Wenn nfs oder nfs4 gemeldet wird, suchen Sie auf jedem Host nach schreibenden Prozessen und bitten Sie den Speicheradministrator, die hostübergreifenden Sperren für diese Einbindung zu prüfen. Beenden Sie die verbleibenden Clients, bevor Sie es erneut versuchen.

Worauf sollte ich in der Migrationsausgabe achten?

Für jede Datenbank gibt Codex Migrated database: und WAL backup: oder Already in DELETE mode: aus. Wenn Sie auf Gruppenberechtigungen oder erweiterte Zugriffsregeln angewiesen sind, prüfen Sie diese nach der Migration und bevor Sie Clients erneut öffnen.

Wenn log_dir bereits festgelegt war, überspringt der Befehl die Protokolldatenbank. Bevor Sie diese Datenbank hostübergreifend nutzen, stellen Sie sicher, dass sie DELETE verwendet, oder belassen Sie sie auf einem lokalen Datenträger.

Wenn Sie No databases found. sehen, prüfen Sie das effektive SQLite-Verzeichnis für den Benutzer, dem das Home-Verzeichnis gehört. Wenn der lokale Speicherplatz für temporäre Dateien nicht ausreicht, wählen Sie ein hostlokales Verzeichnis mit ausreichend Speicherplatz und übergeben Sie dessen absoluten Pfad mit --staging-dir.

Wie stelle ich den Zustand nach einer fehlgeschlagenen Migration wieder her?

Lassen Sie die anderen Clients beendet. Sichern Sie die genaue Fehlermeldung, den Datenbankpfad und den ausgegebenen Sicherungspfad. Einige Datenbanken wurden möglicherweise bereits migriert. Bewahren Sie die ursprüngliche Datenbank und ihre Begleitdateien zusammen in ihrem Sicherungsverzeichnis auf. Führen Sie nach dem Beheben eines Sperr- oder Speicherplatzfehlers codex migrate-nfs-db auf demselben Host erneut aus. Arbeiten Sie bei einem Integritätsfehler oder einer fehlenden Ersatzdatei mit Kopien, bevor Sie etwas wiederherstellen. Sitzungs-Rollouts können helfen, den Gesprächsverlauf wiederherzustellen. Die Wiederherstellung von Zuständen, die nur in SQLite gespeichert sind, einschließlich Zielen, erfordert eine intakte Datenbank.

Bevor Sie eine separate CLI-Sitzung starten, stellen Sie sicher, dass verwaltete Speichereinstellungen Schreibzugriffe nicht auf das betroffene Home-Verzeichnis umleiten. Starten Sie Codex anschließend mit einem temporären Verzeichnis auf einem lokalen Datenträger. Das neue Home-Verzeichnis erfordert möglicherweise eine Anmeldung.

recovery_home=$(mktemp -d /tmp/codex-nfs-recovery.XXXXXXXX) &&
  CODEX_HOME="$recovery_home" CODEX_SQLITE_HOME="$recovery_home" \
  codex --no-daemon --sandbox read-only \
    "Help me recover a failed Codex NFS migration, run `$ codex doctor` to get the information about corrupted databases. Backup paths for databases should be in the original database with `_wal_migration_backup` in the end of the file. Ask user for the original error. Plan a recovery using copies and leave the originals untouched."