Referencia de configuración

Todas las claves se muestran con sus valores predeterminados. Salvo que se indique que son solo de entorno, cada opción se puede establecer en config.yaml o mediante la variable de entorno indicada, que tiene prioridad. Los valores no válidos (tiempos de espera no positivos, concurrencia en cero, TTL fuera de rango) abortan el inicio con un error config: validate: que nombra la clave problemática.

General

Clave	Variable de entorno	Valor predeterminado	Descripción
env	VISION_ENV	development	Entorno de despliegue: development | staging | production. Determina el rigor de la validación

HTTP

Clave	Variable de entorno	Valor predeterminado	Descripción
http.addr	VISION_HTTP_ADDR	:3303	Dirección y puerto de escucha
http.read_timeout	VISION_HTTP_READ_TIMEOUT	15s	Tiempo máximo para leer una solicitud completa
http.write_timeout	VISION_HTTP_WRITE_TIMEOUT	30s	Tiempo máximo para escribir una respuesta
http.idle_timeout	VISION_HTTP_IDLE_TIMEOUT	60s	Tiempo de inactividad de keep-alive
http.shutdown_grace	VISION_HTTP_SHUTDOWN_GRACE	10s	Periodo de gracia para las solicitudes en curso al apagar
http.pre_drain_delay	VISION_HTTP_PREDRAIN_DELAY	5s	Retraso desde que /readyz empieza a fallar hasta el apagado (para balanceadores de carga)
http.secure_cookies	VISION_HTTP_SECURE_COOKIES	true	Marca las cookies de sesión/autenticación como Secure (solo HTTPS). vision install escribe false (http:// sin cifrar); establécelo en true cuando haya HTTPS delante
http.allowed_origins	VISION_ALLOWED_ORIGINS	["http://localhost:3303"]	Lista de orígenes permitidos de CORS. Staging y production rechazan * y una lista vacía al iniciar
http.internal_addr	VISION_HTTP_INTERNAL_ADDR	(vacío)	Listener independiente para /healthz, /readyz, /metrics

Los orígenes se comparan como scheme://host[:port], sin distinguir mayúsculas de minúsculas, con el encabezado Origin de la solicitud. Las solicitudes de origen cruzado solo pueden usar los encabezados Authorization, Content-Type, X-Request-ID, Idempotency-Key y Last-Event-ID — la lista de encabezados permitidos es fija, y cualquier otro falla en la comprobación previa (preflight). La lista efectiva de orígenes se registra al iniciar como CORS allow-list. En production, HSTS se habilita automáticamente. Cada respuesta también incluye X-Frame-Options: DENY; la interfaz no se puede incrustar en un iframe, y no hay ningún interruptor para cambiarlo.

Base de datos

Clave	Variable de entorno	Valor predeterminado	Descripción
db.path	VISION_DB_PATH	./data/vision.db	Ruta del archivo SQLite (el directorio padre debe existir)
db.connect_timeout	VISION_DB_CONNECT_TIMEOUT	5s	Tiempo de espera para abrir la conexión
db.query_timeout	VISION_DB_QUERY_TIMEOUT	30s	Tiempo de espera de una sola consulta

Registro

Clave	Variable de entorno	Valor predeterminado	Descripción
log.level	VISION_LOG_LEVEL	info	debug | info | warn | error
log.format	VISION_LOG_FORMAT	json	json (production) | text (development)

Autenticación y criptografía

Clave	Variable de entorno	Valor predeterminado	Descripción
auth.jwt_secret	VISION_AUTH_JWT_SECRET	(vacío)	Secreto de firma JWT. Obligatorio en staging/production
auth.access_ttl	VISION_AUTH_ACCESS_TTL	15m	Duración del token de acceso de corta vida (> 0, ≤ 1h)
auth.refresh_ttl	VISION_AUTH_REFRESH_TTL	168h	Duración de la sesión de renovación rotativa (> 0, ≤ 720h). Una sesión de navegador inactiva caduca pasado este tiempo
auth.oauth2_secret	VISION_OAUTH2_SECRET	(vacío)	Secreto base64 de 32 bytes para los tokens entrantes de credenciales de cliente OAuth2. Si no se establece, POST /api/v1/events no se monta
crypto.encryption_keys	VISION_ENCRYPTION_KEY, _V2, _V3, …	[]	Solo de entorno. Claves AES-256-GCM en base64 para los campos cifrados de la base de datos. La primera clave es la activa; las claves anteriores descifran durante la rotación. Obligatorio en staging/production

Genera una clave con openssl rand -base64 32. Un valor YAML para crypto.encryption_keys se ignora; mantén todas las claves en /etc/vision/vision.env. Numera las claves rotadas sin saltos (_V2, _V3, …), porque la carga se detiene en el primer número que falta. El secreto JWT acepta base64 estándar o seguro para URL, con o sin relleno, y debe decodificarse a exactamente 32 bytes.

Precaución

El secreto JWT y la clave de cifrado deben ser valores distintos — fuera de development, el inicio falla si son idénticos.

Arranque del administrador

Estos valores crean el primer usuario administrador solo mientras la tabla de usuarios está vacía y se ignoran después — editarlos una vez que existe un administrador no tiene efecto. En development, los valores ausentes recurren a admin@localhost / admin (con una advertencia al iniciar). En staging y production, la creación inicial aborta el inicio cuando la base de datos no tiene usuarios y falta cualquiera de los dos valores. El instalador genera ambos en /etc/vision/vision.env.

Clave	Variable de entorno	Valor predeterminado	Descripción
bootstrap.admin_email	ADMIN_EMAIL	(vacío)	Correo electrónico inicial del administrador. Valor alternativo en desarrollo: admin@localhost
bootstrap.admin_password	ADMIN_PASSWORD	(vacío)	Contraseña inicial del administrador. Valor alternativo en desarrollo: admin

Cliente de Alta

Los datos de conexión del servidor Alta (URL base, credenciales y la callback base URL de cada servidor) residen en la base de datos y se administran en la interfaz. Estas claves solo ajustan el cliente compartido.

Clave	Variable de entorno	Valor predeterminado	Descripción
alta.default_timeout	VISION_ALTA_DEFAULT_TIMEOUT	10s	Tiempo de espera por intento para las llamadas CRUD
alta.long_timeout	VISION_ALTA_LONG_TIMEOUT	30s	Tiempo de espera por intento para las llamadas Preview/VOD
alta.breaker_threshold	VISION_ALTA_BREAKER_THRESHOLD	5	Fallos consecutivos antes de que se abra el circuit breaker
alta.breaker_open_for	VISION_ALTA_BREAKER_OPEN_FOR	30s	Cuánto tiempo permanece abierto el breaker
alta.bulkhead_capacity	VISION_ALTA_BULKHEAD_CAPACITY	64	Máximo de llamadas a Alta en curso simultáneas
alta.stream.hls_token_ttl	VISION_ALTA_STREAM_HLS_TOKEN_TTL	5m	TTL de los tokens de lista de reproducción HLS (≤ 1h)
alta.stream.webrtc_token_ttl	VISION_ALTA_STREAM_WEBRTC_TOKEN_TTL	2m	TTL de los tokens bearer de WHEP (≤ 1h)
alta.stream.archive_token_ttl	VISION_ALTA_STREAM_ARCHIVE_TOKEN_TTL	5m	TTL de los tokens de reproducción del archivo (VOD) (≤ 1h)
alta.stream.preview_list_max_window	VISION_ALTA_STREAM_PREVIEW_LIST_MAX_WINDOW	2h	Intervalo de tiempo máximo que puede cubrir una sola solicitud de lista de vistas previas (≤ 24h)
alta.stream.auth_mode	VISION_ALTA_STREAM_AUTH_MODE	jwt	jwt (production) | none (solo para desarrollo, registra una advertencia)

Workers

Clave	Variable de entorno	Valor predeterminado	Descripción
workers.enabled	VISION_WORKERS_ENABLED	workers estándar	Lista de permitidos separada por comas de {clips, cleanup, health_server, health_camera, health, alta_prober, alerts, notifications, io, reconcile}. true habilita el conjunto estándar (excluido el io retirado); false no habilita ninguno. motion y screenshots no son válidos y abortan el inicio
workers.health_probe_concurrency	VISION_WORKERS_HEALTH_PROBE_CONCURRENCY	8	Máximo de sondeos de salud de Alta simultáneos por ciclo (≥ 1)
workers.clips_output_path	CLIPS_OUTPUT_PATH	/var/lib/vision/clips	Ruta heredada que se conserva para los registros existentes; las nuevas exportaciones requieren un almacenamiento de salida
workers.clips_ffmpeg_binary	CLIPS_FFMPEG_BINARY	ffmpeg	Ruta del ejecutable de ffmpeg
workers.clips_ffprobe_binary	CLIPS_FFPROBE_BINARY	ffprobe	Ruta de ffprobe, usado al agregar cámaras RTSP y al medir los clips exportados
workers.clips_worker_timeout	CLIPS_WORKER_TIMEOUT	5m	Plazo de ffmpeg por clip
workers.clips_worker_concurrency	CLIPS_WORKER_CONCURRENCY	2	Máximo de subprocesos de ffmpeg simultáneos
workers.screenshots_output_path	SCREENSHOTS_OUTPUT_PATH	/var/lib/vision/screenshots	Ruta heredada que se conserva para los registros existentes; las nuevas capturas requieren un almacenamiento de salida
workers.notifications_dispatch_concurrency	VISION_NOTIFICATIONS_DISPATCH_CONCURRENCY	8	Máximo de goroutines simultáneas que envían correos electrónicos, notificaciones push y webhooks
workers.drain_timeout	VISION_WORKERS_DRAIN_TIMEOUT	10s	Presupuesto total para vaciar los workers al apagar

El worker io sigue disponible solo por compatibilidad y registra una advertencia cuando se habilita explícitamente; su interfaz ha sido retirada. El worker alta_prober hace ping a cada servidor Alta aproximadamente una vez por segundo para detectar caídas y reinicios rápidamente; su cadencia es el parámetro del sistema Server ping interval que aparece más abajo.

El worker reconcile se ejecuta cada hora y elimina los recursos huérfanos del lado de Alta — pero solo los que esta instalación puede demostrar que creó (un registro de propiedad duradero, no una suposición basada en un patrón de nombres), de modo que una instalación nunca puede eliminar los recursos de otra en un servidor Alta compartido. Consulta Conectar un servidor Alta para ver qué significa esto en el día a día, y las filas Reconcile de más abajo para los parámetros que limitan cuánto elimina en cada pasada.

Retención

El worker cleanup aplica la retención. La política del registro de auditoría que aparece abajo se inicializa en la primera instalación; una vez escrita, la fuente de verdad en tiempo de ejecución es el parámetro de la aplicación en Settings → Storages.

Clave	Variable de entorno	Valor predeterminado	Descripción
retention.audit_days	VISION_RETENTION_AUDIT_DAYS	365	Valor inicial en la primera instalación para la retención del registro de auditoría, en días

Parámetros del sistema

El sondeo de salud y el ajuste de reconcile residen en la base de datos, no en config.yaml. Cada clave de abajo se puede escribir mediante PUT /api/v1/settings/{key}; la columna UI muestra cuáles tienen además un control en Settings → Connections hoy — el resto, por ahora, solo están disponibles mediante la API de parámetros o la CLI.

Clave	UI	Valor predeterminado	Rango	Descripción
connection.camera_health_interval	Camera health interval	3	1–30	Intervalo de sondeo de salud de las cámaras, en segundos
connection.server_ping_interval	Server ping interval	1	1–10	Intervalo de la sonda de disponibilidad de Alta, en segundos. Determina la rapidez con que se detectan las caídas y los reinicios
connection.server_health_interval	Server status	15	10–300	Sondeo de telemetría del host/almacenamiento, más la corroboración de accesibilidad y el filtro de sondeos limpios que da por recuperado a un servidor inestable. No determina la velocidad de detección de caídas — eso lo hace el intervalo de ping de arriba
connection.server_config_interval	Server config	300	60–3600	Cadencia de la inspección de desviación de configuración — con qué frecuencia se obtiene la configuración completa de Alta para detectar ediciones manuales. Es la llamada más pesada a Alta; mantenerla poco frecuente es seguro y no afecta la detección de caídas
connection.reconcile_grace_seconds	(ninguno)	600	60–86400	Cuánto tiempo debe permanecer un recurso de Alta sin un registro de Vision correspondiente, sin referencias y sin reclamar, antes de que el worker reconcile lo elimine. No es un interruptor para desactivar el barrido — la misma clave regula la ruta de recuperación tras una caída del worker de salud; para desactivar el barrido, quita reconcile de workers.enabled
connection.reconcile_max_deletes_per_tick	(ninguno)	20	1–1000	Límite por servidor y por ciclo de cuántos recursos elimina el barrido de reconcile; el resto espera al siguiente ciclo
connection.reconcile_candidate_ratio_guard	(ninguno)	1	0–100	Rechaza toda la pasada de reconcile de un servidor cuando los candidatos a eliminar superan references × this ratio — un freno contra una lectura de referencias errónea que vacíe un servidor. 0 desactiva la protección, para una limpieza masiva intencional

connection.server_health_interval y connection.server_config_interval se separaron a partir de un único parámetro (ADR-0045): el sondeo de accesibilidad/estado/telemetría y el análisis más pesado de desviación de configuración ahora se ejecutan con cadencias independientes, de modo que la inspección de desviaciones puede mantenerse lenta sin ralentizar también la detección de caídas. Las dos protecciones de reconcile se añadieron junto con el registro de reclamaciones de propiedad — consulta Conectar un servidor Alta para ver qué hace el barrido con ellas.

Mapas

Clave	Variable de entorno	Valor predeterminado	Descripción
maps_background_path	MAPS_BACKGROUND_PATH	(vacío)	Raíz del sistema de archivos para las imágenes de los planos. Si está vacío, usa un directorio maps junto a db.path; el instalador escribe /var/lib/vision/maps

Observabilidad

Clave	Variable de entorno	Valor predeterminado	Descripción
metrics.enabled	VISION_METRICS_ENABLED	true	Expone las métricas de Prometheus en /metrics
readiness.timeout	VISION_READINESS_TIMEOUT	5s	Plazo global de /readyz
readiness.check_workers	VISION_READINESS_CHECK_WORKERS	true	Incluye la actividad de los workers en la comprobación de disponibilidad
readiness.check_schema	VISION_READINESS_CHECK_SCHEMA	true	Incluye la comprobación de la versión del esquema
readiness.worker_stale_multiplier	VISION_READINESS_WORKER_STALE_MULTIPLIER	2.0	Un worker se considera obsoleto cuando su último latido es más antiguo que multiplier × tick

Seguridad e inicio

Clave	Variable de entorno	Valor predeterminado	Descripción
security.csp_strict_mode	VISION_SECURITY_CSP_STRICT	false	Activa la CSP estricta en desarrollo (siempre estricta en producción)
startup.check_schema	VISION_STARTUP_CHECK_SCHEMA	true	Verifica el esquema de la base de datos al arrancar
startup.check_environment	VISION_STARTUP_CHECK_ENVIRONMENT	true	Verifica el entorno al arrancar
startup.check_keyring	VISION_STARTUP_CHECK_KEYRING	true	Verifica el llavero de cifrado al arrancar
startup.check_alta	VISION_STARTUP_CHECK_ALTA	true	Verifica la accesibilidad de Alta al arrancar. Pasa cuando aún no se ha agregado ningún servidor
startup.timeout	VISION_STARTUP_TIMEOUT	10s	Presupuesto total para las comprobaciones de inicio

Limitación de tasa

Token bucket por usuario, con el ID de usuario como clave. Los endpoints públicos (/healthz, /readyz, /metrics, /auth/verify) están exentos.

El video en vivo (iniciar y detener streams) y el PTZ usan un presupuesto de tiempo real independiente de 300 solicitudes por minuto, de modo que paginar un videowall nunca consume el presupuesto de edición. Un 429 indica cuánto hay que esperar.

Clave	Variable de entorno	Valor predeterminado	Descripción
rate_limit.enabled	VISION_RATE_LIMIT_ENABLED	true	Habilita el limitador
rate_limit.read_per_min	VISION_RATE_LIMIT_READ_PER_MIN	60	Solicitudes de lectura por minuto
rate_limit.write_per_min	VISION_RATE_LIMIT_WRITE_PER_MIN	60	Solicitudes de escritura por minuto
rate_limit.burst	VISION_RATE_LIMIT_BURST	0	Margen de ráfaga (0 = usar el presupuesto por minuto)

Limitación de autenticación y bloqueo

Independiente del limitador por usuario de arriba, esto protege las solicitudes no autenticadas de inicio de sesión, renovación y restablecimiento de contraseña. El inicio de sesión debe cumplir tanto el presupuesto configurado por correo electrónico como un presupuesto fijo de 60 por minuto por IP de origen. El bloqueo por correo electrónico es de 60 segundos fijos. La renovación de sesión se identifica por IP de origen y solo tiene limitación de tasa, nunca bloqueo — una ráfaga de recargas de página espera unos segundos en lugar de cerrar la sesión. El restablecimiento de contraseña se identifica por IP de origen y usa los parámetros de bloqueo progresivo de abajo. Los contadores residen en el proceso y se reinician con él.

Clave	Variable de entorno	Valor predeterminado	Descripción
auth_rate_limit.enabled	VISION_AUTH_RATE_LIMIT_ENABLED	true	Habilita la limitación y el bloqueo de autenticación
auth_rate_limit.per_min	VISION_AUTH_RATE_LIMIT_PER_MIN	5	Intentos sostenidos por minuto por clave
auth_rate_limit.burst	VISION_AUTH_RATE_LIMIT_BURST	5	Capacidad del bucket (0 = usar per_min)
auth_rate_limit.max_failures	VISION_AUTH_RATE_LIMIT_MAX_FAILURES	5	Fallos consecutivos antes del bloqueo
auth_rate_limit.lockout_base	VISION_AUTH_RATE_LIMIT_LOCKOUT_BASE	1m	Primer bloqueo; se duplica con cada fallo adicional
auth_rate_limit.lockout_max	VISION_AUTH_RATE_LIMIT_LOCKOUT_MAX	15m	Límite del retroceso progresivo
auth_rate_limit.ttl	VISION_AUTH_RATE_LIMIT_TTL	15m	Ventana de inactividad antes de que se elimine una clave
auth_rate_limit.max_keys	VISION_AUTH_RATE_LIMIT_MAX_KEYS	4096	Límite estricto de claves rastreadas (acota la memoria)