Aller au contenu principal

Variables environnementales clés

Cette page décrit les variables environnementales qui modifient réellement le déploiement et l'exploitation quotidienne du service : surveillance de service, base de données, clés, limites, liaison de services externes, composition de couches et bac à sable sidecar. Les paramètres de contrôle du comportement interne du système (parallèlement, réessai, taille de lot, lecture du rythme du cycle, etc.) ne sont pas disponibles sur cette page, voir Variable environnementale optimale

La plupart des installations ne nécessitent pas de configuration individuelle.

Utilisation officielle Déploiement de Docker Compose Lorsque la grande majorité des variables ont été remplies par le fichier compose, vous n'avez généralement besoin que de .env Il comporte trois conditions obligatoires : POSTGRES_PASSWORDREDIS_PASSWORDJWT_SECRET Les autres variables peuvent être consultées sur cette page.

Durée du format

Toutes les variables de longueur (comme ACCESS_TTLREFRESH_TTL Utilisation du format Go duration : numéros plus unités, support s des secondes, m des minutes), h Il peut être combiné (comme 1h30m * * Non pas d Unité : 30 jours à écrire. 720h

1 La base des services

VariableValeur par défautExpliquer
AIVORY_LISTEN:8787Surveillance des adresses de service. Surveillance par défaut des ports 8787 pour toutes les cartes réseau; n'écrivez que lorsque vous voulez lier votre ordinateur natif 127.0.0.1:8787
AIVORY_ENVdevelopmentIdentification de l’environnement : mise en place production Une évaluation de sécurité au niveau du déploiement est déclenchée après une valeur non dev (voir ci-dessous). JWT_SECRET règles de démarrage).
STATIC_DIR( le vide )Lorsque vous dirigez vers un répertoire front-end SPA, le processus API serve la page front-end sur le même port. L'image de production est intégrée dans le répertoire et n'a pas besoin d'être configurée.

** Choisir un trou habituel ** Le déploiement de la production doit être AIVORY_ENVétablies pour production Dans le cas contraire, une partie des évaluations de sécurité qui n’est valide que dans l’environnement de déploiement ne sera pas activée. STATIC_DIR Ce n'est nécessaire que lorsque vous construisez votre propre front-end et que vous voulez que l'API héberge directement des fichiers statiques ; ne le déplacez pas lorsque vous utilisez un miroir officiel. /api Il s’agit d’une méthode recommandée qui permet d’éviter la configuration transfrontalière.

Base de données et cache

VariableValeur par défautExpliquer
DATABASE_URL./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)La chaîne de connexion de base de données est le chemin de fichier SQLite par défaut (avec les paramètres WAL et busy_timeout); pour postgres:// Il a commencé par PostgreSQL.
REDIS_URL( le vide )Chaîne de connexion Redis. Utilisez le cache et la cohorte dans le processus lorsqu'il est vide; activez le cache Redis, la cohorte de tâches et la récupération de flux après avoir été configuré.
QDRANT_URL( le vide )Qdrant adresse de la bibliothèque vectorielle. Désactiver la récupération du vecteur lorsqu'il est vide, RAG retourne à l'intégralité de l'injection.
QDRANT_API_KEY( le vide )Accédez à la clé API de Qdrant pour la configuration du serveur Qdrant.

DATABASE_URL Deux exemples de formes :

# SQLite(单机小规模,详见 SQLite 模式文档)
DATABASE_URL="./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"

# PostgreSQL(compose 部署默认形态)
DATABASE_URL="postgres://aivory:你的密码@postgres:5432/aivory"
DATABASE_URL Déterminer plus de bases de données

DATABASE_URL Est-ce pour postgres:// Le préfixe est également l'une des entrées pour déterminer si vous êtes dans un environnement de déploiement : une fois que vous vous connectez à PostgreSQL, il est obligatoire de le lancer. JWT_SECRET En outre, il n'y a pas de migration automatique de données entre SQLite et PostgreSQL, passez par Sauvegarde et migration Exporter les données.

