Variables d'environnement
bext lit les variables d'environnement au démarrage. Un ensemble organisé de variables BEXT_* remplace la valeur correspondante dans bext.config.toml, vous offrant ainsi un moyen propre d'injecter des secrets et une configuration par environnement sans modifier les fichiers de configuration - le modèle à 12 facteurs attendu par les déploiements de conteneurs et PaaS.
Priorité#
Les valeurs de configuration sont résolues dans cet ordre (la priorité la plus élevée en premier) :
- Variables d'environnement (par exemple
BEXT_LISTEN,PORT) - Fichier de configuration (
bext.config.toml) - Valeurs par défaut (intégrées au binaire)
Une variable d'environnement remplace toujours la valeur du fichier de configuration correspondante.
Remarque
En mode mascarade, bext dérive ses auditeurs et TLS de vos hôtes virtuels nginx, donc BEXT_LISTEN et BEXT_TLS_* n'y ont aucun effet. Utilisez-les uniquement dans les déploiements bext run / bext serve autonomes.
Portée#
Les remplacements s'appliquent lorsque bext charge un bext.config.toml pour le serveur autonome ( bext run, bext serve et lors du rechargement de SIGHUP). En mode mascarade , bext dérive ses auditeurs et TLS de vos hôtes virtuels nginx, donc BEXT_LISTEN / BEXT_TLS_* ne s'y appliquent pas.
Chaque ligne des tableaux ci-dessous indique le champ bext.config.toml qu'elle remplace. Les variables sans note « remplace … » ( DATABASE_URL, REDIS_URL, BEXT_LICENSE_KEY, BEXT_STORAGE_*, BEXT_CLOUD_*, DOTENV_PATH, NODE_ENV, RUST_LOG ) sont consommées directement plutôt que superposées sur un champ de configuration.
Référence des variables#
Serveur#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_CONFIG |
Chemin d'accès au fichier de configuration | bext.config.toml |
/etc/bext/bext.config.toml |
BEXT_LISTEN |
Adresse d'écoute ( host:port ); remplace [server] listen |
0.0.0.0:3061 |
127.0.0.1:8080 |
PORT |
Port d'écoute uniquement : conserve l'hôte configuré, échange le port (convention PaaS ; BEXT_LISTEN gagne si les deux sont définis) |
3061 |
3000 |
BEXT_STATIC_DIR |
Répertoire des actifs statiques ; remplace [server] static_dir |
(aucun) | /var/www/static |
BEXT_MAX_BODY_SIZE_MB |
Taille maximale du corps de la requête, en mégaoctets ; remplace [waf] max_body_size_bytes et le plafond de charge utile |
10 |
50 |
BEXT_WAF_CRAWLER_RPM |
Limitation globale intégrée pour les robots d'exploration agressifs hors recherche (un budget partagé par minute ; moteurs de recherche + utilisateurs réels jamais égalés). 0 est désactivé. Voir Sécurité |
0 |
30 |
Rendu / SSR#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_BUNDLE_PATH |
Chemin d'accès au bundle SSR ; remplace [render] bundle_path |
(aucun) | /app/dist/server/index.js |
BEXT_RENDER_WORKERS |
Nombre d’isolats de travailleurs V8 SSR ; remplace [render] workers |
4 |
8 |
BEXT_V8_POOL |
Utilisez le pool de tâches de rendu multiplexé (réponses démultiplexées par ID de demande) au lieu de l'ancien client à poste unique. Le client sérialisé limite un travailleur à un rendu en cours, mettant le thread de rendu au ralenti entre les allers-retours IPC, ce qui permet au pool de mesurer un débit de travail unique environ 7 fois plus élevé. Activé par défaut sous bext run. 0 revient |
1 (bext run) |
1 |
BEXT_V8_POOL_SIZE |
Rendu les ouvriers que le pool apparaît (bridés 1 à 16) ; sous bext run, il suit [render] workers. Un travailleur sature déjà le maître sur les routes liées aux IO/maître ; mise à l'échelle pour le SSR gourmand en CPU (le pool évolue ~ de manière linéaire) |
min(workers, 16) |
8 |
BEXT_V8_SHM_IPC |
Renvoie le corps de la réponse de rendu via la mémoire partagée plutôt que via le socket IPC de travail - enregistre une écriture + lecture de socket par requête (les corps plus grands en bénéficient le plus). Activé par défaut sous bext run. 0 revient |
1 (bext run) |
1 |
BEXT_V8_ASYNC_EVAL |
Attendez le pool de rendu directement sur le travailleur HTTP au lieu de garer un thread spawn_blocking sur l'aller-retour IPC. Libère le travailleur pendant que le rendu est en cours et réduit de moitié les changements de contexte par requête, de sorte que le pool multiplexé évolue au-delà d'un seul travailleur (un pool de blocage régresse). Couvre les gestionnaires /api/* mis en mémoire tampon et les rendus de page. Nécessite le pool ( BEXT_V8_POOL=1 ). Activé par défaut sous bext run. 0 revient |
1 (bext run) |
1 |
TLS#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_TLS_CERT |
Chemin d'accès au certificat TLS (PEM) ; remplace [tls] cert |
(aucun) | /etc/ssl/certs/domain.pem |
BEXT_TLS_KEY |
Chemin d'accès à la clé privée TLS (PEM) ; remplace [tls] key |
(aucun) | /etc/ssl/private/domain.key |
BEXT_ACME_EMAIL |
E-mail pour l'enregistrement du compte ACME ; remplace [tls] acme_email |
(aucun) | admin@example.com |
Cache#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_CACHE_MAX_ENTRIES |
Nombre maximal d'entrées de cache ISR ; remplace [cache.isr] max_entries |
10000 |
50000 |
BEXT_CACHE_TTL_MS |
Durée de vie du cache ISR par défaut en millisecondes ; remplace [cache.isr] default_ttl_ms |
60000 |
300000 |
BEXT_CACHE_SWR_MS |
Fenêtre périmée par défaut lors de la revalidation (ms) ; remplace [cache.isr] default_swr_ms |
3600000 |
86400000 |
Base de données#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
DATABASE_URL |
URL de connexion PostgreSQL (utilisée lorsque [database] url n'est pas défini) |
(aucun) | postgres://user:pass@db:5432/bext |
BEXT_DB_POOL_SIZE |
Connexions maximales à la base de données ; remplace [database] max_connections |
(pool par défaut) | 25 |
Redis#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
REDIS_URL |
URL de connexion Redis pour le cache L2 et les fonctionnalités distribuées (utilisée lorsque [redis] url n'est pas défini) |
(aucun) | redis://redis.internal:6379/0 |
Enregistrement#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_LOG_LEVEL |
Niveau de journalisation simple appliqué lorsque RUST_LOG n'est pas défini ( error / warn / info / debug / trace ) |
info |
debug |
RUST_LOG |
Filtre de journal à granularité fine (syntaxe standard tracing) ; a priorité sur BEXT_LOG_LEVEL |
info |
warn,bext_server=debug |
Licence#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_LICENSE_KEY |
Clé de licence pour les fonctionnalités Pro ou Enterprise | (aucun) | BEXT-PRO-eyJ0aWVy... |
Stockage et sauvegardes#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_STORAGE_PROVIDER |
Back-end de stockage d'objets | local |
s3, r2 |
BEXT_STORAGE_BUCKET |
Nom du compartiment S3/R2 | (aucun) | my-bext-backups |
BEXT_STORAGE_REGION |
Région AWS (ignorée pour R2) | us-east-1 |
eu-west-1 |
BEXT_STORAGE_ENDPOINT |
Point de terminaison personnalisé (obligatoire pour R2/MinIO) | (aucun) | https://ACCT.r2.cloudflarestorage.com |
BEXT_STORAGE_ACCESS_KEY |
Clé d'accès S3/R2 | (aucun) | AKIA... |
BEXT_STORAGE_SECRET_KEY |
Clé secrète S3/R2 | (aucun) | wJalr... |
Synchronisation cloud ( nginx )#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_CLOUD_URL |
URL de l'API bext cloud | http://localhost:3025 |
https://cloud.bext.dev |
BEXT_CLOUD_API_KEY |
Clé API pour l'authentification CLI-to-cloud | (aucun) | my-secret-key |
Performances du PRISM et rechargement en direct#
Expédié le 2026-06-12. Celles-ci correspondent par défaut aux valeurs éprouvées en production ; définissez-le sur 0 pour vous désinscrire. Ils s'appliquent à la pile PRISM / turbopack + V8.
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
BEXT_TURBOPACK_DISK_CACHE |
Cache persistant du bundle compilé sur disque : survit au redémarrage, de sorte qu'un redéploiement sert des routes inchangées à partir du disque (~ 80 µs) au lieu d'une recompilation (~ 8 ms) | sur | 0 |
BEXT_TURBOPACK_DISK_CACHE_DIR |
Répertoire de cache de compilation de disque | /var/cache/bext/compile |
/mnt/cache/compile |
BEXT_TURBOPACK_DISK_CACHE_MAX_ENTRIES |
Limite d'entrée du cache de compilation du disque (la plus ancienne élaguée) | 4096 |
8192 |
BEXT_V8_BYTECODE_DISK_CACHE |
Bytecode V8 persistant (code-cache) sur le disque : restauration des builds de contexte après le redémarrage via ConsumeCodeCache au lieu d'une nouvelle analyse |
sur | 0 |
BEXT_V8_BYTECODE_DISK_CACHE_DIR |
Répertoire de cache de bytecode | /var/cache/bext/bytecode |
/mnt/cache/bytecode |
BEXT_MASQUERADE_ROUTE_WATCH |
Surveillance d'itinéraire maître par site : les nouveaux itinéraires et modifications sont mis en ligne environ 2 s sans redémarrage/purge | sur | 0 |
BEXT_MASQUERADE_ROUTE_WATCH_MS |
Intervalle d'interrogation de Route-Watcher (ms) | 2000 |
1000 |
BEXT_WORKER_CONSOLE_LOG |
Mettre en miroir le travailleur console.* vers des fichiers par site (également servi via GET /__bext/sdk/logs?site=<s>) |
sur | 0 |
BEXT_WORKER_CONSOLE_DIR |
Répertoire des journaux de la console de travail par site | /var/log/bext/console |
/var/log/bext-console |
BEXT_PRISM_SOURCEMAPS |
Émettre + composer des mappages sources pour les rendus PRISM afin que les traces de la pile V8 soient mappées au TSX d'origine dans la superposition de développement (développement uniquement ; association avec BEXT_TURBOPACK_DISK_CACHE=0) |
désactivé | 1 |
BEXT_TURBOPACK_COMPILE_SINGLEFLIGHT |
Compilations simultanées de déduplication du même module | sur | 0 |
BEXT_TURBOPACK_PIPE_POOL_SIZE |
Taille du pool de tâches tsc-rs --pipe |
min(cores, 4) |
8 |
Pour les indicateurs de résilience du pool V8 (disjoncteur, délai de rendu, voies de streaming, etc.), voir Moteur de rendu V8 et Piscine de rendu V8.
Divers#
| Variable | Description | Défaut | Exemple |
|---|---|---|---|
DOTENV_PATH |
Chemin d'accès au fichier .env |
.env |
/etc/bext/.env.production |
BEXT_UPGRADE_FDS |
Socket FD pour une mise à niveau sans temps d'arrêt (défini automatiquement) | (aucun) | 3,4 |
BEXT_UPGRADE_OLD_PID |
Ancien PID de processus lors de la mise à niveau (défini automatiquement) | (aucun) | 12345 |
NODE_ENV |
Transmis aux bundles et plugins SSR | production |
development |
Utilisation des fichiers .env#
bext charge automatiquement un fichier .env depuis le répertoire de travail au démarrage :
# .env
BEXT_LICENSE_KEY=BEXT-PRO-eyJ0aWVy...
DATABASE_URL=postgres://user:pass@db:5432/bext
REDIS_URL=redis://localhost:6379/0
Remplacez le chemin du fichier .env :
DOTENV_PATH=/etc/bext/.env.production bext-server run
Les variables de .env ne remplacent pas les variables d'environnement du système d'exploitation existantes. Cela signifie que vous pouvez définir des secrets dans l'environnement du système d'exploitation et utiliser .env uniquement pour les valeurs par défaut non sensibles.
Notes de sécurité#
- Ne soumettez jamais les fichiers
.envcontenant des secrets au contrôle de version. Ajoutez.envà votre.gitignore. - Préférez
BEXT_LICENSE_KEYcomme variable d'environnement plutôt que de mettre la clé dansbext.config.toml, en particulier dans les environnements conteneurisés. - Le tableau de bord d'administration est activé via le paramètre de configuration
[admin] enabled = true(ou[endpoints] admin = true), et non une variable d'environnement. Lorsqu'ils sont désactivés, les points de terminaison d'administration renvoient 404. Voir Points de terminaison et informations d'identification. - Pour Kubernetes, utilisez Secrets ou un gestionnaire de secrets externe (Vault, AWS Secrets Manager) pour injecter des variables sensibles.
En rapport#
- bext.config.toml — les champs de configuration que ces variables remplacent
- Moteur de rendu V8 — Indicateurs de résilience du pool V8 (
BEXT_V8_*,BEXT_RENDER_DEADLINE_MS) - Architecture : pool de rendu V8 — indicateurs de réglage du pool référencés à partir de la table PRISM
- Docker — transmission de variables via
environmentetenv_file - Points de terminaison et informations d'identification — activation/désactivation du panneau d'administration (config, pas variable d'environnement)