Documentación
Configuración de tiempo de ejecución
Elija el proceso, el directorio de datos, el tipo de credencial y la configuración de integración que realmente controlan cada tiempo de ejecución.
Traducido automáticamente del inglés. Ver el original en inglés
Propietarios de configuración
El sidecar lee la configuración del entorno a través de AppConfigService en apps/sidecar/src/config.ts. Una capa lee esos valores cuando se construye y pasa un valor de AppConfig a los servicios que lo necesitan. Cambiar una variable de shell principal no muta un servicio que ya se está ejecutando.
Tauri proporciona su propio token de lanzamiento y rutas de migración/datos de aplicación al iniciar el niño. La vista previa del navegador utiliza variables de conexión del lado de Vite. El móvil almacena una conexión de escritorio emparejada y las credenciales del dispositivo. El sitio de documentación tiene enlaces de trabajador separados y un proceso de estudio local independiente. No comparten un archivo de configuración universal.
Configure el propietario del comportamiento que desea cambiar. Por ejemplo, configurar la URL de migración de CLI no redirige la base de datos del escritorio nativo y configurar el asistente de documentación no proporciona las credenciales del proveedor de IA del escritorio.
Iniciar un sidecar aislado
CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-config-example \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.tsEsto utiliza un directorio desechable y un token de desarrollo de ejemplo. Elija un token apropiado para su propio proceso. El servidor vincula el loopback en un puerto asignado; lea ese puerto desde su evento listo. Mantenga stdin abierto porque cerrarlo indica apagado. El comando pasa deliberadamente la configuración de forma explícita y desactiva la carga automática de archivos del entorno de Bun.
Para el bucle nativo normal, utilice bun run desktop:dev. Prepara el binario sidecar y las migraciones antes de lanzar Tauri, que posee la conexión del proceso resultante. No inicie un segundo sidecar manual y asuma que la vista web nativa se adjuntará a él.
Configuración de conexión y almacenamiento requerida
| Configuración | Por defecto | Comportamiento |
|---|---|---|
CADCAMFUN_TOKEN | Requerido | Credencial de portador de aplicación redactada para rutas API locales protegidas. |
CADCAMFUN_DATA_DIR | Requerido | Raíz del estado local gestionado por sidecar. La base de datos es cadcamfun.db debajo de él. |
CADCAMFUN_MIGRATIONS_DIR | Ausente | Directorio de migración pasado a la capa de base de datos. Sin él, abrir la base de datos no crea ni actualiza las tablas de la aplicación. |
CADCAMFUN_APP_URL | Ausente en la configuración | URL base proporcionada a las integraciones de enlaces de cuentas. El servicio correspondiente decide su alternativa. |
CADCAMFUN_DEBUG_LINKS | FALSO | Habilita campos de respuesta de desarrollo para enlaces de cuentas en controladores que los admiten. |
El directorio de datos es una raíz de almacenamiento, no una dirección de enlace HTTP. El oyente del servidor principal está fijado en 127.0.0.1 con un puerto efímero. Las redes complementarias utilizan su propia puerta de enlace HTTPS habilitada explícitamente; cambiar una configuración de URL no hace que el oyente de bucle invertido sea público.
Mantenga el directorio de migración configurado alineado con el binario. El inicio puede fallar antes de estar listo cuando no se puede planificar, realizar una copia de seguridad o aplicar una migración. La referencia de la base de datos explica el comportamiento de las transacciones y las copias de seguridad; una tabla que falta después de omitir migraciones es un problema de configuración más que una prueba de que el proyecto fue eliminado.
El token de la aplicación se lee como un valor redactado y nunca aparece en los registros de configuración. Cada configuración en esta página se lee una vez, en apps/sidecar/src/config.ts; un valor modificado entra en vigor sólo después de que se reinicia el sidecar.
Host de IA y conectividad
| Configuración | Por defecto | Comportamiento |
|---|---|---|
CADCAMFUN_AI_HOST | nikcli | Seleccionar nikcli o direct. El host directo no agrega el bucle de herramientas persistentes integrado ni el programador especializado. |
CADCAMFUN_AI_OFFLINE | FALSO | Deshabilita la carga del catálogo de proveedores de red y el controlador de búsqueda web en vivo. No es una implementación de modelo local. |
CADCAMFUN_AI_MINIMAX_BASE_URL | Ausente | Anulación de punto final recortado opcional para la configuración MiniMax integrada. |
Las claves de proveedor son administradas por la API de credenciales y persistidas por el servicio de IA en <dataDir>/ai/credentials.json. No se obtienen inventando una variable de entorno no documentada para cada proveedor. Utilice los puntos finales de estado del proveedor/modelo para establecer qué está configurado y el guía de IA para enrutamiento de modelo directo compatible.
El modo sin conexión no convierte una llamada del proveedor de la nube en una respuesta sin conexión. Un modelo integrado o directo configurado aún puede requerir la conexión de su proveedor para realizar inferencias. El producto local primero conserva proyectos locales sin una conexión modelo; esa propiedad de almacenamiento es distinta de la inferencia de IA fuera de línea.
La política del operador se carga desde <dataDir>/ai/policy.json. El host integrado aísla sus propios directorios de trabajo/configuración debajo del almacenamiento de IA de la aplicación. La política, las credenciales, el contexto de la sesión y el caché del catálogo de proveedores tienen diferentes propósitos; copiar un archivo no reconstruye todo el tiempo de ejecución de una conversación.
Integraciones de cuentas y facturación
| Configuración | Usar | cuando está ausente |
|---|---|---|
STRIPE_SECRET_KEY | Autenticación API de Stripe saliente. | El pago pagado y la integración del portal de facturación no están disponibles. |
STRIPE_WEBHOOK_SECRET | Verifique las cargas útiles del webhook de Stripe firmadas. | El controlador del webhook rechaza la ingesta sin una configuración de verificación. |
STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, STRIPE_PRICE_ENTERPRISE | Identificadores de precios para planes pagos. Los valores en blanco se ignoran. | Una asignación faltante no puede identificar un precio de pago configurado para ese plan. |
CRON_SECRET | Credencial compartida adicional para mantenimiento cron. | Ese guardia no requiere ningún secreto cron adicional; la admisión del portador de la solicitud aún se aplica. |
ADMIN_EMAIL | Identidad del administrador utilizada por la política de cuenta/servicio. | El perfil de la instalación local conserva el comportamiento administrativo local implementado por sus servicios. |
Estos ajustes configuran las integraciones; no establecen que exista una cuenta remota, un precio, una suscripción o una entrega de webhook. Verifique la falla real de la operación y el estado del servicio en ejecución. No infiera que la presencia de una tabla significa que la función alojada relacionada está completamente configurada.
La interfaz AppConfig también contiene ganchos de inyección de prueba, como una fábrica de modelos de reemplazo y una base API de Stripe. No son variables de entorno leídas por esta capa de configuración de producción. Mantenga los enlaces de prueba fuera de las instrucciones de implementación a menos que el host en ejecución los exponga explícitamente.
La ruta de prueba de facturación comienza un 14 día PRO ensayo (TRIAL_DAYS en apps/sidecar/src/repos/billing-repo.ts, utilizado por http/billing.ts). Los planes disponibles son FREE, BASIC, PRO, y ENTERPRISE; sólo los tres planes pagos toman un STRIPE_PRICE_* configuración.
Registros y telemetría
OTEL_EXPORTER_OTLP_ENDPOINT habilita los exportadores de registros, métricas y rastreos OTLP/HTTP del sidecar. Sin un punto final que no esté en blanco, esta capa de telemetría opcional está deshabilitada. El código del exportador construye los puntos finales específicos de la señal; configurar un recopilador que admita esas señales.
El registro normal de sidecar es independiente de la exportación de telemetría. Stdout lleva el protocolo de error/preparación JSON consumido por el shell, mientras que los registros se dirigen a stderr. Al diagnosticar el inicio, conserve el primer error relevante y su contexto de operación en lugar de esperar que la ventana de la aplicación contenga todos los detalles de la inicialización.
No incluya tokens de inicio, claves de proveedor, tokens de sesión ni archivos de credenciales completos en los paquetes de diagnóstico. Las rutas de origen, el método/estado, los ID de los puntos finales, los ID de los proyectos no secretos y la operación fallida de la base de datos suelen proporcionar un punto de partida más seguro y útil.
Configuración del cliente
Una vista previa de escritorio solo para navegador utiliza la API en memoria falsa cuando VITE_SIDECAR_URL está ausente. Para conectarlo a un sidecar iniciado manualmente, configure esa URL y VITE_SIDECAR_TOKEN antes de iniciar Vite. En su lugar, la ruta Tauri empaquetada obtiene su conexión del shell.
VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop devReemplace el marcador de posición del puerto. La configuración de Vite pertenece al proceso de desarrollo del frontend; cambiarlos no reinicia ni reconfigura el sidecar. El acceso al navegador está sujeto a la política de loopback/Tauri CORS del sidecar y a la admisión normal del portador.
El emparejamiento móvil almacena su dirección de escritorio, huella digital del certificado y token del dispositivo a través de la aplicación móvil. Cambiar el token de inicio del escritorio no es una forma normal de emparejar un teléfono. Utilice el procedimiento de emparejamiento y revocar dispositivos individuales cuando sea necesario.
Selección de ruta de base de datos
| Proceso | Regla de selección |
|---|---|
| Sidecar de escritorio nativo | Directorio de datos de aplicaciones proporcionado por Tauri, luego cadcamfun.db. |
| sidecar manual | CADCAMFUN_DATA_DIR/cadcamfun.db. |
| CLI de migración de base de datos | DATABASE_URL, eliminando una inicial file:; de lo contrario, relativo al proceso ./data/cadcamfun.db. |
Raíz db:migrate envoltura | Ejecuta el script del paquete DB, por lo que el valor predeterminado se resuelve dentro packages/db. |
| Estudio de documentación | CADCAMFUN_DB, entonces DATABASE_URL, luego raíz del repositorio data/cadcamfun.db. El archivo debe existir. |
Por lo tanto, una lista de proyectos vacía puede significar que abrió otra base de datos válida. Registre el proceso y la ruta absoluta seleccionada antes de cambiar migraciones o copiar datos. Una sesión de cuenta también puede cambiar qué recursos son visibles sin cambiar el archivo.
Aplicar y verificar un cambio
- Identifique el proceso propietario y la ruta de almacenamiento actual. Conserve los datos necesarios antes de cambiar el almacenamiento o las migraciones.
- Detenga ese proceso limpiamente y actualice su configuración de inicio explícita o configuración nativa.
- Inícielo de nuevo y espere el resultado de preparación real. Resuelva la nueva conexión en lugar de reutilizar un puerto antiguo.
- Consulta una llamada de salud pública y una llamada protegida admitida.
- Verifique el comportamiento específico: aparece el proyecto deseado, el estado del proveedor cambia, la puerta de enlace se vuelve accesible o el recopilador de telemetría configurado recibe la señal esperada.
La presencia de un valor configurado no es lo mismo que una integración externa funcional. Lea el resultado del servicio después de realizar un cambio. Los valores de configuración predeterminados deben distinguirse de los valores opcionales para los cuales el servicio receptor decide su respaldo.
Diagnóstico de configuración
Si la inicialización falla antes de estar listo, inspeccione la configuración requerida, la disponibilidad de la migración, el acceso al directorio y el error de construcción de la primera capa. Si el estado tiene éxito pero falla una llamada protegida, verifique el tipo de token y el proceso actual. Si un proveedor falla mientras los proyectos funcionan, inspeccione la configuración de AI en lugar de restablecer la base de datos.
Si Studio no está disponible en el sitio alojado, su API de producción devuelve intencionalmente 503; inicie su proceso Bun local contra el archivo existente seleccionado. Si el asistente de documentación no está disponible, inspeccione los enlaces del trabajador o su backend nikcli configurado. Ninguno de los diagnósticos requiere reemplazar las credenciales del escritorio.
Fuente de evidencia: apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts, y packages/web/script/studio-server.ts.
Cada configuración de sidecar en una mesa
AppConfigService es el único lugar del sidecar que lee el entorno. La tabla enumera cada variable que lee, en el orden en que las lee. Los valores opcionales que están vacíos o con espacios en blanco se tratan como ausentes cuando se indique lo contrario.
| Variable | Tipo | Por defecto | Utilizado por |
|---|---|---|---|
CADCAMFUN_TOKEN | cadena redactada | requerido | Middleware portador para cada ruta protegida |
CADCAMFUN_DATA_DIR | cadena | requerido | Base de datos, almacenamiento de IA, complementos, complemento, cargas |
CADCAMFUN_MIGRATIONS_DIR | cadena | ausente | Capa de base de datos; ausente significa que no se crea ningún esquema |
CADCAMFUN_APP_URL | cadena | ausente | Enlaces en los correos electrónicos de cuentas (el legado NEXTAUTH_URL) |
CADCAMFUN_DEBUG_LINKS | booleano | false | Restablecimiento de eco y enlaces mágicos en las respuestas (solo desarrollo) |
CADCAMFUN_AI_OFFLINE | booleano | false | Sin descarga del catálogo de proveedores ni búsqueda web en vivo |
CADCAMFUN_AI_HOST | nikcli | direct | nikcli | Anfitrión asistente; cualquier otro valor falla al iniciar |
CADCAMFUN_AI_MINIMAX_BASE_URL | cuerda, recortada | ausente | Punto final MiniMax para el host integrado |
STRIPE_WEBHOOK_SECRET | cadena | ausente | Sin él, los webhooks de Stripe se rechazan |
STRIPE_SECRET_KEY | cadena redactada | ausente | Sin él, el pago pago y el portal de facturación no están disponibles |
STRIPE_PRICE_BASIC, _PRO, _ENTERPRISE | cuerda, recortada | ausente | ID de precio por plan pago; los valores en blanco se ignoran |
CRON_SECRET | cadena | ausente | secreto compartido para /api/cron/*; sin él, la ruta está abierta a la aplicación local. |
ADMIN_EMAIL | cadena | ausente | Correo electrónico del administrador; por defecto el perfil local administra su propia instalación |
OTEL_EXPORTER_OTLP_ENDPOINT | cuerda, recortada | ausente | URL base del recopilador OTLP/HTTP; la telemetría está apagada sin ella |
La aplicación reportada version está arreglado en el código (6.0.0), no leer del entorno.
Los valores no válidos detienen el inicio
Una variable requerida que falta o un valor que no se analiza (por ejemplo CADCAMFUN_AI_HOST=local), falla la capa de configuración. Luego, el sidecar imprime un error en lugar de su línea de listo y el escritorio informa el error de inicio.
Variables leídas fuera de la configuración del sidecar
| Variable | Lector | Objetivo |
|---|---|---|
DATABASE_URL | packages/db migrar script y llovizna-kit | Objetivo para db:migrate / db:generate; un líder file: está despojado. Por defecto ./data/cadcamfun.db relativo a packages/db. |
CADCAMFUN_DB, entonces DATABASE_URL | Servidor Web Studio (packages/web/script/studio-server.ts) | Se abre la base de datos del estudio local; por defecto data/cadcamfun.db en la raíz del repositorio. |
NIKCLI_LOCALE, NIKCLI_LANGUAGE, NIKCLI_REGION | Anfitrión asistente integrado | Anula el idioma y la región del asistente. |
LC_ALL, LC_MESSAGES, LANG, LANGUAGE, TZ | Anfitrión asistente integrado | Detección de zona horaria y configuración regional del sistema cuando no se establece ninguna anulación. |
El shell del escritorio pasa exactamente tres variables al sidecar que inicia: CADCAMFUN_TOKEN (un nuevo token aleatorio por lanzamiento), CADCAMFUN_DATA_DIR (el directorio de datos de la aplicación) y CADCAMFUN_MIGRATIONS_DIR (las migraciones agrupadas). Cualquier otra cosa debe estar presente en el entorno con el que se inició la aplicación de escritorio.
¿Qué vive en el directorio de datos?
cadcamfun.db SQLite database (+ -wal / -shm while running)
backups/ pre-migration snapshots, newest five kept
auth-secret signing secret for account session tokens (0600)
auth-revoked.json revoked session tokens
ai/
credentials.json provider API keys (owner-readable only)
policy.json operator policy for the assistant
skills/ user skills
session-owners/ which account owns which assistant session
nikcli/ isolated working and config dirs of the embedded host
plugins/ assistant plugins loaded at startup
plugins-registry/ installed marketplace plugin files
companion/ gateway TLS cert.pem and key.pem (0600)
storage/ file storage for library import/export, entity I/O and plugins
uploads/profiles/ profile pictures
downloads/ files served by /api/download
waitlist.json local waitlist entriesLos directorios se crean en el primer uso, por lo que una nueva instalación contiene sólo aquellos que sus funciones han tocado. Haga una copia de seguridad de todo el directorio con la aplicación detenida: la base de datos, las credenciales, el secreto de autenticación y las claves complementarias van juntas. Los dispositivos complementarios emparejados se almacenan en la tabla clave-valor de la base de datos, no en companion/.
Trate el directorio como secreto
ai/credentials.json, auth-secret y la clave privada complementaria son credenciales. No envíe un directorio de datos de desarrollo ni lo adjunte a informes de errores.
Configuraciones de ejemplo
export CADCAMFUN_TOKEN=dev-$(openssl rand -hex 16)
export CADCAMFUN_DATA_DIR="$(mktemp -d)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=true
bun --no-env-file apps/sidecar/src/main.tsexport CADCAMFUN_APP_URL=http://localhost:4321
export CADCAMFUN_DEBUG_LINKS=true # reset/magic links appear in responsesexport OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318export STRIPE_SECRET_KEY=sk_test_...
export STRIPE_WEBHOOK_SECRET=whsec_...
export STRIPE_PRICE_PRO=price_...Nunca configurar CADCAMFUN_DEBUG_LINKS desarrollo externo: coloca enlaces de cuentas en respuestas HTTP.