** Choisir un trou habituel ** Vous pouvez travailler seul ou en petit groupe. Modèle SQLite Zéro dépendance externe ; les environnements de production multi-utilisateur suggèrent PostgreSQL + Redis + Qdrant (composer par défaut). REDIS_URL La dégradation des capacités des cohortes dépendantes, telles que la récupération de flux d'espace, est réalisée dans le processus, et Redis doit être configuré lors du déploiement de plusieurs copies. QDRANT_URL Le vide n'affecte pas la disponibilité de la fonction de base de connaissances, mais la qualité de la récupération se dégrade à l'injection de l'intégralité du document, l'effet du volume du document et la consommation de jetons se détériorent.

Sécurité et séance

VariableValeur par défautExpliquer
JWT_SECRET( le vide )Émettre les clés pour accéder/renouveler les jetons. Voir les avertissements ci-dessous pour le démarrage des règles de vérification.
ACCESS_TTL30mLes jetons d'accès sont valides au format Go duration.
REFRESH_TTL720hLa période de validité par défaut de la mise à jour est de 720 heures, soit 30 jours.
ALLOWED_ORIGINShttp://localhost:5173,http://127.0.0.1:5173Permet l'accès à la liste blanche d'origine de l'API sur plusieurs domaines, avec séparation de signes. Le déploiement de la séparation avant et arrière est uniquement requis; le déploiement de conteneur unique à la source n'a pas besoin d'être configuré.
Règles de test de démarrage de JWT_SECRET

Pas d’environnement de développement JWT_SECRET Le service génère automatiquement une clé temporaire aléatoire. ** Chaque réinitialisation entraîne l’annulation de toutes les sessions de connexion. ** Lorsque le système « semble être un environnement de déploiement »AIVORY_ENV une valeur non dev, ou DATABASE_URL Lorsqu'il s'agit de PostgreSQL), une clé d'au moins 32 caractères doit être définie explicitement, sinon le service refusera de démarrer.

openssl rand -base64 48

Ne le remplacez pas volontairement une fois que la clé est mise en production : l'état de connexion de tous les utilisateurs est immédiatement invalide après le remplacement.

** Choisir un trou habituel **: ACCESS_TTL Le raccourcissement de la fenêtre réduit les fuites de jetons, mais augmente la fréquence de rafraîchissement. REFRESH_TTL Déterminer combien de temps l’utilisateur « n’a pas besoin de se connecter à nouveau ». ALLOWED_ORIGINS C'est un trou fréquent pour les débutants: le déploiement de la même source (recommandé) n'est pas complètement compatible; il suffit d'ajouter l'original du premier bout lorsqu'il est déployé séparément sur un autre nom de domaine et de l'écrire complètement. scheme://host[:port] Ne prenez pas le chemin et la trajectoire.

Stockage et limites

VariableValeur par défautExpliquer
UPLOAD_DIR./data/uploadsL'utilisateur télécharge un répertoire de stockage des documents.
ARTIFACT_DIR./data/artifactsCatalogue de stockage des produits générés (code exécutant le fichier de sortie, etc.).
BACKUP_DIR./data/backupsCatalogue de stockage des documents de sauvegarde.
MAX_UPLOAD_BYTES52428800Le plafond de téléchargement de fichiers individuels est de 50 Mo par défaut. Les administrateurs peuvent également resserrer les images/fichiers séparément dans ce plafond.
MAX_BACKUP_BYTES21474836480La taille de la sauvegarde importée est limitée par défaut à 20 GiB.
DAILY_MESSAGE_LIMIT200Limitation du nombre de messages par utilisateur par jour.
IMAGE_DAILY_LIMIT30La limite du nombre de générations d'images par utilisateur par jour.

** Choisir un trou habituel ** Trois catalogues sont disponibles. ./data Dans le cadre du déploiement de la composition, l’hôte DATA_DIR Pour accrocher le volume, assurez-vous qu'il dispose d'espace disque suffisant et qu'il est inclus dans la stratégie de sauvegarde. MAX_UPLOAD_BYTES C'est le plafond du serveur, la limite d'image / de fichier de la console d'administration ne peut être plus petite que celle-ci et ne peut pas être agrandie; si vous agrandissez ici, vous pouvez également synchroniser le plafond de la requête de proxy inverse (par exemple Nginx). client_max_body_size Dans le cas contraire, la demande sera d’abord interrompue par l’agent. Proxy inverseDAILY_MESSAGE_LIMITIMAGE_DAILY_LIMIT Il s'agit d'un ajustement global par défaut pour les quotas pour les utilisateurs individuels. Utilisateurs et quotas dans l’opération.

