Referencia del entorno autohospedado
Comience con el lanzamiento env.example, que descargaste como .env en Empezando. Es la configuración de Compose admitida más pequeña. uso env.full.example cuando necesita una configuración opcional; Esta página explica qué configuraciones van juntas y cuándo cambiarlas.
Después de editar .env, validar la interpolación sin imprimir la configuración resuelta:
docker compose config --quiet
no te comprometas .env, péguelo en solicitudes de soporte o exponga el resultado de docker compose config: el resultado resuelto contiene secretos.
Valores de producción requeridos
Genera cada secreto de forma independiente con openssl rand -hex 32. Mantenga los valores antiguos en cada actualización y almacene una copia de recuperación fuera del servidor.
| variable | Valor de producción | Por qué es importante |
|---|---|---|
POSTGRES_PASSWORD | Contraseña aleatoria única | Protege la base de datos PostgreSQL incluida. |
WEB_ORIGIN | Origen de la aplicación HTTPS pública, como https://kanera.example.com | Se utiliza para enlaces de navegador, CORS y flujos de autenticación. No incluya una barra diagonal. |
COOKIE_DOMAIN | Nombre de host de la aplicación, como kanera.example.com | Alcance de la cookie de actualización. |
COOKIE_SECURE | true | Requerido cuando la aplicación se entrega a través de HTTPS. |
JWT_SECRET | Secreto aleatorio estable, al menos 16 caracteres | Firma sesiones de usuario. La rotación firma la salida de todos. |
MCP_INTERNAL_SECRET | Secreto aleatorio estable, de al menos 32 caracteres y diferente de JWT_SECRET | Permite que los servicios MCP y API públicos intercambien credenciales OAuth vinculadas a la audiencia sin reenviar un token MCP a /api/v1. Ambos servicios deben utilizar siempre el mismo valor. |
MFA_ENCRYPTION_KEY | Secreto aleatorio estable, al menos 32 caracteres | Protege la inscripción y los desafíos del autenticador. La rotación invalida los autenticadores inscritos. |
MEDIA_SIGNING_SECRET | Secreto aleatorio estable, al menos 32 caracteres | Firma URL de medios privados. La rotación invalida las URL firmadas existentes. |
SECRETS_ENCRYPTION_KEY | Secreto aleatorio estable, de al menos 32 caracteres y diferente de JWT_SECRET | Cifra SMTP, almacenamiento, webhook y credenciales de integración almacenadas en la base de datos. |
KANERA_DEPLOYMENT_MODE por defecto es self_hosted. El modo alojado y sus variables Stripe, PostHog, límite de plan y licencia son para implementaciones operadas por Kanera y deben permanecer sin configurar en una instalación autohospedada.
Componer suministros NODE_ENV=production y ANALYTICS_ENABLED=false. salir ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, cada STRIPE_*, HOSTED_*y el token en modo alojado no está configurado. Estas configuraciones no convierten una instalación autohospedada en Kanera Cloud.
URL y servicios públicos
| variable | Predeterminado | Configúrelo cuando |
|---|---|---|
KANERA_ENVIRONMENT | production en producción componer | Necesita un prefijo de clave API diferente para el desarrollo, la prueba o la puesta en escena. |
API_PUBLIC_URL | WEB_ORIGIN | La API de la aplicación orientada al navegador utiliza un origen público diferente. |
KANERA_PUBLIC_API_URL | http://public-api:3001 en componer | MCP u otro proceso interno llega a la API pública en algún lugar distinto de su dirección de servicio de redacción. Esta es una URL interna, no el origen de la API orientada al navegador. |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | Expones OAuth o la API pública de forma remota; utilice su origen HTTPS accesible al navegador. |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | Expone MCP remoto; utilizar el público completo /mcp URL. |
MCP_PUBLIC_URL | Derivado de MCP_SERVER_PUBLIC_URL por componer | El servicio MCP se ejecuta fuera del cableado Compose incluido. |
OAUTH_ISSUER_URL | Derivado de PUBLIC_API_OAUTH_ISSUER por componer | El MCP se ejecuta fuera del cableado Compose incluido. |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | Ejecuta servicios fuera de Compose o necesita diferentes puertos de escucha internos. |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | Un proxy inverso confiable proporciona la IP real del cliente. Nunca confíes en los encabezados reenviados de clientes arbitrarios. |
El navegador se conecta a web; no publicar el principal api servicio. Ver Servicios y enrutamiento antes de exponer la API pública o MCP.
Cuentas y autenticación
| variable | Predeterminado | Propósito |
|---|---|---|
SIGNUPS_ENABLED | true | conjunto false para detener el registro público y la creación de nuevas organizaciones. Los enlaces de invitación a organizaciones existentes todavía funcionan. |
EMAIL_VERIFICATION_ENABLED | false | Requerir una verificación de correo electrónico de seis dígitos para el registro, el registro de invitaciones y los cambios de correo electrónico. Habilítelo solo después de que SMTP funcione. |
AUTH_RATE_LIMIT_ENABLED | true | Habilite el acelerador de fuerza bruta por IP en rutas de autenticación no autenticadas. |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | Intentos de autenticación permitidos por ventana. |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | Duración del token de acceso y de la sesión de actualización. |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | Desarmado | Protección de registro alojada. Déjelo sin configurar para el autohospedaje normal. |
Los usuarios configuran su propio autenticador en Configuración -> Tu cuenta -> Seguridad. Los administradores de la organización pueden solicitarlo en Configuración -> Organización -> Seguridad. Ver Perfil y seguridad.
Límites de API pública y MCP
| variable | Predeterminado | Propósito |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | Habilita límites de solicitudes de API pública y MCP. |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | Límite para descubrimientos no autenticados y formatos de portador no válidos. |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | Límite por IP para fallas kanera_* intentos clave. |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | Límite de solicitudes por clave después de una autenticación exitosa. |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | Límite de carga de archivos adjuntos por clave. |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | Ventana de límite de velocidad compartida por la API pública y MCP. |
MCP_BODY_MAX_BYTES | 1048576 | Cuerpo de solicitud de MCP máximo. |
MCP_REQUEST_TIMEOUT_MS | 30000 | Tiempo máximo para una solicitud de MCP. |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | Tiempos de espera de conexión HTTP de MCP. |
KANERA_API_KEY | Desarmado | Requerido solo por el puente stdio MCP local, no por el servicio HTTP MCP. |
Base de datos, caché y capacidad
Componer suministros DATABASE_URL y REDIS_URL para los servicios incluidos PostgreSQL y Valkey. Configúrelos usted mismo solo cuando ejecute un proceso fuera de esa red o utilice servicios administrados.
| variable | Redactar por defecto | Propósito |
|---|---|---|
DATABASE_SSL | false | Habilítelo solo cuando una base de datos externa requiera SSL. |
POSTGRES_BIND_PORT | 5433 | Puerto de host de solo bucle invertido para PostgreSQL incluido. |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | El proceso de servicio cuenta. Mantenga al trabajador exactamente en uno. |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | Conexiones máximas de bases de datos por proceso de aplicación y para el trabajador. |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | Tiempos de espera de adquisición e inactividad del grupo. |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | Tiempo de espera de consulta de base de datos y umbral de registro de consultas lentas. |
NODE_OPTIONS | Desarmado | Indicadores de nodo opcionales, como un límite de montón. |
UV_THREADPOOL_SIZE | 16 | Hilos de trabajo nativos utilizados por hash, criptografía y procesamiento de imágenes. |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | Comprime mensajes Socket.IO WebSocket más grandes. |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | Tamaño mínimo de fotograma en tiempo real para comprimir. |
REALTIME_OUTBOX_POLL_MS | 500 en componer | Intervalo de sondeo alternativo del trabajador para filas de bandeja de salida de webhook y en tiempo real. |
USER_DISPLAY_CACHE_TTL_MS | 60000 | Duración de la caché en proceso para búsquedas de nombres para mostrar. |
Aumente las réplicas y los grupos juntos solo después de medir la capacidad. Ver Actualizaciones y escalamiento.
Almacenamiento de archivos y objetos.
| variable | Predeterminado | Propósito |
|---|---|---|
UPLOADS_DIR | /data/uploads en componer | Directorio de carga local. Bundled Compose corrige esta ruta y la mantiene en kanera_uploads; cambiar el mapeo de volumen en lugar de .env. |
ATTACHMENT_MAX_BYTES | 104857600 | Tamaño máximo de archivos adjuntos cargados en bytes. |
S3_REGION / S3_BUCKET | Desarmado | Inicie el almacenamiento compatible con S3 en toda la implementación cuando se le proporcionen las credenciales. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | Desarmado | Credenciales para el depósito de carga. Ambos son necesarios para S3 basado en el entorno. |
S3_ENDPOINT | Desarmado | Punto final personalizado para MinIO, R2 u otro proveedor compatible con S3. Configurarlo habilita solicitudes de estilo de ruta. |
S3_PUBLIC_URL_PREFIX | Desarmado | Prefijo público o CDN opcional para objetos almacenados. |
El almacenamiento del entorno tiene prioridad sobre el almacenamiento de la organización configurado en la aplicación. Ver Almacenamiento y copias de seguridad antes de cambiar una instalación que ya tiene cargas.
Correo electrónico, notificaciones e integraciones
| variable | Predeterminado | Propósito |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | Desarmado | Conexión SMTP saliente predeterminada y remitente. |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | Puerto SMTP y transporte: starttls, tls, o none. |
SMTP_FROM_NAME | Kanera | Nombre para mostrar del remitente. |
SMTP_IDENTITY_DOMAIN | Dominio de correo electrónico del remitente | Dominio EHLO y Message-ID. |
INTERNAL_NOTIFICATION_EMAILS | Desarmado | Destinatarios separados por comas para registros de texto sin formato y alertas de invitación. Requiere entorno SMTP. |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | Permitir receptores personales de ntfy, Gotify y webhook en HTTP o redes privadas. Las direcciones reservadas y de metadatos permanecen bloqueadas. |
ALERT_WEBHOOK_URL | Desarmado | Destino compatible con Slack para alertas de preparación, tiempo de ejecución y Grafana. |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | Habilite y deduplica alertas operativas. No se envía nada sin destino. |
SLOW_REQUEST_LOG_MS | 2500 | Umbral para una advertencia de solicitud lenta en los registros. |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | Desarmado | Aplicación GitHub opcional definida por implementación para vistas previas de enlaces privados. En su lugar, los administradores autohospedados pueden utilizar el flujo de manifiesto en la aplicación. |
TRELLO_API_KEY | Desarmado | Permite que Trello importe archivos adjuntos autenticados y copiados. |
Ver Correo electrónico y notificaciones y Integraciones y API.
Copias de seguridad y retención
| variable | Predeterminado | Propósito |
|---|---|---|
DB_BACKUPS_ENABLED | false | Habilite copias de seguridad cifradas programadas de PostgreSQL en almacenamiento compatible con S3. |
DB_BACKUP_ENCRYPTION_PASSPHRASE | Desarmado | Se requiere cuando las copias de seguridad están habilitadas y se requiere nuevamente para restaurarlas. |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | Horas de respaldo UTC diarias separadas por comas. |
DB_BACKUP_RETENTION_DAYS | 14 | Ventana de retención de copia de seguridad exitosa. |
DB_BACKUP_S3_PREFIX | backups/postgres | Prefijo de objeto para volcados de bases de datos. |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | Valores de carga y almacenamiento | Destino de copia de seguridad independiente opcional. |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | Valores de carga y almacenamiento | Credenciales de copia de seguridad independientes opcionales. |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | Retención del historial de actividades. |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | Retención de registros de auditoría de gestión. |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | Notificación de lectura y retención absoluta de notificaciones. |
AUTH_TOKEN_RETENTION_DAYS | 30 | Período de gracia antes de que se eliminen los artefactos de autenticación vencidos o consumidos. |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | Retención de bandeja de salida procesada y permanentemente atascada. |
Ver Almacenamiento y copias de seguridad para requisitos de respaldo y planificación de restauración.
Monitoreo
| variable | Predeterminado | Propósito |
|---|---|---|
METRICS_ENABLED | true | Registra puntos finales de métricas de Prometheus. ellos regresan 404 sin un token válido. |
METRICS_TOKEN | Desarmado | Se requiere token de portador, al menos 16 caracteres, para el scraping. |
COMPOSE_PROFILES | Desarmado | incluir monitoring iniciar Grafana, Prometheus, Loki, Alloy y exportadores; incluir admin para el portal de gestión. |
COMPOSE_PROJECT_NAME | kanera | Redacte la identidad utilizada por Alloy para seleccionar los registros de esta implementación. comprobar docker compose ls en plataformas administradas. |
GRAFANA_ADMIN_PASSWORD | Desarmado | Requerido cuando el perfil de monitoreo está habilitado. |
MONITORING_BIND_IP | 127.0.0.1 | Interfaz de host para Grafana y Prometheus. Utilice una dirección VPN privada, nunca 0.0.0.0 en producción. |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | Puertos de host para las dos UI de monitoreo. |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Límites de tiempo y disco para datos de Prometheus. |
GRAFANA_ROOT_URL | Desarmado | URL externa de Grafana cuando se sirve a través de un proxy. |
POSTGRES_EXPORTER_DSN | Base de datos incluida | Anulación para un servidor PostgreSQL externo. |
REALTIME_EMIT_METRICS_ENABLED | false | Habilite métricas de carga útil de muestra en tiempo real. |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | Muestreo de métricas en tiempo real y tamaño mínimo de carga útil. |
Portal de gestión opcional
El portal de administración está separado de la configuración del inquilino y tiene su propio límite de autenticación. Habilítelo solo cuando los operadores necesiten administración entre organizaciones o sesiones de soporte auditadas.
| variable | Predeterminado | Propósito |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | Origen público y límite CORS para la consola de administración. |
ADMIN_API_PORT | 3002 | Puerto de escucha de API de administración interna cuando se ejecuta fuera del cableado incluido. |
ADMIN_COOKIE_DOMAIN | Desarmado | Anulación del dominio de cookies cuando el nombre de host del administrador está fuera COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | Desarmado | Requerido para la API de administración y debe diferir de JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | Desarmado | Inicialice el primer superadministrador solo mientras la tabla administrador-usuario esté vacía. No restablecen una cuenta existente. |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | Acceso de administrador y duración de actualización. |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | Acelerador de inicio de sesión de administrador por IP. |
ADMIN_TRUST_PROXY | true | Confíe en el proxy inverso del administrador para las IP de clientes reales. |
SUPPORT_SESSION_TTL_MINUTES | 60 | Duración breve de la sesión de soporte; máximo ocho horas y sin token de actualización. |
Mantenga privado el portal de administración, utilice un nombre de host y un secreto separados y revise su registro de auditoría. El cableado de implementación completo está documentado en DEPLOY.md en el repositorio de Kanera.
Aplicar y verificar cambios
La mayoría de los cambios requieren recrear los servicios afectados:
docker compose config --quiet
docker compose up -d
docker compose ps
Verifique los registros de servicio relevantes después de cambiar la configuración de autenticación, entrega, almacenamiento, API, MCP o administración. Una sintácticamente válida. .env no prueba que las credenciales externas o las URL funcionen.