Jalankan Codex dengan direktori home NFS

Konfigurasikan home Codex bersama untuk pekerjaan interaktif di berbagai host Linux.

Saat host Linux berbagi home Codex (secara default ~/.codex) melalui Network File System (NFS), host tersebut dapat merusak database SQLite jika membukanya dalam mode write-ahead log (WAL) secara bersamaan. Untuk pekerjaan interaktif di CLI atau aplikasi Codex melalui SSH, migrasikan home bersama. Untuk pekerjaan batch independen, simpan home Codex atau direktori SQLite setiap host pada disk lokal.

Mengapa NFS dapat merusak SQLite

Aplikasi Codex dan antarmuka terminal menggunakan indeks SQLite untuk menampilkan daftar percakapan. Database tersebut juga menyimpan tujuan dan status pemrosesan memori. Pada disk lokal, Codex biasanya menggunakan mode WAL. Proses pada host yang berbeda tidak dapat berbagi memori yang diperlukan WAL.

Saat Codex mendeteksi NFS di Linux, Codex membuat database dalam mode rollback-journal (DELETE), yang menggunakan kunci file sebagai gantinya. Migrasikan database WAL yang sudah ada sebelum membukanya dari host lain.

Codex juga menyimpan peristiwa percakapan dalam file rollout-*.jsonl. File ini sudah dapat disimpan di NFS karena hanya satu proses yang menulis setiap rollout pada satu waktu. Migrasi SQLite membiarkan file tersebut tetap di tempatnya.

Migrasikan home NFS yang sudah ada

1. Periksa home bersama

Jalankan codex --version di setiap host, termasuk backend SSH apa pun. Gunakan build yang menyertakan codex migrate-nfs-db, seperti Codex CLI 0.166.0. Pastikan semua host yang menggunakan home bersama ini memakai direktori SQLite yang sama. Minta administrator penyimpanan memverifikasi bahwa kunci file yang dipegang satu host memblokir kunci yang berkonflik pada host lain. Tetap simpan SQLite secara lokal jika mount tidak dapat melakukannya.

2. Hentikan Codex di setiap host

Dalam mode daemon, CLI terhubung ke server latar belakang yang tetap berjalan di antara sesi. Soket Unix-nya hanya berfungsi pada host yang memulainya. Sebaiknya jalankan CLI tanpa daemon saat beberapa host berbagi home Codex melalui NFS. Hentikan daemon di setiap host yang menjalankannya dengan codex app-server daemon stop.

Agar CLI tidak memulainya lagi, tetapkan daemon_auto_start ke false di bawah [features] dalam config.toml bersama Anda.

[features]
daemon_auto_start = false

Untuk satu sesi CLI, sertakan --no-daemon. Flag ini juga melewati daemon yang sudah berjalan.

3. Jalankan migrasi

Jalankan migrasi hanya pada satu host Linux untuk setiap home Codex bersama. Gunakan akun pemilik home dan konfigurasi yang biasa digunakan. Pastikan Codex tetap berhenti di host lain hingga migrasi selesai.

codex migrate-nfs-db

4. Lanjutkan percakapan

Jika perintah melaporkan Skipped logs database, periksa lokasinya. Database log pada disk lokal tidak memerlukan tindakan lebih lanjut. Jika berada di NFS, pastikan database tersebut menggunakan mode jurnal DELETE atau pindahkan ke disk lokal sebelum membuka kembali Codex di host lain.

Setelah migrasi berhasil, buka proyek yang sama pada host lain sebagai pengguna yang sama. Lanjutkan percakapan yang Anda kenali di aplikasi atau jalankan codex --no-daemon resume. Pastikan giliran terakhir Anda ada dan Anda dapat melanjutkan percakapan.

Pindahkan log diagnostik ke disk lokal

Opsional, disarankan setelah migrasi. Log diagnostik membantu Anda menyelidiki kesalahan dan peluncuran yang lambat. Menulisnya secara lokal mengurangi lalu lintas di NFS.

Buat direktori log privat yang dapat ditulisi pada setiap host. Tetapkan log_dir dalam config.toml pengguna ke jalur absolut untuk pengguna tersebut. Misalnya, Alice dapat menggunakan pengaturan ini.

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

Log baru masuk ke direktori tersebut. Log lama tetap berada di tempatnya.

Terapkan mode jurnal di seluruh armada host

Pertama, hentikan semua klien di setiap host yang menggunakan home yang terdampak. Pengaturan ini dinamai unsafe karena mengonversi database saat host lain menulis ke dalamnya dapat merusaknya.

Setelah klien dihentikan, tambahkan pengaturan ini ke konfigurasi terkelola host dalam /etc/codex/requirements.toml.