5 - Services externes

VariableValeur par défautExpliquer
SEARCH_PROVIDER( le vide )Recherche à l’arrière-plan, comme serper Il peut également être configuré dans la console d'administration.
SEARCH_API_KEY( le vide )Rechercher la clé API à l'arrière.
SEARCH_BASE_URL( le vide )Adresse personnalisée pour la recherche en arrière-plan (utilisée lors de la création d'une passerelle personnalisée ou d'un agent).
EMBEDDING_BASE_URL( le vide )L’adresse API du service d’embedding, l’interface compatible avec OpenAI.
EMBEDDING_API_KEY( le vide )La clé API intégrée au service.
EMBEDDING_MODELtext-embedding-3-smallLe modèle d’embedding.
EMBEDDING_DIM1536Introduction à la dimension vectorielle.
MINERU_API_URL( le vide )Adresse de service MinerU pour la résolution OCR de la version PDF numérisée.compose remplit par défaut https://mineru.net
MINERU_API_KEY( le vide )La clé API de MinerU.
SANDBOX_BASE_URL( le vide )Code bac à sable sidecar.compose par défaut http://sandbox:8000
SANDBOX_API_KEY( le vide )La clé partagée pour communiquer avec bac à sable sidecar.compose utilise les valeurs partagées par défaut aivory-bundled-sandbox
ENABLE_MOCK_PROVIDERfalseEntrée à partir de compose pour activer le modèle de démonstration intégré (l'expérience de l'interface sans une API de modèle réel).
EMBEDDING_DIM doit correspondre à la dimension réelle du modèle

L’assemblage est fixé sur des dimensions fixes, EMBEDDING_DIMEMBEDDING_MODEL Lorsque les dimensions de sortie réelles ne sont pas cohérentes, le vecteur écrira et récupère des erreurs. Lorsque vous remplacez le modèle d'embedding, vous devez le modifier en synchronisation et le vecteur ancien de la bibliothèque n'est pas compatible avec la nouvelle dimension, il faut reconstituer l'indice de base de connaissances par défaut. text-embedding-3-small Il correspond à 1536 V.

** Choisir un trou habituel ** Les services de recherche et d’emballage ne sont pas nécessaires, et les fonctionnalités correspondantes (recherche réseau, récupération vectorielle) ne sont pas automatiquement dégradées ou disponibles lors de la configuration. SEARCH_* Prise en charge dans la configuration de la console d'administration, les variables de l'environnement et l'arrière-plan peuvent être sélectionnés, l'avantage de la configuration de fond est que le changement ne nécessite pas de redémarrer le conteneur, voir Console d'administration La fonctionnalité d'exécution du code n'est pas disponible pour les deux variables bac à sable; sidecar est lancé avec le kit lorsqu'il est officiel compose et n'a pas besoin d'une configuration manuelle, mais** s'il est exposé au bac à sable dans un environnement hors réseau, assurez-vous d'effectuer SANDBOX_API_KEY Passez de la valeur par défaut partagée à la clé forte aléatoire** (modification de la synchronisation du côté de la page, voir section 8), pour plus de détails. Déploiement du code bac à sableENABLE_MOCK_PROVIDER Utilisé uniquement pour la démonstration et la vérification du déploiement, le maintien de l'environnement de production false

Noms de domaine multiples OAuth

VariableValeur par défautExpliquer
OAUTH_CALLBACK_BASE_URL( le vide )Lors du déploiement de plusieurs noms de domaine, fixer le seul outil utilisé pour les retours OAuth scheme://host
OAUTH_RETURN_ORIGINS( le vide )Une fois la connexion interdomaine terminée, la permission de sauter à la liste blanche de l'origine, séparation de signes.

