Запуск Codex с домашним каталогом на NFS
Настройте общий домашний каталог Codex для интерактивной работы на разных хостах Linux.
Когда хосты Linux совместно используют домашний каталог Codex (по умолчанию ~/.codex) через Network File System (NFS), они могут повредить базу данных SQLite, если одновременно откроют ее в режиме журнала упреждающей записи (WAL). Для интерактивной работы в CLI или приложении Codex через SSH выполните миграцию общего домашнего каталога. Для независимых пакетных заданий храните домашний каталог Codex или каталог SQLite каждого хоста на локальном диске.
Почему NFS может нарушить работу SQLite
Приложение Codex и терминальный интерфейс используют индекс SQLite для отображения списка диалогов. Базы данных также хранят цели и состояние обработки памяти. На локальном диске Codex обычно использует режим WAL. Процессы на разных хостах не могут совместно использовать память, необходимую для WAL.
Когда Codex обнаруживает NFS в Linux, он создает базы данных в режиме журнала отката (DELETE), который вместо этого использует файловые блокировки. Выполните миграцию существующих баз данных WAL, прежде чем открывать их с другого хоста.
Codex также сохраняет события диалогов в файлах rollout-*.jsonl. Их уже можно хранить на NFS, поскольку в каждый момент времени запись в каждый файл хода сессии выполняет только один процесс. При миграции SQLite эти файлы остаются на месте.
Миграция существующего домашнего каталога на NFS
1. Проверьте общий домашний каталог
Выполните codex --version на каждом хосте, включая все серверные компоненты SSH. Используйте сборку, включающую codex migrate-nfs-db, например Codex CLI 0.166.0. Убедитесь, что все хосты, использующие этот общий домашний каталог, используют один и тот же каталог SQLite. Попросите администратора хранилища проверить, что файловая блокировка, удерживаемая на одном хосте, препятствует получению конфликтующей блокировки на другом. Храните SQLite локально, если смонтированная файловая система этого не поддерживает.
2. Остановите Codex на всех хостах
В режиме фоновой службы CLI подключается к фоновому серверу, который продолжает работать между сессиями. Его сокет Unix работает только на хосте, где он был запущен. Мы рекомендуем запускать CLI без фоновой службы, когда хосты совместно используют домашний каталог Codex через NFS. Остановите фоновую службу на каждом хосте, где она запущена, с помощью codex app-server daemon stop.
Чтобы CLI не запустил ее снова, задайте для daemon_auto_start значение false в разделе [features] общего файла config.toml.
[features]
daemon_auto_start = falseДля отдельной сессии CLI передайте --no-daemon. Этот флаг также позволяет обойти уже запущенную фоновую службу.
3. Выполните миграцию
Выполняйте миграцию только на одном хосте Linux для каждого общего домашнего каталога Codex. Используйте учетную запись владельца каталога и обычную конфигурацию. Не запускайте Codex на других хостах до завершения миграции.
codex migrate-nfs-db4. Возобновите диалог
Если команда сообщает Skipped logs database, проверьте расположение этой базы данных. Если база данных журналов находится на локальном диске, дополнительных действий не требуется. Если она находится на NFS, убедитесь, что она использует режим журналирования DELETE, или перенесите ее на локальный диск, прежде чем снова открывать Codex на другом хосте.
После успешной миграции откройте тот же проект на другом хосте от имени того же пользователя. Возобновите знакомый диалог в приложении или выполните codex --no-daemon resume. Убедитесь, что ваш последний запрос сохранился и вы можете продолжить диалог.
Перенос диагностических журналов на локальный диск
Необязательно; рекомендуется после миграции. Диагностические журналы помогают исследовать ошибки и медленный запуск. Локальная запись уменьшает трафик NFS.
Создайте на каждом хосте закрытый каталог журналов с правом записи. Задайте для log_dir в пользовательском файле config.toml абсолютный путь для этого пользователя. Например, Алиса может использовать такую настройку.
log_dir = "/var/local/codex/alice/logs"Новые журналы будут записываться в этот каталог. Старые останутся на месте.
Принудительное применение режима журналирования на всех хостах
Сначала остановите все клиенты на каждом хосте, использующем затронутый домашний каталог. Параметр называется unsafe, поскольку преобразование базы данных во время записи в нее с другого хоста может привести к ее повреждению.
После остановки клиентов добавьте эту настройку в управляемую конфигурацию хостов в /etc/codex/requirements.toml.
unsafe_enforce_sqlite_journal_mode = trueНастройка применяется ко всем пользователям настроенных хостов. При следующем открытии Codex пользователем он автоматически выполняет миграцию существующих баз данных WAL, когда открывает их для записи на NFS. Для каждого общего домашнего каталога дождитесь завершения миграции на одном хосте, прежде чем подключать остальные. Если миграция завершилась ошибкой, оставьте остальные клиенты остановленными и выполните шаги восстановления.
Запуск независимых пакетных заданий
Если автоматическому заданию не нужна история ваших интерактивных сессий, запускайте codex exec с домашним каталогом Codex на локальном диске рабочего узла. Если файлы сессий должны оставаться на NFS, задайте для CODEX_SQLITE_HOME отдельный локальный каталог для каждого задания, чтобы рабочие узлы не конкурировали за одну базу данных.
- Сохраняйте запись диалога. Выделите каждому заданию отдельный постоянный каталог
CODEX_HOMEдля записи хода сессии и отдельный локальный каталогCODEX_SQLITE_HOMEна хосте для базы данных. Индекс рабочего узла отделен от вашего интерактивного индекса. Храните запись хода сессии в$CODEX_HOME/sessions/, если нужно изучить задание после завершения работы узла. - Сохраняйте только результат. Разместите домашний каталог задания на локальном диске и выполните
codex exec --ephemeral. При этом сессия, которую можно возобновить, не сохраняется. Используйте-o, чтобы записать итоговый ответ в постоянный файл, или--json, чтобы передавать события потоком в систему выполнения заданий.
Для задания, которому нужна запись хода сессии, настройте планировщик так, чтобы он создавал оба каталога и обеспечивал аутентификацию и конфигурацию для домашнего каталога задания. Замените пути в примере на постоянный домашний каталог Codex этого задания и локальный каталог SQLite рабочего узла. Управляемый или настроенный параметр sqlite_home имеет приоритет над 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."Часто задаваемые вопросы
Как определить, связана ли ошибка с NFS?
Ошибка миграции, например cannot open source database exclusively, означает, что Codex не смог заблокировать базу данных. Другой клиент может вызвать это и на локальном диске. В Linux выполните findmnt -T "$DB_PATH", указав путь к затронутой базе данных. Если команда сообщает nfs или nfs4, проверьте наличие процессов записи на всех хостах и попросите администратора хранилища проверить работу блокировок между хостами для этой смонтированной файловой системы. Остановите оставшиеся клиенты перед повторной попыткой.
На что обращать внимание в выводе миграции?
Для каждой базы данных Codex выводит Migrated database: и WAL backup: либо Already in DELETE mode:. Если вы используете групповые разрешения или расширенные правила доступа, проверьте их после миграции и до повторного запуска клиентов.
Если log_dir уже задан, команда пропускает базу данных журналов. Прежде чем предоставлять к ней общий доступ с разных хостов, убедитесь, что она использует DELETE, или храните ее на локальном диске.
Если вы видите No databases found., проверьте фактически используемый каталог SQLite для пользователя, которому принадлежит домашний каталог. Если локального места для промежуточных файлов недостаточно, выберите локальный каталог хоста с достаточным свободным местом и передайте его абсолютный путь с помощью --staging-dir.
Как восстановить данные после неудачной миграции?
Оставьте остальные клиенты остановленными. Сохраните точный текст ошибки, путь к базе данных и выведенный путь к резервной копии. Некоторые базы данных уже могли пройти миграцию. Храните исходную базу данных и ее сопутствующие файлы вместе в каталоге резервной копии. После устранения ошибки блокировки или нехватки места повторно выполните codex migrate-nfs-db на том же хосте. При ошибке целостности или отсутствии заменяющего файла сначала работайте с копиями и лишь затем выполняйте восстановление. Записи хода сессий могут помочь восстановить историю диалогов. Для восстановления состояния, хранящегося только в SQLite, включая цели, нужна неповрежденная база данных.
Перед запуском отдельной сессии CLI убедитесь, что управляемые настройки хранилища не перенаправят запись в затронутый домашний каталог. Затем запустите Codex с временным каталогом на локальном диске. Для нового домашнего каталога может потребоваться вход в учетную запись.
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."