COURIER_ROLES.
En las tablas, la columna Obligatoria marca una variable que debes definir, siempre o en la condición indicada. — significa sin valor predeterminado. 🔒 marca un secreto: guárdalo en tu bóveda de secretos.
Con
ENVIRONMENT_NAME=production, el Courier no arranca a menos que todo esto sea cierto: PLUGIN_AUTH_ENABLED es true, POSTGRES_PASSWORD está definida, POSTGRES_SSLMODE no es disable y ALLOW_CORS_WILDCARD no es true. Cada rol agrega sus propias verificaciones, indicadas en las tablas siguientes.Servicio y servidor
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
COURIER_ROLES | Los roles del proceso, separados por comas: spb-consumer, spb-sender, pix-ingress, admin. Un rol desconocido o repetido detiene el arranque. spb-consumer se ejecuta solo en su proceso. | — | Sí |
ENVIRONMENT_NAME | El entorno. production activa las verificaciones de producción. ENV_NAME se lee cuando ENVIRONMENT_NAME no está definida. | development | No |
DEPLOYMENT_MODE | byoc, saas o local. Otro valor detiene el arranque. | local | No |
LOG_LEVEL | El nivel de log. | info | No |
SERVER_ADDRESS | El puerto HTTP: las sondas, la API del operador, la API de los motores y la dirección Pix. | :8080 | No |
SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE | El certificado y la clave para TLS en el puerto HTTP. Define las dos o ninguna. Un proceso con spb-sender o con el tránsito Pix las rechaza, a menos que TLS_TERMINATED_UPSTREAM sea true. | — | No |
TLS_TERMINATED_UPSTREAM | true cuando TLS termina antes del puerto HTTP. | false | No |
HTTP_BODY_LIMIT_BYTES | El cuerpo de solicitud más grande en el puerto HTTP, en bytes. | 1048576 | No |
SWAGGER_ENABLED | Sirve el documento OpenAPI en la raíz del puerto HTTP. El Courier la ignora en producción. | false | No |
SYSTEMPLANE_ENABLED | Activa la configuración de runtime y su API en /system. | false | No |
INFRA_CONNECT_TIMEOUT_SEC | El límite de tiempo para conectarse a los datastores en el arranque, en segundos. | 30 | No |
IDEMPOTENCY_RETRY_WINDOW_SEC | Cuánto tiempo guarda el Courier la respuesta a una clave X-Idempotency, en segundos. | 300 | No |
ALLOW_CORS_WILDCARD | Producción rechaza true. | — | No |
PostgreSQL
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
POSTGRES_HOST | El host primario. | localhost | No |
POSTGRES_PORT | El puerto primario. | 5432 | No |
POSTGRES_USER | El usuario de la base de datos. | jd-courier | No |
POSTGRES_PASSWORD | 🔒 La contraseña de la base de datos. | — | En producción |
POSTGRES_NAME | El nombre de la base de datos. | jd-courier | No |
POSTGRES_SSLMODE | El modo TLS de libpq. Con disable, el Courier no arranca, a menos que ALLOW_INSECURE_TLS sea true. Producción rechaza disable. Usa verify-full en producción. | require | No |
POSTGRES_REPLICA_HOST, POSTGRES_REPLICA_PORT, POSTGRES_REPLICA_USER, POSTGRES_REPLICA_PASSWORD, POSTGRES_REPLICA_NAME, POSTGRES_REPLICA_SSLMODE | Una réplica de lectura opcional. Un valor que no defines toma el valor del primario. Cuando defines cualquiera de ellas, POSTGRES_REPLICA_HOST es obligatoria. Producción rechaza POSTGRES_REPLICA_SSLMODE=disable. | — | No |
POSTGRES_MAX_OPEN_CONNS | El mayor número de conexiones abiertas. | 25 | No |
POSTGRES_MAX_IDLE_CONNS | El mayor número de conexiones inactivas. | 5 | No |
POSTGRES_CONN_MAX_LIFETIME_MINS | La mayor duración de una conexión, en minutos. | 30 | No |
POSTGRES_CONN_MAX_IDLE_TIME_MINS | El mayor tiempo inactivo de una conexión, en minutos. | 5 | No |
POSTGRES_CONNECT_TIMEOUT_SEC | El límite de tiempo para abrir una conexión, en segundos. | 10 | No |
ALLOW_INSECURE_TLS | true permite que las conexiones a los datastores funcionen sin TLS. | false | No |
Access Manager
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
PLUGIN_AUTH_ENABLED | Verifica el token y el permiso de Access Manager en cada llamada. false necesita ALLOW_AUTH_DISABLED_LOCAL_ONLY=true. Producción y el modo multi-tenant rechazan false. | true | No |
PLUGIN_AUTH_HOST | La dirección de tu Access Manager. | — | Cuando PLUGIN_AUTH_ENABLED es true |
ALLOW_AUTH_DISABLED_LOCAL_ONLY | Permite que PLUGIN_AUTH_ENABLED=false arranque, solo en la máquina de un desarrollador. | false | No |
AUTH_M2M_INVERSION_ENABLED | Vincula cada llamada de motor a la identidad que Access Manager verificó. Con false, el Courier rechaza cada credencial de motor con 401, y un proceso de producción con el rol admin no arranca. | true | No |
AUTH_M2M_PRODUCT_FORWARD_ENABLED | Envía el nombre de producto del Courier a Access Manager cuando autoriza una llamada de motor. | true | No |
AUTH_TIMEOUT, AUTH_CACHE_TTL, AUTH_RETRY_MAX, AUTH_BREAKER_ENABLED, AUTH_REQUIRED, AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED, AUTH_JWT_VERIFY_CERT, AUTH_JWT_VERIFY_CERT_PATH, AUTH_JWT_ISSUER | La configuración del cliente de Access Manager. Un valor que no es válido detiene el arranque. | Los valores predeterminados del cliente | No |
IDP_DECLARATION_ENABLED | En modo single-tenant, true publica en tu Access Manager los permisos del Courier y su adhesión a socios. Sin valor o false, publica solo la adhesión a socios. | — | No |
IDP_HOST | La dirección del servicio de identidad de Access Manager, donde el Courier los publica. | — | Para la publicación |
IDP_M2M_CLIENT_ID | El client ID de la aplicación que los publica. | — | Para la publicación |
IDP_M2M_CLIENT_SECRET | 🔒 El secret de esa aplicación. | — | Para la publicación |
Canal SPB de JD
Los rolesspb-consumer y spb-sender leen estas variables.
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
JD_BASE_URL | La dirección del servicio SPB de JD. Usa https en producción. | — | En producción, en modo single-tenant |
JD_SOAP_PATH | La ruta del servicio SOAP de JD. | /soap | No |
JD_LEGACY_CODE | La credencial JD que ya tienes. Como máximo 10 bytes. | — | En producción, en modo single-tenant |
JD_USER_CODE | La credencial JD que ya tienes. Como máximo 10 bytes. | — | En producción, en modo single-tenant |
JD_PASSWORD | 🔒 La credencial JD que ya tienes. Como máximo 20 bytes. | — | En producción, en modo single-tenant |
SPB_VENDOR_TIMEOUT | Cuánto tiempo espera el Courier a JD. Debe ser mayor que cero y menor que 8s. | 7s | No |
JD_ALLOW_PRIVATE_NETWORK | true permite que el Courier se conecte a JD en una dirección de red privada, para el canal SPB y la cabina SPI. Producción la acepta. | false | No |
JD_PRIVATE_KEY_PEM | No debe estar presente en producción. El Courier no firma nada. | — | No |
Interfaz SOAP
El rolspb-sender lee estas variables.
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
SOAP_SERVER_ADDRESS | El puerto SOAP. | :8081 | No |
SOAP_MAX_BODY_BYTES | El cuerpo de solicitud SOAP más grande, en bytes. | 10485760 | No |
SOAP_TLS_CERT_FILE, SOAP_TLS_KEY_FILE | El certificado y la clave para TLS en el puerto SOAP. Define las dos o ninguna. La versión mínima de TLS es 1.2. | — | En producción, a menos que SOAP_TLS_TERMINATED_UPSTREAM sea true |
SOAP_TLS_TERMINATED_UPSTREAM | true cuando TLS termina antes del puerto SOAP. | false | No |
SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP | Cuánto tiempo siguen funcionando las credenciales SOAP y del tránsito Pix anteriores de un motor después de que el operador emite una nueva. El rol admin la lee cuando emite una credencial. spb-sender rechaza un valor que no es positivo. | 24h | No |
Tránsito Pix
El roladmin lee estas variables.
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
PIX_TRANSIT_SERVER_ADDRESS | La dirección del tránsito Pix. Cuando está vacía, el Courier no sirve tránsito. | — | Para el tránsito |
PIX_TRANSIT_TLS_CERT_FILE, PIX_TRANSIT_TLS_KEY_FILE | El certificado y la clave para TLS en el tránsito. Define las dos o ninguna. La versión mínima de TLS es 1.2. | — | En producción, a menos que PIX_TRANSIT_TLS_TERMINATED_UPSTREAM sea true |
PIX_TRANSIT_TLS_TERMINATED_UPSTREAM | true cuando TLS termina antes del tránsito. | false | No |
JD_SPI_BASE_URL | En modo single-tenant, la dirección de la cabina SPI de JD. Usa https en producción. | — | Para el tránsito |
JD_SPI_CLIENT_ID | En modo single-tenant, el client ID de la credencial de la cabina SPI de tu institución. | — | Para el tránsito |
JD_SPI_CLIENT_SECRET | 🔒 En modo single-tenant, el secret de esa credencial. | — | Para el tránsito |
JD_SPI_USE_SERVICE_SEGMENTS | true cuando JD sirve la cabina SPI por las rutas de su gateway: el Courier entonces pide su token en /auth y envía los resultados de las validaciones de cuenta en /spi-api. | false | No |
Drenaje de SPB
El rolspb-consumer lee estas variables. SPB_TAKE_BUDGET_SEC más el mayor entre SPB_IDLE_INTERVAL_SEC y SPB_EMPTY_BACKOFF_CAP_SEC debe quedar por debajo de SPB_LEASE_TTL_SEC.
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
POD_NAME | El nombre del titular del lease de lectura. Cuando está vacío, el Courier usa el nombre del host. | — | No |
SPB_LEASE_TTL_SEC | Cuánto dura el lease de lectura sin una renovación, en segundos. | 30 | No |
SPB_TAKE_BUDGET_SEC | El mayor tiempo para tomar un mensaje de JD, en segundos. Debe ser al menos SPB_VENDOR_TIMEOUT. | 15 | No |
SPB_IDLE_INTERVAL_SEC | La espera mientras el drenaje no lee, en segundos. | 5 | No |
SPB_EMPTY_BACKOFF_CAP_SEC | La mayor espera después de que JD informa una cola vacía, en segundos. | 10 | No |
SPB_PERSIST_TIMEOUT_SEC | El límite de tiempo de un intento de guardar un mensaje, en segundos. | 60 | No |
SPB_TENANT_REFRESH_SEC | Con qué frecuencia el drenaje lee de nuevo la lista de tenants, en segundos. | 30 | No |
SPB_MESSAGE_SIZE_ALERT_BYTES | Un mensaje más grande que esto escribe una advertencia. El Courier lo guarda. | 1048576 | No |
Pix y credenciales de los motores
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
AWS_REGION | La región de AWS de AWS Secrets Manager, donde el Courier lee las credenciales que usa en los motores. | us-east-1 | No |
Licencia
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
LICENSE_KEY | 🔒 Tu clave de licencia de Lerian. | — | Sí |
ORGANIZATION_IDS | El ID de tu organización. | — | No |
APPLICATION_NAME | El nombre de producto que usa la verificación de la licencia. Déjala sin valor: el Courier entonces usa su propio nombre de producto. | — | No |
Multi-tenancy
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
MULTI_TENANT_ENABLED | Activa el modo multi-tenant. | false | No |
MULTI_TENANT_URL | La dirección del Tenant Manager. | — | En modo multi-tenant |
MULTI_TENANT_SERVICE_API_KEY | 🔒 La clave del Courier en el Tenant Manager. | — | En modo multi-tenant |
MULTI_TENANT_REDIS_HOST | El host Redis de la caché de tenants. | — | En modo multi-tenant |
MULTI_TENANT_REDIS_PORT | El puerto Redis. | 6379 | No |
MULTI_TENANT_REDIS_PASSWORD | 🔒 La contraseña de Redis. | — | No |
MULTI_TENANT_REDIS_TLS | Conecta a Redis con TLS. | false | No |
MULTI_TENANT_MAX_TENANT_POOLS | El mayor número de pools de conexión de tenant. | 100 | No |
MULTI_TENANT_IDLE_TIMEOUT_SEC | Cuánto tiempo queda abierto un pool de tenant inactivo, en segundos. | 300 | No |
MULTI_TENANT_TIMEOUT | El límite de tiempo de una llamada al Tenant Manager, en segundos. | 30 | No |
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD | Las fallas que abren el circuit breaker del Tenant Manager. | 5 | No |
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC | Cuánto tiempo queda abierto el circuit breaker, en segundos. | 30 | No |
MULTI_TENANT_CACHE_TTL_SEC | Cuánto tiempo guarda el Courier la configuración de un tenant, en segundos. | 120 | No |
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC | Con qué frecuencia el Courier verifica las conexiones de tenant, en segundos. | 30 | No |
Telemetría
| Variable | Descripción | Predeterminado | Obligatoria |
|---|---|---|---|
ENABLE_TELEMETRY | Activa OpenTelemetry. | true | No |
OTEL_EXPORTER_OTLP_ENDPOINT | La dirección del colector OTLP. | localhost:4317 | No |
OTEL_RESOURCE_SERVICE_NAME | El nombre del servicio en la telemetría. | jd-courier | No |
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT | El nombre del entorno en la telemetría. | development | No |
OTEL_LIBRARY_NAME | El nombre de la biblioteca de instrumentación en la telemetría. | El nombre del módulo del Courier | No |
OTEL_TRUST_INBOUND_TRACE_CONTEXT | Continúa el trace que envía un llamador. Define true solo detrás de un gateway en el que confías. | false | No |