** Choisir un trou habituel **: Le déploiement d'un seul nom de domaine ne nécessite pas de configuration. Lorsque le même ensemble de services est accessible par plusieurs noms de domaine et que les fournisseurs OAuth (tels que GitHub/Google) n'autorisent l'enregistrement que d'adresses de rétroaction fixes, il est possible de OAUTH_CALLBACK_BASE_URL C'est le nom de domaine que vous avez enregistré auprès du fournisseur; les utilisateurs peuvent revenir à leur nom de domaine d'origine après s'être connectés à d'autres noms de domaine et les ajouter. OAUTH_RETURN_ORIGINS Les origines en dehors de la liste blanche ne seront pas sautées, ce qui est un design de sécurité anti-ouverture et de redirection, qui se traduit par une "connexion réussie mais pas retour à la page d'origine".

Variable de la couche composite (.env)

Les variables suivantes sont écrites dans le répertoire racine de compose. .env Dans les documents, par docker-compose.yml Démarrez les configurations d'injection des conteneurs et non celles que le processus Aivory lit directement :

VariableValeur par défautExpliquer
IMAGE_OWNERhjxwz123Le propriétaire du miroir, pour ghcr.io/<IMAGE_OWNER>/aivory-app Modifier le nom du miroir lors de l'utilisation d'un entrepôt de miroir.
IMAGE_TAGlatestL’environnement de production suggère de verrouiller un numéro de version spécifique (par exemple 2.2.0) et non latest
POSTGRES_USERaivoryNom d’utilisateur PostgreSQL.
POSTGRES_PASSWORDobligatoire)Un mot de passe PostgreSQL, sans valeur par défaut, doit être rempli pour la première déploiement.
POSTGRES_DBaivoryBase de données PostgreSQL.
REDIS_PASSWORDobligatoire)Un mot de passe Redis, sans valeur par défaut, doit être rempli pour la première déploiement.
QDRANT_API_KEYaivory-internal-qdrantLa clé API de Qdrant, le conteneur app partage la même valeur que le conteneur qdrant.
JWT_SECRETobligatoire)Envoyé directement au conteneur de l'application, voir la section 3 des règles.
DATA_DIR./dataCatalogue de données de l'hôte, qui affiche des données persistantes pour chaque conteneur.

** Choisir un trou habituel **: POSTGRES_PASSWORDREDIS_PASSWORDJWT_SECRET Trois n’ont pas de valeur par défaut. .env Toute défaillance entraînera une défaillance du démarrage, ce qui est intentionnellement conçu pour empêcher l'immobilisation. POSTGRES_* Une fois modifié, compose les conteneurs de l'application. DATABASE_URL Il n’est plus nécessaire d’écrire manuellement les liens. QDRANT_API_KEY Bien qu’il existe une valeur par défaut, elle est sécurisée tant que le port Qdrant n’est pas exposé à l’extérieur du réseau compose ; si vous exposez Qdrant séparément, passez à une valeur aléatoire forte. DATA_DIR Le répertoire indiqué est l'état permanent (base de données, téléchargement, vecteur, sauvegarde), le répertoire entier peut être copié lors de la migration de l'hôte. Déploiement de Docker Compose

Variable de fonctionnement de bac à sable sidecar

Les variables suivantes fonctionnent aivory-sandbox-sidecar le conteneur (code bac à sable), avec le côté de l'application de la section 5 SANDBOX_BASE_URL/SANDBOX_API_KEY Il s'agit d'une configuration à deux extrémités.sidecar retire le code d'exécution des conteneurs isolés par Docker pour chaque session. Déploiement du code bac à sable Le côté utilisateur est visible. Python bac à sable

Miroirs et conteneurs