unsafe_enforce_sqlite_journal_mode = true

Pengaturan ini berlaku untuk setiap pengguna pada host yang dikonfigurasi. Saat pengguna membuka Codex berikutnya, Codex secara otomatis memigrasikan database WAL yang sudah ada ketika membukanya untuk ditulis di NFS. Untuk setiap home bersama, biarkan migrasi selesai pada satu host sebelum menghubungkan kembali host lain. Jika migrasi gagal, biarkan klien lain tetap berhenti dan ikuti langkah pemulihan.

Jalankan pekerjaan batch independen

Jika pekerjaan tanpa pengawasan tidak memerlukan riwayat sesi interaktif Anda, jalankan codex exec dengan home Codex pada disk lokal worker. Jika file sesi harus tetap berada di NFS, tetapkan CODEX_SQLITE_HOME ke direktori lokal privat untuk setiap pekerjaan agar worker tidak berebut database yang sama.

  • Simpan catatan percakapan. Berikan setiap pekerjaan CODEX_HOME privat yang persisten untuk rollout-nya dan CODEX_SQLITE_HOME privat yang lokal pada host untuk database-nya. Indeks worker terpisah dari indeks interaktif Anda. Simpan rollout di bawah $CODEX_HOME/sessions/ jika Anda perlu memeriksa pekerjaan setelah worker berakhir.
  • Simpan hanya hasilnya. Tempatkan home pekerjaan pada disk lokal dan jalankan codex exec --ephemeral. Perintah ini tidak menyimpan sesi yang dapat dilanjutkan. Gunakan -o untuk menulis respons akhir ke file persisten atau --json untuk mengalirkan peristiwa ke pelaksana pekerjaan Anda.

Untuk pekerjaan yang memerlukan rollout, atur penjadwal agar membuat kedua direktori serta menyiapkan autentikasi dan konfigurasi untuk home pekerjaan. Ganti jalur contoh dengan home Codex persisten pekerjaan ini dan direktori SQLite lokal worker. sqlite_home yang dikelola atau dikonfigurasi lebih diprioritaskan daripada 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."

Pertanyaan umum

Bagaimana cara mengetahui apakah suatu kesalahan berkaitan dengan NFS?

Kesalahan migrasi seperti cannot open source database exclusively berarti Codex tidak dapat mengunci database. Klien lain juga dapat menyebabkan hal ini pada disk lokal. Di Linux, jalankan findmnt -T "$DB_PATH" dengan jalur ke database yang terdampak. Jika perintah melaporkan nfs atau nfs4, periksa proses penulis di setiap host dan minta administrator penyimpanan memverifikasi penguncian lintas host pada mount tersebut. Hentikan klien yang tersisa sebelum mencoba lagi.

Apa yang perlu saya perhatikan dalam keluaran migrasi?

Untuk setiap database, Codex mencetak Migrated database: dan WAL backup:, atau Already in DELETE mode:. Jika Anda mengandalkan izin grup atau aturan akses tambahan, verifikasi semuanya setelah migrasi dan sebelum membuka kembali klien.

Jika log_dir sudah ditetapkan, perintah melewati database log. Sebelum berbagi database tersebut di berbagai host, pastikan database menggunakan DELETE atau simpan pada disk lokal.

Jika Anda melihat No databases found., periksa direktori SQLite yang berlaku untuk pengguna pemilik home. Jika ruang penampungan sementara lokal tidak cukup, pilih direktori lokal host dengan ruang yang cukup dan sertakan jalur absolutnya dengan --staging-dir.

Bagaimana cara memulihkan keadaan setelah migrasi gagal?

Biarkan klien lain tetap berhenti. Simpan pesan kesalahan persisnya, jalur database, dan jalur cadangan yang dicetak. Beberapa database mungkin sudah dimigrasikan. Simpan database asli beserta file pendampingnya bersama-sama dalam direktori cadangannya. Setelah mengatasi kesalahan penguncian atau ruang penyimpanan, jalankan kembali codex migrate-nfs-db pada host yang sama. Untuk kesalahan integritas atau file pengganti yang hilang, kerjakan salinannya sebelum memulihkan apa pun. Rollout sesi dapat membantu membangun kembali riwayat percakapan. Pemulihan status yang hanya tersimpan di SQLite, termasuk tujuan, memerlukan database yang utuh.

Sebelum memulai sesi CLI terpisah, pastikan pengaturan penyimpanan terkelola tidak akan mengalihkan penulisan ke home yang terdampak. Kemudian mulai Codex menggunakan direktori sementara pada disk lokal. Home baru mungkin mengharuskan Anda masuk.

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."