Cuando varios hosts Linux comparten un directorio de inicio de Codex (~/.codex de forma predeterminada) mediante el sistema de archivos de red (NFS), pueden dañar una base de datos SQLite si la abren al mismo tiempo en modo de registro de escritura anticipada (WAL). Para trabajar de forma interactiva en la CLI o en Codex App a través de SSH, migra el directorio de inicio compartido. Para ejecutar trabajos por lotes independientes, mantén el directorio de inicio de Codex o el directorio de SQLite de cada host en su disco local.
Por qué NFS puede dañar una base de datos SQLite
Codex App y la interfaz de la terminal usan un índice de SQLite para mostrar la lista de conversaciones. Las bases de datos también almacenan los objetivos y el estado del procesamiento de las memorias. En un disco local, Codex normalmente usa el modo WAL. Los procesos que se ejecutan en hosts distintos no pueden compartir la memoria que necesita WAL.
Cuando Codex detecta NFS en Linux, crea las bases de datos en modo de diario de reversión (DELETE), que usa bloqueos de archivos en lugar de memoria compartida. Migra las bases de datos WAL existentes antes de abrirlas desde otro host.
Codex también guarda los eventos de las conversaciones en archivos rollout-*.jsonl. Estos archivos pueden estar en NFS incluso antes de la migración, ya que solo un proceso a la vez escribe en cada archivo. Al migrar SQLite, estos archivos permanecen en su ubicación original.
Migrar un directorio de inicio existente en NFS
1. Verificar el directorio de inicio compartido
Ejecuta codex --version en cada host, incluidos los que funcionen como backend SSH. Usa una versión que incluya codex migrate-nfs-db, como Codex CLI 0.166.0. Confirma que todos los hosts que usan este directorio de inicio compartido también usen el mismo directorio de SQLite. Pídele al administrador de almacenamiento que verifique que el bloqueo de un archivo en un host impida que el otro host adquiera un bloqueo incompatible sobre el mismo archivo. Si el montaje no garantiza este comportamiento, mantén SQLite en el disco local.
Durante la migración, no definas ni cambies el directorio de inicio de SQLite ni el directorio de registros.
2. Detener Codex en todos los hosts
Finaliza los turnos activos, cierra la aplicación y la CLI y detén los servidores remotos de la aplicación, los demonios en segundo plano y los trabajos programados que usen este directorio de inicio. Mantenlos detenidos en todos los hosts hasta que termine la migración. Si otro proceso escribe al mismo tiempo, puede dañar la base de datos y provocar la pérdida de cambios en los objetivos o las memorias.
Los eventos de las sesiones se guardan en archivos separados. Estos archivos solo permiten restaurar parte del estado de la base de datos.
En modo demonio, la CLI se conecta a un servidor en segundo plano que sigue en ejecución entre sesiones. Su socket de Unix solo funciona en el host que inició el servidor. Recomendamos ejecutar la CLI sin el demonio cuando varios hosts comparten un directorio de inicio de Codex mediante NFS. Detén el demonio en cada host donde se ejecute con codex app-server daemon stop.
Para evitar que la CLI vuelva a iniciarlo, establece daemon_auto_start en false en la sección [features] del archivo config.toml compartido.
[features]
daemon_auto_start = falsePara una sola sesión de la CLI, usa la opción --no-daemon. Con esta opción, la CLI tampoco se conecta a un demonio que ya esté en ejecución.
3. Ejecutar la migración
Ejecuta la migración en un solo host Linux por cada directorio de inicio compartido de Codex. Usa la cuenta del propietario del directorio y su configuración habitual. Mantén Codex detenido en los demás hosts hasta que termine la migración.
codex migrate-nfs-db4. Reanudar una conversación
Si el comando muestra Skipped logs database, verifica la ubicación de la base de datos de registros. Si está en el disco local, no necesitas hacer nada más. Si está en NFS, confirma que use el modo de diario DELETE o muévela al disco local antes de volver a abrir Codex en otro host.
Una vez que la migración finalice correctamente, abre el mismo proyecto en otro host con la misma cuenta de usuario. Reanuda una conversación que reconozcas en la aplicación o ejecuta codex --no-daemon resume. Verifica que aparezca tu último turno y que puedas continuar la conversación.
Mover los registros de diagnóstico al disco local
Paso opcional, recomendado después de la migración. Los registros de diagnóstico te ayudan a investigar errores y problemas de lentitud al iniciar Codex. Guardarlos en el disco local reduce el tráfico en NFS.
Crea en cada host un directorio privado para los registros en el que el usuario tenga permiso de escritura. Asigna a log_dir, en el archivo config.toml del usuario, la ruta absoluta del directorio que le corresponde. Por ejemplo, Alice podría usar esta configuración.
log_dir = "/var/local/codex/alice/logs"Los registros nuevos se guardan en ese directorio. Los anteriores permanecen en su ubicación original.
Si sqlite_home se define en la configuración administrada, la base de datos de registros de SQLite permanece en el directorio requerido incluso si estableces log_dir. Consulta la configuración administrada.
Aplicar el modo de diario a todos los hosts de una flota
Primero, detén todos los clientes en cada host que use un directorio de inicio afectado. El nombre del parámetro incluye unsafe porque convertir una base de datos mientras otro host escribe en ella puede dañarla.
Con los clientes detenidos, agrega este parámetro a la configuración administrada de los hosts en /etc/codex/requirements.toml.
unsafe_enforce_sqlite_journal_mode = trueEste parámetro se aplica a todos los usuarios de los hosts configurados. La próxima vez que un usuario abra Codex, este migrará automáticamente las bases de datos WAL existentes a medida que las abra para escritura en NFS. Para cada directorio de inicio compartido, deja que la migración termine en un host antes de volver a conectar los demás. Si la migración falla, mantén detenidos los demás clientes y sigue los pasos de recuperación.
Ejecutar trabajos por lotes independientes
Si un trabajo desatendido no necesita el historial de tus sesiones interactivas, ejecuta codex exec con un directorio de inicio de Codex en el disco local del nodo de trabajo. Si los archivos de sesión deben permanecer en NFS, establece CODEX_SQLITE_HOME en un directorio local privado para cada trabajo. Así evitas que varios nodos de trabajo compitan por el acceso a la misma base de datos.
- Conservar un registro de la conversación. Asigna a cada trabajo un
CODEX_HOMEprivado y persistente para su archivo de eventos y unCODEX_SQLITE_HOMEprivado en el disco local del host para su base de datos. El índice del nodo de trabajo es independiente del que usas en las sesiones interactivas. Conserva el archivo de eventos en$CODEX_HOME/sessions/si necesitas revisar el trabajo después de que el nodo deje de ejecutarse. - Conservar solo el resultado. Coloca el directorio de inicio del trabajo en el disco local y ejecuta
codex exec --ephemeral. Así, Codex omite el guardado de una sesión que puedas reanudar. Usa-opara escribir la respuesta final en un archivo persistente o--jsonpara transmitir los eventos al sistema que ejecuta el trabajo.
Si el trabajo necesita un archivo de eventos, configura el planificador para que cree ambos directorios y prepare la autenticación y la configuración en el directorio de inicio del trabajo. Reemplaza las rutas del ejemplo por el directorio de inicio persistente de Codex que corresponda al trabajo y el directorio de SQLite en el disco local del nodo de trabajo. Si sqlite_home se define en la configuración administrada o en la configuración del usuario, tiene prioridad sobre CODEX_SQLITE_HOME.
CODEX_HOME="/mnt/nfs/codex/jobs/job-1234" \
CODEX_SQLITE_HOME="/var/local/codex/jobs/job-1234" \
codex exec "Resume los pasos para compilar el código de este repositorio."Preguntas frecuentes
¿Cómo puedo saber si un error está relacionado con NFS?
Un error de migración como cannot open source database exclusively indica que Codex no pudo bloquear la base de datos. Otro cliente también puede causar este error en un disco local. En Linux, ejecuta findmnt -T "$DB_PATH" con la ruta de la base de datos afectada. Si el comando muestra nfs o nfs4, comprueba en todos los hosts si hay procesos que estén escribiendo en la base de datos y pídele al administrador de almacenamiento que verifique el bloqueo entre hosts en ese montaje. Detén los clientes que sigan activos antes de volver a intentarlo.
¿Qué debo revisar en la salida de la migración?
Por cada base de datos, Codex muestra Migrated database: y WAL backup:, o bien Already in DELETE mode:. Si dependes de permisos de grupo o de reglas de acceso extendidas, verifícalos después de la migración y antes de volver a abrir los clientes.
Si log_dir ya estaba configurado, el comando omite la base de datos de registros. Antes de compartir esa base de datos entre varios hosts, asegúrate de que use DELETE o mantenla en el disco local.
Si ves No databases found., verifica el directorio de SQLite que se usa en la práctica para el usuario propietario del directorio de inicio. Si el espacio local para archivos temporales es insuficiente, elige un directorio en el disco local del host con espacio suficiente y pasa su ruta absoluta con --staging-dir.
¿Cómo puedo recuperar los datos si falla la migración?
Mantén detenidos los demás clientes. Guarda el mensaje de error exacto, la ruta de la base de datos y la ruta de la copia de seguridad que mostró el comando. Es posible que algunas bases de datos ya se hayan migrado. Mantén la base de datos original y sus archivos auxiliares juntos en el directorio de la copia de seguridad. Una vez resuelto un error de bloqueo o de espacio, vuelve a ejecutar codex migrate-nfs-db en el mismo host. Si hay un error de integridad o falta la base de datos de reemplazo, trabaja con copias antes de restaurar nada. Los archivos de eventos de las sesiones pueden ayudarte a reconstruir el historial de conversaciones. Para recuperar el estado que se almacena exclusivamente en SQLite, incluidos los objetivos, necesitas una base de datos intacta.
Antes de iniciar otra sesión de la CLI, confirma que la configuración de almacenamiento administrada no redirija las escrituras al directorio de inicio afectado. Luego, inicia Codex con un directorio temporal en el disco local. Es posible que debas iniciar sesión al usar el nuevo directorio de inicio.
recovery_home=$(mktemp -d /tmp/codex-nfs-recovery.XXXXXXXX) &&
CODEX_HOME="$recovery_home" CODEX_SQLITE_HOME="$recovery_home" \
codex --no-daemon --sandbox read-only \
"Ayúdame a recuperar los datos tras una migración fallida de Codex en NFS. Ejecuta `$ codex doctor` para obtener información sobre las bases de datos dañadas. La ruta de la copia de seguridad de cada base de datos debería ser la ruta original con el sufijo `_wal_migration_backup` al final del nombre del archivo. Pídele al usuario el mensaje de error original. Planifica la recuperación usando copias y deja intactos los archivos originales."