VariableValeur par défautExpliquer
SANDBOX_IMAGEaivory-sandbox:latestMiroir du temps de fonctionnement utilisé par le conteneur de session.
SANDBOX_NETWORKnoneMode de réseau du conteneur de session Par défaut, le réseau est complètement déconnecté. bridge Une connexion en temps d’exécution est autorisée (par exemple, un package d’installation pip).
SANDBOX_MEMORY2gLimite supérieure de la mémoire pour les conteneurs de session individuels.Les tâches de rendu de document sont moins importantes que les tâches de mémoire et ne sont pas recommandées en dessous de la valeur par défaut.
SANDBOX_CPUS1CPU quota pour un conteneur de session unique.
SANDBOX_PIDS_LIMIT256Limiter le nombre de processus pour chaque conteneur de session, protéger contre les bombes de fork.
SANDBOX_NOFILE_ULIMIT1024:1024Descripteur du fichier du conteneur de session ulimit (soft: dur).
SANDBOX_PULL_ON_START(Vac et fermé)vide et non 0/false Avant de lancer Sidecar. docker pull Le temps d'exécution de l'image miroir une fois pour éviter que la première session du nouveau serveur échoue en raison de l'absence de l'image miroir. Le tirage est fait pour le mieux, l'échec n'empêche pas le démarrage de l'enregistrement.

certifié

VariableValeur par défautExpliquer
SANDBOX_API_KEY( le vide )sidecar exige que toutes les demandes portent une clé Bearer correspondante, et la vérification échoue. ** Lorsque la clé est vide et non explicitement exemptée, sidecar refuse directement le démarrage. ** (fail-closed)。
SANDBOX_ALLOW_NO_AUTH(Vac et fermé)Exemption explicite sans clé de démarrage, uniquement pour les développeurs localhost fiables. 1/true/yes/on Les quatre modes d’écriture (y compris False/no/off Elles sont considérées comme non immunisées.
Ne désactivez pas l'authentification bac à sable dans un environnement connecté.

sidecar dirige directement Docker sur l'hôte, ce qui équivaut aux droits de root de l'hôte. SANDBOX_ALLOW_NO_AUTH Il ne doit apparaître que dans un environnement de développement natif totalement non externe; l'environnement de production doit être fortement aléatoire. SANDBOX_API_KEY et en cohérence avec le côté de l'application (section 5).

Récupération des heures supplémentaires et des séances

VariableValeur par défautExpliquer
SANDBOX_EXEC_TIMEOUT_CAP_MS600000Exécution d'un délai de fonctionnement supérieur à 10 minutes.Chaque délai d'exécution d'appel dans la configuration de la console d'administration est limité à cette valeur; la réduction resserre le plafond.
SANDBOX_DEFAULT_EXEC_TIMEOUT_MS120000L'appelant n'a pas spécifié l'exécution par défaut de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution de l'exécution (120 secondes) et n'hérite pas silencieusement de la limite de 10 minutes.
SANDBOX_IDLE_TTL_SECONDS1800Après combien de temps la session est libre est récupérée, 30 minutes par défaut.
SANDBOX_IDLE_TTL_CAP_SECONDS86400Gratuit pour le recyclage de TTL, limite de durabilité (24 heures). la console d'administration peut raccourcir la fenêtre de recyclage, mais ne doit jamais dépasser cette limite.
SANDBOX_MAX_SESSIONS16Limitation du nombre de conteneurs de session survivants en même temps.
SANDBOX_MAX_CONCURRENT_EXECS4Le nombre de codes exécutés en même temps est limité.
SANDBOX_MAX_CONCURRENT_CREATES2Le nombre de sessions simultanément créé est limité.
SANDBOX_QUEUE_TIMEOUT_SECONDS150La requête est la plus longue période d'attente dans une coquille parallèle et le temps d'attente retourne l'erreur.

Systèmes de fichiers et protection des disques

VariableValeur par défautExpliquer
SANDBOX_READ_ONLY_ROOTFS1Le système de fichiers racine des conteneurs de session ne lit que (attaque de disque de protection). /workspace/tmp$HOME Il y a des tmpfs avec une limite de taille. 0false Peut être fermé, pas recommandé.
SANDBOX_TMPFS_SIZE256m/tmp La taille maximale du tmpfs est fixée.
SANDBOX_WORKSPACE_SIZE512mEspace de travail écrite. /workspace La limite de taille de tmpfs. ancien nom SANDBOX_WORKSPACE_TMPFS_SIZE Elle reste en vigueur en tant que dénomination compatible.
SANDBOX_DISK_SIZE(Vac et fermé)Le conteneur de session peut écrire des quotas de disque (tels que 1g Docker overlay2 est nécessaire lorsque le lecteur de stockage et l'activation de pquota/prjquota ne sont pas satisfaits docker run L'erreur est signalée et, par conséquent, elle est appliquée de la manière optionnelle et de la manière la plus efficace possible (le paramètre est automatiquement supprimé en cas d'échec).
SANDBOX_SECCOMP_PROFILE(Vac et fermé)Spécifiez un parcours fixe du fichier seccomp profile pour le conteneur de session (le parcours doit être lu dans le conteneur sidecar). docker run

Limites d'exportation et de produits

VariableValeur par défautExpliquer
SANDBOX_MAX_OUTPUT_BYTES32768Exécutez une seule fois la limite de coupe pour stdout/stderr (32KB).
SANDBOX_MAX_ARTIFACT_BYTES20971520Taille maximale de chaque fichier de produit (20 MiB).
SANDBOX_MAX_TOTAL_ARTIFACT_BYTES52428800Exécution de la taille maximale totale de tous les produits à la fois (50 MiB).
SANDBOX_MAX_FILES_PER_EXEC20Exécution du nombre de documents susceptibles d’être téléchargés.
SANDBOX_MAX_UPLOAD_BYTES20971520Téléchargez un fichier individuel dans le bac à sable avec une taille maximale (20 MiB).
SANDBOX_MAX_ARCHIVE_BYTES209715200La taille maximale du package tar de l'espace de travail d'archivage (200 MiB). session /workspace Au-delà de cette valeur, sauter à l’archivage (log), la session elle-même est toujours recyclée normalement.

Durabilité des espaces de travail

VariableValeur par défautExpliquer
SANDBOX_LOCAL_STORAGE_DIR(Vac et fermé)Archives de disques locaux dans le répertoire arrière, remplacement sans dépendance en dehors de S3/OSS. Les paquets tar de l'espace de travail sont écrits dans le répertoire après la configuration, il faut les accrocher en volumes pour redémarrer les réserves sur le sidecar. local L'arrière-plan n'est pas valide et la session est récupérée, c'est-à-dire que l'espace de travail est perdu. Le parcours peut être spécifié uniquement par l'opération par la variable de l'environnement et n'accepte pas l'entrée de l'appelant distant.

** Choisir un trou habituel **: le compose officiel a rempli les valeurs par défaut disponibles pour sidecar, la plupart des scénarios ne nécessitent que des préoccupations SANDBOX_API_KEY (compatible avec l'application) et si elle est désactivée SANDBOX_NETWORK Déconnecter le réseau (bridge Pour ce qui est de l'évaluation des risques, veuillez procéder à l'évaluation des risques et à la réévaluation des risques (SANDBOX_MEMORY/SANDBOX_MAX_SESSIONS/SANDBOX_MAX_CONCURRENT_EXECS En fonction de l'estimation de la mémoire de l'hôte ≥ nombre de sessions × mémoire de session unique, le pic théorique par défaut de 16 sessions × 2g dépasse la capacité de la petite machine, la petite machine de mémoire doit être abaissée. SANDBOX_MAX_SESSIONS Le nombre d'exemplaires de l'exemplaire S3 et de l'exemplaire S3 et du nombre d'exemplaires de l'exemplaire (SANDBOX_S3_*SANDBOX_MAX_BODY_BYTES a) à entrer Variable environnementale optimale

Variables de la période de construction avant

VariableValeur par défautExpliquer
VITE_API_BASE/apil'appel à l'appel de base de l'API, en ** Lors de la construction ** Injection.L'adresse complète du service API est modifiée uniquement lorsque le déploiement de l'avant-derrière est séparé (l'avant-derrière est statiquement hébergé ailleurs).

** Choisir un trou habituel ** Il s'agit d'une variable de période de construction et non d'une variable de temps de fonctionnement : si elle a été modifiée, elle doit être reconstruite et n'a aucun effet sur la configuration officielle de l'image miroir qui a été construite. /api Il est possible de le modifier uniquement lorsque vous déployez votre front-end sur un nom de domaine / CDN indépendant. https://api.example.com/api Cette adresse complète, tout en gardant à l'esprit d'ajouter l'original à l'avant du serveur ALLOWED_ORIGINS (Article 3 du présent article).

Prochaine étape